Unit conversion

Unit conversion allows you to connect a physical unit to a Vali. For each calculation with this Vali, the necessary conversion will be performed automatically in the back end. The Pint library is used as the backbone for this.

unit-conversion gif

For example, you can specify a formula $vali3 = $vali1 + $vali2 using $vali1 = 10 meter and vali2 = 100 cm. If you set the unit of vali3 to yd (yard) you will have this result automatically calculated and converted: 12.030 yd. If you don't specify a unit for vali3, there will be a unit calculated automatically (in this case it would be meter or centimeter). The unit of each vali is the same for all users viewing the vali. All supported units and constants are listed below.

Unit conversion can be switched on or off. Additionally, it is possible to switch on or off 'strict' unit conversion. These settings are set per Valispace deployment and are defined in the configuration part of the administration pages. In strict mode you are not allowed to have inconsistencies in the unit calculations and it is not be possible to specify a unit for a Vali which is not in accordance with the dimensionality of the calculated result for this Vali. In non-strict mode these are allowed, but warnings will be displayed when units don't match.

Strict mode

Creating a Vali

When creating a new Vali in strict mode, the unit must be in line with the specified formula. The expected behaviour depending on the different creation options are:

Vali creation options Expected behaviour
numerical value and no unit a dimensionless value is created
numerical value and a specified unit a value with the specified unit is created
a formula and no unit the unit will be automatically calculated from the formula
a formula and a custom unit
  • if the calculated unit from the formula has a valid conversion to the user specified unit, the Vali will be displayed in the specified unit
  • if a conversion is not possible an empty Vali (with value 0) will be created with the user specified unit
Vali with a type the unit will be automatically taken from the type unit (it is possible to change it afterwards as long as you stay within the same dimensionality)

Changing units

Numerical values

If a Vali is just a numerical value (not a formula), and it is not used in any other formula, you can change the unit e.g. from m to s without any error. The value will simply become 100 s instead of 100 m. When a unit is changed to something that is a valid conversion (e.g. s to ms or m/s to km/s), the value will be recalculated and changed to the corresponding value after conversion, e.g 100 s = 100 000 ms. This is the same behaviour as in the non-strict mode.

If a Vali has a numerical formula, but it is used in any other formula, it will not be possible to change the unit to something that is not a valid unit conversion.

Formulas

If a Vali has a formula, the formula decides the expected unit depending on the variables used. In strict mode you can choose to display the value in any unit which is a valid conversion from the formula's unit. Changing the display unit from m/s to km/s will change the value accordingly, but it is not possible to change from m/s to m, since this is not a valid conversion.

Dimensionless values

Dimensionless values can be used in multiplications and divisions, but not in additions and subtractions with values that have a unit, because the units will not be compatible. All values that have a unit should be saved as Valis with a unit and used as parameters in formulas (meaning that no 'magic' numbers should be used).

Units that are not recognized ('undefined units') are also considered dimensionless.

Non-strict mode

Creating a Vali

When creating a new Vali in non-strict mode, the unit is specified by the user at creation time. The expected behaviours depending on the different creation options are:

Vali creation options Expected behaviour
numerical value and no unit a dimensionless value is created
numerical value and a specified unit a value with the specified unit is created
a formula and no unit the unit will be automatically calculated from the formula
a formula and a custom unit the Vali will be displayed in the user specified unit. If there is no valid conversion between the formula's unit and the user specified unit, a warning (warning code 2160) will be shown.
Vali with a type the unit will be automatically taken from the type unit

Changing units

Numerical values

If a Vali is just a numerical value (not a formula), you can change the unit e.g. from m to s without a warning, as long as the Vali is not used in any other formula. The value will simply become 100 s instead of 100 m. When a unit is changed to something that is a valid conversion (e.g. s to ms or m/s to km/s), the value will be recalcuated and changed to the corresponding value after conversion, e.g 100 s = 100 000 ms.

If a Vali is a numerical formula but it is used in any other formula, it is not possible to change the unit to something that is not a valid unit conversion. This prevents an accumulation of unit conversion issues.

Formulas

If a Vali has a formula, the formula decides the expected unit depending on the parameters used in the formula. In non-strict mode you can choose to display the value in any unit, but a warning will show if the display unit does not match the formula's calculated unit. Changing the display unit from m/s to km/s will change the value accordingly, because this is a valid conversion.

If the Vali is used in another formula, it will not be possible to change the unit to a non-compatible one.

