Skip to content

Parameters, properties, arguments

Goals, transforms and needs give us the expressiveness to build a complete specification. However, sometimes, variables need to be available outside a component's own definition. For instance, when we imposed the min-water-flow design requirement, we could not yet link it to the water-flow inside the pump component.

Just as well, we would like both the pump and drive-mechanism to work with the same torque variable, instead of each having their own unique variables. That way we can check whether the requirements that all components impose on a variable are carefully captured and coordinated.

To indicate the owner of a certain design variable, you can add the property keyword to the parameter declaration.

Parameters

Let's review the CentrifugalPump's definition. It now has a parameters section:

world.esl
1
2
3
4
5
6
7
8
define component CentrifugalPump
  parameters
    torque is a MechanicalEnergyFlow
    water-flow is a LiquidMaterialFlow
    length is a SpatialMeasure property

  transformation-requirements
    convert-torque: must convert torque into water-flow
world.esl
  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
# Specification of a drive-mechanism driving a pump.
define type
  MechanicalEnergyFlow is a real with unit Nm
  ElectricalEnergyFlow is a real with unit W
  LiquidMaterialFlow is a real with unit L/s
  EnergyPotential is a real with unit Wh
  ControlSignal is a boolean
  Distance is a real with unit m
  SpatialMeasure is a Distance of at least 0.0 [m]


define verb
  provide to
  convert into
  send to

# ---8<--- [start:world-vars]
world
  variables
    torque is a MechanicalEnergyFlow
    water-flow is a LiquidMaterialFlow
    drive-length is a SpatialMeasure
    pump-length is a SpatialMeasure
# ---8<--- [end:world-vars]

  design-requirements
    min-water-flow: water-flow must be at least 1.0 [L/s]

  design-constraints
    dc-drive-length: drive-length must be equal to pump-length

# ---8<--- [start:pump-inst]
  components
    pump is a CentrifugalPump with arguments
      * torque
      * water-flow
      * pump-length
# ---8<--- [end:pump-inst]

    drive-mechanism is an ElectricalDriveMechanism with arguments
      * torque
      * drive-length

  goal-requirements
    provide-torque: drive-mechanism must provide torque to pump

  need
    IP68: drive-mechanism must be IP68 compliant


# ---8<--- [start:pump-def]
define component CentrifugalPump
  parameters
    torque is a MechanicalEnergyFlow
    water-flow is a LiquidMaterialFlow
    length is a SpatialMeasure property

  transformation-requirements
    convert-torque: must convert torque into water-flow
# ---8<--- [end:pump-def]

define component ElectricalDriveMechanism
  parameters
    torque is a MechanicalEnergyFlow
    length is a SpatialMeasure property

  variables
    power-potential is an EnergyPotential
    power is an ElectricalEnergyFlow
    motor-control-signal is a ControlSignal

  transformation-requirements
    convert-power-potential: must convert power-potential into torque

  components
    power-source is a Battery with arguments
      * power-potential
      * power

    motor is a BrushlessMotor with arguments
      * power
      * torque

    power-switch is a Switch with arguments
      * motor-control-signal

  goal-requirements
    provide-power: power-source must provide power to motor
    send-control-signal: power-switch must send motor-control-signal to power-source

  behavior-requirements
    toggle-power:
      case on:
        when
          * c1: motor-control-signal is equal to True [-]
        then
          * r1: power must be at least 300 [W]
      case off:
        when no other case applies
        then
          * r2: power must be equal to 0 [W]


define component BrushlessMotor
  parameters
    power is an ElectricalEnergyFlow
    torque is a MechanicalEnergyFlow

  transformation-requirements
    convert-power: must convert power into torque


define component Battery
  parameters
    power-potential is an EnergyPotential
    power is an ElectricalEnergyFlow

  transformation-constraints
    convert-potential: does convert power-potential into power


define component Switch
  parameters
    motor-control-signal is a ControlSignal

So instead of the earlier "variables", it now has "parameters". Parameters of a definition are the variables that are expected to be supplied as arguments when you create an instance of the definition.

Properties

We also added a dimension parameter, length. The property keyword is added to this parameter, as this is a typical characteristic of the drive mechanism component.

Warning

Note that by definition flows cannot be properties of components as they flow through the system. As such, no single component owns a flow. Flows are variables that are involved in goal- or transformation-requirements and constraints. The flows in this definition are the torque and water-flow.

Arguments

The definition of parameters means that the instantiation of the components living in the world has also changed. The parameters you set in a definition are required to be provided at each instantiation. Let's review this for the pump component instance:

