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.

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, 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

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.