Physiology Engine Interface

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.

std::unique_ptr<PhysiologyEngine> bg = CreatePulseEngine("MyEngine.log");

Logging

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:

//--------------------------------------------------------------------------------------------------
/// \brief
/// Retrieve the Logger associated with this engine
//--------------------------------------------------------------------------------------------------
virtual Logger* GetLogger() = 0;

Initializing the Engine

There are two ways to initialize the engine once created.

Engine State

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.

//--------------------------------------------------------------------------------------------------
/// \brief
/// Reset engine and set it to the state in the provided file.
/// The file may contain json or binary. 
/// Anything but an extension of .json will be interpreted as binary.
/// Return value indicates engine was able to load provided state file.
/// Engine will be in a cleared state if this method fails.
//--------------------------------------------------------------------------------------------------
virtual bool SerializeFromFile(const std::string& file) = 0;
 
//--------------------------------------------------------------------------------------------------
/// \brief
/// Reset engine and set it to the state in the provided string.
/// The string can contain JSON or binary.
/// Note that a string of bytes are binary, not text; we only use the string class as a convenient container.
/// Return value indicates engine was able to load provided state file.
/// Engine will be in a cleared state if this method fails.
//--------------------------------------------------------------------------------------------------
virtual bool SerializeFromString(const std::string& state, SerializationFormat m) = 0;

At any point during the life of an engine, you create your own state object for later use.

//--------------------------------------------------------------------------------------------------
/// \brief
/// Save the current state of the engine to provided filename.
/// Using a .json extension will save a json/ascii file.
/// Anything else will save as binary.
//--------------------------------------------------------------------------------------------------
virtual bool SerializeToFile(const std::string& filename) const = 0;
 
//--------------------------------------------------------------------------------------------------
/// \brief
/// Reset engine and set it to the state in the provided string.
/// The string can contain JSON or binary.
/// Note that a string of bytes are binary, not text; we only use the string class as a convenient container.
/// Return value indicates engine was able to load provided state file.
 
//--------------------------------------------------------------------------------------------------
virtual bool SerializeFromString(const std::string& state, SerializationFormat m) = 0;

Patient Creation

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

//--------------------------------------------------------------------------------------------------
/// \brief
/// locates the xml patient file and reads in the values. 
///
/// This will create an engine that you can send instructions (patient,actions,conditions) to dynamically.
/// The return value will indicate success failure of the creation of the engine.  
/// Some combinations of patients and conditions may prevent the engine from stabilizing
///
//--------------------------------------------------------------------------------------------------
virtual bool InitializeEngine(const std::string& patientConfiguration, SerializationFormat m) = 0;
 
//--------------------------------------------------------------------------------------------------
/// \brief
///
/// This will create an engine that you can send instructions (patient,actions,conditions) to dynamically.
/// The return value will indicate success failure of the creation of the engine.  
/// Some combinations of patients and conditions may prevent the engine from stabilizing
///
//--------------------------------------------------------------------------------------------------
virtual bool InitializeEngine(const SEPatientConfiguration& patientConfiguration) = 0;

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.

Patient Conditions

• ARDS
• Chronic Anemia
• COPD
• Chronic Pericardial Effusion
• Chronic Renal Stenosis
• Consume Meal
• Impaired Alveolar Exchange
• Pneumonia
• Pulmonary Fibrosis
• Pulmonary Shunt
• Sepsis

Environment Conditions

Initial Environment

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.

//--------------------------------------------------------------------------------------------------
/// \brief
/// Get the Condition Manager.
/// Allows a user to check the state of active conditions
///
//--------------------------------------------------------------------------------------------------
virtual const SEConditionManager& GetConditionManager() const = 0;

Engine Configuration

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)

//--------------------------------------------------------------------------------------------------
/// \brief
/// Engines can have a configuration for allowing a user to set certain internal parameters
/// Engines with configurations will have all configuration parameters defaulted,
/// This allow you to change one or more or those parameters.
/// The parameters provided will be applied during SerializeFrom* and InitializeEngine methods.
/// Use with caution! (Use nullptr to revert back to using all engine defaults)
//--------------------------------------------------------------------------------------------------
virtual bool SetConfigurationOverride(const SEEngineConfiguration* config) = 0;

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)

//--------------------------------------------------------------------------------------------------
/// \brief
/// returns the engine configuration.   
//--------------------------------------------------------------------------------------------------
virtual const PhysiologyEngineConfiguration* GetConfiguration() = 0;

