mcell/libmcell/definition/model.yaml

Model:
  superclasses: [Subsystem, Instantiation, Observables, Introspection]
  doc: |
     This is the main class that is used to assemble all simulation input 
     and configuration. It also provides methods to do initialization,
     run simulation, and introspect the running simulation.
  examples: tests/pymcell4/1400_rel_site_for_each_it/model.py
  items:
  - name: config
    type: Config
    default: Config()
    doc: Simulation configuration.

  - name: warnings
    type: Warnings
    default: Warnings()
    doc: Configuration on how to report warnings. 

  - name: notifications
    type: Notifications
    default: Notifications()
    doc: Configuration on how to report certain notifications.

  methods:
  - name: initialize
    doc: | 
      Initializes model, initialization blocks most of changes to 
      contained components. 
    params:
    - name: print_copyright
      type: bool
      default: True
      doc: Prints information about MCell.
      
  - name: run_iterations
    doc: | 
       Runs specified number of iterations. Returns the number of iterations
       executed (it might be less than the requested number of iterations when 
       a checkpoint was scheduled). 
    return_type: uint64
    params:
    - name: iterations
      type: float
      doc: Number of iterations to run. Value is truncated to an integer.

  - name: end_simulation
    doc: |
      Generates the last visualization and reaction output (if they are included 
      in the model), then flushes all buffers and optionally prints simulation report. 
      Buffers are also flushed when the Model object is destroyed such as when Ctrl-C
      is pressed during simulation.   
    params:
    - name: print_final_report
      type: bool
      default: True
      doc: Print information on simulation time and counts of selected events. 
      
  - name: add_subsystem
    doc: Adds all components of a Subsystem object to the model.
    params:
    - name: subsystem
      type: Subsystem*
      
  - name: add_instantiation
    doc: Adds all components of an Instantiation object to the model.
    params:
    - name: instantiation
      type: Instantiation*

  - name: add_observables
    doc: Adds all counts and viz outputs of an Observables object to the model.
    params:
    - name: observables
      type: Observables*
      
  - name: dump_internal_state
    doc: Prints out the simulation engine's internal state, mainly for debugging.
    params:      
    - name: with_geometry
      type: bool
      default: false
      doc: Include geometry in the dump.
          
  - name: export_data_model
    doc: | 
       Exports the current state of the model into a data model JSON format.
       Does not export state of molecules.
       Must be called after model initialization.
       Always exports the current state, i.e. with the current geometry and reaction rates. 
       Events (ReleaseSites and VizOutputs) with scheduled time other than zero are not exported correctly yet.  
    params: 
    - name: file
      type: str
      default: unset
      doc: | 
         If file is not set, then uses the first VizOutput to determine the target directory 
         and creates name using the current iteration. Fails if argument file is not set and 
         there is no VizOutput in the model.
        
  - name: export_viz_data_model
    doc: |
       Same as export_data_model, only the created data model will contain only information required for visualization
       in CellBlender. This makes the loading of the model by CellBlender faster and also allows to avoid potential
       compatibility issues.
       Must be called after model initialization.
    examples: tests/pymcell4_positive/1520_sphere_collision/model.py
    params: 
    - name: file
      type: str
      default: unset
      doc: Optional path to the output data model file. 

  - name: export_geometry
    doc: |
       Exports model geometry as Wavefront OBJ format. 
       Must be called after model initialization.
       Does not export material colors (yet).
    params: 
    - name: output_files_prefix
      type: str
      default: unset
      doc: | 
         Optional prefix for .obj and .mtl files that will be created on export. 
         If output_files_prefix is not set, then uses the first VizOutput to determine the target directory 
         and creates names using the current iteration. Fails if argument output_files_prefix is not set and 
         there is no VizOutput in the model.
     
  # --- state modification ---
  - name: release_molecules
    doc: | 
       Performs immediate release of molecules based on the definition of the release site argument.
       The ReleaseSite.release_time must not be in the past and must be within the current iteration 
       meaning that the time must be greater or equal iteration * time_step and less than (iteration + 1) * time_step.
       The ReleaseEvent must not use a release_pattern because this is an immediate release and it is not 
       scheduled into the global scheduler.
    examples: tests/pymcell4/2300_immediate_release/model.py
    params:
    - name: release_site
      type: ReleaseSite*
      
  - name: run_reaction
    doc: | 
      Run a single reaction on reactants. Callbacks will be called if they are registered for the given reaction.
      Returns a list of product IDs.
      Note\: only unimolecular reactions are currently supported.
    examples: tests/pymcell4_positive/1850_run_unimol_rxn_in_callback/model.py
    return_type: List[int]
    params:
    - name: reaction_rule
      type: ReactionRule*
      doc: Reaction rule to run.
      
    - name: reactant_ids
      type: List[int]
      doc: | 
        The number of reactants for a unimolecular reaction must be 1 and for a bimolecular reaction must be 2.
        Reactants for a bimolecular reaction do not have to be listed in the same order as in the reaction rule definition. 
    
    - name: time
      type: float
      doc: |
        Precise time in seconds when this reaction occurs. Important to know for how long the products
        will be diffused when they are created in a middle of a time step. 
      
  # --- dynamic geometry ---
      
  - name: add_vertex_move
    doc: |
       Appends information about a displacement for given object's vertex into an internal list of vertex moves. 
       To do the actual geometry change, call Model.apply_vertex_moves.
       The reason why we first need to collect all changes and then apply them all at the same time is for performance
       reasons. 
    examples: tests/pymcell4_positive/1510_tetrahedron_box_collision_moving_3_verts/model.py
    params: 
    - name: object
      type: GeometryObject*
      doc: Object whose vertex will be changed.
    - name: vertex_index
      type: int
      doc: Index of vertex in object's vertex list that will be changed.
    - name: displacement
      type: List[float]
      doc: |
        Change of vertex coordinates [x, y, z] (in um) that will be added to the current 
        coordinates of the vertex.
      
  - name: apply_vertex_moves
    doc: | 
       Applies all the vertex moves specified with Model.add_vertex_move call.
       
       All affected vertices are first divided based on to which geometery object they belong. 
       Then each object is manipulated one by one. 
       
       During vertex moves, collisions are checked\:
       a) When a moved vertex hits a wall of another object, it is stopped at the wall.
       b) When a second object's vertex would end up inside the moved object, the vertex move 
       that would cause it is canceled (its displacement set to 0) because finding the maximum 
       distance we can move is too computationally expensive. To minimize the impact of this 
       cancellation, the vertices should be moved only by a small distance.
       
       Applying vertex moves also takes paired molecules into account\: 
       When moves are applied to an object, all moved molecules that are paired are collected.
       For each of the paired molecules, we collect displacements for each 
       of the vertices of the 'primary' wall where this molecule is located (that were provided by the user 
       through add_vertex_move, and were possibly truncated due to collisions).
       Then we find the second wall where the second molecule of the pair is located.
       For each of the vertices of all 'secondary' walls, we collect a list of displacements
       that move the vertices of 'primary' walls. 
       Then, an average displacement is computed for each vertex, and these average displacements
       are used to move the 'secondary' walls.
       When a 'primary' wall collides, its displacement is clamped or canceled. This is true even if 
       it collides with a 'secondary' wall that would be otherwise moved. So, the displacement of the 
       'primary' wall will mostly just pull the 'secondary' wall, not push. Therefore it is needed 
       that both objects are active and pull each other. 
       
       This process is well commented in MCell code\: 
       `partition.cpp <https://github.com/mcellteam/mcell/blob/master/src4/partition.cpp>`_ in functions
       apply_vertex_moves, apply_vertex_moves_per_object, and move_walls_with_paired_molecules. 
            
       When argument collect_wall_wall_hits is True, a list of wall pairs that collided is returned,
       when collect_wall_wall_hits is False, an empty list is returned.
       
    examples: | 
       tests/pymcell4_positive/1510_tetrahedron_box_collision_moving_3_verts/model.py 
       tests/pymcell4/3200_sphere_collision_against_each_other/model.py
       tests/pymcell4/3150_dyn_vert_intramembrane_rxns_and_paired_mols/model.py
       
    return_type: List[WallWallHitInfo*]
    params:
    - name: collect_wall_wall_hits
      type: bool
      default: false
      doc: |
         When set to True, a list of wall pairs that collided is returned,
         otherwise an empty list is returned.
         
    - name: randomize_order
      type: bool
      default: true
      doc: |
          When set to True (default), the ordering of the vertex move list created by add_vertex_move
          calls is randomized. This allows to avoid any bias in the resulting positions of surface
          molecules.  
          However, the individual vertex moves are then sorted by the object to which the vertex belongs
          and the moves are applied object by object for correctness. Setting this to True also radomizes the 
          order of objects to which the vertex moves are applied.
  
  # --- molecule pairing (used by dynamic geometry) ---
  - name: pair_molecules
    doc: | 
       Sets that two surface molecules are paired. Paired molecules bind walls together
       and when one wall is moved, the wall that is bound through a paired molecule is moved as well.
       Throws exception if the molecule ids are not surface molecules.
       Throws exception if the molecules are on the same object.  
       Throws exception if any of the molecules is already paired.
       May be called only after model initialization.
    examples: tests/nutmeg4_pymcell4/2900_pair_unpair_molecules/model.py tests/pymcell4_positive/3160_dyn_vert_paired_mols_box_box/model.py
    params:  
    - name: id1
      type: int  
    - name: id2
      type: int  

  - name: unpair_molecules
    doc: | 
       Sets that two surface molecules are not paired. 
       Throws exception if the molecule ids are not surface molecules. 
       Throws exception if the molecules are not paired together.
       May be called only after model initialization.
    examples: tests/nutmeg4_pymcell4/2900_pair_unpair_molecules/model.py
    params:  
    - name: id1
      type: int  
    - name: id2
      type: int  
  
  - name: get_paired_molecule
    doc: |
       Return id of the molecule to which the molecule with 'id' is paired.
       Returns ID_INVALID (-1) when the molecule is not paired.
       May be called only after model initialization.
    examples: tests/nutmeg4_pymcell4/2900_pair_unpair_molecules/model.py
    return_type: int
    params:  
    - name: id
      type: int  
  
  - name: get_paired_molecules
    examples: tests/pymcell4_positive/3170_get_paired_molecules/model.py
    doc: |
       Returns a dictionary that contains all molecules that are paired.
       Molecule ids are keys and the value associated with the key is the second paired molecule.
       The returned dictionary is a copy and any changes made to it are ignored by MCell.
       Note\: The reason why uint32 is used as the base type for the dictionary but type int is used
       everywhere else for molecule ids is only for performance reasons. 
    return_type: Dict[uint32, uint32]
  
  # --- callbacks ---
  
  - name: register_mol_wall_hit_callback
    doc: |
       Register a callback for event when a molecule hits a wall. 
       May be called only after model initialization because it internally uses geometry object
       and species ids that are set during the initialization. 
       
    examples: tests/pymcell4_positive/1300_wall_hit_callback/model.py
           
    params:
    - name: function
      type: std::function<void(std::shared_ptr<MolWallHitInfo>, py::object)>
      doc: | 
         Callback function to be called. 
         The function must have two arguments MolWallHitInfo and context.
         Do not modify the received MolWallHitInfo object since it may be reused for other 
         wall hit callbacks (e.g. when the first callback is for a specific geometry object and 
         the second callback is for any geometry object). 
         The context object (py::object type argument) is on the other hand provided 
         to be modified and one can for instance use it to count the number of hits.. 

    - name: context
      type: py::object
      doc: | 
         Context passed to the callback function, the callback function can store
         information to this object. Some context must be always passed, even when 
         it is a useless python object. 
     
    - name: object
      type: GeometryObject*
      default: unset
      doc: Only hits of this object will be reported, any object hit is reported when not set.
      internal: Extend this to Region later
      
    - name: species
      type: Species*
      default: unset
      doc: | 
         Only hits of molecules of this species will be reported, any hit of volume molecules of 
         any species is reported when this argument is not set.
         Sets an internal flag for this species to make sure that the species id does not change 
         during simulation.           
      
  - name: register_reaction_callback
    doc: | 
       Defines a function to be called when a reaction was processed.
       It is allowed to do state modifications except for removing reacting molecules, 
       they will be removed automatically after return from this callback. 
       Unlimited number of reaction callbacks is allowed. 
       May be called only after model initialization because it internally uses 
       reaction rule ids that are set during the initialization. 
       
    examples: tests/pymcell4_positive/1800_vol_rxn_callback/model.py    
    params: 
    - name: function
      type: std::function<bool(std::shared_ptr<ReactionInfo>, py::object)>
      doc: | 
         Callback function to be called. 
         The function must have two arguments ReactionInfo and context.
         Called right after a reaction occured but before the reactants were removed.
         It is also allowed to return a boolean value from the callbck function.
         If False or None is returned the reaction proceeds and reactants are removed 
         (unless they were kept by the reaction such as with reaction A + B -> A + C).
         If True is returned, the reaction is cancelled, reactants are kept and products 
         are removed.         
         No return is needed in the callback function since Python 
         automatically returns None that is cast to False.
         
    - name: context
      type: py::object
      doc: | 
         Context passed to the callback function, the callback function can store
         information to this object. Some context must be always passed, even when 
         it is a useless python object. 
      internal: |
         In the future, One may set attributes of ReactionInfo to say how the reaction should proceed. 
         If unchanged, reaction proceeds as it woudl without this callback. 
         
    - name: reaction_rule
      type: ReactionRule*
      doc: The callback function will be called whenever this reaction rule is applied.
      internal: maybe also add filtering by species
  
  # --- other ---
  
  - name: load_bngl
    doc: | 
      Loads sections\: molecule types, reaction rules, seed species, and observables from a BNGL file
      and creates objects in the current model according to it.
      All elementary molecule types used in the seed species section must be defined in subsystem.
      If an item in the seed species section does not have its compartment set,
      the argument default_region must be set and the molecules are released into or onto the 
      default_region. 
    examples: pymcell4/1400_rel_site_for_each_it/model.py
    params:
    - name: file_name
      type: str  
      doc: Path to the BNGL file to be loaded.
      
    - name: observables_path_or_file
      type: str
      default: unset
      doc: |
         Directory prefix or file name where observable values will be stored.
         If a directory such as './react_data/seed_' + str(SEED).zfill(5) + '/' or an empty 
         string/unset is used, each observable gets its own file and the output file format for created Count 
         objects is CountOutputFormat.DAT.
         When not set, this path is used: './react_data/seed_' + str(model.config.seed).zfill(5) + '/'.
         If a file has a .gdat extension such as 
         './react_data/seed_' + str(SEED).zfill(5) + '/counts.gdat', all observable are stored in this 
         file and the output file format for created Count objects is CountOutputFormat.GDAT.
         Must not be empty when observables_output_format is explicitly set to CountOutputFormat.GDAT.
      
    - name: default_release_region
      type: Region*
      default: unset
      doc: | 
         Used as region for releases for seed species that have no compartments specified.
      
    - name: parameter_overrides
      type: Dict[str, float]
      default: empty
      doc: |
         For each key k in the parameter_overrides, if it is defined in the BNGL's parameters section,
         its value is ignored and instead value parameter_overrides[k] is used.

    - name: observables_output_format
      type: CountOutputFormat
      default: CountOutputFormat.AUTOMATIC_FROM_EXTENSION
      doc: |
         Selection of output format. Default setting uses automatic detection
         based on contents of the 'observables_path_or_file' attribute.
      
  - name: export_to_bngl
    doc: |
      Exports all defined species, reaction rules and applicable observables
      as a BNGL file that can be then loaded by MCell4 or BioNetGen. 
      The resulting file should be validated that it produces expected results. 
      Many MCell features cannot be exported into BNGL and when such a feature is 
      encountered the export fails with a RuntimeError exception.
      However, the export code tries to export as much as possible and one can catch
      the RuntimeError exception and use the possibly incomplete BNGL file anyway.   
      
    params:
    - name: file_name
      type: str
      doc: Output file name.
      
    - name: simulation_method
      type: BNGSimulationMethod
      default: BNGSimulationMethod.ODE
      doc: |
         Selection of the BioNetGen simulation method. 
         Selects BioNetGen action to run with the selected simulation method.
         For BNGSimulationMethod.NF the export is limited to a single volume and
         a single surface and the enerated rates use volume and surface area so that 
         simulation with NFSim produces corect results. 
      
  - name: save_checkpoint
    todo: provide more configurability for parameters
    doc: |
       Saves current model state as checkpoint. 
       The default directory structure is checkpoints/seed_<SEED>/it_<ITERATION>,
       it can be changed by setting 'custom_dir'.
       If used during an iteration such as in a callback, an event is scheduled for the  
       beginning of the next iteration. This scheduled event saves the checkpoint.  
    examples: tests/pymcell4_positive/2700_save_checkpoint_rxn_in_box/model.py
    params:
    - name: custom_dir
      type: str
      default: unset
      doc: |
         Sets custom directory where the checkpoint will be stored. 
         The default is 'checkpoints/seed_<SEED>/it_<ITERATION>'. 

  - name: schedule_checkpoint
    todo: provide more configurability for parameters
    doc: |
       Schedules checkpoint save event that will occur when an iteration is started.  
       This means that it will be executed right before any other events scheduled for 
       the given iteration are executed.
       Can be called asynchronously at any time after initialization.
    examples: tests/nutmeg4_pymcell4/2760_schedule_checkpoint_async_w_timer/model.py
    params:
    - name: iteration
      type: uint64
      default: 0
      todo: shouldn't we specify simulated time instead?
      doc: |
        Specifies iteration number when the checkpoint save will occur. 
        Please note that iterations are counted from 0.
        To schedule a checkpoint for the closest time as possible, keep the default value 0,
        this will schedule checkpoint for the beginning of the iteration with number current iteration + 1.  
        If calling schedule_checkpoint from a different thread (e.g. by using threading.Timer), 
        it is highly recommended to keep the default value 0 or choose some time that will be 
        for sure in the future.
    
    - name: continue_simulation
      type: bool
      default: false
      doc: |
        When false, saving the checkpoint means that we want to terminate the simulation 
        right after the save. The currently running function Model.run_iterations
        will not simulate any following iterations and execution will return from this function
        to execute the next statement which is usually 'model.end_simulation()'.
        When true, the checkpoint is saved and simulation continues uninterrupted.
              
    - name: custom_dir
      type: str
      default: unset
      doc: |
         Sets custom directory where the checkpoint will be stored. 
         The default is 'checkpoints/seed_<SEED>/it_<ITERATION>'.