3.5. Variable references

A “variable reference” is an attribute value that specifies a CellML variable.

  1. A variable reference SHALL be a CellML identifier.

  2. The variable identified by a variable reference SHALL be determined as follows:

    1. If present in a descendant of a component element, then it SHALL refer to the variable of the same name within that component.

    2. If present in the variable_1 attribute of a map_variables element, then it SHALL refer to the variable of the same name in the component identified by the component_1 attribute in the same map_variables element.

    3. If present in the variable_2 attribute of a map_variables element, then it SHALL refer to the variable of the same name in the component identified by the component_2 attribute in the same map_variables element.

  3. If no variable can be identified using the rules above, then the attribute value SHALL NOT be a valid variable reference.

See more

Understanding variable references

A variable item only exists within its parent component item, but can be connected to others via the map_variables functionality. There are two different ways that any variable could be referenced.

The first and simplest is within its own local scope, the parent component. In that situation, the variable element’s name attribute is enough to uniquely locate it.

The second situation is when a variable is referred to from a component other than its parent, so a reference to the parent component as well as the variable’s name is required. This is found when creating connection items using map_variables.

The example below shows how the pairing of components and variables are required to form a valid connection.

<model name="FamousFreds">

  <component name="Flintstone">
    <variable name="Fred" units="dimensionless" />
    <variable name="Wilma" units="dimensionless" />
  </component>

  <component name="Astair">
    <variable name="Fred" units="dimensionless" />
  </component>

  <component name="CartoonCharacters">
    <variable name="FredFlintstone" units="dimensionless" />
    <variable name="DaffyDuck" units="dimensionless" />
  </component>

  <component name="Dancers">
    <variable name="FredAstaire" units="dimensionless" />
    <variable name="GingerRogers" units="dimensionless" />
  </component>

  <!-- Correct: connecting the variable "Fred" in component "Flintstone" into the
       variable "FredFlintsone" in the "CartoonCharacters" component. -->
  <connection component_1="Flintstone" component_2="CartoonCharacters" >
    <map_variables variable_1="Fred" variable_2="FredFlintstone" />
  </connection>

  <!-- Incorrect: trying to connect variable "Fred" from component "Dancers" into the
       variable "FredAstaire" from component "Astair": variable_1 must exist within
       component_1, and variable_2 must exist within component_2. -->
  <connection component_1="Dancers" component_2="Astaire">
    <map_variables variable_1="Fred" variable_2="FredAstaire" />
  </connection>
</model>