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 centimetre). 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 following 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:

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:

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 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. 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 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 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 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 '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

Your system admin can define custom units in the admin interface. Feel free to get in touch if you have suggestions for additional default units.