mcell/libmcell/definition/introspection.yaml

Molecule:
  superclass: BaseIntrospectionClass 
  doc: |
    Representation of a molecule obtained from Model 
    during simulation obtained through Model.get_molecule.
    Changes through changing attributes of this object are not allowed except 
    for complete removal of this molecule.   
  examples: tests/pymcell4_positive/1900_molecule_introspection/model.py
  items:
  - name: id
    type: int
    default: ID_INVALID
    doc: | 
       Unique id of this molecule. MCell assigns this unique id to each created 
       molecule. All reactions change ID of molecules even in reactions such as 
       A@CP -> A@EC.
     
  - name: type
    type: MoleculeType
    default: MoleculeType.UNSET
    doc: |
       Type of this molecule, either volume or surface. 
    
  - name: species_id
    type: int
    default: ID_INVALID
    doc: | 
       Species id of this molecule.
       The species_id value is only temporary. Species ids are created and removed as needed
       automatically and if this species is removed, this particular species_id value 
       won't be valid. This can happen when a following iteration is simulated.
     
  - name: pos3d
    type: List[float]
    default: unset
    doc: |
      Contains position of a molecule in 3D space.        
      
  - name: orientation
    type: Orientation
    default: Orientation.NOT_SET
    doc: |
      Contains orientation for surface molecule. Volume molecules 
      have always orientation set to Orientation.NONE.
      
  - name: pos2d
    type: List[float] 
    default: unset
    doc: |
      Set only for surface molecules. Position on a wall in UV coordinates 
      relative to the triangle of the wall.
              
  - name: geometry_object
    type: GeometryObject*
    default: unset
    doc: |
       Set only for surface molecules.
       Is set to a reference to the geometry object on whose surface is the molecule located.
     
  - name: wall_index
    type: int
    default: -1
    doc: |
       Set only for surface molecules.
       Index of wall belonging to the geometry_object where is the 
       molecule located. 
          
  methods:
  - name: remove
    doc: | 
       Removes this molecule from simulation. Any subsequent modifications
       of this molecule won't have any effect.
    examples: tests/pymcell4_positive/1920_molecule_remove/model.py  

Wall:
  superclass: BaseIntrospectionClass 
  doc: |
    Constant representation of wall of a geometry object.
    Changes through changing attributes of this object are not allowed
    except for the attribute is_movable.
  examples: tests/pymcell4_positive/1330_get_wall/model.py
  items:
  - name: geometry_object
    type: GeometryObject*
    doc: Object to which this wall belongs.
  
  - name: wall_index
    type: int
    doc: Index of this wall in the object to which this wall belongs.
    
  - name: vertices
    type: List[List[float]]
    doc: Vertices of the triangle that represents this wall.
    
  - name: area
    type: float
    doc: Area of the wall in um^2.
    
  - name: unit_normal
    type: List[float]
    doc: | 
       Normal of this wall with unit length of 1 um.
       There is also a method Model.get_wall_unit_normal that allows to 
       retrieve just the normal value without the need to prepare this 
       whole Wall object.  

  - name: is_movable
    type: bool
    default: true
    doc: | 
       If True, whis wall can be moved through Model.apply_vertex_moves,
       if False, wall moves are ignored. 
       Can be set during simulation.
    
    
WallWallHitInfo:
  superclass: BaseIntrospectionClass 
  doc: | 
     This class is used in the return type of Model.apply_vertex_moves.
     Contains pair of walls that collided.
  examples: tests/pymcell4_positive/1515_tetrahedron_box_collision_moving_3_w_wall_wall_hit/model.py
  items:
  - name: wall1
    type: Wall*
    doc: First colliding wall. 
           
  - name: wall2
    type: Wall*
    doc: Second colliding wall.
    
    
Introspection:
  doc: 
     Only internal. 
     This class is used only as a base class to Model, it is not provided through API.
     Defines interface to introspect simulation state.

  methods:      
  - name: get_molecule_ids
    doc: | 
      Returns a list of ids of molecules.
      If the arguments pattern is not set, the list of all molecule ids is returned.  
      If the argument pattern is set, the list of all molecule ids whose species match 
      the pattern is returned. 
    examples: tests/pymcell4_positive/1910_get_molecule_ids_w_pattern/model.py
    return_type: List[int]
    params:
    - name: pattern
      type: Complex*
      default: unset
      doc: BNGL pattern to select molecules based on their species, might use compartments.
  
  - name: get_molecule
    doc: |
       Returns a information on a molecule from the simulated environment, 
       None if the molecule does not exist.
    examples: tests/pymcell4_positive/1900_molecule_introspection/model.py
    return_type: Molecule*
    params: 
    - name: id
      type: int
      doc: Unique id of the molecule to be retrieved.

  - name: get_species_name
    doc: | 
       Returns a string representing canonical species name in the BNGL format.
    examples: tests/pymcell4_positive/1850_run_unimol_rxn_in_callback/model.py 
    return_type: str
    params: 
    - name: species_id
      type: int
      doc: Id of the species. 
  
  # --- geometry ---
  - name: get_vertex
    doc: Returns coordinates of a vertex.
    examples: tests/pymcell4_positive/1340_get_vertex/model.py
    return_type: List[float] 
    params:
    - name: object
      type: GeometryObject*
    - name: vertex_index
      type: int 
      doc: This is the index of the vertex in the geometry object's walls (wall_list).
      
  - name: get_wall
    doc: Returns information about a wall belonging to a given object.
    examples: tests/pymcell4_positive/1330_get_wall/model.py
    return_type: Wall* 
    params:
    - name: object
      type: GeometryObject*
      doc: Geometry object whose wall to retrieve.
    - name: wall_index
      type: int 
      doc: This is the index of the wall in the geometry object's walls (wall_list).
      
  - name: get_vertex_unit_normal
    doc: | 
       Returns sum of all wall normals that use this vertex converted to a unit vector of 
       length 1 um (micrometer).
       This represents the unit vector pointing outwards from the vertex.
    examples: tests/pymcell4_positive/1320_get_vertex_unit_normal/model.py
    return_type: List[float]
    params:
    - name: object
      type: GeometryObject*
      doc: Geometry object whose vertex to retrieve.
    - name: vertex_index
      type: int 
      doc: This is the index of the vertex in the geometry object's vertex_list.

  - name: get_wall_unit_normal
    doc: Returns wall normal converted to a unit vector of length 1um.
    examples: tests/pymcell4_positive/1310_get_wall_unit_normal/model.py
    return_type: List[float]
    params:
    - name: object
      type: GeometryObject*
      doc: Geometry object whose wall's normal to retrieve.
    - name: wall_index
      type: int 
      doc: This is the index of the vertex in the geometry object's walls (wall_list).
          
          
  # --- display/export manipulation ---
  - name: get_wall_color
    doc: Returns color of a wall.
    return_type: Color*
    params:
    - name: object
      type: GeometryObject*
      doc: Geometry object whose wall's color to retrieve.
    - name: wall_index
      type: int 
      doc: This is the index of the vertex in the geometry object's walls (wall_list).
    
  - name: set_wall_color
    doc: Sets color of a wall.
    params:
    - name: object
      type: GeometryObject*
      doc: Geometry object whose wall's color to retrieve.
    - name: wall_index
      type: int 
      doc: This is the index of the vertex in the geometry object's walls (wall_list).
    - name: color
      type: Color*
      doc: Color to be set.