The following information is a method by method walk through of the PhysiologyEngine.h class that everything revolves around. Reading this in parallel with the HowTo-EngineUse.cpp provided in the SDK will give you a firm understanding of using the engine.
When you create an instance of an engine, you will be returned a pointer to a PhysiologyEngine object. This generic interface is the controlling class for a physiology engine modeling a single patient.
The Pulse Logger class can write messages from the engine to the console and/or a file. You can also provide a callback class to the logger for the engine to forward all logging events to your application so it can easily monitor the engine. The Logger class is used to specify the name of a file to write messages to. (An empty string will disable writing to file), You may also turn on and off writing of messages to the console.
It is highly recommended to create a log, and check it often. Many problems can be identified through the log. You can access the log at any time, the engine does not have to be initialized or have a state loaded.
For more details, please consult the HowTo-EngineUse.cpp file in the SDK. You can access and utilize this logger with in your own application as such:
Initializing the Engine
There are two ways to initialize the engine once created.
An engine state file is the exact state of the engine written into an file/string. Once loaded, the engine is instantly ready to process instructions. You can specify a file on disk, or the string contents of a state held in memory. The Pulse build can provide a set of state files for various patients at simulation time 0 located in the bin/states directory. When providing a state (from file or string) Pulse will not need to access any files on disk. All required data is provided in the state itself.
At any point during the life of an engine, you create your own state object for later use.
If you would like to create your own patient or apply a condition to a specific patient, you will need to initialize the engine with a patient definition. When creating a new patient state, Pulse need to access files on disk. You can specify the root directory containing these files in the provided SEPatientConfiguration object/string. More about files required by Pulse can be found on our wiki
When a patient definition is provided, the engine will go through an initialization algorithm that will take several minutes as to tune the engine to model the specific state requested of the patient. This initialization method is also the only way to specify any conditions (chronic/disease states). The following conditions are specified via the SEPatientConfiguration object.
Adding conditions to the patient configuration object will extend the initialization time by a few more minutes. Once the InitalizeEngine method returns, the engine is stabilize, and it is recommended to save the engine state for future use. (Assuming the patient vitals are acceptable, it may take some adjusting of condition severity to get a desired patient state with conditions applied.) The SDK provides multiple tested patient files for use in the bin/patients directory. For more information on this look at the Patient Methodology.
The engine configuration is used to tweek various variables associated in the engine methodology. Configuration modification requires a very in-depth knowledge of the engine. It is not recommended to provide another configuration unless you know what effects it will have. Note that if you provide a configuration, you can specify any number of configuration properties (1 or more). And only those specified values will be used to replace the default configuration values. There are some useful configuration options that you may want to change, such as writing data to a csv file while the initialization algorithm executes. Come visit us on the forums if this is something you want to know more about.
You can provide an engine configuration parameter to the engine via this method: (Note you will need to instantiate a PulseConfiguration object to pass to this method)
You can retrieve and view the configuration with this method: (note you will need to cast it to the PulseConfiguration class to see configuration data)
The engine has the ability to write specifically requested data to a comma seperated text file as the engine advances time. These csv file are very helpful in debugging and ensuring the engine is modeling correctly. How to utilize this functionality is demonstrated in all the HowTo files provided in the SDK.
Advancing The Simulation In Time
Once the engine is initialized, it is ready to accept direction. The engine does not advance time on its own, you must explicitly tell the engine to simulate a specific amount of time. It is recommended to not to pull data from or provide actions to the engine during simulation. It is the responsibility of the end user to ensure that a multi-threaded system adheres to this practice as the Pulse engine does not block I/O access during simulation. There is a HowTo example that shows how to encapsulate the engine in a thread class that automatically advances time and processes actions. How you decide to drive the simulation is up to you, but you must explicitly advance time in order for the models to simulate physiology.
If no time is provided, the engine will simulate for the smallest amount of time it can. The minimum amount of time the engine can simulate is the engines' time step, you can retrieve this duration with this method:
You can retrieve the total amount of time the engine has simulated with the following call:
Note that the simulation time is 0 when the InitializeEngine method returns.
You can set the simulation time of the engine with the following call: It will then be incremented from that point on whenever you call AdvanceModelTime.
You can provide a callback object with the following call: The engine will call the method implementation after each time step.
Actions are the means by which instructions are provided to a physiology engine. You will need to create an instance of an action class, fill it out with the necessary data and pass it into this method.
- Acute Stress
- ARDS Exacerbation
- Airway Obstruction
- Asthma Attack
- Brain Injury
- Cardiac Arrest
- Chest Compression Force
- Chest Compression Force Scale
- Chest Occlusive Dressing
- Conscious Respiration
- Consume Nutrients
- COPD Exacerbation
- Impaired Alveolar Exchange Exacerbation
- Lobar Pneumonia Exacerbation
- Mechanical Ventilation
- Needle Decompression
- Pericardial Effusion
- Pulmonary Shunt Exacerbation
- Respiratory Fatigue
- Substance Bolus
- Substance Compound Infusion
- Substance Infusion
- Supplemental Oxygen
- Tension Pneumothorax
Anesthesia Machine Actions
Mechanical Ventilator Actions
You can query the engine's action manager to get action information. For example, this may be useful to understand the current state of a infusion.
As the engine runs, it can change the patient settings. If you would like to get the original, stabilized healthy patient values, you can get the Initial Patient object via this method:
Once you start advancing time and processing actions, the patient state can start to change. Depending on what actions you process, it can change slightly, such as a slight increase weight or a change in a baseline value, such as the mean arterial pressure baseline.
You can get the Current Patient object via this method:
As the engine runs and depending on actions taken the engine can enter and exit various clinically based patient states that can affect multiple systems through various physiological feedback mechanisms. These dramatic changes in the engine are listed in our Engine Events Table.
You can access event states by getting the SEEventManager object with this method:
You can then gain access to events by either
- Polling the active events directly on the event manager
- Set up a callback method on the SEEventManager to notify you when the engine enters and exits any event.
Events are primarily associated with the patient, but there are events associated with Equipment.
Look at the SDK HowTo-UseEngine.cpp for a full example of using engine events.
Patient assessments are intended to give general patient overviews, formed at the level of a clinician's report. The following assessments are available :
You must create and provide an assessment object to the physiology engine via this method:
Note that assessments could add extra computation time to gather and format data for the assessment.
The bodies physiology, equipment, and the environment are all systems and each system has a method to retrieve its associated class in order to access this system data.
The engine supports the following systems:
|Code Method||CDM Table|
virtual const SEEnvironment* GetEnvironment() = 0;
virtual const SEBloodChemistrySystem* GetBloodChemistrySystem() = 0;
virtual const SECardiovascularSystem* GetCardiovascularSystem() = 0;
virtual const SEEndocrineSystem* GetEndocrineSystem() = 0;
virtual const SEEnergySystem* GetEnergySystem() = 0;
virtual const SERenalSystem* GetRenalSystem() = 0;
virtual const SEGastrointestinalSystem* GetGastrointestinalSystem() = 0;
virtual const SENervousSystem* GetNervousSystem() = 0;
virtual const SERespiratorySystem* GetRespiratorySystem() = 0;
virtual const SEDrugSystem* GetDrugSystem() = 0;
virtual const SETissueSystem* GetTissueSystem() = 0;
virtual const SEAnesthesiaMachine* GetAnesthesiaMachine() = 0;
virtual const SEElectroCardioGram* GetElectroCardioGram() = 0;
virtual const SEInhaler* GetInhaler() = 0;
virtual const SEMechanicalVentilator* GetMechanicalVentilator() = 0;
A compartment represents the fluid dynamics of an anatomical organ or equipment component. Compartments can represent various fidelities of data for these components, such as:
- An anatomical space, such as the body's skin, muscles
- An organ, such as the liver
- An organ substructure, such as the Left Heart
- Extravascular tissue of an organ
- A component of a piece of equipment, such as an anesthesia machine ventilator
The following compartment types are used to represent various anatomical structures for both physiology and equipment:
Various compartments can be used to represent a parent/child hierarchical structure, and compartments can be a parent for one or more child compartments. Parent compartments aggregate data from their children, such as the parent compartment volume is simply the sum of each of its childrens' volume.
For example, the heart has the following hierarchy :
- Right Heart
- Left Heart
Compartments also contain a substance quatity for each substance in the compartment as it moves through the body/equipment.
The following types are used to hold compartment substance information
The enumerations for compartments available is found in the PulsePhysiologyEngine.h file. As these are programmatic enumerations, you can use the auto-complete feature of your favorite programming IDE to view these enumerations as you code. The engine discretizes it's compartments into enumerations based on fluid type and equipment. Here is a list of the various enumerated compartment names:
As we make changes to models, some of the naming/hierarchy of compartments used could change, it's best to refer to the code file itself for the latest list of available compartments and their hierarchy.
Note that there are both liquid and gas compartments available for pulmonary spaces. The gas compartments represent the air flow and gaseous substances through the pulmonary tract. The liquid compartments represent the air flow and aerosolized liquid/solid substances through the pulmonary tract.
All compartments are accessed via the SECompartmentManager retrieved from this method:
Various Substances are available in the body and there is a SESubstanceManager associated with the engine.
You can retrieve the SESubstanceManager with this method:
In practice, only a substance reference are used with compartments to get the Substance Quantity object associated with a particular compartment. The data contained in the substance definition is primarily used in engine methodology, but there may be substance data you maybe interested in, such as the Partition Coefficient of a substance.