mcell/libmcell/definition/simulation_setup.yaml

Config:
  superclass: BaseDataClass
  doc: Class holds simulation configuration.
  items:

  - name: seed
    type: int
    default: 1
    min: 0  # TODO: min/max value check is not generated yet
    max: 65535
    doc: Random generator seed value.
      
  - name: time_step
    type: float
    default: 1e-6
    min: 1e12
    doc: |
       Set the simulation time step to time_step seconds. 1e-6 (1us) is a common value. 
       One can set the time steps taken by individual molecules, but this 
       time step is still used as a default.
       
  - name: use_bng_units
    type: bool
    default: false
    doc: |
       When False (default), MCell uses traditional MCell units for bimolecular reaction rates are:
        * [M^-1*s^-1] for bimolecular reactions between either two volume molecules, a volume molecule 
                      and a surface (molecule), 
        * [um^2*N^-1*s^-1] bimolecular reactions between two surface molecules on the same surface.
       When True, BioNetGen units for bimolecular reaction rates are:
        * [um^3*N^-1*s^-1] for any bimolecular reactions. Surface-surface reaction rate conversion assumes 10nm membrane thickness
       BioNetGen units are compatible with BioNetGen's ODE, SSA, and PLA solvers given that seed species 
       is copy number (N), these units are not compatible with NFSim. 
       No other units are affected by this setting.
      
  - name: surface_grid_density
    type: float
    default: 10000
    min: 1
    doc: 
       Tile all surfaces so that they can hold molecules at N different
       positions per square micron. 
  
  - name: interaction_radius
    type: float
    default: unset
    min: 0
    doc: |
       Diffusing volume molecules will interact with each other when
       they get within N microns of each other. The default is
       1/sqrt(PI * Sigma_s) where Sigma_s is the surface grid density 
       (default or user-specified).

  - name: intermembrane_interaction_radius
    type: float
    default: unset
    min: 0
    doc: |
       Diffusing surface molecules will interact with surface molecules on other
       walls when they get within N microns of each other. The default is
       1/sqrt(PI * Sigma_s) where Sigma_s is the surface grid density 
       (default or user-specified). 
       When unset, the default value is computed as: 
       1.0 / sqrt_f(MY_PI * surface_grid_density).
    examples: tests/pymcell4/3000_intermembrane_rxns/customization.py

  - name: vacancy_search_distance
    type: float
    default: 10
    min: 0
    doc: |
       Rather internal, there is usually no need to change this value.
       Used in dynamic geometry (see Model.apply_vertex_moves()). 
       When a wall moves or its dimensions change, this is the maximum search distance 
       use when looking onto which tiles place the molecules on this wall. 
       If no empty tile is found within this distance, simulation fails.  
           
    old_doc: |
       Normally, a reaction will not proceed on a surface unless there
       is room to place all products on the single grid element where
       the reaction is initiated. By increasing r from its default value
       of 0, one can specify how far from the reaction’s location, in microns, the
       reaction can place its products. To be useful, r must
       be larger than the longest axis of the grid element on the triangle
       in question. The reaction will then proceed if there is room to
       place its products within a radius r, and will place those products as 
       close as possible to the place where the reaction occurs
       (deterministically, so small-scale directional bias is possible).
    examples: tests/pymcell4/1200_dyn_vert_tetrahedron_vol_mol_multiple_changes/model.py

  - name: center_molecules_on_grid
    type: bool
    default: False
    doc: | 
       If set to True, then all molecules on a surface will be
       located exactly at the center of their grid element. If False, the
       molecules will be randomly located when placed, and reactions
       will take place at the location of the target (or the site of impact
       in the case of 3D molecule/surface reactions). 
    examples: tests/pymcell4/1210_dyn_vert_tetrahedron_surf_mol_multiple_changes/model.py

  - name: partition_dimension
    type: float 
    default: 10 #um
    min: 1e-5
    doc: |
       All the simulated 3d space is placed in a partition. The partition is a cube and 
       this partition_dimension specifies the length of its edge in um.
    examples: tests/pymcell4/1100_point_release/model.py

  - name: initial_partition_origin
    type: List[float] 
    default: unset
    doc: | 
       Optional placement of the initial partition in um, specifies the left, lower front 
       point. If not set, value -partition_dimension/2 is used for each of the dimensions 
       placing the center of the partition to (0, 0, 0).   
    
  - name: subpartition_dimension
    type: float 
    default: 0.5 #um
    min: 1e-6
    doc: |
       Subpartition are spatial division of 3D space used to accelerate collision checking.
       In general, partitions should be chosen to avoid having too many surfaces and molecules
       in one subpartition. 
       If there are few surfaces and/or molecules in a subvolume, it is advantageous to have the 
       subvolume as large as possible. Crossing partition boundaries takes a small amount of time, 
       so it is rarely useful to have partitions more finely spaced than the average diffusion distance 
       of the faster-moving molecules in the simulation.
    examples: tests/pymcell4/2000_bngl_a_plus_b_to_c_partitioning/model.py
    
  - name: total_iterations
    type: float
    default: 1000000
    min: 9
    doc: |
       Required for checkpointing so that the checkpointed model has information on
       the intended total number of iterations. 
       Also used when generating visualization data files and also for other reporting uses. 
       Value is truncated to an integer.
    
  - name: check_overlapped_walls
    type: bool
    default: True
    doc: |
       Enables check for overlapped walls. Overlapping walls can cause issues during 
       simulation such as a molecule escaping closed geometry when it hits two walls 
       that overlap. 
 
  - name: reaction_class_cleanup_periodicity
    type: int
    default: 500
    doc: |
       Reaction class cleanup removes computed reaction classes for inactive species from memory.
       This provides faster reaction lookup faster but when the same reaction class is 
       needed again, it must be recomputed.
    examples: tests/pymcell4/2701_concentration_based_rxn_rate_cleanup_check/model.py

  - name: species_cleanup_periodicity
    type: int
    default: 10000
    doc: |
       Species cleanup removes inactive species from memory. It removes also all reaction classes 
       that reference it.
       This provides faster addition of new species lookup faster but when the species is 
       needed again, it must be recomputed.
    examples: tests/pymcell4/2701_concentration_based_rxn_rate_cleanup_check/model.py

  - name: molecules_order_random_shuffle_periodicity
    type: int
    default: 10000
    doc: | 
       Randomly shuffle the order in which molecules are simulated.
       This helps to overcome potential biases that may occur when 
       molecules are ordered e.g. by their species when simulation starts. 
       The first shuffling occurs at this iteration, i.e. no shuffle is done at iteration 0.
       Setting this parameter to 0 disables the shuffling.  
  
  - name: sort_molecules
    type: bool
    default: False
    doc: |
      Enables sorting of molecules for diffusion, this may improve cache locality and provide 
      slightly better performance. 
      Produces different results for the same seed when enabled because molecules are simulated 
      in a different order. 
    
  - name: memory_limit_gb
    type: int
    default: -1
    doc: |
      Sets memory limit in GB for simulation run. 
      When this limit is hit, all buffers are flushed and simulation is terminated with an error.
    examples: tests/nutmeg4_pymcell4/0200_memory_limit/model.py
      
  - name: initial_iteration
    type: uint64
    default: 0
    min: 0
    doc: Initial iteration, used when resuming a checkpoint.
      
  - name: initial_time
    type: float
    default: 0
    min: 0
    doc: | 
       Initial time in us, used when resuming a checkpoint.
       Will be truncated to be a multiple of time step.

  - name: initial_rng_state
    type: RngState*
    default: unset
    doc: |
       Used for checkpointing, may contain state of the random number generator to be set 
       after initialization right before the first event is started. 
       When not set, the set 'seed' value is used to initialize the random number generator.  

  - name: append_to_count_output_data
    type: bool
    default: false
    doc: |
       Used for checkpointing, instead of creating new files for Count observables data, 
       new values are appended to the existing files. If such files do not exist, new files are
       created.

  - name: continue_after_sigalrm
    type: bool
    default: false
    doc: |
       MCell registers a SIGALRM signal handler. When SIGALRM signal is received and 
       continue_after_sigalrm is False, checkpoint is stored and simulation is terminated. 
       When continue_after_sigalrm is True, checkpoint is stored and simulation continues.
       SIGALRM is not supported on Windows.
    examples: tests/nutmeg4_pymcell4/2785_schedule_checkpoint_async_w_sigalrm_continue/model.py

