Units and Automatic Unit Conversions
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.
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 possible to specify a unit for a Vali which is not in accordance with the dimensionality of the calculated result for this Vali. In nonstrict 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 behavior 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 

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 behavior as in the nonstrict 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.
Nonstrict mode
Creating a Vali
When creating a new Vali in nonstrict mode, the unit is specified by the user at creation time. The expected behaviors 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 recalculated and changed to the corresponding value after conversion, e.g 100 s = 100 000 ms
.
If a Vali is a numerical formula but 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 nonstrict 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 noncompatible one. You can also copy and paste formulas from one Vali to another.
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 nonvalid 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 is 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 the 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 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' does 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 scales (e.g. dBW to W).
Pay attention when using the automatic conversion for temperature values. Temperatures are 'nonmultiplicative' units and have some particular behavior, which is explained in more detail in the Pint documentation.
The following prefixes can be used:
Decimal prefixes
yocto = 1e24 = y
zepto = 1e21 = z
atto = 1e18 = a
femto = 1e15 = f
pico = 1e12 = p
nano = 1e9 = n
micro = 1e6 = u = ยต
milli = 1e3 = m
centi = 1e2 = c
deci = 1e1 = 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.