Skip to content

GR(1) Getting Started

Consider a cooling controller connected to a fan actuator. The environment provides the Boolean signal hot. The controller produces the internal command fan_command, and the actuator produces airflow. We use composition to obtain a contract over the external variables hot and airflow.

Cooling controller and fan actuator composition

Figure 1: The internal fan_command variable connects the controller and actuator. Composition eliminates it and retains hot and airflow.

The controller starts with the command off, copies hot to fan_command at every step, and assumes that hot recurs. The recurrence assumption lets it guarantee that the command also recurs.

from pacti.iocontract import GR1IoContract, Var

controller = GR1IoContract.from_dict({
    "input_vars": ["hot"],
    "output_vars": ["fan_command"],
    "variable_sorts": {"hot": "bool", "fan_command": "bool"},
    "assumptions": {"init": ["!hot"], "liv": ["hot"]},
    "guarantees": {
        "init": ["!fan_command"],
        "inv": ["fan_command = hot"],
        "liv": ["fan_command"],
    },
})
print(controller.to_pretty_string())
Inputs:  hot
Outputs: fan_command

Assumptions
  INIT:
    ¬(hot)
  LIV:
    □◇(hot)

Guarantees
  INIT:
    ¬(fan_command)
  INV:
    □(fan_command = hot)
  LIV:
    □◇(fan_command)

The actuator assumes the same initial and recurring properties for its input. Its invariant states that airflow follows the command one transition later.

fan = GR1IoContract.from_dict({
    "input_vars": ["fan_command"],
    "output_vars": ["airflow"],
    "variable_sorts": {"fan_command": "bool", "airflow": "bool"},
    "assumptions": {"init": ["!fan_command"], "liv": ["fan_command"]},
    "guarantees": {
        "init": ["!airflow"],
        "inv": ["fan_command = X(airflow)"],
        "liv": ["airflow"],
    },
})
print(fan.to_pretty_string())
Inputs:  fan_command
Outputs: airflow

Assumptions
  INIT:
    ¬(fan_command)
  LIV:
    □◇(fan_command)

Guarantees
  INIT:
    ¬(airflow)
  INV:
    □(fan_command = X(airflow))
  LIV:
    □◇(airflow)

Composition

The command is an output of the controller and an input of the actuator. Composition connects the two contracts and uses CAVE to eliminate this internal variable.

cooling_system = controller.compose(fan)
print(cooling_system.to_pretty_string())
Inputs:  hot
Outputs: airflow

Assumptions
  INIT:
    ¬(hot)
  LIV:
    □◇(hot)

Guarantees
  INIT:
    ¬(X(airflow)) ∧ ¬(airflow)
  INV:
    □(hot = X(airflow))
  LIV:
    □◇(airflow)

Substitution gives the invariant X(airflow) = hot. Initially both hot and fan_command are false. The actuator starts with no airflow, and its invariant therefore also makes the next airflow value false. We use the resulting external contract \(\mathcal{C}_{target}\) both as the reference for composition and as the target for quotient. It has initial guarantee !airflow & !X(airflow) and recurring guarantee GF airflow.

target = GR1IoContract.from_dict({
    "input_vars": ["hot"],
    "output_vars": ["airflow"],
    "variable_sorts": {"hot": "bool", "airflow": "bool"},
    "assumptions": {"init": ["!hot"], "liv": ["hot"]},
    "guarantees": {
        "init": ["!airflow", "!X(airflow)"],
        "inv": ["X(airflow) = hot"],
        "liv": ["airflow"],
    },
})

assert cooling_system.refines(target)
assert target.refines(cooling_system)
assert Var("fan_command") not in cooling_system.a.vars + cooling_system.g.vars
print("The computed composition and target contract refine one another.")
The computed composition and target contract refine one another.

The two refinement certificates establish equivalence between the computed composition and \(\mathcal{C}_{target}\). The target assumes that the hot signal recurs and requires airflow one step after each request, with recurring airflow.

Quotient

The quotient \(\mathcal{C}_{target}/\mathcal{C}_{fan}\) holds the fan contract fixed and computes the requirement for a controller that completes the target defined above.

Controller requirement computed by quotient

Figure 2: The fan contract is fixed. Quotient computes a controller requirement over hot and fan_command whose composition with the fan meets the target over hot and airflow.

controller_requirement = target.quotient(fan)
print(controller_requirement.to_pretty_string())
Inputs:  hot
Outputs: fan_command

Assumptions
  INIT:
    ¬(hot)
  LIV:
    □◇(hot)

Guarantees
  INV:
    □(hot = fan_command)
  LIV:
    □◇(fan_command)

The quotient has interface hot -> fan_command. It requires the command to equal hot and to recur. The initial assumption !hot and the invariant equality imply that the command is initially off, so a separate initial guarantee is unnecessary.

recomposed = controller_requirement.compose(fan)

assert [variable.name for variable in controller_requirement.inputvars] == ["hot"]
assert [variable.name for variable in controller_requirement.outputvars] == ["fan_command"]
assert controller.refines(controller_requirement)
assert controller_requirement.refines(controller)
assert recomposed.refines(target)
assert target.refines(recomposed)
print("The original and quotient-derived controller contracts refine one another.")
print("Recomposition with the fan is equivalent to the system target.")
The original and quotient-derived controller contracts refine one another.
Recomposition with the fan is equivalent to the system target.

Composition and quotient both recover exact contracts for this example. For general GR(1) formulas, CAVE returns sound finite-window bounds and is not complete for every temporal projection.