Example:

satellite.speed = 12 000 m/s
satellite.velocity.X = $satellite.speed = 12 000 m/s

After changing the unit of satellite.velocity.X to the valid conversion unit km/s:

satellite.speed = 12 000 m/s
satellite.velocity.X = $satellite.speed = 12 km/s

After changing the unit of satellite.velocity.X to a non-valid conversion unit m:

satellite.speed = 12 000 m/s
satellite.velocity.X = $satellite.speed = 12 000 m (and a warning with code 2160 is created)

Dimensionless values

Dimensionless Valis or Valis with undefined units can be used in any formula, but a warning (with code 2150) will be created if the units are not compatible. Dimensionless values, as well as incompatible unit additions, will be calculated with the absolute values and will be shown in the chosen display unit. So the formula 10 [cm] + 5 [-], chosen to be displayed in m will give you 15 m (addition of the absolute values). Likewise, the formula 10 [cm] + 5 [kg], would not be able to resolve a valid unit conversion and will be calculated as 15 regardless of its display unit.

Undefined units

A separate setting is available to allow the use of undefined units. If this enabled (default setting), it is possible to add units that are not supported but a warning will be created. If this is disabled, it is not possible to give a Vali an undefined unit.

Changing Valitype units

A unit of a Valitype can only be changed to a different unit that has the same dimensionality as the original unit. This change will not affect any existing Valis of that type, but new Valis created with this Valitype will have the new unit.

Requirements and worst cases

Requirements (min/max values) and worst cases are always displayed in the same unit as the Vali unit. If the unit is changed, the requirements and worst cases will also be recalculated to correspond to the selected unit.

Supported units and constants

Valispace supports all the default units and conversions defined in the Pint library, as well as the default constants.

A couple of modifications are by default foreseen in Valispace:

  • Case sensitivity for unit recognition is switched off (not for prefixes). For example you can define a resistance in ohm, Ohm or OHM.
  • Hour is be abbreviated as 'h' or 'hr'. 'h' cannot be used to represent the Planck constant, for that 'planck_constant' should be used.
  • Euro and dollar are supported as units, but no conversion is implemented between them. They are abbreviated as 'EUR' or 'euro' and 'USD' and 'dollar' respectively.
  • 'dB' do not map to 'decibarn' as it would in the default unit list, but is mapped to its own dimensionless unit 'decibel'. Other logarithmic units (e.g. dBW) are considered as undefined units and so are handled the same way as dimensionless units. No automatic conversion is foreseen between linear and logarithmic scale (e.g. dBW to W).

Pay attention when using the automatic conversion for temperature values. Temperatures are 'non-multiplicative' units and have some particular behaviour, which is explained in more detail in the Pint documentation.

The following prefixes can be used:

Decimal prefixes

yocto- = 1e-24 = y-  
zepto- = 1e-21 = z-  
atto- =  1e-18 = a-  
femto- = 1e-15 = f-  
pico- =  1e-12 = p-  
nano- =  1e-9  = n-  
micro- = 1e-6  = u- = ยต-  
milli- = 1e-3  = m-  
centi- = 1e-2  = c-  
deci- =  1e-1  = d-  
deca- =  1e+1  = da- = deka  
hecto- = 1e2   = h-  
kilo- =  1e3   = k-  
mega- =  1e6   = M-  
giga- =  1e9   = G-  
tera- =  1e12  = T-  
peta- =  1e15  = P-  
exa- =   1e18  = E-  
zetta- = 1e21  = Z-  
yotta- = 1e24  = Y-  

Binary prefixes

kibi- = 2^10 = Ki-  
mebi- = 2^20 = Mi-  
gibi- = 2^30 = Gi-  
tebi- = 2^40 = Ti-  
pebi- = 2^50 = Pi-  
exbi- = 2^60 = Ei-  
zebi- = 2^70 = Zi-  
yobi- = 2^80 = Yi-  

Any combination of prefix and unit can be used, for example ks = kiloseconds, since both the prefix and unit are defined (1 kilosecond = 1000 seconds).

Unsupported units

Using operators as units is not supported. For example %, -, &, $, #. These Valis will be treated as dimensionless and a warning (with code 2115) will be created. For example, the unit % will not be treated as a percentage (50% = 0.5) but as the raw value (50).

Custom units

It is possible for your system admin to define custom units in the admin interface. Feel free to get in touch if you have suggestions for additional default units.