Design and Layout - illinoistech-itm/py-mgipsim GitHub Wiki

Quick overview

Scenario

A scenario is a unique descriptor of a simulation. Outside of the simulator a scenario is described in a JSON file. At the end of each simulation the scenario is exported and can be reused later to make a simulation reproducable. The core element of the simulator is the scenario JSON file/class. Between the class and the file there is a one-to-one mapping, all the fields in the file are mirrored as the scenario class attributes. For the detailed description of the fields in the scenario please refer to the Scenario class.

Simulation given a defined scenario

  1. If a scenario object contains all the necessary information for a successful simulation, it can be passed to VirtualCohort class to a initialize a virtual cohort object.
  2. The VirtualCohort class (during init) will:
    1. initialize a model object by calling the from_scenario function of the model that was defined in the scenario objects.
    2. The from_scenario function of the model initializes the model given the information in the scenario (e.g. input variables, patient model parameters, time sequence).
    3. The initialized model and the scenario object is passed to a ModelSolver class.
  3. The preprocessing function of the model object, nested in the model solver object, nested in the virtual cohort object has to be called.
  4. The do_simulation function of the virtual cohort object can be called to run the simulation.

Building blocks

Time-series signal

Any time-series signal is represented in the signal class. For instances, input variables of the models are signals. It holds:

  • Time, a np.array that defines the sequence of time instances (minutes) at which the signal will sampled.
  • Sampling time (minutes).
  • Attributes of an event object.

Event class represents a time-series signal before sampling it by holding the following variables:

  • Magnitudes np.array (unit of the signal)
  • Start times np.array (minutes)
  • Durations np.array (minutes), if undefined zero order hold will be assumed during the sampling process. If defined, the energy (value in the magnitude variable) will be distributed equally.

(Abstract) model

All models have the following attributes:

  • Inputs, holds the input variables. (The inputs class itself are model specific but all of them are a container of signal attributes).
  • States, holds the state variables (The states class itself are model specific but all of them are a container of signal attributes).
  • Parameters, holds the parameters of the model.
  • Time, same as the time attribute of any of the input variables.
  • Sampling time, as as the sampling time attribute of any of the input variables.

Both inputs, states and parameters have a common function as_array that returns the input variables, state variables or parameters as a np.array.

All models have a model function that defines the differential equations.