Biogears IO Library

#Introduction Traditionally BioGears has required a number of runtime files in order to properly function. These files include XML Schema Definition files, and Material and Data definitions including Patients, Scenarios, Substances, and Environments. When BioGears is embedded in IoT hardware or included as part of a larger project like a Unity or Unreal Game. It can be difficult for the downstream development team to properly bundle and deploy these files on the device in a way BioGears understands. For this reason we know offer a libiogears_io dynamic library which can seralize these files as binary and embedded the as part of the BioGears library itself. Obviously, this comes with a large memory cost when loading these libraries so the use of it is optional at compile time, but on by default for simplicity. This documentation runs through the types of files we embedded how to modify, remove, or add additional files in addition to how to toggle this functionality off.

CMAKE Controls

Name	Default	Note
Biogears_BUILD_IO_LIBRARY	ON	Toggles the existence of libbiogears_io. All functionality for this library is stripped when it is set to off.
Biogears_IO_INCLUDE_DATA_TEMPLATES	OFF	Embedded CSV files that contain the source values for supported data files. Mostly used for offical Biogears releases to allow bg-cli to generate a complete runtime directory.
Biogears_IO_INCLUDE_SCENARIOS	OFF	Includes all Scenario files known at compile time files are generally smaller then state files, but by default arbitrary and not needed. This option is very useful for library embedding as developers can replace the default scenarios with implementation specific ones.
Biogears_IO_INCLUDE_STATES	OFF	Includes All State files known at compile time state files are about 1.1M apiece so it greatly increases the size of the library and slows down initial generation.
Biogears_IO_USE_SHORT_TARGET_NAMES	OFF	Changes the Target Names for IO Embedding to a less human friendly name which may have name collisions. This is intended to assist windows developers dealing with PATH and FILENAME length limitations and is safe to use as of 2022-03-18, but is not tested daily.

How this works.

Embedded files are in <root>/share/data and <root>/share/Scenarios. They represent the standard files for a release of BioGears. All files found at the time CMake is invoked will be recorded and included for embedding. You are free to remove, modify, or add additional files to the shared space but it is important to know that BioGears does expect a subset of substances to exist at standup and must have access either physically or through embedding to the xsd files needed to validate all input XML files as our XML reader does not have network based validation support as of BioGears 7.X.

Can I add files

You are free to add as many data files to the embedding as you need. Incorporation to the library is mostly automatic and you simply need to play the file in the correct folder and rerun CMake configure.

Can I remove files

Patient, State, and Scenario files are easily removed and modified. Substance, Environment, and XSD files can be modified if care is taken, but only expert BioGears users should remove these files as it can cause issues at runtime if key files are missing.

Will my modifications be recorded

Each time you build BioGears it will HAS the known data files and if any changes were made it will embedded the modified files for that build.

Biogears Data Files

Data Files are source from files in /share/data, /share/Scenarios and /share/XSD. At compile time these files are embedded in to individual files which can be access through the biogears::io-mnager class and are categorized based on the following table.

Category	Path	Required	Default	Note
Config	share/data/config	Yes	DynamicStabiliztion.xml	Combination of bg-cli and libBioGears configuration files. DynamicStabilization.xml, TimedStabilization.xml are required at runtime.
EGC	share/data/ecg	Yes	StandardECG.xml	Array Constants for Sinus wave forms. An ECG is required.
Environments	share/data/environments	Yes	StandardEnvironment.xml	Custom Environments for the atmospheric conditions for the simulation. At least one environment must be present.
Nutrition	share/data/neutrition	No	--	Optional Meal definition files for the Patient Neutrition Action.
Override	share/data/override	No	--	List over override parameters when patient override action is true.
Patients	share/data/patients	No	DefaultMake.xml	Patient definition files for initial simulation inputs prior to stabilization. Most scenarios refer to a patient file or state by path relative to the runtime directory, but inline patients are allowed in XML and API.
States	share/data/states	No	--	Serialized patients from any time in a simulation after stabilization. BioGears releases include all known patients in stabilized form by default, but any state could be added and removed from this list. Embedded implementations are encouraged to generate states used for there exercises and embedded them to allow skipping of stabilization.
Substances	share/data/substances	Yes	Several	List of substances tracked in biogears, water, saline, morphine, blood, ... Multiple substances are required for stabilization to complete, but any substances can be tracked and infused in Bio gears for testing. Folder also includes Compound Substance definition for mixtures which can consist of various concentrations of known substances.
Templates	share/data/templates	No	--	List of development files for generating default substances list. These files are use by bg-cli GENDATA
Scenarios	share/Scenarios	No	--	Pre scripted Biogears timelines that allow the registering of data sources and scenario actions. This is the primary way of using BioGears for cli users. However, the C++ api allows for immediate mode operations
XSD	share/xsd	YES	ALL	These files are the XML schema files that allow BioGears to validate XML input files and throw reasonable error messages. If you remove all other files from the IO library it is just easier if you leave these.

• Required Files are needed in some form at startup

Data Files

share/data/
├──  BioGearsConfiguration.xml
├──  OverrideConfig.xml
├──  PopulationTemplate.xml
├──  config/
├──  docs/
├──  ecg/
├──  environments/
├──  nutrition/
├──  override/
├──  patients/
├──  states/
├──  substances/
├──  templates/
└──  validation/

Scenario Files

share/Scenarios/
├──  AnesthesiaMachine/
├──  Burncare/
├──  BurncareStates/
├──  Combined/
├──  Compartments/
├──  ConsumeMeal/
├──  Drug/
├──  EnergyEnvironment/
├──  EngineState.xml
├──  InitialPatientState.xml
├──  InitialPatientStateAll.xml
├──  Miscellaneous/
├──  OverrideTest.xml
├──  Patient/
├──  Showcase/
└──  Validation/

#XSD Files

../share/xsd/
├── BioGearsDataModel.xsd
├── CommonDataModel.xsd
├── biogears/
└── cdm/

IO Manager

Io Manager is the IO Abstraction library which searches for Biogears files based on the presense of libbiogears_io and the operating system present. The manager has multiple fallback routines the following list is intended to document possible locations BioGears will search for files

1. Relative/Absolute File Path Given
2. ENV{BIOGEARS_DATA_ROOT} + Given
3. ENV{BIOGEARS_SCHEMA_ROOT} + given
4. On WIN32 ENV{APPDATA}\biogears\
5. On WIN32 ENV{HOMEPATH},biogears\
6. On *NIX ~/.biogears/
7. The Value of CMAKE_INSTALL_PREFIX at compile time
8. For packages installed using MSI,DMG the default installer directory (until we can make this dynamic)
9. libBiogearsIO by Given

When All other fallback routines failed. BioGears will search each embedded directory using a key/value map where the key is the path relative to the embedding folder and the file name for instance ecg\standardECG.xml this search is case sensitive and care should be taken when testing it to ensure the correct casing is known. Weather BioGears finds a file or returns the embedding a char array of the entire file is passed to the IO processing library. Theoretically this could have an impact on exceptionally large scenario files, but is almost a non issue on any modern hardware.