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? #