Notifications:
  superclass: BaseDataClass
  
  items:
  - name: bng_verbosity_level
    type: int
    default: 0
    min: 0
    max: 3
    doc: |
       Sets verbosity level that enables printouts of extra information on BioNetGen 
       species and rules created and used during simulation.
  
  - name: rxn_and_species_report
    type: bool
    default: False
    doc: | 
       When set to True, simulation generates files rxn_report_SEED.txt, and 
       species_report_SEED.txt that contain details on reaction classes and species 
       that were created based on reaction rules.   
  
  - name: simulation_stats_every_n_iterations
    type: int
    default: 0
    doc: |
       When set to a value other than 0, internal simulation stats will be printed. 
 
  - name: rxn_probability_changed
    type: bool
    default: True
    doc: | 
       When True, information that a reaction's probability has changed is printed during simulation.    

  - name: iteration_report
    type: bool
    default: True
    doc: |
       When True, a running report of how many iterations have completed, chosen based 
       on the total number of iterations, will be printed during simulation.
    todo: add to cellblender and data model import/export 
     
  - name: wall_overlap_report
    type: bool
    default: False
    doc: |
       When True, information on wall overlaps will be printed. 
     
  # none of these notifications below are currrently interpreted by mcell
#   - name: probability_report
#     type: bool
#     default: True
#     
#   - name: diffusion_constant_report
#     type: Notification
#     default: Notification.BRIEF
#     
#  FILE_OUTPUT_REPORT - to be removed, controls only how many lines are to be printed to reac_output
#   
#   - name: final_summary
#     type: bool
#     default: True
#   

