mcell/libmcell/definition/observables.yaml

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.