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

The example below shows how 50 kg are automatically converted into 110.23 pounds (lbs) since the Formula and unit field contains 50kg 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 example below.

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 do not specify a Display unit for vali3, there will be a unit calculated automatically (in this case, it would be meter or centimeter).

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 behavior 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, Requirements Portal 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, for example, from m to s. The Vali will become 100 s instead of 100 m. However, if after the change, the display unit does not match dimensionally, the new unit then Requirements Portal 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 Requirements Portal 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

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

When working with units in Requirements Portal, note the following:

• 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, planck_constant should be used for that.

• 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, 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 behavior, 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. 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 (those that are not defined in the Pint library) on the Settings – Custom Units page (accessed by clicking the  icon at the bottom left, selecting Settings from the menu that appears, and then selecting Custom Units from list in the left-hand pane). To create a new custom unit, clicking on the  button at the top right and define the units based on the existing units in the Pint library.