This page briefly describes Units Signatures and how they are used in Kornucopia. Units Signatures are one of the key technology components behind the Kornucopia Units Engine. While you, the user, never directly interact with these Units Signatures per say, they are used extensively by Kornucopia within its internal tracking and calculations related to Units. The purpose of this page is to briefly describe what they are and how they work so that you can better understand how Kornucopia robustly handles Units.
Listed below are the Kornucopia Units Signature categories:
Primary Signatures and their Principal Unit
length: m (meter)
mass: kg (kilogram)
current: A (ampere)
substance: mol (mole)
luminousIntensity: cd (candela)
currency: currency (generic financial currency for money)
item: item (for tracking "items" or "things". This is a very generic type of unit signature) Added in Kornucopia V5.2-01
time: s (second)
absTemperature: K (Kelvin)
Additional Signatures and their Principal Unit
celsius: degC (Celsius)
fahrenheit: degF (Fahrenheit)
angle: rad (radian)
frequency: Hz (Hertz)
percent: % (percent)
microStrain: uStrain (microStrain) Added in Kornucopia V5.2-01
Each of the Units Signatures above has an associated Principal Unit. When Kornucopia stores and tracks any entity of data type k_units or a Kornucopia compatible data type, it ultimately internally relates any Unit being used as some combination of these Units Signatures and their Principal Units. It is noted that an entity with no units is dimensionless; Kornucopia tracks this also. It is further noted that Kornucopia gives special attention to Units for Celsius or Fahrenheit temperatures, as well as Units related to angle, frequency, percent and microStrain.
Kornucopia's Unit Signatures are divided into two groups, Primary Signatures and Additional Signatures.
The Primary Signatures are truly fundamental independent quantities, meaning one Primary Signature is not derivable from any of the other Primary Signatures. A few examples of how a Unit is represented and tracked internally by Kornucopia's Unit Signatures are listed below.
The unit m (meter) gets tracked as 1*length in terms of its Units Signature.
The unit in (inch) gets tracked as 0.0254*length in terms of its Units Signature.
The unit N (Newton) gets tracked as 1*length*mass/(time^2) in terms of its Units Signature.
The unit lbf (pound force) gets tracked as 4.4482216152605*length*mass/(time^2) in terms of its Units Signature.
The unit cal (calorie) gets tracked as 4.1868*(length^2)*mass/(time^2) in terms of its Units Signature.
When Kornucopia performs math operations such as addition, subtraction, multiplication, division, raise to a power, etc., the software internally checks and utilizes the Units Signature information to ensure an accurate and valid calculation, from a Units perspective. This allows you to freely use mixed units in your calculation, such as using the Unit of N and lbf in the same calculation. Kornucopia will handle all needed conversions and Units compatibility checking for you. The Units returned in all math operations (and other math related calculations) are controlled by the active Units Preference (see Units Library and Units Preferences and/or k_unitsPreferenceActivate). Moreover, when you attempt to perform an invalid Units calculation, such as 5*N + 3*kg, Kornucopia issues an error stating there is an incompatible units error because two units do not resolve to the same primary units signature.
A unique feature of Kornucopia's Units Engine is that it does additional special units-related tracking of Celsius and Fahrenheit temperature Units, as well as Units related to angle, frequency, percent and microStrain. This additional tracking is needed to help ensure that calculations related to these items are done correctly and robustly.
The meaning and conversion of temperatures using Units of Celsius and Fahrenheit can be problematic due to their potentially affine nature.
When a temperature defined in terms of Celsius or Fahrenheit is NOT representing a change in temperature (so called delta temperature), the relationship between Celsius and Fahrenheit is defined by the equation of a line (meaning a multiplication factor plus an offset). The same is true between either of these temperature Units and either of the absolute temperature Units of Kelvin or Rankine. This affine case must be handled with special care as it does not obey the typical multiplicative Units conversion rules. Kornucopia has special features and internal algorithms to do this special handling.
When a temperature defined in terms of Celsius or Fahrenheit IS representing a change in temperature (so called delta temperature), the relationship between Celsius and Fahrenheit is defined by only a multiplicative conversion factor (just like all other units such as m, in, N, lbf, etc.). The same is true between either of these temperature Units and either of the absolute temperature Units of Kelvin or Rankine. This non-affine case is handled with the typical multiplicative Units conversion rules.
The problem: When you define a variable, say T1 = 100*degC, and then you need or want to convert this temperature to either Fahrenheit, Kelvin, or Rankine, the conversion is NOT clear. From your simple variable definition, there is no information clearly stating if the T1 temperature is a change in temperature or not. So the method of conversion, affine or non-affine, is not clear. This issue occurs whenever you have Celsius or Fahrenheit temperature Units.
The solution: Kornucopia provides a clear and flexible solution to this problem through the optional ADV argument 'affine' that can be used with the function k_unitsConvert or the k_units data type method convert. It is noted that if you attempt to perform a Unit's conversion starting with or converting to a Unit of Celsius or Fahrenheit and you do not specify the ADV setting of 'affine', then an appropriate error message will be returned instructing you to add this to your command.
Additional information and examples related to working with temperature Units and the use of the 'affine' ADV option are found on the help page Temperature and Frequency.
Kornucopia performs additional internal tracking of Units related to frequency, angular frequency, and angles due to potential difficulties with these types of quantities. This additional tracking allows Kornucopia to automatically convert, in many cases (but not all cases) between Units of frequency (containing some form of a hertz Unit such as Hz, kHz, MHz, etc.) and Units like rpm (revolutions per minute), rad/s, 1/s, etc. The additional tracking enables Kornucopia to tell the difference between 1/s and rad/s (where most software that tracks units cannot do this). This also carries through to enable seamless use of deg (as in angular degree), rad, and rev (as in revolution) in calculations.
It is noted above that there are limitations to Kornucopia's ability to fully track these sets of units. This mostly derives around the challenge of knowing tracking intent when using angular frequency, such as rad/s. There are several cases where calculations using such units are difficult to know intent when and if the user attempts to switch between angular frequency and frequency (typically represented in Units of Hz (or similar) or 1/s. This is not a limitation in Kornucopia per say, it is a fundamental problem with how angular frequency and frequency are defined.
Additional information related to working with Units of Frequency, angular frequency, and angles is found on the help page Temperature and Frequency.
Kornucopia's additional internal tracking and logic allows you to use the Unit of percent (%) and microStrain (uStrain) with dimensionless quantities. The ultimate goal of this extra tracking is:
To allow the % Unit or the uStrain Unit to "smartly" stay with variables and entities when appropriate and then for it to disappear when appropriate (while applying the appropriate factor of 0.01 for % or 1e-6 for uStrain).
That all calculations with and without % Units process the factor of 0.01 automatically (internally) so that you, the user, are NOT placing factors of 0.01 (or 100) all over your calculations.
That all calculations with and without uStrain Units process the factor of 1e-6 automatically (internally) so that you, the user, are NOT placing factors of 1e-6 (or 1e6) all over your calculations.
The Unit of percent can be associated to dimensionless quantities such as, for example, a ratio or a variable representing strain. The percent Unit might be associated to an entity because that Unit was in a text file that was imported, or perhaps you did a Unit conversion of an entity to the Unit of percent (%). Regardless of how the percent Unit becomes associated with an entity, the Unit of percent will stay with the entity until some math operation that multiplies the entity by other quantities having some form of Units other than purely dimensionless, or until you issue a Units conversion command the converts the entity to something without percent. It is noted that a purely dimensionless entity has zero powers for all of its Units Signatures. The same comments are valid for uStrain, although you would typically only use this type of Unit for strain and not other dimensionless quantities.
The simple example below working with strain, modulus (E), and stress demonstrates the general concept of how Kornucopia allows you to naturally and easily work with percent (%) and microStrain (uStrain).
% Activate a Units Preference and
define
% Convert strain
back to uStrain Units
% Subtract 1000*uStrain,
but via a dimensionless # |
 |