ComponentType: superclass: BaseDataClass doc: Multiple functional attributes for each molecule type are described using components. And this class defines a type of a component. For example, proteins have multiple functional substructures such as domains, motifs, and binding sites. These components can be unchanging (called stateless) or exist in one of many different internal states For example, certain binding motifs may have different behaviors depending on whether they are unphosphorylated or phosphorylated. examples: tests/pymcell4_positive/0040_to_bngl_str/model.py items: - name: name type: str doc: Name of this component type. - name: states type: List[str] default: empty doc: List of states allowed by this component. methods: - name: inst doc: Instantiate a component from this component type. return_type: Component* params: - name: state type: str default: STATE_UNSET doc: Selected state, must be from the list of the allowed states. - name: bond type: int default: BOND_UNBOUND doc: Bond information for the created component instance. - name: inst doc: Instantiate a component from this component type. return_type: Component* params: - name: state type: int default: STATE_UNSET_INT doc: Selected state, must be from the list of the allowed, converted to string. - name: bond type: int default: BOND_UNBOUND doc: Bond information for the created component instance. - name: to_bngl_str return_type: str doc: Creates a string that corresponds to its BNGL representation. is_const: true Component: superclass: BaseDataClass doc: | Instance of a component type belonging to a molecule instance. A component instance must have its state set if there is at least one allowed state. It is also used to connect molecule instance in a complex instance through bonds. examples: tests/pymcell4_positive/0040_to_bngl_str/model.py items: - name: component_type type: ComponentType* doc: Reference to a component type. - name: state type: str default: STATE_UNSET doc: Specific state value of this component instance. - name: bond type: int default: BOND_UNBOUND doc: | Specific bond for this component instance. It is either a numberical value such as in A(c!1), or one of special values BOND_UNBOUND in A(c), BOND_BOUND in A(c!+) or BOND_ANY in A(c!?). methods: - name: to_bngl_str return_type: str doc: Creates a string that corresponds to this component's BNGL representation. is_const: true ElementaryMoleculeType: todo: | How can we share members such as diff const between this class and Species? custom_time_step, custom_space_step and target_only are currently supported only when used in Species superclass: BaseDataClass doc: | An elementary molecule type is a base indivisible entity. It is the same as a molecule type in BNGL entered in section molecule types. The 'elementary' prefix was added to distinguish it clearly from molecules in simulation. examples: tests/pymcell4_positive/0040_to_bngl_str/model.py items: - name: name type: str doc: Name of this elementary molecule type. - name: components type: List[ComponentType*] default: empty doc: List of components used by this elementary molecule type. - name: diffusion_constant_2d type: float default: unset doc: | Elementary molecule based on this type is constrained to a surface and diffuses with the specified diffusion constant. D can be zero, in which case the molecule doesn’t move. The units of D are cm^2 /s. - name: diffusion_constant_3d type: float default: unset doc: | Elementary molecule based on this type diffuses in space with the specified diffusion constant D. D can be zero, in which case the molecule doesn’t move. The units of D are cm^2 /s. - name: custom_time_step type: float default: unset doc: | This molecule should take timesteps of length custom_time_step (in seconds). Use either this or custom_time_step, not both. - name: custom_space_step type: float default: unset doc: | This molecule should take steps of average length given by the custom_space_step value (in microns). Use either this or custom_time_step, not both. - name: target_only type: bool default: False doc: | This molecule will not initiate reactions when it runs into other molecules. This setting can speed up simulations when applied to a molecule at high concentrations that reacts with a molecule at low concentrations (it is more efficient for the low-concentration molecule to trigger the reactions). This directive does not affect unimolecular reactions. methods: - name: inst return_type: ElementaryMolecule* doc: Create an elementary molecule based on this elementary molecule type. params: - name: components type: List[Component*] default: empty doc: | Instances of components for the the created elementary molecule. Not all components need to be specified in case when the elementary molecule is used in a pattern. - name: compartment_name type: str default: unset doc: | Optional specification of compartment name for the created elementary molecule. - name: to_bngl_str return_type: str doc: Creates a string that corresponds to its BNGL representation. is_const: true ElementaryMolecule: superclass: BaseDataClass doc: Instance of an elementary molecule type. A BNGL complex is composed of elementary molecules. examples: tests/pymcell4_positive/0040_to_bngl_str/model.py items: - name: elementary_molecule_type type: ElementaryMoleculeType* doc: Reference to the type of this elementary molecule. - name: components type: List[Component*] default: empty doc: | List of component instances. Not all components need to be specified in case when this elementary molecule is used in a pattern. - name: compartment_name type: str default: unset doc: Optional BNGL compartment name for this elemenrary molecule. If a 2D/surface compartment is specified, the elementary moelcule must be of surface type. If a 3D/volume compartment is specified, the elementary moelcule must be of volume type. methods: - name: to_bngl_str return_type: str doc: Creates a string that corresponds to its BNGL representation is_const: true params: - name: with_compartment type: bool default: true doc: Include compartment name in the returned BNGL string. Complex: superclass: BaseDataClass doc: | This class represents a complex molecule composed of molecule instances. It is either defined using a BNGL string or using a list of elementary molecule instances. On top of that, orientation may be defined. This class is most often by calling its constructor as m.Complex(bngl_string) in cases where a fully qualified instance (such as for molecule releases) or a pattern (in observable counts) is needed. Comparison operator __eq__ first converts complexes to their canonical representation and then does comparison so for instance m.Complex('A(b!1).B(a!1)') == m.Complex('B(a!2).A(b!2)'). examples: tests/pymcell4_positive/0040_to_bngl_str/model.py internal: | Ctor Species(Complex& cplx_inst) must be updated if if attributes change items: - name: name type: str default: empty doc: | When set, this complex instance is initialized from a BNGL string passed as this argument, the string is parsed and elementary_molecules and compartment are initialized. Only one of name or elementary_molecules can be set. - name: elementary_molecules type: List[ElementaryMolecule*] default: empty doc: | Individual molecule instances contained in the complex. Only one of name or elementary_molecules can be set. - name: orientation type: Orientation default: Orientation.DEFAULT doc: | Specifies orientation of a molecule. When Orientation.DEFAULT if kept then during model initialization is 'orientation' set to Orientation.NONE for volume complexes and to Orientation.UP for surface complexes. Ignored by derived class Species. - name: compartment_name type: str default: unset doc: | Specifies compartment name of this Complex. Only one of 'orientation' and 'compartment_name' can be set. Corresponds to BNGL specification of a compartment for the whole complex '@COMP\:'. If a 2D/surface compartment is specified, the complex must be a surface complex and orientation is set to Orientation.UP. If a 3D/volume compartment is specified, the complex must be a volume complex and orientation is set to Orientation.NONE. Sets compartment to all elementary molecules whose compartment is unset. Does not override specific compartments of elementary molecules that were already set. If this is a volume complex (all elementary molecules have their diffusion_constant_3d set), all compartments of elementary molecules must be the same volume compartment. If this is a surface complex (at least one elementary molecule has its their diffusion_constant_2d set), all compartments of surface elementary molecules must be the same, and all compartments of volume elementary molecules must be from the two neighboring volume compartments. methods: - name: to_bngl_str return_type: str doc: Creates a string that corresponds to its BNGL representation including compartments. is_const: true - name: as_species return_type: Species* doc: | Returns a Species object based on this Complex. All species-specific attributes are set to their default values and 'name' is set to value returned by 'to_bngl_str()'. Species: superclass: Complex TODO: | Ignore orientation when comparing species on equality. doc: | There are three ways how to use this class\: 1) definition of simple species - in this case 'name' is a single identifier and at least 'diffusion_constant_2d' or 'diffusion_constant_3d' must be provided. Example\: m.Species('A', diffusion_constant_3d=1e-6). Such a definition must be added to subsystem or model so that during model initialization this species is transformed to MCell representation and an ElementaryMoleculeType 'A' with a given diffusion constant is created as well. 2) full definition of complex species - in this case the inherited attribute 'elementary_molecules' from Complex is used as a definition of the complex and this gives information on diffusion constants of the used elementary molecules. Example\: m.Species(elementary_molecules=[ei1, ei2]). Such a definition must be added to subsystem or model. 3) declaration of species - in this case only 'name' in the form of an BNGL string is provided. The complex instance specified by the name must be fully qualified (i.e. all components are present and those components that have a state have their state set). No information on diffusion constants and other properties of used elementary molecules is provided, it must be provided elsewhere. Example\: m.Species('A(b!1).B(a!1)'). This is a common form of usage when reaction rules are provided in a BNGL file. Such declaration does no need to be added to subsystem or model. This form is used as argument in cases where a fully qualified instance must be provided such as in molecule releases. examples: tests/pymcell4_positive/0040_to_bngl_str/model.py items: - name: name type: str default: unset doc: | Name of the species in the BNGL format. One must either specify name or elementary_molecules (inherited from Complex). This argument name is parsed during model initialization. - name: diffusion_constant_2d type: float default: unset doc: | This molecule is constrained to surface with diffusion constant D. D can be zero, in which case the molecule doesn’t move. The units of D are cm^2/s. - name: diffusion_constant_3d type: float default: unset # the value is optional and might need to be checked with a more complex check doc: | This molecule diffuses in space with diffusion constant D. D can be zero, in which case the molecule doesn’t move. The units of D are cm^2/s. - name: custom_time_step type: float default: unset doc: | Optional setting of a custom time step for this specific species. A molecule of this species should take timesteps of length custom_time_step (in seconds). Use either this or custom_time_step. - name: custom_space_step type: float default: unset doc: | Optional setting of a custom space step for this specific species. A molecule of this species should take steps of average length custom_space_step (in microns). Use either this or custom_time_step. - name: target_only type: bool default: False doc: | A molecule of this species will not initiate reactions when it runs into other molecules. This setting can speed up simulations when applied to a molecule at high concentrations that reacts with a molecule at low concentrations (it is more efficient for the low-concentration molecule to trigger the reactions). This directive does not affect unimolecular reactions. methods: - name: inst return_type: Complex* doc: | Creates a copy of a Complex from this Species with specified orientation and compartment name. params: - name: orientation type: Orientation default: Orientation.DEFAULT doc: Maximum one of orientation or compartment_name can be set, not both. - name: compartment_name type: str default: unset doc: Maximum one of orientation or compartment_name can be set, not both. SurfaceProperty: superclass: BaseDataClass doc: Single property for a SurfaceClass. items: - name: type type: SurfacePropertyType default: SurfacePropertyType.UNSET doc: | Must be set. See SurfacePropertyType for options. todo: Links in documentation - name: affected_complex_pattern type: Complex* default: unset doc: | A complex pattern with optional orientation must be set. Default orientation means that the pattern matches any orientation. For concentration or flux clamp the orientation specifies on which side will be the concentration held (UP is front or outside, DOWN is back or inside, and DEFAULT, ANY or NONE is on both sides). The complex pattern must not use compartments. - name: concentration type: float default: unset doc: | Specifies concentration when type is SurfacePropertyType.CLAMP_CONCENTRATION or SurfacePropertyType.CLAMP_FLUX. Represents concentration of the imagined opposide side of the wall that has this concentration or flux clamped. SurfaceClass: superclass: SurfaceProperty doc: | Defining a surface class allows surfaces to behave like species. For instance, one may wish to specify that a surface does not block the diffusion of molecules. Each type of surface is defined by name, and each surface name must be unique in the simulation and should not match any molecule names. To define a reaction with a surface class, use constructor call m.Complex(name) as one of the reactants. examples: tests/pymcell4/1600_crossing_transparent_compartment_wall/model.py tests/pymcell4_positive/1840_vol_plus_surf_class_rxn_callback/model.py items: - name: name type: str doc: Name of the surface class. - name: properties type: List[SurfaceProperty*] default: empty doc: | A surface class can either have a list of properties or just one property. In the usual case of having one property, one can set the attributes type, affected_species, etc. inherited from SurfaceProperty directly. ReactionRule: superclass: BaseDataClass doc: | Represents a BioNetGen Language (BNGL) reaction rule. In BNGL, a reaction is simply one or more transformations applied simultaneously to one or more species. The following transformations (and their combinations) are allowed\: * Forming a bond, e.g. A(b) + B(a) -> A(b!0).B(a!0) * Breaking a bond, e.g. A(b!0).B(a!0)-> A(b)+ B(a) * Changing of component state, e.g. X(y~0) -> X(y~p) * Creating a molecule, e.g. A(b) -> A(b) + C(d) * Destroying a molecule, e.g. A(b) + B(a) -> A(b) or A -> Null (Null here means that there is no product) * Changing species of a bound molecule when the molecule type has the same components, e.g. A(b!0).B(a!0)-> A(b!0).C(a!0) Also compartments may be specified in reactants (patterns) and for products. Special compartment classes supported by MCell4 are @IN and @OUT. They can be used in surface reactions to constrain a reaction with a volume molecule hitting a surface molecule from the inside or outside of the compartment, e.g. A(s)@IN + S(a) -> S(a!1).A(s!1) and/or to define the location of the product, e.g. S(a!1).A(s!1) -> S(a) + A(s)@OUT. examples: tests/pymcell4_positive/0040_to_bngl_str/model.py tests/pymcell4_positive/1840_vol_plus_surf_class_rxn_callback/model.py items: - name: name type: str default: unset doc: | Name of the reaction. If this is a reversible reaction, then it is the name of the reaction in forward direction. - name: reactants type: List[Complex*] default: empty # must be set, but C++ ordering of arguments requires that all defaults are at the end doc: List of reactant patterns. Must contain one or two patterns. - name: products type: List[Complex*] default: empty doc: List of reactant patterns. May be empty. - name: fwd_rate type: float default: unset examples: tests/pymcell4/2500_rxn_rate_change_bimol_box_it_100/model.py tests/pymcell4/2700_concentration_based_rxn_rate/model.py doc: | The units of the reaction rate for uni- and bimolecular reactions are\: * [s^-1] for unimolecular reactions, * [N^-1*s^-1] bimolecular reactions between two surface molecules on different objects (this is a highly experimental feature and the unit will likely change in the future, not sure if probability is computed correctly, it works the way that the surface molecule is first diffused and then a potential collisions within the distance of Config.intermembrane_interaction_radius are evaluated). Other bimolecular reaction units depend on Model.config.use_bng_units settings. When use_bng_units is False (default), traditional MCell units are used: * [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, and When use_bng_units is True, units compatible with BioNetGen's ODE, SSA, and PLA solvers are used: * [um^3*N^-1*s^-1] for any bimolecular reactions, surface-surface reaction rate conversion assumes 10nm membrane thickness. M is the molarity of the solution and N the number of reactants. May be changed after model initialization. Setting of value is ignored if the rate does not change. If the new value differs from previous, updates all information related to the new rate including recomputation of reaction times for molecules if this is a unimolecular reaction. - name: rev_name type: str default: unset doc: | Name of the reaction in reverse direction. - name: rev_rate type: float default: unset doc: | Reverse reactions rate, reaction is unidirectional when not specified. May be changed after model initialization, in the case behaves the same was as for changing the 'fwd_rate'. Uses the same units as 'fwd_rate'. - name: variable_rate type: List[List[float]] default: empty doc: | The array passed as this argument must have as its items a pair of floats (time in s, rate). Must be sorted by time (this is not checked). Variable rate is applicable only for irreversible reactions. When simulation starts and the table does not contain value for time 0, the initial fwd_rate is set to 0. When time advances after the last time in this table, the last rate is used for all subsequent iterations. Members fwd_rate and rev_rate must not be set when setting this attribute through a constructor. When this attribute is set outside of the class constructor, fwd_rate is automatically reset to an 'unset' value. Cannot be set after model initialization. - name: is_intermembrane_surface_reaction type: bool default: false doc: | Experimental, see addintinal explanation in 'fwd' rate. Then set to true, this is a special type of surface-surface reaction that allows for two surface molecules to react when they are on different geometrical objects. Note\: This support is limited for now, the reaction rule must be in the form of A + B -> C + D where all reactants and products must be surface molecules and their orientation must be 'any' (default). examples: tests/pymcell4/3000_intermembrane_rxns/customization.py todo: not sure whether we should allow this rxn also for standard surf-surf rxns methods: - name: to_bngl_str return_type: str doc: Creates a string that corresponds to the reaction rule's BNGL representation, does not contain rates. is_const: true Subsystem: doc: | Subsystem usually defines a reaction network. It is a collection of species and reaction rules that use these species. The main motivation for introducing such an object to MCell4 is to have a class independent on that particular initial model state and observables that only contains reactions. This way, one can define independent reusable subsystems and possibly merge them together when creating a model that includes multiple reaction networks. examples: tests/pymcell4/2550_variable_rate_unimol_w_rxn_class_cleanup/sybsystem.py items: - name: species type: List[Species*] default: empty doc: | List of species to be included in the model for initialization. Used usually only for simple species (species that are defined using a single molecule type without components such as 'A'). Other species may be created inside simulation - name: reaction_rules type: List[ReactionRule*] default: empty - name: surface_classes type: List[SurfaceClass*] default: empty - name: elementary_molecule_types type: List[ElementaryMoleculeType*] default: empty doc: | Contains list of elementary molecule types with their diffusion constants and other information. Populated when a BNGL file is loaded and also on initialization from Species objects present in the species list. methods: - name: add_species doc: Add a reference to a Species object to the species list. params: - name: s type: Species* - name: find_species doc: | Find a Species object using name in the species list. Returns None if no such species is found. return_type: Species* params: - name: name type: str - name: add_reaction_rule doc: Add a reference to a ReactionRule object to the reaction_rules list. params: - name: r type: ReactionRule* - name: find_reaction_rule doc: | Find a ReactionRule object using name in the reaction_rules list. Returns None if no such reaction rule is found. return_type: ReactionRule* params: - name: name type: str - name: add_surface_class doc: Add a reference to a SurfaceClass object to the surface_classes list. params: - name: sc type: SurfaceClass* - name: find_surface_class doc: | Find a SurfaceClass object using name in the surface_classes list. Returns None if no such surface class is found. return_type: SurfaceClass* params: - name: name type: str - name: add_elementary_molecule_type doc: Add a reference to an ElementaryMoleculeType object to the elementary_molecule_types list. params: - name: mt type: ElementaryMoleculeType* - name: find_elementary_molecule_type doc: | Find an ElementaryMoleculeType object using name in the elementary_molecule_types list. Returns None if no such elementary molecule type is found. return_type: ElementaryMoleculeType* params: - name: name type: str - name: load_bngl_molecule_types_and_reaction_rules doc: | Parses a BNGL file, only reads molecule types and reaction rules sections, i.e. ignores observables and seed species. Parameter values are evaluated and the result value is directly used. Compartments names are stored in rxn rules as strings because compartments belong to geometry objects and the subsystem is independent on specific geometry. However, the compartments and their objects must be defined before initialization. examples: tests/pymcell4/2100_gradual_bngl_load/model.py params: - name: file_name type: str doc: Path to the BNGL file to be loaded. - 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.