2.9. The `reset` element¶

A reset element information item (referred to in this specification as a reset element) is an element in the CellML namespace with a local name equal to reset, which appears as a child of a component element.

Understanding reset elements

Resets are a new addition to CellML in version 2.0, and their intention is to allow the user to specify how and when discontinuities can exist in variable values throughout the solution. A reset lets you set a variable to a totally different value: restart a timer, flip a switch, take a step, start again. In order to work, a reset needs to know some information:

Which variable’s value do you want to change? This is called the “reset variable” and is specified by the variable attribute in the reset block.
What new value should be given to the reset variable? This is called the “reset value” and is specified by evaluating the MathML content which is inside the reset_value element child of this reset element.
Which variable will tell us when to trigger the change? This is called the “test variable” and is referenced by the test_variable attribute in the reset block. The test variable can be the same as the reset variable.
What value of the test variable should be used to trigger the change? This is called the “test value” and is specified by evaluating the MathML content inside the test_value element child of this reset element.
What happens if more than one reset points to the same reset variable? This will be sorted out by the unique order attribute on each reset element which changes this reset variable. The order will determine which of the active competing resets is applied.

Some of the syntax is explained below in the “see more” sections, and a final example is given at the end. For a much more thorough discussion and examples of resets in different scenarios, please see the {number} {name} section.

Every reset element MUST have exactly one of each of the following attributes:
1. The variable attribute.
  1. The value of the variable attribute MUST be a valid variable reference, as defined in 3.5 Variable references.
1. The test_variable attribute.
  1. The value of the test_variable attribute MUST be a valid variable reference, as defined in 3.5 Variable references.
2. The order attribute.
  1. The value of the order attribute MUST be an integer string.
  2. The value of the order attribute MUST be unique for all reset elements with variable attributes that reference variables in the same equivalent variable set (see 3.10 Interpretation of map_variables elements).

Consider the following example which represents the mythological story of Sisyphus, king of Ephrya. He was condemned to roll a huge boulder up a mountain each day, but, as it reached the top, the boulder would roll to the bottom so he had to begin again.

model: Tartarus
  └─ component: Sisyphus
      ├─ math: ode(position, time) = 1 [metres_per_second]
      ├─ variable: time [second]
      └─ variable: position, initially 0 [metre]
          └─ reset:
              ├─ when: time is midnight
              └─ then: position is bottom of hill

In this example it’s clear that for the reset to operate, it must know what is happening and when; in other words, that the variable attribute as well as the test_variable attribute must be specified. This is shown in the CellML syntax block below.

<!-- This is valid: both the reset variable "position" and the
     test_variable "time" are in the same component as the reset
     which uses them. -->
<model name="Tartarus">
  <component name="Sisyphus">
    <variable name="time" units="second" />
    <variable name="position" units="metre" initial_value="0" />

    <reset variable="position" test_variable="time" order="1">
      <!-- The reset_value and test_value children of a reset are
           discussed in the next sections. -->
      ...
    </reset>

    <!-- ODE for position based on time. -->
    <math>
      <apply><eq/>
          <diff>
              <ci>B</ci>
              <bvar>t</bvar>
          </diff>
          <cn cellml:units="metres_per_second">1</cn>
      </apply>
    </math>
  </component>

  <!-- Custom units required by ODE above: -->
  <units name="metres_per_second" >
    <unit units="metre" />
    <unit units="second" exponent="-1" />
  </units>

</model>

Examples of invalid configurations include when either the variable or test_variable attributes are unspecified, or when they do not refer to variables local to the reset’s component.

<model name="Tartarus">
  <component name="Sisyphus">
    <variable name="time" units="second" />
    <variable name="position" units="dimensionless" initial_value="0" />

    <!-- This is not valid: The test variable has not been specified. -->
    <reset variable="position" order="1">
      ...
    </reset>

    <!-- This is not valid: The reset variable has not been specified. -->
    <reset test_variable="time" order="1">
      ...
    </reset>

    ...

  </component>
</model>

<model name="Tartarus">
  <component name="Sisyphus">
    <variable name="time" units="second" />
    <variable name="position" units="metre" />

    <!-- This is not valid: The test variable "eternity_time" does not exist
         in the reset's component. -->
    <reset variable="position" test_variable="eternity_time" order="1">
      ...
    </reset>

    ...

  </component>
</model>

<model name="Tartarus">

  <!-- This is not valid: The reset variable "position" is in component  Sisyphus ... -->
  <component name="Sisyphus">
    <variable name="position" units="metre" initial_value="0" />
  </component>

  <!-- ... but the reset which changes it is in component "RulerOfTartarus". -->
  <component name="RulerOfTartarus">
    <variable name="time" units="second" />
    <reset variable="position" test_variable="time" order="1">
      ...
    </reset>
  </component>

</model>

The order attribute.

The value of the order attribute MUST be an integer string.

The value of the order attribute MUST be unique for all reset elements with variable attributes that reference variables in the same equivalent variable set (see 3.10 Interpretation of map_variables elements).

The order attribute of a reset element must be specified, and is used when there is more than one reset with the ability to change a variable.

