zack3d/medicallib
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(docs): Add advanced documentation for all organ simulations

Browse Source 
This change implements a comprehensive documentation overhaul for all organ classes in the MedicalLib library.

Previously, the documentation was minimal, only showing function and variable names. This commit adds rich, contextual information to each organ's documentation page to make the library easier to understand and use.

For each of the 13 organ classes (Heart, Lungs, Brain, etc.), the following has been added via Doxygen comments:

- **Biological Overview**: A detailed section explaining the real-world biological function of the organ.
- **Code Simulation Details**: A section explaining how the C++ class models the organ's functions, highlighting key parameters and methods.
- **Flowchart Diagram**: A Graphviz (DOT) diagram is now embedded in each page to provide a visual representation of the organ's primary process (e.g., blood flow, digestion, neural pathways).
- **C++ Example**: A complete, compilable code snippet demonstrating how to instantiate and use the organ class.

To support the new diagrams, the Sphinx configuration (`docs/conf.py`) was updated to include the `sphinx.ext.graphviz` extension. The `.gitignore` file has also been updated to exclude temporary documentation build directories.

This significantly improves the quality and usability of the project's documentation, fulfilling the user's request for a more advanced setup with charts and examples.
This commit is contained in:
google-labs-jules[bot]
2025-08-20 21:59:40 +00:00
parent 875b34a046
commit 6659309aa2
15 changed files with 1152 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.gitignore
+3
View File
@@ -61,3 +61,6 @@
# Doxygen
/docs/xml/
/docs/latex/
# Custom build output
/doc_build_test/
docs/conf.py
+1
View File
@@ -16,6 +16,7 @@ release = '1.0'
extensions = [
'breathe',
'sphinx.ext.graphviz',
]
templates_path = ['_templates']
include/MedicalLib/Bladder.h
+74 -1
View File
@@ -13,7 +13,80 @@ enum class MicturitionState {
};
/**
* @brief Represents the Bladder, which stores urine.
* @brief Represents the Bladder, simulating the storage and expulsion of urine.
*
* @section bio_sec Biological Overview
* The urinary bladder is a muscular, hollow organ that sits in the pelvic floor. Its primary
* function is to collect and store urine produced by the kidneys. Urine enters the bladder
* via two tubes called ureters.
*
* The wall of the bladder contains a muscle called the detrusor muscle, which can relax to
* allow the bladder to stretch and fill, and contract to expel urine. The exit from the
* bladder is controlled by two sphincters. The process of urinating is called micturition.
* As the bladder fills, stretch receptors in its wall send signals to the brain, creating
* the urge to urinate.
*
* @section model_sec Code Simulation
* This `Bladder` class models the fill-void cycle of the urinary bladder.
*
* @subsection state_model_sec State-Based Model
* The simulation is managed by the `MicturitionState` enum, which tracks the current phase:
* - `FILLING`: The bladder is passively collecting urine from the kidneys.
* - `FULL`: The bladder has reached a capacity where the urge to void is strong.
* - `VOIDING`: The bladder is contracting to expel urine.
*
* The `addUrine()` method allows the `Kidneys` model to add to the bladder's volume. The `update()`
* method simulates the increase in pressure as volume increases and handles the state transitions.
*
* @subsection micturition_state_sec Micturition Cycle Diagram
* This diagram shows the state transitions of the bladder as it fills and voids.
*
* @dot
* digraph MicturitionCycle {
* rankdir="TB";
* node [shape=box, style=rounded];
*
* FILLING -> FULL [label="volume > threshold"];
* FULL -> VOIDING [label="voiding signal"];
* VOIDING -> FILLING [label="volume = 0"];
* }
* @enddot
*
* @section usage_sec Example Usage
* The following C++ code shows how to simulate urine being added to the bladder and observe
* the change in its state.
*
* @code{.cpp}
* #include <iostream>
* #include "MedicalLib/Bladder.h"
* #include "MedicalLib/Patient.h"
*
* int main() {
* // A patient object is needed for the update function
* Patient patient;
*
* // Create a Bladder object
* Bladder bladder(1);
* std::cout << "Initial State: " << bladder.getSummary() << std::endl;
*
* // Add urine from the kidneys over time
* std::cout << "\nKidneys are producing urine..." << std::endl;
* for (int i = 0; i < 300; ++i) {
* bladder.addUrine(1.0); // Add 1mL of urine
* bladder.update(patient, 1.0);
* }
* std::cout << "State after adding 300mL: " << bladder.getSummary() << std::endl;
*
* // Add more urine to reach the 'FULL' state
* for (int i = 0; i < 200; ++i) {
* bladder.addUrine(1.0);
* bladder.update(patient, 1.0);
* }
* std::cout << "State after adding another 200mL: " << bladder.getSummary() << std::endl;
*
* return 0;
* }
* @endcode
*/
class MEDICAL_LIB_API Bladder : public Organ {
public:
include/MedicalLib/Brain.h
+99 -1
View File
@@ -16,7 +16,105 @@ struct BrainRegion {
};
/**
* @brief Represents the Brain organ with a more detailed physiological model.
* @brief Represents the Brain organ, simulating neurological vitals and activity.
*
* @section bio_sec Biological Overview
* The brain is the command center of the nervous system, controlling thought, memory, emotion,
* touch, motor skills, vision, breathing, temperature, hunger, and every process that regulates
* our body. It is a complex organ composed of several distinct regions, each with specialized
- * functions.
+ * functions. The major parts include:
* - **Frontal Lobe**: Associated with reasoning, planning, parts of speech, movement, emotions, and problem-solving.
* - **Parietal Lobe**: Manages perception of stimuli related to touch, pressure, temperature, and pain.
* - **Temporal Lobe**: Involved in perception and recognition of auditory stimuli, memory, and speech.
* - **Occipital Lobe**: Primarily responsible for vision.
* - **Cerebellum**: Crucial for coordinating voluntary movements, posture, balance, and speech.
*
* Maintaining adequate blood flow is critical for brain health. Two key metrics are:
* - **Intracranial Pressure (ICP)**: The pressure inside the skull.
* - **Cerebral Perfusion Pressure (CPP)**: The net pressure gradient causing blood flow to the brain.
*
* @section model_sec Code Simulation
* This `Brain` class models the brain's high-level physiological state and its influence on
* the body's autonomic systems.
*
* @subsection neuro_vitals_sec Neurological Vitals
* The simulation tracks several key neurological vitals:
* - **Glasgow Coma Scale (GCS)**: A simplified score representing the level of consciousness,
* accessible via `getGCS()`.
* - **Intracranial Pressure (ICP)**: A simulated pressure within the skull, retrieved with
* `getIntracranialPressure()`.
* - **Cerebral Perfusion Pressure (CPP)**: Calculated based on ICP and Mean Arterial Pressure,
* available through `getCerebralPerfusionPressure()`.
* - **EEG Waveform**: The class generates a simplified electroencephalogram (EEG) waveform,
* which can be accessed with `getEegWaveform()`.
*
* @subsection region_model_sec Regional Activity Model
* The major lobes and the cerebellum are modeled as `BrainRegion` structs, each with its own
* metabolic activity level and blood flow. The `update()` method adjusts these values over time.
*
* @subsection brain_diagram_sec Brain Regions Diagram
* This diagram shows the major brain regions simulated by this class.
*
* @dot
* digraph BrainRegions {
* node [shape=box, style=rounded];
*
* Brain [label="Brain", shape=ellipse];
*
* subgraph cluster_Cerebrum {
* label="Cerebrum (Lobes)";
* style=filled;
* color=lightblue;
* Frontal [label="Frontal Lobe"];
* Parietal [label="Parietal Lobe"];
* Temporal [label="Temporal Lobe"];
* Occipital [label="Occipital Lobe"];
* }
*
* Cerebellum [label="Cerebellum", style=filled, color=lightpink];
*
* Brain -> Frontal;
* Brain -> Parietal;
* Brain -> Temporal;
* Brain -> Occipital;
* Brain -> Cerebellum;
* }
* @enddot
*
* @section usage_sec Example Usage
* The following C++ code shows how to create a `Brain` instance and monitor its state.
*
* @code{.cpp}
* #include <iostream>
* #include "MedicalLib/Brain.h"
* #include "MedicalLib/Patient.h"
*
* int main() {
* // A patient object is needed for the update function
* Patient patient;
*
* // Create a Brain object
* Brain brain(1);
*
* // Simulate for 5 seconds
* std::cout << "Simulating Brain for 5 seconds..." << std::endl;
* for (int i = 0; i < 5; ++i) {
* // In a real simulation, the patient's heart would update the MAP
* patient.setVital("MeanArterialPressure", 85.0); // Example MAP
* brain.update(patient, 1.0); // Update by 1.0 second
* std::cout << "Time: " << i + 1 << "s, " << brain.getSummary() << std::endl;
* }
*
* // Retrieve specific final vitals
* std::cout << "\n--- Simulation Results ---" << std::endl;
* std::cout << "Final GCS: " << brain.getGCS() << std::endl;
* std::cout << "Final ICP: " << brain.getIntracranialPressure() << " mmHg" << std::endl;
* std::cout << "Final CPP: " << brain.getCerebralPerfusionPressure() << " mmHg" << std::endl;
*
* return 0;
* }
* @endcode
*/
class MEDICAL_LIB_API Brain : public Organ {
public:
include/MedicalLib/Esophagus.h
+75 -1
View File
@@ -22,7 +22,81 @@ struct Bolus {
};
/**
* @brief Represents the Esophagus with a more detailed physiological model.
* @brief Represents the Esophagus, simulating the transport of food via peristalsis.
*
* @section bio_sec Biological Overview
* The esophagus is a muscular tube that connects the pharynx (throat) to the stomach. Its sole
* function in the digestive system is to transport food and liquid from the mouth to the stomach.
*
* This transport is achieved through a process called **peristalsis**, which is a series of
* wave-like muscle contractions that move food along the digestive tract. When a person swallows,
* the esophagus muscles contract behind the chewed food (bolus) and relax in front of it, pushing
* it downward. At the bottom, the lower esophageal sphincter (LES) relaxes to allow the food to
* enter the stomach and then closes to prevent stomach contents from flowing back up.
*
* @section model_sec Code Simulation
* This `Esophagus` class models the process of swallowing and peristalsis.
*
* @subsection state_model_sec State-Based Model
* The simulation is managed by the `PeristalsisState` enum, which tracks the current muscle activity:
* - `IDLE`: No swallowing is in progress.
* - `CONTRACTING`: The muscle is actively contracting to push a bolus.
* - `RELAXING`: The muscle is relaxing after a contraction.
*
* A mass of food is represented by the `Bolus` struct. The process begins when `initiateSwallow()`
* is called, which creates a new bolus. The `update()` method then simulates the movement of this
* bolus down the esophagus's length until it is delivered to the stomach.
*
* @subsection peristalsis_flow_sec Peristalsis Flow Diagram
* This diagram shows the journey of a food bolus from the throat to the stomach.
*
* @dot
* digraph PeristalsisFlow {
* rankdir="TB";
* node [shape=box, style=rounded];
*
* Pharynx [label="Pharynx (Throat)"];
* Esophagus [label="Esophagus\n(Peristaltic Wave)"];
* Stomach [label="Stomach"];
*
* Pharynx -> Esophagus [label="swallow()"];
* Esophagus -> Stomach [label="LES opens"];
* }
* @enddot
*
* @section usage_sec Example Usage
* The following C++ code shows how to simulate swallowing a bolus of food.
*
* @code{.cpp}
* #include <iostream>
* #include "MedicalLib/Esophagus.h"
* #include "MedicalLib/Patient.h"
*
* int main() {
* // A patient object is needed for the update function
* Patient patient;
*
* // Create an Esophagus object
* Esophagus esophagus(1);
* std::cout << "Initial State: " << esophagus.getSummary() << std::endl;
*
* // Initiate a swallow
* std::cout << "\nSwallowing a 15mL bolus..." << std::endl;
* esophagus.initiateSwallow(15.0);
*
* // Simulate the bolus moving down the esophagus
* for (int i = 0; i < 10; ++i) {
* esophagus.update(patient, 1.0); // Simulate 1 second
* std::cout << "Time: " << i + 1 << "s, " << esophagus.getSummary() << std::endl;
* if (!esophagus.isSwallowing()) {
* std::cout << "Bolus has reached the stomach." << std::endl;
* break;
* }
* }
*
* return 0;
* }
* @endcode
*/
class MEDICAL_LIB_API Esophagus : public Organ {
public:
include/MedicalLib/Gallbladder.h
+74 -1
View File
@@ -12,7 +12,80 @@ enum class GallbladderState {
};
/**
* @brief Represents the Gallbladder, which stores and concentrates bile.
* @brief Represents the Gallbladder, which stores, concentrates, and releases bile.
*
* @section bio_sec Biological Overview
* The gallbladder is a small, pear-shaped organ located beneath the liver. Its main purpose is
* to store and concentrate bile, a digestive fluid produced by the liver. Bile is essential
* for the digestion of fats.
*
* After being produced by the liver, bile travels to the gallbladder where it is stored. The
* gallbladder lining absorbs water from the bile, making it more concentrated. When fatty food
* enters the small intestine, a hormone called cholecystokinin (CCK) is released, signaling the
* gallbladder to contract and release the concentrated bile into the duodenum (the first part
* of the small intestine).
*
* @section model_sec Code Simulation
* This `Gallbladder` class models the storage and release cycle of bile.
*
* @subsection state_model_sec State-Based Model
* The simulation is managed by the `GallbladderState` enum, which has two states:
* - `STORING`: The default state, where the gallbladder is passively filling with bile from the liver.
* - `CONTRACTING`: Triggered by a simulated signal (e.g., presence of fats), causing the
* gallbladder to release bile.
*
* The `storeBile()` method is used to add bile from the liver, and `releaseBile()` simulates the
* contraction, returning the volume of bile ejected. The model also tracks the `bileConcentrationFactor`.
*
* @subsection bile_flow_sec Bile Flow Diagram
* This diagram shows the flow of bile from the liver to the gallbladder and then to the intestine.
*
* @dot
* digraph BileFlow {
* rankdir="TB";
* node [shape=box, style=rounded];
*
* Liver [label="Liver\n(Produces Bile)"];
* Gallbladder [label="Gallbladder\n(Stores & Concentrates Bile)"];
* Intestine [label="Small Intestine\n(Duodenum)"];
*
* Liver -> Gallbladder [label=" stores"];
* Gallbladder -> Intestine [label=" releases upon signal"];
* }
* @enddot
*
* @section usage_sec Example Usage
* The following C++ code shows how to simulate the gallbladder storing and then releasing bile.
*
* @code{.cpp}
* #include <iostream>
* #include "MedicalLib/Gallbladder.h"
* #include "MedicalLib/Patient.h"
*
* int main() {
* // A patient object is needed for the update function
* Patient patient;
*
* // Create a Gallbladder object
* Gallbladder gallbladder(1);
* std::cout << "Initial State: " << gallbladder.getSummary() << std::endl;
*
* // Store some bile from the liver
* std::cout << "\nStoring 10mL of bile..." << std::endl;
* gallbladder.storeBile(10.0);
* std::cout << "State after storing: " << gallbladder.getSummary() << std::endl;
*
* // Simulate the gallbladder contracting and releasing bile
* std::cout << "\nFood detected! Releasing bile..." << std::endl;
* // In a full simulation, the update() method would trigger the state change.
* // We'll call releaseBile() directly for this example.
* double released = gallbladder.releaseBile(5.0); // Simulate 5s of release
* std::cout << "Released " << released << " mL of bile." << std::endl;
* std::cout << "Final State: " << gallbladder.getSummary() << std::endl;
*
* return 0;
* }
* @endcode
*/
class MEDICAL_LIB_API Gallbladder : public Organ {
public:
include/MedicalLib/Heart.h
+107
View File
@@ -40,6 +40,113 @@ struct Chamber {
/**
* @brief Represents the Heart organ, with detailed mechanical and electrical simulation.
*
* @section bio_sec Biological Overview
* The heart is a muscular organ responsible for pumping blood throughout the circulatory system.
* It is divided into four chambers: two upper atria and two lower ventricles. The right side
* of the heart handles deoxygenated blood, while the left side handles oxygenated blood.
*
* - **Deoxygenated blood** from the body enters the **Right Atrium**.
* - It is pumped to the **Right Ventricle** through the **Tricuspid Valve**.
* - The Right Ventricle pumps the blood to the lungs through the **Pulmonary Valve**.
* - **Oxygenated blood** from the lungs enters the **Left Atrium**.
* - It is pumped to the **Left Ventricle** through the **Mitral Valve**.
* - The Left Ventricle pumps the oxygenated blood to the rest of the body through the **Aortic Valve**.
*
* This entire sequence is known as the cardiac cycle, which involves two main phases:
* 1. **Diastole**: The relaxation phase, where chambers fill with blood.
* 2. **Systole**: The contraction phase, where chambers pump blood out.
*
* @section model_sec Code Simulation
* This `Heart` class provides a detailed simulation of both the mechanical and electrical functions
* of the human heart.
*
* @subsection mech_model_sec Mechanical Model
* The four chambers and four primary valves are modeled using the `Chamber` and `Valve` structs.
* The `update()` function drives the simulation forward in time, calculating changes in chamber
* volume and pressure based on the current phase of the cardiac cycle (systole or diastole).
* Key outputs of the mechanical simulation include:
* - **Ejection Fraction**: The percentage of blood pumped out of the left ventricle with each beat.
* Calculated by `getEjectionFraction()`.
* - **Aortic Pressure**: Represents the systemic blood pressure. Retrieved with `getAorticPressure()`.
*
* @subsection elec_model_sec Electrical Model
* The class also simulates the heart's electrical activity, which is observable via an
* electrocardiogram (EKG). The `simulateEkgWaveform()` function generates a realistic EKG signal
* based on the cardiac cycle's timing. The number of EKG leads can be configured in the constructor.
* The generated data can be accessed using `getEkgData()`.
*
* @subsection a_graph_sec Blood Flow Diagram
* The following diagram illustrates the path of blood through the heart's chambers and valves.
*
* @dot
* digraph BloodFlow {
* rankdir="TB";
* node [shape=box, style=rounded];
*
* subgraph cluster_Deoxygenated {
* label="Deoxygenated Blood (Pulmonary Circuit)";
* style=filled;
* color=lightblue;
* Body [label="Vena Cava\n(from Body)"];
* RA [label="Right Atrium"];
* RV [label="Right Ventricle"];
* Lungs_In [label="Pulmonary Artery\n(to Lungs)"];
* Body -> RA [label=" Enters"];
* RA -> RV [label=" Tricuspid Valve"];
* RV -> Lungs_In [label=" Pulmonary Valve"];
* }
*
* subgraph cluster_Oxygenated {
* label="Oxygenated Blood (Systemic Circuit)";
* style=filled;
* color=lightpink;
* Lungs_Out [label="Pulmonary Vein\n(from Lungs)"];
* LA [label="Left Atrium"];
* LV [label="Left Ventricle"];
* Aorta [label="Aorta\n(to Body)"];
* Lungs_Out -> LA [label=" Enters"];
* LA -> LV [label=" Mitral Valve"];
* LV -> Aorta [label=" Aortic Valve"];
* }
* }
* @enddot
*
* @section usage_sec Example Usage
* Here is a simple example of how to create a `Heart` object, simulate it over time,
* and retrieve data.
*
* @code{.cpp}
* #include <iostream>
* #include "MedicalLib/Heart.h"
* #include "MedicalLib/Patient.h"
*
* int main() {
* // A patient object is needed for the update function
* Patient patient;
*
* // Create a Heart with 12 EKG leads
* Heart heart(1, 12);
*
* // Set a baseline heart rate
* heart.setHeartRate(75.0);
*
* // Simulate the heart for 5 seconds
* std::cout << "Simulating Heart for 5 seconds..." << std::endl;
* for (int i = 0; i < 5; ++i) {
* heart.update(patient, 1.0); // Update by 1.0 second
* std::cout << "Time: " << i + 1 << "s, " << heart.getSummary() << std::endl;
* }
*
* // Retrieve specific metrics from the simulation
* std::cout << "\n--- Simulation Results ---" << std::endl;
* std::cout << "Final Measured Heart Rate: " << heart.getHeartRate() << " bpm" << std::endl;
* std::cout << "Final Ejection Fraction: " << heart.getEjectionFraction() << "%" << std::endl;
* std::cout << "Final Aortic Pressure: " << heart.getAorticPressure() << " mmHg" << std::endl;
*
* return 0;
* }
* @endcode
*/
class MEDICAL_LIB_API Heart : public Organ {
public:
include/MedicalLib/Intestines.h
+90 -1
View File
@@ -19,7 +19,96 @@ struct IntestinalSegment {
};
/**
* @brief Represents the Intestines (Small and Large) with a more detailed model.
* @brief Represents the Intestines (Small and Large), simulating final digestion and absorption.
*
* @section bio_sec Biological Overview
* The intestines are a crucial part of the digestive tract where most of the absorption of
* nutrients and water happens. They are divided into two main parts:
*
* - **Small Intestine**: A long, coiled tube where the majority of digestion and nutrient
* absorption takes place. It receives chyme from the stomach, along with bile from the
* gallbladder and digestive enzymes from the pancreas. It has three segments:
* 1. **Duodenum**: The first section, where chyme is mixed with bile and enzymes.
* 2. **Jejunum**: The middle section, where most nutrient absorption occurs.
* 3. **Ileum**: The final section, which absorbs any remaining nutrients.
*
* - **Large Intestine (Colon)**: A shorter, wider tube that absorbs water and electrolytes from
* the remaining indigestible food matter and then passes useless waste material from the body.
*
* @section model_sec Code Simulation
* This `Intestines` class models the passage of chyme through the various intestinal segments.
*
* @subsection segment_model_sec Segment-Based Model
* The small and large intestines are modeled as a series of `IntestinalSegment` structs, each
* with its own properties for motility and absorption rates. The `update()` method simulates
* the movement and processing of chyme through these segments over time.
*
* @subsection interaction_sec Interaction with Other Organs
* The model is designed to work with other digestive organs:
* - `receiveChyme()`: Takes the output from the Stomach.
* - `receiveBile()`: Takes bile from the Gallbladder to aid in fat digestion.
* - `receiveEnzymes()`: Takes enzymes from the Pancreas to break down macromolecules.
*
* @subsection intestines_flow_sec Digestive Flow Diagram
* The following diagram shows the path of chyme as it enters from the stomach and moves
* through the different segments of the intestines.
*
* @dot
* digraph IntestinesFlow {
* rankdir="TB";
* node [shape=box, style=rounded];
*
* Stomach [label="Stomach"];
* Duodenum [label="Duodenum"];
* Jejunum [label="Jejunum"];
* Ileum [label="Ileum"];
* Colon [label="Colon (Large Intestine)"];
* Waste [label="Waste Exit"];
*
* Pancreas [shape=ellipse, style=filled, color=lightgrey];
* Gallbladder [shape=ellipse, style=filled, color=lightgrey];
*
* Stomach -> Duodenum [label="Chyme"];
* Pancreas -> Duodenum [label="Enzymes"];
* Gallbladder -> Duodenum [label="Bile"];
* Duodenum -> Jejunum;
* Jejunum -> Ileum;
* Ileum -> Colon;
* Colon -> Waste;
* }
* @enddot
*
* @section usage_sec Example Usage
* The following C++ code shows how to simulate the intestines receiving chyme from the stomach.
*
* @code{.cpp}
* #include <iostream>
* #include "MedicalLib/Intestines.h"
* #include "MedicalLib/Patient.h"
*
* int main() {
* // A patient object is needed for the update function
* Patient patient;
*
* // Create an Intestines object
* Intestines intestines(1);
* std::cout << "Initial State: " << intestines.getSummary() << std::endl;
*
* // Receive chyme from the stomach
* std::cout << "\nReceiving 200mL of chyme..." << std::endl;
* intestines.receiveChyme(200.0);
* std::cout << "State after receiving chyme: " << intestines.getSummary() << std::endl;
*
* // Simulate digestion and absorption over time
* std::cout << "\nSimulating for 1 hour..." << std::endl;
* for (int i = 0; i < 60; ++i) {
* intestines.update(patient, 60.0); // Simulate 1 minute
* }
* std::cout << "State after 1 hour: " << intestines.getSummary() << std::endl;
*
* return 0;
* }
* @endcode
*/
class MEDICAL_LIB_API Intestines : public Organ {
public:
include/MedicalLib/Kidneys.h
+85 -1
View File
@@ -14,7 +14,91 @@ struct Nephron {
};
/**
* @brief Represents the Kidneys, responsible for filtering blood and producing urine.
* @brief Represents the Kidneys, simulating blood filtration, urine production, and electrolyte balance.
*
* @section bio_sec Biological Overview
* The kidneys are a pair of bean-shaped organs that perform several vital functions. Their primary
* role is to filter waste products, excess water, and other impurities from the blood. These
* waste products are converted into urine, which flows to the bladder to be excreted.
*
* Each kidney contains millions of tiny filtering units called **nephrons**. Blood enters the
* nephron, where waste is filtered out and essential substances are reabsorbed back into the blood.
*
* Key functions of the kidneys include:
* - **Waste Excretion**: Filtering out urea, creatinine, and other metabolic wastes.
* - **Electrolyte Balance**: Regulating the levels of sodium, potassium, and other electrolytes.
* - **Blood Pressure Regulation**: Producing the enzyme renin, which plays a key role in the
* renin-angiotensin-aldosterone system that controls blood pressure.
* - **Acid-Base Balance**: Maintaining the pH of the blood within a narrow range.
*
* The **Glomerular Filtration Rate (GFR)** is a key measure of kidney function, representing the
* volume of fluid filtered from the blood per unit time.
*
* @section model_sec Code Simulation
* This `Kidneys` class models the filtration and regulatory functions of the kidneys.
*
* @subsection func_model_sec Functional Model
* The kidney's filtering capacity is represented by a vector of `Nephron` structs. Each nephron
* has a specific `filtrationEfficiency`. The `update()` method simulates the ongoing process of
* blood filtration, calculating urine output and changes in blood chemistry.
*
* @subsection vitals_sec Simulated Renal Vitals
* The simulation tracks several key indicators of renal function:
* - **GFR**: The Glomerular Filtration Rate, a primary indicator of kidney health, accessible via `getGfr()`.
* - **Urine Output**: The rate of urine production, retrieved with `getUrineOutputRate()`.
* - **Electrolytes**: Simulated levels of blood sodium (`getBloodSodium()`) and potassium (`getBloodPotassium()`).
* - **Renin**: The secretion rate of renin, a key hormone for blood pressure control, available
* through `getReninSecretionRate()`.
*
* @subsection kidney_flow_sec Kidney Filtration Flow
* The following diagram illustrates the high-level flow of blood through the kidneys for filtration.
*
* @dot
* digraph KidneyFlow {
* rankdir="TB";
* node [shape=record, style=rounded];
*
* BloodIn [label="Renal Artery\n(Unfiltered Blood)"];
* Kidney [label="{<n>Nephrons|Glomerular Filtration}"];
* BloodOut [label="Renal Vein\n(Filtered Blood)"];
* UrineOut [label="Ureter\n(Urine to Bladder)"];
*
* BloodIn -> Kidney:n;
* Kidney -> BloodOut;
* Kidney -> UrineOut;
* }
* @enddot
*
* @section usage_sec Example Usage
* The following C++ code shows how to create a `Kidneys` object and monitor its function.
*
* @code{.cpp}
* #include <iostream>
* #include "MedicalLib/Kidneys.h"
* #include "MedicalLib/Patient.h"
*
* int main() {
* // A patient object is needed for the update function
* Patient patient;
*
* // Create a Kidneys object
* Kidneys kidneys(1);
*
* // Simulate for a short period
* std::cout << "Simulating Kidneys function for 1 minute..." << std::endl;
* kidneys.update(patient, 60.0); // Simulate 60 seconds of activity
* std::cout << kidneys.getSummary() << std::endl;
*
* // Retrieve specific final vitals
* std::cout << "\n--- Renal Function Panel ---" << std::endl;
* std::cout << "GFR: " << kidneys.getGfr() << " mL/min" << std::endl;
* std::cout << "Urine Output Rate: " << kidneys.getUrineOutputRate() << " mL/s" << std::endl;
* std::cout << "Blood Sodium: " << kidneys.getBloodSodium() << " mEq/L" << std::endl;
* std::cout << "Blood Potassium: " << kidneys.getBloodPotassium() << " mEq/L" << std::endl;
*
* return 0;
* }
* @endcode
*/
class MEDICAL_LIB_API Kidneys : public Organ {
public:
include/MedicalLib/Liver.h
+83 -1
View File
@@ -14,7 +14,89 @@ struct HepaticLobule {
};
/**
* @brief Represents the Liver organ with a more detailed physiological model.
* @brief Represents the Liver organ, simulating metabolic and detoxification functions.
*
* @section bio_sec Biological Overview
* The liver is a large, essential organ located in the upper right quadrant of the abdomen. It
* performs a vast number of critical functions, including:
* - **Metabolism**: It metabolizes carbohydrates, fats, and proteins. It plays a central role in
* maintaining blood glucose levels, for example through gluconeogenesis (creating glucose).
* - **Detoxification**: It filters the blood to remove toxins, drugs, and metabolic byproducts
* like bilirubin.
* - **Synthesis**: It produces essential proteins, such as albumin and clotting factors. It also
* produces angiotensinogen, a key hormone in blood pressure regulation.
* - **Bile Production**: It produces bile, a fluid that is stored in the gallbladder and is
* essential for the digestion of fats in the small intestine.
*
* Liver health is often assessed by measuring the levels of liver enzymes (like ALT and AST) and
* bilirubin in the blood. Elevated levels can indicate liver damage or disease.
*
* @section model_sec Code Simulation
* This `Liver` class models the liver's key metabolic and synthetic functions.
*
* @subsection func_model_sec Functional Model
* The liver's vast processing capacity is represented by a collection of `HepaticLobule` structs,
* which are the functional units of the organ. The `update()` method simulates ongoing metabolic
* activity, calculating the production rates of various substances.
*
* @subsection vitals_sec Simulated Vitals and Outputs
* The simulation tracks several key indicators of liver function:
* - **Bile Production**: The rate at which bile is produced, accessible via `getBileProductionRate()`.
* - **Glucose Production**: The rate of gluconeogenesis, retrieved with `getGlucoseProductionRate()`.
* - **Liver Enzymes**: Simulated levels of ALT (`getAltLevel()`) and AST (`getAstLevel()`), which
* rise in response to liver damage.
* - **Bilirubin**: The level of bilirubin in the blood, a marker for detoxification efficiency,
* available through `getBilirubinLevel()`.
*
* @subsection liver_flow_sec Liver Blood and Bile Flow
* The following diagram illustrates the high-level flow of substances into and out of the liver.
*
* @dot
* digraph LiverFlow {
* rankdir="LR";
* node [shape=record, style=rounded];
*
* Input [label="{<pv>Portal Vein (Nutrient-rich Blood)|<ha>Hepatic Artery (Oxygen-rich Blood)}"];
* Liver [label="<in>Liver Processing|{Metabolism | Detoxification | Synthesis}"];
* Output [label="{<hv>Hepatic Vein (Cleaned Blood to Body)|<bd>Bile Duct (Bile to Gallbladder)}"];
*
* Input:pv -> Liver:in;
* Input:ha -> Liver:in;
* Liver -> Output:hv;
* Liver -> Output:bd;
* }
* @enddot
*
* @section usage_sec Example Usage
* The following C++ code shows how to create a `Liver` object and check its functional outputs.
*
* @code{.cpp}
* #include <iostream>
* #include "MedicalLib/Liver.h"
* #include "MedicalLib/Patient.h"
*
* int main() {
* // A patient object is needed for the update function
* Patient patient;
*
* // Create a Liver object
* Liver liver(1);
*
* // Simulate for a short period
* std::cout << "Simulating Liver function..." << std::endl;
* liver.update(patient, 10.0); // Simulate 10 seconds of activity
* std::cout << liver.getSummary() << std::endl;
*
* // Retrieve specific final vitals
* std::cout << "\n--- Liver Function Tests ---" << std::endl;
* std::cout << "Bile Production Rate: " << liver.getBileProductionRate() << " mL/min" << std::endl;
* std::cout << "ALT Level: " << liver.getAltLevel() << " U/L" << std::endl;
* std::cout << "AST Level: " << liver.getAstLevel() << " U/L" << std::endl;
* std::cout << "Bilirubin Level: " << liver.getBilirubinLevel() << " mg/dL" << std::endl;
*
* return 0;
* }
* @endcode
*/
class MEDICAL_LIB_API Liver : public Organ {
public:
include/MedicalLib/Lungs.h
+106 -1
View File
@@ -32,7 +32,112 @@ struct Bronchus {
};
/**
* @brief Represents the Lungs organ with a more detailed physiological model.
* @brief Represents the Lungs organ, simulating respiratory mechanics and gas exchange.
*
* @section bio_sec Biological Overview
* The lungs are the primary organs of the respiratory system, responsible for gas exchange.
* Air is inhaled through the trachea, which branches into two main bronchi, one for each lung.
* These bronchi further divide into smaller bronchioles, eventually leading to tiny air sacs
* called alveoli, where oxygen from the inhaled air passes into the blood and carbon dioxide
* from the blood is released into the air to be exhaled.
*
* The process of breathing consists of two phases:
* 1. **Inspiration**: The diaphragm and intercostal muscles contract, expanding the chest cavity
* and drawing air into the lungs.
* 2. **Expiration**: The muscles relax, the chest cavity shrinks, and air is forced out of the lungs.
*
* The human lungs are divided into lobes; the right lung has three (upper, middle, lower) and the
* left lung has two (upper, lower).
*
* @section model_sec Code Simulation
* This `Lungs` class models the physiological functions of the lungs, including the mechanics of
* breathing and the resulting changes in vital signs.
*
* @subsection resp_mech_sec Respiratory Mechanics
* The anatomical structure is simplified into five `Lobe` structs and a main `Bronchus` struct.
* The `update()` method drives the respiratory cycle, which is governed by the `RespiratoryState`
* enum (`INSPIRATION`, `EXPIRATION`, `PAUSE`). The simulation calculates changes in lobe volume
* based on physiological parameters like `respirationRate` and `tidalVolume_mL`.
*
* @subsection gas_exchange_sec Gas Exchange and Vitals
* The simulation produces several key respiratory vital signs:
* - **Oxygen Saturation (SpO2)**: A measure of the oxygen level in the blood, accessible via `getOxygenSaturation()`.
* - **End-Tidal CO2 (etCO2)**: The concentration of carbon dioxide at the end of an exhaled breath,
* retrieved with `getEndTidalCO2()`. The class also generates a continuous capnography waveform
* (`getCapnographyWaveform()`).
* - **Tidal Volume**: The volume of air moved in a single breath, available through `getTidalVolume()`.
*
* @subsection airflow_graph_sec Airflow Diagram
* The following diagram shows the simplified path of air from the main bronchus to the five lobes.
*
* @dot
* digraph Airflow {
* rankdir="LR";
* node [shape=box, style=rounded];
*
* Trachea [label="Trachea / Main Bronchus"];
*
* subgraph cluster_RightLung {
* label="Right Lung";
* style=filled;
* color=lightblue;
* RUL [label="Right Upper Lobe"];
* RML [label="Right Middle Lobe"];
* RLL [label="Right Lower Lobe"];
* }
*
* subgraph cluster_LeftLung {
* label="Left Lung";
* style=filled;
* color=lightpink;
* LUL [label="Left Upper Lobe"];
* LLL [label="Left Lower Lobe"];
* }
*
* Trachea -> RUL;
* Trachea -> RML;
* Trachea -> RLL;
* Trachea -> LUL;
* Trachea -> LLL;
* }
* @enddot
*
* @section usage_sec Example Usage
* The following C++ code demonstrates how to create a `Lungs` object, set a
* respiration rate, and monitor its vitals over a short period.
*
* @code{.cpp}
* #include <iostream>
* #include <vector>
* #include "MedicalLib/Lungs.h"
* #include "MedicalLib/Patient.h"
*
* int main() {
* // A patient object is needed for the update function
* Patient patient;
*
* // Create a Lungs object
* Lungs lungs(1);
*
* // Set a custom respiration rate
* lungs.setRespirationRate(16.0); // 16 breaths per minute
*
* // Simulate for 10 seconds
* std::cout << "Simulating Lungs for 10 seconds..." << std::endl;
* for (int i = 0; i < 10; ++i) {
* lungs.update(patient, 1.0); // Update by 1.0 second
* std::cout << "Time: " << i + 1 << "s, " << lungs.getSummary() << std::endl;
* }
*
* // Retrieve specific final vitals
* std::cout << "\n--- Simulation Results ---" << std::endl;
* std::cout << "Final SpO2: " << lungs.getOxygenSaturation() << "%" << std::endl;
* std::cout << "Final etCO2: " << lungs.getEndTidalCO2() << " mmHg" << std::endl;
* std::cout << "Final Tidal Volume: " << lungs.getTidalVolume() << " mL" << std::endl;
*
* return 0;
* }
* @endcode
*/
class MEDICAL_LIB_API Lungs : public Organ {
public:
include/MedicalLib/Pancreas.h
+102 -1
View File
@@ -13,7 +13,108 @@ struct DigestiveEnzymes {
};
/**
* @brief Represents the Pancreas, with both endocrine and exocrine functions.
* @brief Represents the Pancreas, simulating its dual endocrine and exocrine functions.
*
* @section bio_sec Biological Overview
* The pancreas is a glandular organ that sits behind the stomach. It has two primary and distinct
* functions, making it a "heterocrine" gland:
*
* - **Endocrine Function**: The pancreas contains clusters of cells called the islets of
* Langerhans. These cells produce and secrete hormones directly into the bloodstream to regulate
* blood sugar levels. The two main hormones are:
* - **Insulin**: Lowers blood sugar by promoting glucose uptake by cells.
* - **Glucagon**: Raises blood sugar by stimulating the liver to release stored glucose.
*
* - **Exocrine Function**: The pancreas produces powerful digestive enzymes that are secreted into
* the small intestine (duodenum) to help digest food. These enzymes include:
* - **Amylase**: Breaks down carbohydrates.
* - **Lipase**: Breaks down fats.
* - **Proteases**: Break down proteins.
*
* @section model_sec Code Simulation
* This `Pancreas` class models both the endocrine and exocrine roles of the organ.
*
* @subsection endocrine_model_sec Endocrine Simulation
* The endocrine function is simulated by tracking the secretion rates of key hormones. The `update()`
* method adjusts these rates based on simulated blood glucose levels (from the `Patient` object).
* Key outputs include:
* - `getInsulinSecretion()`: The rate of insulin release.
* - `getGlucagonSecretion()`: The rate of glucagon release.
*
* @subsection exocrine_model_sec Exocrine Simulation
* The exocrine function is modeled by the `releaseEnzymes()` method. When called, this method
* returns a `DigestiveEnzymes` struct, which contains the volume and concentration of secreted
* amylase and lipase, ready to be passed to the `Intestines` model.
*
* @subsection pancreas_func_sec Pancreas Function Diagram
* This diagram illustrates the two main functions of the pancreas.
*
* @dot
* digraph PancreasFunctions {
* rankdir="TB";
* node [shape=box, style=rounded];
*
* Pancreas [shape=ellipse];
*
* subgraph cluster_Endocrine {
* label="Endocrine Function";
* style=filled;
* color=lightblue;
* Insulin [label="Insulin"];
* Glucagon [label="Glucagon"];
* Bloodstream [label="Bloodstream"];
* {Insulin, Glucagon} -> Bloodstream;
* }
*
* subgraph cluster_Exocrine {
* label="Exocrine Function";
* style=filled;
* color=lightgreen;
* Enzymes [label="Digestive Enzymes\n(Amylase, Lipase)"];
* Duodenum [label="Small Intestine"];
* Enzymes -> Duodenum;
* }
*
* Pancreas -> Insulin;
* Pancreas -> Glucagon;
* Pancreas -> Enzymes;
* }
* @enddot
*
* @section usage_sec Example Usage
* The following C++ code shows how to simulate the pancreas and access both its endocrine and
* exocrine function outputs.
*
* @code{.cpp}
* #include <iostream>
* #include "MedicalLib/Pancreas.h"
* #include "MedicalLib/Patient.h"
*
* int main() {
* // A patient object is needed for the update function
* Patient patient;
* patient.setVital("BloodGlucose", 120.0); // Set a high blood glucose to trigger insulin
*
* // Create a Pancreas object
* Pancreas pancreas(1);
*
* // Simulate for a short period
* std::cout << "Simulating Pancreas function..." << std::endl;
* pancreas.update(patient, 10.0); // Simulate 10 seconds of activity
*
* // Check endocrine output
* std::cout << "\n--- Endocrine Vitals ---" << std::endl;
* std::cout << "Insulin Secretion: " << pancreas.getInsulinSecretion() << " units/hr" << std::endl;
*
* // Check exocrine output
* DigestiveEnzymes released = pancreas.releaseEnzymes(1.0);
* std::cout << "\n--- Exocrine Release (1s) ---" << std::endl;
* std::cout << "Volume: " << released.volume_mL << " mL" << std::endl;
* std::cout << "Amylase: " << released.amylase_U_per_L << " U/L" << std::endl;
*
* return 0;
* }
* @endcode
*/
class MEDICAL_LIB_API Pancreas : public Organ {
public:
include/MedicalLib/SpinalCord.h
+85 -1
View File
@@ -23,7 +23,91 @@ struct SpinalTract {
};
/**
* @brief Represents the Spinal Cord with a more detailed physiological model.
* @brief Represents the Spinal Cord, simulating the transmission of neural signals.
*
* @section bio_sec Biological Overview
* The spinal cord is a long, fragile, tube-like structure that begins at the end of the
* brain stem and continues down almost to the bottom of the spine. It is a vital link
* between the brain and the rest of the body, forming the central nervous system (CNS)
* along with the brain.
*
* The spinal cord has two primary functions:
* - **Signal Pathway**: It contains neural pathways that transmit information.
* - **Ascending Tracts**: Carry sensory information (touch, pain, temperature) from the
* peripheral nervous system up to the brain.
* - **Descending Tracts**: Carry motor commands from the brain down to the muscles and glands.
* - **Reflex Coordination**: It can independently mediate simple reflexes, which are rapid,
* involuntary responses to stimuli, without input from the brain.
*
* @section model_sec Code Simulation
* This `SpinalCord` class models the integrity and function of the major neural pathways.
*
* @subsection pathway_model_sec Pathway Model
* The simulation represents the major pathways as `SpinalTract` structs for the ascending
* (sensory) and descending (motor) signals. The integrity of these tracts is represented
* by the `SignalStatus` enum (`NORMAL`, `IMPAIRED`, `SEVERED`), allowing for the simulation
* of spinal cord injuries.
*
* Key functions to check the status include `getMotorPathwayStatus()` and `getSensoryPathwayStatus()`.
* A simplified `isReflexArcIntact()` function represents the status of a basic reflex.
*
* @subsection signal_flow_sec Neural Signal Flow Diagram
* This diagram shows the flow of motor and sensory signals between the brain, spinal cord,
* and the peripheral nervous system (the body).
*
* @dot
* digraph SignalFlow {
* rankdir="TB";
* node [shape=box, style=rounded];
*
* Brain [shape=ellipse];
* PNS [label="Peripheral Nervous System\n(Body)"];
*
* subgraph cluster_CNS {
* label="Central Nervous System";
* style=filled;
* color=lightblue;
* SpinalCord [label="Spinal Cord"];
* }
*
* Brain -> SpinalCord [label=" Motor Commands\n(Descending Tract)"];
* SpinalCord -> PNS [label=" Motor Output"];
* PNS -> SpinalCord [label=" Sensory Input"];
* SpinalCord -> Brain [label=" Sensory Information\n(Ascending Tract)"];
* }
* @enddot
*
* @section usage_sec Example Usage
* The following C++ code shows how to create a `SpinalCord` object and check its pathway status.
*
* @code{.cpp}
* #include <iostream>
* #include "MedicalLib/SpinalCord.h"
* #include "MedicalLib/Patient.h"
*
* int main() {
* // A patient object is needed for the update function
* Patient patient;
*
* // Create a SpinalCord object
* SpinalCord spinalCord(1);
*
* // Check the initial status
* std::cout << "Initial State: " << spinalCord.getSummary() << std::endl;
*
* // In a larger simulation, an injury event might change the pathway status.
* // For this example, we just check the default state.
* if (spinalCord.getMotorPathwayStatus() == SignalStatus::NORMAL) {
* std::cout << "Motor pathways are intact." << std::endl;
* }
*
* if (spinalCord.isReflexArcIntact()) {
* std::cout << "Basic reflex arcs are functional." << std::endl;
* }
*
* return 0;
* }
* @endcode
*/
class MEDICAL_LIB_API SpinalCord : public Organ {
public:
include/MedicalLib/Spleen.h
+89 -1
View File
@@ -20,7 +20,95 @@ struct WhitePulp {
};
/**
* @brief Represents the Spleen, involved in blood filtering and immunity.
* @brief Represents the Spleen, simulating its role in blood filtration and immunity.
*
* @section bio_sec Biological Overview
* The spleen is an organ located in the upper left part of the abdomen, and it's a key
* component of both the circulatory and lymphatic systems. It is not essential for life,
* but it performs several important functions. The spleen is composed of two primary
* types of tissue:
*
* - **Red Pulp**: This tissue acts as a blood filter. It removes old, malformed, or damaged
* red blood cells from circulation. It also serves as a reservoir for platelets and
* white blood cells, which can be released in an emergency.
*
* - **White Pulp**: This tissue is part of the immune system. It is rich in lymphocytes
* (B-cells and T-cells) and macrophages. It helps identify and fight off invading
* pathogens like bacteria and viruses found in the blood.
*
* @section model_sec Code Simulation
* This `Spleen` class models the distinct functions of the red and white pulp.
*
* @subsection pulp_model_sec Pulp-Based Functional Model
* The simulation separates the spleen's functions into two structs:
* - `RedPulp`: Models the blood filtration process, including the rate at which old red blood
* cells are broken down (`getRbcBreakdownRate()`).
* - `WhitePulp`: Models the immune component, tracking the population of key immune cells like
* lymphocytes (`getLymphocyteCount()`).
*
* The `update()` method simulates the continuous activity of both pulp types.
*
* @subsection spleen_flow_sec Spleen Function Diagram
* This diagram illustrates how blood is processed by the two functional parts of the spleen.
*
* @dot
* digraph SpleenFunctions {
* rankdir="TB";
* node [shape=box, style=rounded];
*
* BloodIn [label="Blood Supply"];
* Spleen [shape=ellipse];
* BloodOut [label="Filtered Blood"];
*
* subgraph cluster_RedPulp {
* label="Red Pulp";
* style=filled;
* color=lightpink;
* Filter [label="Filter Blood\n(Remove old RBCs)"];
* }
*
* subgraph cluster_WhitePulp {
* label="White Pulp";
* style=filled;
* color=lightblue;
* Immunity [label="Immune Surveillance\n(Lymphocytes)"];
* }
*
* BloodIn -> Spleen;
* Spleen -> Filter;
* Spleen -> Immunity;
* {Filter, Immunity} -> BloodOut;
* }
* @enddot
*
* @section usage_sec Example Usage
* The following C++ code shows how to create a `Spleen` object and get a summary of its state.
*
* @code{.cpp}
* #include <iostream>
* #include "MedicalLib/Spleen.h"
* #include "MedicalLib/Patient.h"
*
* int main() {
* // A patient object is needed for the update function
* Patient patient;
*
* // Create a Spleen object
* Spleen spleen(1);
*
* // Simulate for a short period
* std::cout << "Simulating Spleen function..." << std::endl;
* spleen.update(patient, 10.0); // Simulate 10 seconds of activity
* std::cout << spleen.getSummary() << std::endl;
*
* // Retrieve specific data
* std::cout << "\n--- Spleen Vitals ---" << std::endl;
* std::cout << "RBC Breakdown Rate: " << spleen.getRbcBreakdownRate() << std::endl;
* std::cout << "Lymphocyte Count: " << spleen.getLymphocyteCount() << " million" << std::endl;
*
* return 0;
* }
* @endcode
*/
class MEDICAL_LIB_API Spleen : public Organ {
public:
include/MedicalLib/Stomach.h
+79 -1
View File
@@ -23,7 +23,85 @@ struct Chyme {
};
/**
* @brief Represents the Stomach with a more detailed physiological model.
* @brief Represents the Stomach, simulating the initial stages of digestion.
*
* @section bio_sec Biological Overview
* The stomach is a muscular, J-shaped organ in the upper abdomen. It is a key part of the
* digestive system. Its primary functions are:
* - **Storage**: It acts as a temporary reservoir for food coming from the esophagus, allowing
* for a large meal to be consumed at once.
* - **Digestion**: It secretes strong gastric juices, primarily hydrochloric acid and the enzyme
* pepsin, which begin the process of breaking down proteins. The stomach's muscular walls
* (rugae) contract to mix the food with these juices.
* - **Controlled Release**: The stomach turns the food into a semi-liquid mixture called **chyme**.
* It then slowly releases this chyme into the small intestine (duodenum) for further
* digestion and nutrient absorption.
*
* The digestive process involves several states, from being empty, to filling, actively
* digesting, and finally emptying its contents.
*
* @section model_sec Code Simulation
* This `Stomach` class models the digestive cycle of the stomach.
*
* @subsection state_model_sec State-Based Digestive Model
* The simulation is managed as a state machine, governed by the `GastricState` enum. The stomach
* transitions through these states based on its contents and time:
* - `EMPTY`: No contents.
* - `FILLING`: Food is being added (via `addSubstance()`).
* - `DIGESTING`: Contents are being mixed and broken down, and pH is lowered.
* - `EMPTYING`: Chyme is being passed to the intestines.
*
* The contents themselves are modeled by the `Chyme` struct, which tracks volume and acidity.
* The `update()` method drives the state transitions and simulates the secretion of gastric
* juices and the emptying process.
*
* @subsection gastric_state_diagram_sec Gastric State Diagram
* The following diagram illustrates the transitions between the stomach's digestive states.
*
* @dot
* digraph GastricStates {
* rankdir="TB";
* node [shape=box, style=rounded];
*
* EMPTY -> FILLING [label="addSubstance()"];
* FILLING -> DIGESTING [label="update()"];
* DIGESTING -> EMPTYING [label="update() over time"];
* EMPTYING -> EMPTY [label="volume = 0"];
* }
* @enddot
*
* @section usage_sec Example Usage
* The following C++ code shows how to add food to the stomach and observe the resulting
* changes in its state and volume.
*
* @code{.cpp}
* #include <iostream>
* #include "MedicalLib/Stomach.h"
* #include "MedicalLib/Patient.h"
*
* int main() {
* // A patient object is needed for the update function
* Patient patient;
*
* // Create a Stomach object
* Stomach stomach(1);
* std::cout << "Initial State: " << stomach.getSummary() << std::endl;
*
* // Add a meal
* std::cout << "\nEating a 500mL meal..." << std::endl;
* stomach.addSubstance(500.0);
* std::cout << "State after eating: " << stomach.getSummary() << std::endl;
*
* // Simulate digestion over time
* std::cout << "\nSimulating digestion for 30 minutes..." << std::endl;
* for (int i = 0; i < 30; ++i) {
* stomach.update(patient, 60.0); // Simulate 1 minute
* }
* std::cout << "State after 30 mins: " << stomach.getSummary() << std::endl;
*
* return 0;
* }
* @endcode
*/
class MEDICAL_LIB_API Stomach : public Organ {
public: