Skip to content

Model Architecture#

Table of Contents#

Main classes#

We have already mentioned the hierarchy of the four most important classes which, ffrom the point of view of function, could be expressed as: Model > Simulation > Experiment > Engine.

  • Model class expresses the model specification, most important part of which is passed throught the parameters initial_state, state_update_blocks=state_update_blocks, params. Below is an example of an instance from the Model class:
model = Model(initial_state=initial_state, 
              state_update_blocks=state_update_blocks, 
              params=params)
  • Simulation is a class used for simulating a Model. It extends the class Executable and contains nan implemetnation of the method run, most other elements are inherited from the class Executable. Example of initiating the simulation:
simulation = Simulation(model=model, timesteps=100_000, runs=1)

result = simulation.run()
df = pd.DataFrame(result)
  • Experiment consists of one or more Simulation snd is sldo an extension of the class Executable. Example of initiating an experiment consisting of one or more of Simulation:
experiment = Experiment([simulation_1, simulation_2, simulation_3])
result = experiment.run()

df = pd.DataFrame(result)
  • Engine - class that handles configuration and execution of experiments and simulations. It is a method first defined for the class Executable and then inherited by classes Simulation and Experiment.

Additional Classes#

Configuration#

  • SimulationExecutionSpecification - a data class that prepares some of the elements of simulation specification that are common for most experiments, in particular the organisation into blocks, steps and substeps.
  • SimulationExecution - extends SimulationExecutionSpecification and defines various properties and functions needed to execute the simulation.
  • Executable - instances of class Executable contain all information about the model specification and simulation configuration and can be passed to either Simulation (for a single simulation) or to Experiment (for multiple simulations). E contains a method run which is not implemented, as that implementation takes place at the level of either Simulation or Experiment.

Serial or Parallel Processes#

All the classes below extend the Executor and provide an implementation of the execute_runs method. Refer to Selecting single or multi-process modes.

  • ExecutorSingleProcess - simulation will be executed using single (serial) process
  • ExecutorMultiprocessing - simulation will be executed using multiple processes with multiprocessing library, the number of parallel processes used is set up to the number of system CPUs less one
  • ExecutorPathos - simulation will be executed using multiple processes; Pathos re-writes the core code in Python rather than C, for ease of maintenance at cost of performance, see: pathos.multiprocessing
  • ExecutorRay - multiprocessing backend based on Ray, run locally.
  • ExecutorRayRemote - multiprocessing backend based on Ray, run remotely.

Helper classes#

  • Dataclass - used to ascertain that something is a dataclass from module dataclasses,
  • Context - mutable context passed to simulation hooks.
  • Backend - codes which backend to use, current options: single process, multiprocessing, Pathos, Ray and Ray remote, with Pathos being the default.
  • Executor - class that defines the template for executing runs, but itself doesn't provide any implementation for the backend run execution, see: Single or Parallel Process.

Extensions#

For cadCAD compatibility mode:#

In radcad/compat/cadCAD/engine the class Executor is used to extend the cadCAD class Executor from cadcad/engine. Jump here to read more about the cadCAD compatibility mode.

For remote cluster execution (using Ray)#

In radcad/extensions/backends the classes ExecutorRay and ExecutorRayRemote are used to extend the standard radCAD class Executor. Jump here to read more about using the remote cluster execution.

All modules, automated documentation#

radCAD model model software architecture (structural and configuration modules)

In this package:

  • core - data classes for simulation configuration (SimulationExecutionSpecification, SimulationExecution)
  • engine - configuration and execution of experiments and simulations (engine)
  • types - helper functions for input/data processing Dataclass, Context
  • utils - various utility functions for data or variable processing
  • wrappers - the main classes needed to specify the model and simulation specification (Model, Executable, Simulation, Experiment)