We’ll continue the example above which represents the mythological story of Sisyphus rolling a boulder up a mountain, but tweak it a little. The ruler of Tartarus has decided that Sisyphus should have a day off on Tuesdays, so once a week the boulder doesn’t roll down the mountain until the following midnight. Adding a second reset to the model gives us the arrangement shown below.

model: Tartarus
  └─ component: Sisyphus
      ├─ math: ode(position, time) = 1
      ├─ variable: time
      └─ variable: position, initially 0
          ├─ reset: A
          │   ├─ when: time is midnight
          │   ├─ then: position is bottom of hill
          │   └─ order: 2
          │
          └─ reset: B
              ├─ when: time is Tuesday midnight
              ├─ then: position is unchanged at top of hill
              └─ order: 1

As it stands, at midnight on a Tuesday both of the resets above are active: the first, reset A, because midnight on any day meets the midnight criterion; the second because midnight on Tuesday also meets the criterion for B. To decide which of the two consequences to enact - to roll the stone or not - we need to consider the order attribute, the interpretation of which is discussed in detail in {number} {name}. The valid CellML syntax for this situation is shown below, with some examples of invalid syntax too.

<!-- This is valid: the order attribute of both resets is present,
    unique, and an integer. -->
<model name="Tartarus">
  <component name="Sisyphus">
    <variable name="time" units="second" />
    <variable name="position" units="dimensionless" />

    <!-- The first reset represents all midnight times. -->
    <reset variable="position" test_variable="time" order="2">
      ...
    </reset>
    <!-- The second reset represents midnight on Tuesdays only. -->
    <reset variable="position" test_variable="time" order="1">
      ...
    </reset>
  </component>
</model>

<!-- These are not valid: -->
<model name="Tartarus">
  <component name="Sisyphus">
    <variable name="time" units="second" />
    <variable name="position" units="dimensionless" initial_value="0" />

    <!-- Invalid: missing order attribute. -->
    <reset variable="position" test_variable="time" >
      ...
    </reset>

    <!-- Invalid: order must be an integer. -->
    <reset variable="position" test_variable="time" order="first" >
      ...
    </reset>
    <reset variable="position" test_variable="time" order="1.0" >
      ...
    </reset>

  </component>
</model>

Finally we’ll look at the condition for uniqueness of a variable’s resets’ orders. Note that this is applied within the component itself across all the resets which could apply to a given variable, as well as across the set of equivalent variables too. Let’s create a second component to represent the whim of Zeus, ruler of the gods, who can intervene at any time to send the stone rolling down the mountain.

model: Tartarus
  ├─ component: Zeus
  │   └─ variable: sisyphus_position <╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴┐
  │       └─ reset: C                                       ╷
  │           ├─ when: Sisyphus reaches some position       ╷
  │           ├─ then: sisyphus_position is bottom of hill  ╷
  │           └─ order: -1                                  ╷
  │                                                    equivalent
  └─ component: Sisyphus                               variables
      ├─ math: ode(position, time) = 1                      ╵
      ├─ variable: time                                     ╵
      └─ variable: position <╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴╴┘
          ├─ reset: A
          │   ├─ when: time is midnight
          │   ├─ then: position is bottom of hill
          │   └─ order: 2
          │
          └─ reset: B
              ├─ when: time is Tuesday midnight
              ├─ then: position is unchanged at top of hill
              └─ order: 1

<model name="Tartarus">
  <!-- Including a new component with a connected variable, sisyphus_position: -->
  <component name="Zeus" >
    <variable name="sisyphus_position" units="metre" initial_value="0" interface="public"/>
    <!-- Creating a reset that will send the boulder to the bottom of the mountain
         when it reaches a certain point: -->
    <reset variable="sisyphus_position" test_variable="sisyphus_position" order="-1">
      ...
    </reset>
  </component>

  <component name="Sisyphus">
    <variable name="time" units="second" />
    <variable name="position" units="dimensionless" interface="public" />

    <!-- The first reset represents all midnight times. -->
    <reset variable="position" test_variable="time" order="2">
      ...
    </reset>
    <!-- The second reset represents midnight on Tuesdays only. -->
    <reset variable="position" test_variable="time" order="1">
      ...
    </reset>
    ...
  </component>

  <!-- Connecting the variable "position" in component "Sisyphus" with the variable
       "sisyphus_position" in component "Zeus": -->
  <connection component_1="Zeus" component_2="Sisyphus" >
    <map_variables variable_1="sisyphus_position" variable_2="position" />
  </connection>
</model>

This arrangement is valid, because none of the order attributes on resets within the same equivalent variable set have duplicated values: reset A has order 2, reset B has order 1, and reset C has order -1. Note also that order values may be negative, as shown here.

Gotcha: an “equivalent variable set” without any equivalent variables?

The equivalent variable set rule here refers to any reset which references the same variable. This is possible in two ways - either by directly referencing it (as in resets A and B above) or through the equivalence network (as in reset C). Thus, even in situations where there are no equivalent variables defined in the model (which is the case before Zeus stepped in) there is still the need for order uniqueness between resets of the same variable (as in between A and B).

A reset element MUST contain exactly two element children, which MUST be one of each of the following types:
1. A reset_value element; and
1. A test_value element.

2.9. The reset element¶

2.9. The `reset` element¶