Conversion/promotion

For dimensionless quantities, uconvert can be used with the NoUnits unit to strip the units without losing power-of-ten information:

You can also directly convert to a subtype of Real or Complex:

You can specify the result units for promoting quantities of a specific dimension once at the start of a Julia session. For example, you can specify that when promoting two quantities with different energy units, the resulting quantities should be in g*cm^2/s^2. This is accomplished by defining a Unitful.promote_unit method for the units themselves. Here’s an example.

If you’re wondering where Unitful.EnergyUnits comes from, it is defined in src/pkgdefaults.jl by the @derived_dimension macro. Similarly, the calls to the @dimension macro define Unitful.LengthUnits, Unitful.MassUnits, etc. None of these are exported.

Existing users of Unitful may want to call Unitful.promote_to_derived after Unitful loads to give similar behavior to Unitful 0.0.4 and below. It is not called by default.

The Unitful.preferunits function is used to designate fallback preferred units for each pure dimension for promotion. Such a fallback is required because you need some generic logic to take over when manipulating quantities with arbitrary dimensions.

The default behavior is to promote to a combination of the base SI units, i.e. a quantity of dimension 𝐌*𝐋^2/(𝐓^2*𝚯) would be converted to kg*m^2/(s^2*K):

You can however override this behavior by calling Unitful.preferunits at the start of a Julia session, specifically before Unitful.upreferred has been called or quantities have been promoted.

Arrays are typed with as much specificity as possible upon creation. consider the following three cases:

In the first case, an array with a concrete type is created. Good performance should be attainable. The second case invokes promotion so that an array of concrete type can be created. The third case falls back to an abstract type, which cannot be stored efficiently and will incur a performance penalty. An additional benefit of having a concrete type is that we can dispatch on the dimensions of the array’s elements:

Sometimes, a package may want to default to a particular behavior for promotion, in the presence of other packages that may require differing default behaviors. An example would be a CAD package for nanoscale device design: it makes more sense to promote to nanometers or microns than to meters. For this purpose we define Unitful.ContextUnits{N,D,P,A}. The P in this type signature should be some type Unitful.FreeUnits{M,D,B} (the dimensions must be the same). We refer to this as the "context." ContextUnits may be easily instantiated by e.g. ContextUnits(nm, μm) for a nm unit that will promote to μm. Here’s an example:

If the context does not agree, then we fall back to FreeUnits:

Multiplying a ContextUnits by a FreeUnits yields a ContextUnits object, with the preferred units for the additional dimensions being determined by calling Unitful.upreferred on the FreeUnits object:

Sometimes, there may be times where it is required to disable automatic conversion between quantities with different units. For this purpose there are Unitful.FixedUnits{N,D,A}. Trying to add or compare two quantities with FixedUnits will throw an error, provided the units are not the same. Note that you can still add/compare a quantity with FixedUnits to a quantity with another kind of units; in that case, the result units (if applicable) are determined by the FixedUnits, overriding the preferred units from ContextUnits or FreeUnits. Multiplying FixedUnits with any other kind of units returns FixedUnits:

Much of this functionality is enabled by promote_unit definitions. These are not readily extensible by the user at this point.