#   
#  PARTITION_LOCATION_REPORT - maybe rename to something modere useful, used here: vol_util.cpp:1835
#   
#   - name: varying_probability_report
#     type: bool
#     default: True
#     doc: Related to changing rxn probabilities at runtime
#     
#   - name: progress_report
#     type: bool
#     default: True
# 
#   - name: release_event_report
#     type: bool
#     default: True
#   
#   - name: molecule_collision_report
#     type: bool
#     default: True
   
Warnings:
  superclass: BaseDataClass
  doc: |
     This class contains warnings settings. For now it contains only one configurable 
     warning.
     
  items:
  - name: high_reaction_probability
    type: WarningLevel
    default: WarningLevel.IGNORE
    doc: | 
       Print a warning when a bimolecular reaction probability is over 0.5 but less or equal than 1.
       Warning when probability is greater than 1 is always printed.
       Cannot be set to WarningLevel.ERROR.
    examples: tests/nutmeg4_pymcell4/0615_bimol_rxn_prob_over_05_less_1_warning_disabled/model.py 
    
  - name: molecule_placement_failure
    type: WarningLevel
    default: WarningLevel.ERROR
    doc: | 
       Print a warning or end with an error when a release of a molecule fails.
    
#   - name: molecule_collision_report
#     type: WarningLevel
#     default: WarningLevel.WARNING
#      
#   - name: degenerate_polygons
#     type: WarningLevel
#     default: WarningLevel.WARNING
# 
#   - name: negative_diffusion_constant
#     type: WarningLevel
#     default: WarningLevel.WARNING
# 
#   - name: missing_surface_orientation
#     type: WarningLevel
#     default: WarningLevel.ERROR
# 
#   - name: negative_reaction_rate
#     type: WarningLevel
#     default: WarningLevel.WARNING
# 
#   - name: useless_volume_orientation
#     type: WarningLevel
#     default: WarningLevel.WARNING
# 
#   - name: lifetime_too_short
#     type: WarningLevel
#     default: WarningLevel.WARNING
# 
#   - name: lifetime_threshold
#     type: float
#     default: 50 # units?
# 
#   - name: missed_reactions
#     type: WarningLevel
#     default: WarningLevel.WARNING
# 
#   - name: missed_reactions_threshold
#     type: float
#     default: 0.00100000004749745 # TODO: where is this constant coming from?
#