Data Tracking

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.

//--------------------------------------------------------------------------------------------------
/// \brief
/// Retrieve the PhysiologyEngineTrack associated with tracking data from this engine to a file
//--------------------------------------------------------------------------------------------------
virtual PhysiologyEngineTrack* GetEngineTrack() = 0;

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.

//--------------------------------------------------------------------------------------------------
/// \brief
/// executes one pass through the time loop of the engine at the fixed time step
///
/// Events, errors, and warning as are logged to file not errors are returned
/// through the API at this time. 
///
//--------------------------------------------------------------------------------------------------
virtual void AdvanceModelTime() = 0;
 
//--------------------------------------------------------------------------------------------------
/// \brief
/// executes one pass through the time loop of the engine at the fixed time step
///
/// Events, errors, and warning as are logged to file not errors are returned
/// through the API at this time. 
///
//--------------------------------------------------------------------------------------------------
virtual void AdvanceModelTime(double time, const TimeUnit& unit) = 0;

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:

//--------------------------------------------------------------------------------------------------
/// \brief
/// returns the engine time step that is used when advancing time. 
///
//--------------------------------------------------------------------------------------------------
virtual double GetTimeStep(const TimeUnit& unit) = 0;

You can retrieve the total amount of time the engine has simulated with the following call:

//--------------------------------------------------------------------------------------------------
/// \brief
/// returns the current time of the simulation.   
//--------------------------------------------------------------------------------------------------
virtual double GetSimulationTime(const TimeUnit& unit) = 0;

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.

//--------------------------------------------------------------------------------------------------
/// \brief
/// Set the current time of the simulation.
/// Engine Simulation time will be advanced from this time point
//--------------------------------------------------------------------------------------------------
virtual void SetSimulationTime(const SEScalarTime& time) = 0;

You can provide a callback object with the following call: The engine will call the method implementation after each time step.

//--------------------------------------------------------------------------------------------------
/// \brief
/// Add a callback object that will be called after each timestep
//--------------------------------------------------------------------------------------------------
virtual void SetAdvanceHandler(SEAdvanceHandler* handler) = 0;

Process Action

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.

//--------------------------------------------------------------------------------------------------
/// \brief
/// Execute the provided action.
/// true will be returned if the engine supports the action
/// false will be returned if the engine does not support the action
///
//--------------------------------------------------------------------------------------------------
virtual bool ProcessAction(const SEAction& action) = 0;

Patient Actions

• ARDS Exacerbation
• Acute Stress
• Airway Obstruction
• Arrhythmia
• Asthma Attack
• Brain Injury
• Bronchoconstriction
• Chest Compression
• Chest Compression Automated
• Chest Compression Instantaneous Scale
• Chest Occlusive Dressing
• Conscious Respiration
• Consume Nutrients
• COPD Exacerbation
• Conscious Respiration
• Consume Nutrients
• Dyspnea
• Exercise
• Hemorrhage
• Impaired Alveolar Exchange Exacerbation
• Intubation
• Pneumonia Exacerbation
• Mechanical Ventilation
• Needle Decompression
• Pericardial Effusion
• Pulmonary Shunt Exacerbation
• Respiratory Fatigue
• Respiratory Mechanics Configuration
• Substance Bolus
• Substance Compound Infusion
• Substance Infusion
• Supplemental Oxygen
• Tension Pneumothorax
• Urinate

Environment Actions

Environment Change
• Thermal Application

Anesthesia Machine Actions

• Anesthesia Machine Configuration
• Expiratory Valve Leak
• Expiratory Valve Obstruction
• Inspiratory Valve Leak
• Inspiratory Valve Obstruction
• Mask Leak
• Oxygen Tank Pressure Loss
• Oxygen Wall Port Pressure Loss
• SodaLime Failure
• Tube Cuff Leak
• Vaporizer Failure
• Ventilator Pressure Loss
• Y-Piece Disconnect

Bag Valve Mask Actions

• Bag Valve Mask Configuration
• Bag Valve Mask Automated
• Bag Valve Mask Instantaneous
• Bag Valve Mask Squeeze

Inhaler Actions

• Inhaler Configuration

Mechanical Ventilator Actions

