VizOutput: superclass: BaseDataClass doc: | Defines a visualization output with locations of molecules that can be then loaded by CellBlender. examples: tests/pymcell4/1100_point_release/model.py items: - name: output_files_prefix type: str default: unset doc: | Prefix for the viz output files. When not set, the default prefix value is computed from the simulation seed when the model is initialized to\: './viz_data/seed_' + str(seed).zfill(5) + '/Scene'. - name: species_list type: List[Species*] default: empty doc: Specifies a list of species to be visualized, when empty, all_species will be generated. TODO: | This should be a list of BNGL patterns to be consistent with Counts, but this feature is rarely used so for now those must be defined species. - name: mode type: VizMode default: VizMode.ASCII doc: | Specified the output format of the visualization files. VizMode.ASCII is a readable representation, VizMode.CELLBLENDER is a binary representation that cannot be read using a text editor but is faster to generate. - name: every_n_timesteps type: float default: 1 doc: | Specifies periodicity of visualization output. Value is truncated (floored) to an integer. Value 0 means that the viz output is ran only once at iteration 0. CountTerm: superclass: BaseDataClass doc: | A count observable can be defined as an expression composed of addition or subtraction individual count terms. This class represents one count term in this expression. items: - name: species_pattern type: Complex* default: unset doc: | Count the number of molecules that match the given complex instance pattern. This corresponds to the BNGL 'Species' specifier in the BNGL seed species section. Counts each molecule exactly once. If the pattern has a compartment set, this specifies the counted region. Exactly one of species_pattern, molecules_pattern, and reaction_rule must be set. - name: molecules_pattern type: Complex* default: unset doc: | Count the number of matches of the given pattern on molecules. This corresponds to the BNGL 'Molecules' specifier in the BNGL seed species section. The observable will increment the count every time the pattern matches the molecule. For instance, pattern A will match a complex A(a!1).B(a!1,a!2).A(b!2) twice. When the pattern is symmetric, e.g. as in A(a!1).A(a!1) then a molecule A(b.a!1).A(a!1,b!2).B(a!2) will be counted twice because the pattern may match in two different ways. If the pattern has a compartment set, the compartment is used to filter out the molecules. Exactly one of species_pattern, molecules_pattern, and reaction_rule must be set. - name: reaction_rule type: ReactionRule* default: unset doc: | Count the number of applications of this specific reactions that occurred since the start of the simulation. Exactly one of species_pattern, molecules_pattern, and reaction_rule must be set. - name: region type: Region* default: unset doc: | Only a GeometryObject or SurfaceRegion can be passed as the region argument, compound regions (created with +, -, *) are not supproted yet. Can be combined with a compartment specified in the species_pattern or molecules_pattern. If compartment in species_pattern or molecules_pattern is not specified and region is left unset, counting is done in the whole world. - name: node_type type: ExprNodeType default: ExprNodeType.LEAF doc: Internal, used to specify what type of count expression node this object represents. - name: left_node type: CountTerm* default: unset doc: Internal, when node_type is not Leaf, this is the left operand. - name: right_node type: CountTerm* default: unset doc: Internal, when node_type is not Leaf, this is the right operand. - name: initial_reactions_count type: uint64 default: 0 doc: | Used for checkpointing, allows to set initial count of reactions that occurred. Ignored when molecules are counted. methods: - name: __add__ doc: | Create a new CountTerm that represents addition of two count terms. Usually used through operator '+' such as in ct1 + ct2. return_type: CountTerm* params: - name: op2 type: CountTerm* - name: __sub__ doc: | Create a new CountTerm that represents subtraction of two count terms. Usually used through operator '-' such as in ct1 - ct2. return_type: CountTerm* params: - name: op2 type: CountTerm* Count: superclass: BaseDataClass doc: | Represents a molecule or reaction count observable. What is counted is defined through a CounTerm tree and a reference to the root of this tree is stored into attribute expression. This tree usually contains just one node. examples: tests/pymcell4/1500_region_release_must_set_compartment/model.py items: - name: name type: str default: unset doc: | Name of a count may be specified when one needs to search for them later. When the count is created when a BNGL file is loaded, its name is set, for instance when the following BNGL code is loaded\: begin observables Molecules Acount A end observables the name is set to Acount. - name: file_name type: str default: unset doc: | File name where this observable values will be stored. File extension or setting explicit output_format determines the output format. A) When not set, the value is set using seed during model initialization as follows: file_name = './react_data/seed_' + str(model.config.seed).zfill(5) + '/' + name + '.dat' and the output format is set to CountOutputFormat.DAT in the constructor. B) When the file_name is set explicitly by the user and the extension is .dat such as here: file_name = './react_data/seed_' + str(SEED).zfill(5) + '/' + name + '.dat' and the output format is set to CountOutputFormat.DAT in the constructor. File names for individual Counts must be different. C) When the file_name is set explicitly by the user and the extension is .gdat such as here: file_name = './react_data/seed_' + str(SEED).zfill(5) + '/counts.gdat' and the output format is set to CountOutputFormat.GDAT in the constructor. The file name is usually the same for all counts but one can create multiple gdat files with different observables. All observables that are stored into a single .gdat file must have the same periodicity specified by attribute every_n_timesteps. Must be set. - name: expression type: CountTerm* default: unset doc: | The expression must be set to a root of an expression tree composed of CountTerms. In the usual cases, there is just one CountTerm in this expression tree and its node_type is ExprNodeType.LEAF. The count expression tree defines CountTerm objects that are added or subtracted from each other. - name: multiplier type: float default: 1 doc: | In some cases it might be useful to multiply the whole count by a constant to get for instance concentration. The expression tree allows only addition and subtraction of count terms so such multiplication can be done through this attribute. It can be also used to divide the resulting count by passing an inverse of the divisor (1/d). - name: every_n_timesteps type: float default: 1 doc: | Specifies periodicity of this count's output. Value is truncated (floored) to an integer. If value is set to 0, this Count is used only on-demand through calls to its get_current_value method. - name: output_format type: CountOutputFormat default: CountOutputFormat.AUTOMATIC_FROM_EXTENSION doc: | Listed as the last attribute because the automatic default value is sufficient in most cases. Selection of output format. Default setting uses file extension from attribute file_name. When set to CountOutputFormat.AUTOMATIC_FROM_EXTENSION, this output_format is set automatically only in the Count's constructor. methods: - name: get_current_value return_type: float doc: | Returns the current value for this count. Can be used to count both molecules and reactions. Reaction counting starts at the beginning of the simulation. The model must be initialized with this Count present as one of the observables. examples: tests/pymcell4_positive/2600_get_current_mol_count/model.py tests/pymcell4_positive/2650_get_current_rxn_count/model.py Observables: doc: | Container used to hold observables-related model data. Observables are the measured values of the system. This class also includes information on visualization of simulation. examples: tests/pymcell4_positive/2600_get_current_mol_count/observables.py items: - name: viz_outputs type: List[VizOutput*] default: empty doc: | List of visualization outputs to be included in the model. There is usually just one VizOutput object. - name: counts type: List[Count*] default: empty doc: | List of counts to be included in the model. methods: - name: add_viz_output doc: Adds a reference to the viz_output object to the list of visualization output specifications. params: - name: viz_output type: VizOutput* - name: add_count doc: Adds a reference to the count object to the list of count specifications. params: - name: count type: Count* - name: find_count doc: Finds a count object by its name, returns None if no such count is present. return_type: Count* params: - name: name type: str - name: load_bngl_observables doc: | Loads section observables from a BNGL file and creates Count objects according to it. All elementary molecule types used in the seed species section must be defined in subsystem. examples: tests/pymcell4/2100_gradual_bngl_load/model.py params: - name: file_name type: str doc: Path to the BNGL file. - 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: 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.