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. Figure Unit Conversion shows how 50 kg are automatically converted into 110.23 pounds (lbs) since the Value+Unit field contains 50 kg but the Display Unit is “lbs”. Also prefixes and suffixes are automatically applied, as exemplified when converting the Display Unit of the Mass Vali from “kg” to “g” in the video. Note that the units should match and any mismatch is indicated by an exclamation point on the Vali name by Valispace.

Furthermore, you can specify a formula $vali3 = $vali1 + $vali2 using $vali1 = 10 meter and vali2 = 100 cm. If you set the Display Unit of vali3 to yd (yard) you will have this result automatically calculated and converted: 12.030 yd. If you don't specify a Display 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 in the Pint Library.

Handling Units on Valis and Formulas

Creating a Vali

When creating a new Vali (numerical value or formula) there are two important property fields:

• Formula and Unit (mandatory)

  • For numerical values (e.g. 50 kg) this field must contain the value and the unit

  • For formulas (e.g. $wheel1.mass+$wheel2.mass) the unit results from the calculation.

• Display Unit (optional - if empty the Display Unit will be based by on Units from the Formula and Unit field)

The Table below shows a summary of the expected behaviour for Vali creation, depending on the different creation options:

Changing units

Display Unit Field

It is always possible to change the Display Unit field as long as the Display Unit matches a valid conversion from the used (or through formulas calculated) unit from the Formula and Unit field. If there is a dimension mismatch, Valispace will indicate this with an exclamation point and a message on the Vali.

When the Display Unit is changed to something that is a valid conversion (e.g. s to ms or m/s to km/s), the Vali will be recalculated and displayed in the corresponding unit after conversion, e.g 100 s = 100 000 ms.

Formula and Unit Field

If a Vali is just a numerical value (not a formula), you can change the unit e.g. from m to s. The Vali will simply become 100 s instead of 100 m. However, if after the change, the Display Unit does not match dimensionally the new unit then Valispace will indicate a dimension mismatch and the Display Unit needs to be adjusted.

Formulas

If a Vali has a formula, the formula decides the expected unit depending on the variables used. You can choose to display the value in any unit (by using the Display Unit field) which is a valid conversion from the formula's unit. Changing the Display Unit from m/s to km/s will display the value accordingly. It is possible to change the Display Unit from m/s to m but Valispace will indicate a unit dimension issue.

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 Valis that have a unit should be saved as values with a unit (in the Formula and Unit field) 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.

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.

Please note while working with units in Valispace:

• Units and prefixes are case sensitive. For example, kilogram should always be “kg“ and never “Kg“ or “KG“. Please keep the unit Pint Library in mind when working with units and you are not sure about the capitalization.

• 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, and their conversion was fixed at 1 EUR = 1.123 USD (this conversion can be changed in the Admin Panel to match current economics). 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)

• For temperature units please use degC, degF and degK (or here also just K)

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

Admins can define custom units in the Settings page, which is visible only to admin users. Admins can create custom units that are not defined in the Pint library. To access the Custom Units settings, click on the Settings icon(1) and navigate to the Custom Units(2) section within the settings menu.

The admins can add new custom units by clicking on the + icon or “Add custom unit”(3) and define the units with the existing units in the pint library.