Skip to content

Relations

Variables are powerful in themselves, but they can be interdependent, too. They may be coupled via mathematical equations, models, laws of physics, or any other means of interdependency. We signal this by defining relations between them. Relations can have names and arguments. The explicit math or implementation is not covered in ESL. This is intentional, as the language is not designed to replace all kinds of complex computation environments and languages. Instead, we provide means to accurately capture the dependencies.

Lets say we want to describe the battery's efficiency as a relation between power potential (chemical) and the output power (electrical):

Definition

world.esl
1
2
3
4
5
define relation
  BatteryEfficiencyModel
    relating parameters
      * potential is an EnergyPotential
      * output is an ElectricalEnergyFlow
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
125
126
127
128
129
130
131
132
133
134
135
136
137
# 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:definition]
define relation
  BatteryEfficiencyModel
    relating parameters
      * potential is an EnergyPotential
      * output is an ElectricalEnergyFlow
# ---8<--- [end:definition]


world
  variables
    torque is a MechanicalEnergyFlow
    water-flow is a LiquidMaterialFlow
    drive-length is a SpatialMeasure
    pump-length is a SpatialMeasure

  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

  components
    pump is a CentrifugalPump with arguments
      * torque
      * water-flow
      * pump-length

    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


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


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


# ---8<--- [start:battery]
define component Battery
  parameters
    power-potential is an EnergyPotential
    power is an ElectricalEnergyFlow

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

  relations
    efficiency-model: BatteryEfficiencyModel
      relating arguments
        * power-potential
        * power
# ---8<--- [end:battery]


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

Here we define an undirected relation using the syntax [name] relating parameters followed by an ordered parameter list using * [name] is a [type].

Relating, requiring, returning

By using a relating parameters section, you include "undirected" parameters to a relation. This means that these variables are related, but the (model to do the) calculation does not distinguish typical input or output parameters. Think Newton's second law of physics, \(F = m \cdot a\), where you could calculate each of the variables if you were given the other two. It isn't a one-way computer program existing somewhere next to the ESL specification, but rather an interaction you could signal between the given parameters.

However, when you want to express that some relation or model (partially) works in a directed fashion, you can also include a requiring parameters section on a new line for typical input parameters and a returning parameters section on another new line for typical output parameters. You are allowed to include all three sections in a relation, but only one of each kind such that this is a valid example including all three:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
define relations
  Foo
    relating parameters
      * bar is a string  # undirected

    requiring parameters
      * baz is a real    # inputs

    returning parameters
      * quux is a boolean   # outputs

Instantiation

This relation is then instantiated in the relations section of the Battery component definition, which now looks like:

world.esl
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
define component Battery
  parameters
    power-potential is an EnergyPotential
    power is an ElectricalEnergyFlow

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

  relations
    efficiency-model: BatteryEfficiencyModel
      relating arguments
        * power-potential
        * power
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
125
126
127
128
129
130
131
132
133
134
135
136
137
# 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:definition]
define relation
  BatteryEfficiencyModel
    relating parameters
      * potential is an EnergyPotential
      * output is an ElectricalEnergyFlow
# ---8<--- [end:definition]


world
  variables
    torque is a MechanicalEnergyFlow
    water-flow is a LiquidMaterialFlow
    drive-length is a SpatialMeasure
    pump-length is a SpatialMeasure

  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

  components
    pump is a CentrifugalPump with arguments
      * torque
      * water-flow
      * pump-length

    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


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


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


# ---8<--- [start:battery]
define component Battery
  parameters
    power-potential is an EnergyPotential
    power is an ElectricalEnergyFlow

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

  relations
    efficiency-model: BatteryEfficiencyModel
      relating arguments
        * power-potential
        * power
# ---8<--- [end:battery]


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

Note

Note the use of relating arguments during instantiation versus relating parameters during definition.

See the Parameters versus arguments section from before for the explanation for this distinction.

Next!

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