• Mechanical Ventilator Configuration
• Mechanical Ventilator Hold
• Mechanical Ventilator Leak
• Mechanical Ventilator CPAP Mode
• Mechanical Ventilator Pressure Control Mode
• Mechanical Ventilator Volume Control Mode

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.

//--------------------------------------------------------------------------------------------------
/// \brief
/// Get the Action Manager.
/// Allows a user to check the state of active actions
///
//--------------------------------------------------------------------------------------------------
virtual const SEActionManager& GetActionManager() const = 0;

Patient State

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:

//--------------------------------------------------------------------------------------------------
/// \brief
/// Returns the initial simulation patient object used by the engine 
///
//--------------------------------------------------------------------------------------------------
virtual const SEPatient& GetInitialPatient() = 0;

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:

//--------------------------------------------------------------------------------------------------
/// \brief
/// Returns the patient object used by the engine 
///
//--------------------------------------------------------------------------------------------------
virtual const SEPatient& GetPatient() = 0;

Engine Events

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:

//--------------------------------------------------------------------------------------------------
/// \brief
/// Retrieves the associated event manager.
///
//--------------------------------------------------------------------------------------------------
virtual const SEEventManager& GetEventManager() const = 0;

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

Patient assessments are intended to give general patient overviews, formed at the level of a clinician's report. The following assessments are available :

• Complete Blood Count
• Comprehensive Metabolic Panel
• Urinalysis

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.

//--------------------------------------------------------------------------------------------------
/// \brief
/// Determines the assessment type and fills the data object with current data. 
///
/// Assessments can be queried at any point in the calculation and as many times are desired. 
///
//--------------------------------------------------------------------------------------------------
virtual bool GetPatientAssessment(SEPatientAssessment& assessment) = 0; 

Systems Data

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;	Environment
Equipment
virtual const SEAnesthesiaMachine* GetAnesthesiaMachine() = 0;	Anesthesia Machine
virtual const SEBagValveMaskSystem* GetBagValveMaskSystem() = 0;	BagValveMask
virtual const SEElectroCardioGram* GetElectroCardioGram() = 0;	ElectroCardioGram
virtual const SEInhaler* GetInhaler() = 0;	Inhaler
virtual const SEMechanicalVentilator* GetMechanicalVentilator() = 0;	MechanicalVentilator
Physiology
virtual const SEBloodChemistrySystem* GetBloodChemistrySystem() = 0;	BloodChemistry
virtual const SECardiovascularSystem* GetCardiovascularSystem() = 0;	Cardiovascular
virtual const SEEndocrineSystem* GetEndocrineSystem() = 0;	Endocrine
virtual const SEEnergySystem* GetEnergySystem() = 0;	Energy
virtual const SERenalSystem* GetRenalSystem() = 0;	Renal
virtual const SEGastrointestinalSystem* GetGastrointestinalSystem() = 0;	Gastrointestinal
virtual const SENervousSystem* GetNervousSystem() = 0;	Nervous
virtual const SERespiratorySystem* GetRespiratorySystem() = 0;	Respiratory
virtual const SEDrugSystem* GetDrugSystem() = 0;	Drug
virtual const SETissueSystem* GetTissueSystem() = 0;	Tissue

Compartments

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:

• Gas Compartment
• Liquid Compartment
• Thermal Compartment
• Tissue Compartment

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 :

• Heart
  • Myocardium
  • Right Heart
  • Left Heart
  • Pericardium

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

• Gas Substance Quantity
• Liquid Substance Quantity

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:

• Chyme
• Pulmonary
• Pulmonary(Aerosols)
• Tissue
• Extracellular
• Intracellular
• Vascular
• Urine
• Lymph
• Temperature
• Environment
• Anesthesia Machine
• Inhaler

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:

//--------------------------------------------------------------------------------------------------
/// \brief
/// Retrieves the engine compartments, providing such data as:
/// flows, pressure, volume as well as substance volumes and volume fractions.
///
//--------------------------------------------------------------------------------------------------
virtual const SECompartmentManager& GetCompartments() = 0;

Substances

Various Substances are available in the body and there is a SESubstanceManager associated with the engine.
You can retrieve the SESubstanceManager with this method:

//--------------------------------------------------------------------------------------------------
/// \brief
/// Retrieves the associated substance manager.
///
//--------------------------------------------------------------------------------------------------
virtual const SESubstanceManager& GetSubstanceManager() = 0;

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.