world.esl
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
world
  variables
    torque is a MechanicalEnergyFlow
    water-flow is a LiquidMaterialFlow
    drive-length is a SpatialMeasure
    pump-length is a SpatialMeasure
  components
    pump is a CentrifugalPump with arguments
      * torque
      * water-flow
      * pump-length
world.esl
  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
# Specification of a drive-mechanism driving a pump.
define type
  MechanicalEnergyFlow is a real with unit Nm
  ElectricalEnergyFlow is a real with unit W
  LiquidMaterialFlow is a real with unit L/s
  EnergyPotential is a real with unit Wh
  ControlSignal is a boolean
  Distance is a real with unit m
  SpatialMeasure is a Distance of at least 0.0 [m]


define verb
  provide to
  convert into
  send to

# ---8<--- [start:world-vars]
world
  variables
    torque is a MechanicalEnergyFlow
    water-flow is a LiquidMaterialFlow
    drive-length is a SpatialMeasure
    pump-length is a SpatialMeasure
# ---8<--- [end:world-vars]

  design-requirements
    min-water-flow: water-flow must be at least 1.0 [L/s]

  design-constraints
    dc-drive-length: drive-length must be equal to pump-length

# ---8<--- [start:pump-inst]
  components
    pump is a CentrifugalPump with arguments
      * torque
      * water-flow
      * pump-length
# ---8<--- [end:pump-inst]

    drive-mechanism is an ElectricalDriveMechanism with arguments
      * torque
      * drive-length

  goal-requirements
    provide-torque: drive-mechanism must provide torque to pump

  need
    IP68: drive-mechanism must be IP68 compliant


# ---8<--- [start:pump-def]
define component CentrifugalPump
  parameters
    torque is a MechanicalEnergyFlow
    water-flow is a LiquidMaterialFlow
    length is a SpatialMeasure property

  transformation-requirements
    convert-torque: must convert torque into water-flow
# ---8<--- [end:pump-def]

define component ElectricalDriveMechanism
  parameters
    torque is a MechanicalEnergyFlow
    length is a SpatialMeasure property

  variables
    power-potential is an EnergyPotential
    power is an ElectricalEnergyFlow
    motor-control-signal is a ControlSignal

  transformation-requirements
    convert-power-potential: must convert power-potential into torque

  components
    power-source is a Battery with arguments
      * power-potential
      * power

    motor is a BrushlessMotor with arguments
      * power
      * torque

    power-switch is a Switch with arguments
      * motor-control-signal

  goal-requirements
    provide-power: power-source must provide power to motor
    send-control-signal: power-switch must send motor-control-signal to power-source

  behavior-requirements
    toggle-power:
      case on:
        when
          * c1: motor-control-signal is equal to True [-]
        then
          * r1: power must be at least 300 [W]
      case off:
        when no other case applies
        then
          * r2: power must be equal to 0 [W]


define component BrushlessMotor
  parameters
    power is an ElectricalEnergyFlow
    torque is a MechanicalEnergyFlow

  transformation-requirements
    convert-power: must convert power into torque


define component Battery
  parameters
    power-potential is an EnergyPotential
    power is an ElectricalEnergyFlow

  transformation-constraints
    convert-potential: does convert power-potential into power


define component Switch
  parameters
    motor-control-signal is a ControlSignal

Here, the required parameters of the CentrifugalPump definition are provided by means of the with arguments keywords followed by an argument list.

This list is positional, meaning that the arguments are mapped to the parameters by the order in which they are defined and provided.

An argument list may be of the inline form foo is a Foo with arguments bar, baz, quux or the multi-line form as shown in the snippet: using an asterisk (*) list.

Note

Note that we do have to specify the spatial type both at the world level and in the CentrifugalPump's parameters. The compiler will alert you if any type mismatches are found between parameters and the provided arguments.

Parameters versus arguments

We use parameters in definitions and (with) arguments in instantiations. This distinction is often encountered in programming languages and to translate Robert Nystrom's1 excellent definition to our terminology of 'definitions' and 'instantiations':

  • An argument is an actual variable representing a value you pass to an instantiation when you call it. So an instantiation call has an argument list. Sometimes you hear actual parameter used for these.
  • A parameter is a variable that holds the value of the argument inside the body of the definition. Thus, a function declaration has a parameter list. Others call these formal parameters or simply formals.

Next!

Press next (or N on your keyboard) to head over to the next page! P is for Previous.

  1. R. Nystrom. Crafting Interpreters. Genever Benning, 2021. ISBN 9780990582939. ↩