From 587b304e43890779f9841c31da603b5fc62a69e6 Mon Sep 17 00:00:00 2001 From: "Documenter.jl" Date: Wed, 30 Oct 2024 08:00:02 +0000 Subject: [PATCH] build based on 601f9e1 --- dev/.documenter-siteinfo.json | 2 +- dev/LICENSE/index.html | 2 +- dev/conversion/index.html | 14 +++++++------- dev/dates/index.html | 4 ++-- dev/defaultunits/index.html | 2 +- dev/display/index.html | 2 +- dev/extending/index.html | 2 +- dev/highlights/index.html | 2 +- dev/index.html | 2 +- dev/logarithm/index.html | 12 ++++++------ dev/manipulations/index.html | 28 ++++++++++++++-------------- dev/newunits/index.html | 2 +- dev/temperature/index.html | 4 ++-- dev/trouble/index.html | 2 +- dev/types/index.html | 8 ++++---- 15 files changed, 44 insertions(+), 44 deletions(-) diff --git a/dev/.documenter-siteinfo.json b/dev/.documenter-siteinfo.json index 3b039573..4ba388ee 100644 --- a/dev/.documenter-siteinfo.json +++ b/dev/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.10.5","generation_timestamp":"2024-10-04T14:11:18","documenter_version":"1.7.0"}} \ No newline at end of file +{"documenter":{"julia_version":"1.11.1","generation_timestamp":"2024-10-30T07:59:56","documenter_version":"1.7.0"}} \ No newline at end of file diff --git a/dev/LICENSE/index.html b/dev/LICENSE/index.html index 0fe3d621..2bcc2542 100644 --- a/dev/LICENSE/index.html +++ b/dev/LICENSE/index.html @@ -1,2 +1,2 @@ -License · Unitful.jl
GitHub

License

The Unitful.jl package is licensed under the MIT "Expat" License:

Copyright (c) 2016: California Institute of Technology and other contributors.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Portions borrow from EngUnits.jl, which is (c) 2016: Daniel Høegh. Unitful.jl's fastmath implementation and tests draw heavily on those found in Julia.

Neither the name of the California Institute of Technology (“Caltech”) nor the names of its contributors (and/or sponsors) may be used to endorse or promote products derived from this software without specific prior written permission.

Andrew Keller (original package author, assigning his copyright to California Institute of Technology) acknowledges the support of an IQIM Postdoctoral Scholarship (Institute for Quantum Information and Matter, an NSF Physics Frontiers Center, NSF Grant PHY-1125565).

+License · Unitful.jl
GitHub

License

The Unitful.jl package is licensed under the MIT "Expat" License:

Copyright (c) 2016: California Institute of Technology and other contributors.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Portions borrow from EngUnits.jl, which is (c) 2016: Daniel Høegh. Unitful.jl's fastmath implementation and tests draw heavily on those found in Julia.

Neither the name of the California Institute of Technology (“Caltech”) nor the names of its contributors (and/or sponsors) may be used to endorse or promote products derived from this software without specific prior written permission.

Andrew Keller (original package author, assigning his copyright to California Institute of Technology) acknowledges the support of an IQIM Postdoctoral Scholarship (Institute for Quantum Information and Matter, an NSF Physics Frontiers Center, NSF Grant PHY-1125565).

diff --git a/dev/conversion/index.html b/dev/conversion/index.html index 7485344d..e7b7f982 100644 --- a/dev/conversion/index.html +++ b/dev/conversion/index.html @@ -3,14 +3,14 @@ 1801//1800 hr julia> uconvert(u"J",1.0u"N*m") -1.0 Jsource

Since objects are callable, we can also make Unitful.Units callable with a Number as an argument, for a unit conversion shorthand:

julia> u"cm"(1u"m")
+1.0 J
source

Since objects are callable, we can also make Unitful.Units callable with a Number as an argument, for a unit conversion shorthand:

julia> u"cm"(1u"m")
 100 cm

This syntax is a little confusing, but becomes appealing with the function chaining operator |>:

julia> 1u"m" |> u"cm"
 100 cm

Note that since Unitful.Units objects have no fields, we don't have to worry about ambiguity with constructor calls. This way of converting units results in behavior identical to calling uconvert.

Dimensionless quantities

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

julia> uconvert(NoUnits, 1.0u"μm/m")
 1.0e-6
 
 julia> uconvert(NoUnits, 1.0u"m")
 ERROR: DimensionError:  and m are not dimensionally compatible.
Unitful.NoUnits — Constant
NoUnits

An object that represents "no units", i.e., the units of a unitless number. The type of the object is Unitful.FreeUnits{(), NoDims}. It is displayed as an empty string.

Example:

julia> unit(1.0) == NoUnits
-true
source

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

julia> convert(Float64, 1.0u"μm/m")
+true
source

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

julia> convert(Float64, 1.0u"μm/m")
 1.0e-6

Basic promotion mechanisms

We decide the result units for addition and subtraction operations based on looking at the types only. We can't take runtime values into account without compromising runtime performance.

If two quantities with the same units are added or subtracted, then the result units will be the same. If two quantities with differing units (but same dimension) are added or subtracted, then the result units will be specified by promotion.

Promotion rules for specific dimensions

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.

julia> using Unitful
 
 julia> Unitful.promote_unit(::S, ::T) where {S<:Unitful.EnergyUnits, T<:Unitful.EnergyUnits} = u"g*cm^2/s^2"
@@ -21,9 +21,9 @@
 julia> Unitful.promote_unit(::S, ::T) where {S<:Unitful.EnergyUnits, T<:Unitful.EnergyUnits} = u"J"
 
 julia> promote(2.0u"J", 1.0u"kg*m^2/s^2")
-(2.0 J, 1.0 J)

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.

Unitful.promote_to_derived — Function
Unitful.promote_to_derived()

Defines promotion rules to use derived SI units in promotion for common dimensions of quantities:

  • J (joule) for energy
  • N (newton) for force
  • W (watt) for power
  • Pa (pascal) for pressure
  • C (coulomb) for charge
  • V (volt) for voltage
  • Ω (ohm) for resistance
  • F (farad) for capacitance
  • H (henry) for inductance
  • Wb (weber) for magnetic flux
  • T (tesla) for B-field
  • J*s (joule-second) for action

If you want this as default behavior (it was for versions of Unitful prior to 0.1.0), consider invoking this function in your startup.jl file which is loaded when you open Julia. This function is not exported.

source

Fallback promotion rules

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):

julia> promote(1.0u"J/K", 1.0u"g*cm^2/s^2/K")
-(1.0 kg m^2 K^-1 s^-2, 1.0e-7 kg m^2 K^-1 s^-2)

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.

Unitful.preferunits — Function
preferunits(u0::Units, u::Units...)

This function specifies the default fallback units for promotion. Units provided to this function must have a pure dimension of power 1, like 𝐋 or 𝐓 but not 𝐋/𝐓 or 𝐋^2. The function will complain if this is not the case. Additionally, the function will complain if you provide two units with the same dimension, as a courtesy to the user. Finally, you cannot use affine units such as °C with this function.

Once Unitful.upreferred has been called or quantities have been promoted, this function will appear to have no effect.

Usage example: preferunits(u"m,s,A,K,cd,kg,mol"...)

source
Unitful.upreferred — Function
upreferred(x::Number)
-upreferred(x::Quantity)

Unit-convert x to units which are preferred for the dimensions of x. If you are using the factory defaults, this function will unit-convert to a product of powers of base SI units. If quantity x has Unitful.ContextUnits(y,z), the resulting quantity will have units ContextUnits(z,z).

source
upreferred(x::Units)

Return units which are preferred for the dimensions of x, which may or may not be equal to x, as specified by the preferunits function. If you are using the factory defaults, this function will return a product of powers of base SI units.

source
upreferred(x::Dimensions)

Return units which are preferred for dimensions x. If you are using the factory defaults, this function will return a product of powers of base SI units (as Unitful.FreeUnits).

source

Array promotion

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

julia> [1.0u"m", 2.0u"m"]
+(2.0 J, 1.0 J)

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.

Unitful.promote_to_derived — Function
Unitful.promote_to_derived()

Defines promotion rules to use derived SI units in promotion for common dimensions of quantities:

  • J (joule) for energy
  • N (newton) for force
  • W (watt) for power
  • Pa (pascal) for pressure
  • C (coulomb) for charge
  • V (volt) for voltage
  • Ω (ohm) for resistance
  • F (farad) for capacitance
  • H (henry) for inductance
  • Wb (weber) for magnetic flux
  • T (tesla) for B-field
  • J*s (joule-second) for action

If you want this as default behavior (it was for versions of Unitful prior to 0.1.0), consider invoking this function in your startup.jl file which is loaded when you open Julia. This function is not exported.

source

Fallback promotion rules

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):

julia> promote(1.0u"J/K", 1.0u"g*cm^2/s^2/K")
+(1.0 kg m^2 K^-1 s^-2, 1.0e-7 kg m^2 K^-1 s^-2)

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.

Unitful.preferunits — Function
preferunits(u0::Units, u::Units...)

This function specifies the default fallback units for promotion. Units provided to this function must have a pure dimension of power 1, like 𝐋 or 𝐓 but not 𝐋/𝐓 or 𝐋^2. The function will complain if this is not the case. Additionally, the function will complain if you provide two units with the same dimension, as a courtesy to the user. Finally, you cannot use affine units such as °C with this function.

Once Unitful.upreferred has been called or quantities have been promoted, this function will appear to have no effect.

Usage example: preferunits(u"m,s,A,K,cd,kg,mol"...)

source
Unitful.upreferred — Function
upreferred(x::Number)
+upreferred(x::Quantity)

Unit-convert x to units which are preferred for the dimensions of x. If you are using the factory defaults, this function will unit-convert to a product of powers of base SI units. If quantity x has Unitful.ContextUnits(y,z), the resulting quantity will have units ContextUnits(z,z).

source
upreferred(x::Units)

Return units which are preferred for the dimensions of x, which may or may not be equal to x, as specified by the preferunits function. If you are using the factory defaults, this function will return a product of powers of base SI units.

source
upreferred(x::Dimensions)

Return units which are preferred for dimensions x. If you are using the factory defaults, this function will return a product of powers of base SI units (as Unitful.FreeUnits).

source

Array promotion

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

julia> [1.0u"m", 2.0u"m"]
 2-element Vector{Quantity{Float64, 𝐋, Unitful.FreeUnits{(m,), 𝐋, nothing}}}:
  1.0 m
  2.0 m
@@ -104,7 +104,7 @@
 
 julia> 1mm_fix == 0.1cm_fix
 ERROR: automatic conversion prohibited.
-[...]

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

Unitful.promote_unit — Function
promote_unit(::Units, ::Units...)

Given Units objects as arguments, this function returns a Units object appropriate for the result of promoting quantities which have these units. This function is kind of like promote_rule, except that it doesn't take types. It also does not return a tuple, but rather just a Unitful.Units object (or it throws an error).

Although we had used promote_rule for Units objects in prior versions of Unitful, this was always kind of a hack; it doesn't make sense to promote units directly for a variety of reasons.

source

Unit cancellation

For multiplication and division, note that powers-of-ten prefixes are significant in unit cancellation. For instance, mV/V is not simplified, although V/V is. Also, N*m/J is not simplified: there is currently no logic to decide whether or not units on a dimensionless quantity seem "intentional" or not. It is however possible to cancel units manually, by converting the dimensionless quantity to the NoUnits unit. This takes into account different SI-prefixes:

julia> using Unitful
+[...]

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

Unitful.promote_unit — Function
promote_unit(::Units, ::Units...)

Given Units objects as arguments, this function returns a Units object appropriate for the result of promoting quantities which have these units. This function is kind of like promote_rule, except that it doesn't take types. It also does not return a tuple, but rather just a Unitful.Units object (or it throws an error).

Although we had used promote_rule for Units objects in prior versions of Unitful, this was always kind of a hack; it doesn't make sense to promote units directly for a variety of reasons.

source

Unit cancellation

For multiplication and division, note that powers-of-ten prefixes are significant in unit cancellation. For instance, mV/V is not simplified, although V/V is. Also, N*m/J is not simplified: there is currently no logic to decide whether or not units on a dimensionless quantity seem "intentional" or not. It is however possible to cancel units manually, by converting the dimensionless quantity to the NoUnits unit. This takes into account different SI-prefixes:

julia> using Unitful
 
 julia> 1u"kN*m"/4u"J" |> NoUnits
-250.0
+250.0 diff --git a/dev/dates/index.html b/dev/dates/index.html index d3683086..d271fbc9 100644 --- a/dev/dates/index.html +++ b/dev/dates/index.html @@ -2,7 +2,7 @@ Interoperability with Dates · Unitful.jl
GitHub

Interoperability with the Dates standard library

Julia's Dates standard library provides data types for representing specific points in time Date/DateTime and differences between them, i.e., periods. Unitful provides methods for using period types from the Dates standard library together with Quantitys.

Support for Dates.FixedPeriods

The Dates.FixedPeriod union type includes all Dates.Periods that represent a fixed period of time, i.e., Dates.Week, Dates.Day, Dates.Hour, Dates.Minute, Dates.Second, Dates.Millisecond, Dates.Microsecond, and Dates.Nanosecond. These types can be converted to Quantitys or used in place of them.

Note

Dates.Year does not represent a fixed period and cannot be converted to a Quantity. While Unitful's yr unit is exactly equal to 365.25 days, a Dates.Year may contain 365 or 366 days.

Each FixedPeriod is considered equivalent to a Quantity. For example, Dates.Millisecond(5) corresponds to the quantity Int64(5)*u"ms". A FixedPeriod can be converted to the equivalent Quantity with a constructor:

Unitful.Quantity — Method
Quantity(period::Dates.FixedPeriod)

Create a Quantity that corresponds to the given period. The numerical value of the resulting Quantity is of type Int64.

Example

julia> using Dates: Second
 
 julia> Quantity(Second(5))
-5 s
source

In most respects, FixedPeriods behave like their equivalent quantities. They can be converted to other units using uconvert, used in arithmetic operations with other quantities, and they have a unit and dimension:

julia> using Dates: Hour
+5 s
source

In most respects, FixedPeriods behave like their equivalent quantities. They can be converted to other units using uconvert, used in arithmetic operations with other quantities, and they have a unit and dimension:

julia> using Dates: Hour
 
 julia> p = Hour(3)
 3 hours
@@ -73,4 +73,4 @@
 [...]
 
 julia> T = typeof(1.0u"hr"); T(p)  # ... but it can be converted to a concrete time quantity
-8766.0 hr

Consequently, any operation whose result would depend on the input unit is not supported by CompoundPeriods. For example:

+8766.0 hr

Consequently, any operation whose result would depend on the input unit is not supported by CompoundPeriods. For example:

diff --git a/dev/defaultunits/index.html b/dev/defaultunits/index.html index 28c2348c..4a85ca63 100644 --- a/dev/defaultunits/index.html +++ b/dev/defaultunits/index.html @@ -9,4 +9,4 @@ See also: Unitful.W.

For prefixes, see below.

Base dimensions

Amount

Mole

Unitful.mol

The mole, the SI base unit for amount of substance.

Current

Ampere

Unitful.A

The ampere, the SI base unit of electric current.

Length

Angstrom

Unitful.angstrom
 Unitful.Å

The angstrom, a metric unit of length defined as 1/10 nm.

Unitful.ft

The foot, a US customary unit of length defined as 12 inch.

Inch

Unitful.inch

The inch, a US customary unit of length defined as 2.54 cm.

Meter

Unitful.m

The meter, the SI base unit of length.

Mile

Unitful.mi

The mile, a US customary unit of length defined as 1760 yd.

Mil

Unitful.mil

The mil, a US customary unit of length defined as 1/1000 inch.

Yard

Unitful.yd

The yard, a US customary unit of length defined as 3 ft.

Luminosity

Candela

Unitful.cd

The candela, the SI base unit of luminous intensity.

Mass

Dram

Unitful.dr

The dram, a US customary unit of mass defined as 1/16 oz.

Gram

Unitful.g

A prefixed unit, equal to 10^-3 kg. Note that kg, not g, is the base unit.

Grain

Unitful.gr

The grain, a US customary unit of mass defined as 1/7000 lb.

Kilogram

Unitful.kg

The kilogram, the SI base unit of mass. Note that kg, not g, is the base unit.

Pound

Unitful.lb

The pound-mass, a US customary unit of mass defined as exactly 0.453,592,37 kg.

Ounce

Unitful.oz

The ounce, a US customary unit of mass defined as 1/16 lb.

Slug

Unitful.slug

The slug, a US customary unit of mass defined as 1 lbf × s^2 / ft.

UnifiedAtomicMassUnit

Unitful.u

The unified atomic mass unit, or dalton, a unit of mass defined as 1/12 the mass of an unbound neutral atom of carbon-12, equal to 1.660,539,066,60 × 10^-27 kg (the CODATA 2018 recommended value).

Temperature

Kelvin

Unitful.K

The kelvin, the SI base unit of thermodynamic temperature.

Rankine

Unitful.Ra

The rankine, a US customary unit of temperature defined as 5/9 K.

Degree Celcius

Unitful.°C

The degree Celsius, an SI unit of temperature, defined such that 0 °C = 273.15 K.

Degree Fahrenheit

Unitful.°F

The degree Fahrenheit, a US customary unit of temperature, defined such that 0 °F = 459.67 Ra.

Time

Day

Unitful.d

The day, a unit of time defined as 24 hr.

Hour

Unitful.hr

The hour, a unit of time defined as 60 minutes.

Minute

Unitful.minute

The minute, a unit of time defined as 60 s. The full name minute is used instead of the symbol min to avoid confusion with the Julia function min.

Second

Unitful.s

The second, the SI base unit of time.

Week

Unitful.wk

The week, a unit of time, defined as 7 d.

Year

Unitful.yr

The year, a unit of time, defined as 365.25 d.

Derived dimensions

Acceleration

Gal

Unitful.Gal

The gal, a CGS unit of acceleration, defined as 1 cm / s^2.

EarthGravity

Unitful.ge

The nominal acceleration due to gravity in a vacuum near the surface of the earth, a unit of acceleration, defined by standard to be exactly 9.806,65 m / s^2.

Unitful.gn is a quantity (with units m/s^2) whereas Unitful.ge is a unit equal to gn.

Area

Are

Unitful.a

The are, a metric unit of area, defined as 100 m^2.

Acre

Unitful.ac

The acre, a US customary unit of area defined as 4840 yd^2.

Barn

Unitful.b

The barn, a metric unit of area, defined as 100 fm^2.

Hectare

Unitful.ha

The hectare, a metric unit of area, defined as 100 a.

BField

Gauss

Unitful.Gauss

The gauss, a CGS unit of magnetic B-field strength, defined as 1 Mx / cm^2.

Tesla

Unitful.T

The tesla, an SI unit of magnetic B-field strength, defined as 1 kg / (A × s^2).

Capacitance

Farad

Unitful.F

The farad, an SI unit of electrical capacitance, defined as 1 s^4 × A^2 / (kg × m^2).

Charge

Coulomb

Unitful.C

The coulomb, an SI unit of electric charge, defined as 1 A × s.

DynamicViscosity

Poise

Unitful.P

The poise, a CGS unit of dynamic viscosity, defined as 1 dyn × s / cm^2.

ElectricalConductance

Siemens

Unitful.S

The siemens, an SI unit of electrical conductance, defined as 1 Ω^-1.

ElectricalResistance

Ohm

Unitful.Ω

The ohm, an SI unit of electrical resistance, defined as 1 V / A.

Energy

BritishThermalUnit

Unitful.btu

The British thermal unit, a US customary unit of heat defined by ISO 31-4 as exactly 1055.06 J.

Calorie

Unitful.cal

The calorie, a unit of energy defined as exactly 4.184 J.

Erg

Unitful.erg

The erg, a CGS unit of energy, defined as 1 dyn × cm.

eV

Unitful.eV

The electron-volt, a unit of energy, defined as q*V.

Joule

Unitful.J

The joule, an SI unit of energy, defined as 1 N × m.

Force

Dyne

Unitful.dyn

The dyne, a CGS unit of force, defined as 1 g × cm / s^2.

PoundsForce

Unitful.lbf

The pound-force, a US customary unit of force defined as 1 lb × ge.

Newton

Unitful.N

The newton, an SI unit of force, defined as 1 kg × m / s^2.

Frequency

Becquerel

Unitful.Bq

The becquerel, an SI unit of radioactivity, defined as 1 nuclear decay per s.

Hertz

Unitful.Hz

The hertz, an SI unit of frequency, defined as 1 s^-1.

AngHertz

Unitful.Hz2π

A unit for convenience in angular frequency, equal to 2π Hz.

RevolutionsPerMinute

Unitful.rpm

Revolutions per minute, a unit of rotational speed, defined as 2π rad / minute.

RevolutionsPerSecond

Unitful.rps

Revolutions per second, a unit of rotational speed, defined as 2π rad / s.

HField

Oersted

Unitful.Oe

The oersted, a CGS unit of magnetic H-field strength, defined as 1000 A / (4π × m).

Inductance

Henry

Unitful.H

The henry, an SI unit of electrical inductance, defined as 1 J / A^2.

KinematicViscosity

Stokes

Unitful.St

The stokes, a CGS unit of kinematic viscosity, defined as 1 cm^2 / s.

Luminous flux

Lumen

Unitful.lm

The lumen, an SI unit of luminous flux, defined as 1 cd × sr.

MagneticFlux

Maxwell

Unitful.Mx

The maxwell, a CGS unit of magnetic flux, defined as 1 Gauss × cm^2.

Weber

Unitful.Wb

The weber, an SI unit of magnetic flux, defined as 1 kg × m^2 / (A × s^2).

MolarFlow

Katal

Unitful.kat

The katal, an SI unit of catalytic activity, defined as 1 mol of catalyzed substrate per s.

Molarity

Molar

Unitful.M

A unit for measuring molar concentration, equal to 1 mol/L.

Power

Watt

Unitful.W

The watt, an SI unit of power, defined as 1 J / s.

Pressure

Atmosphere

Unitful.atm

The standard atmosphere, a unit of pressure, defined as 101,325 Pa.

Barye

Unitful.Ba

The barye, a CGS unit of pressure, defined as 1 dyn / cm^2.

Bar

Unitful.bar

The bar, a metric unit of pressure, defined as 100 kPa.

Pascal

Unitful.Pa

The pascal, an SI unit of pressure, defined as 1 N / m^2.

PoundsPerSquareInch

Unitful.psi

Pounds per square inch, a US customary unit of pressure defined as 1 lbf / inch^2.

Torr

Unitful.Torr

The torr, a unit of pressure, defined as 1/760 atm.

Velocity

SpeedOfLight

Unitful.c

The speed of light in a vacuum, a unit of speed, defined as exactly 2.997,924,58 × 10^8 m/s.

Unitful.c0 is a quantity (with units m/s) whereas Unitful.c is a unit equal to c0.

Voltage

Volt

Unitful.V

The volt, an SI unit of electric potential, defined as 1 W / A.

Volume

Liter

Unitful.L
 Unitful.l

The liter, a metric unit of volume, defined as 1000 cm^3.

Dimensionless units

Percentmille

Unitful.pcm

Percentmille, a unit meaning parts per hundred thousand.

Percent

Unitful.percent

Percent, a unit meaning parts per hundred. Printed as "%".

Permille

Unitful.permille

Permille, a unit meaning parts per thousand. Printed as "‰".

Pertenthousand

Unitful.pertenthousand

Permyriad, a unit meaning parts per ten thousand. Printed as "‱".

Perbillion

Unitful.ppb

Perbillion, a unit meaning parts per billion (in the short-scale sense), i.e., 10^-9.

Permillion

Unitful.ppm

Permillion, a unit meaning parts per million.

Perquadrillion

Unitful.ppq

Perquadrillion, a unit meaning parts per quadrillion (in the short-scale sense), i.e., 10^-15.

Pertrillion

Unitful.ppt

Pertrillion, a unit meaning parts per trillion (in the short-scale sense), i.e., 10^-12.

Radian

Unitful.rad

The radian, a unit of angle. There are 2π rad in a circle.

Steradian

Unitful.sr

The steradian, a unit of spherical angle. There are 4π sr in a sphere.

Degree

Unitful.°

The degree, a unit of angle. There are 360° in a circle.

Logarithmic units

UnitName
dBDecibel
BBel
NpNeper
cNpCentineper
UnitReference level
dBHz1Hz
dBm1mW
dBV1V
dBusqrt(0.6)V
dBμV1μV
dBSPL20μPa
dBFSRootPowerRatio(1)
dBΩ1Ω
dBS1S

Physical constants

G

Unitful.G

A quantity representing the universal gravitational constant, equal to 6.674,30 × 10^-11 m^3 / (kg × s^2) (the CODATA 2018 recommended value).

Na

Unitful.Na

A quantity representing Avogadro's constant, defined as exactly 6.022,140,76 × 10^23 / mol.

R

Unitful.R

A quantity representing the molar gas constant, defined as Na × k.

R∞

Unitful.R∞

A quantity representing the Rydberg constant, equal to 1.097,373,156,8160 × 10^-7 / m (the CODATA 2018 recommended value).

Z0

Unitful.Z0

A quantity representing the impedance of free space, a constant defined as μ0 × c.

c0

Unitful.c0

A quantity representing the speed of light in a vacuum, defined as exactly 2.997,924,58 × 10^8 m/s.

Unitful.c0 is a quantity (with units m/s) whereas Unitful.c is a unit equal to c0.

gn

Unitful.gn

A quantity representing the nominal acceleration due to gravity in a vacuum near the surface of the earth, defined by standard to be exactly 9.806,65 m / s^2.

Unitful.gn is a quantity (with units m/s^2) whereas Unitful.ge is a unit equal to gn.

h

Unitful.h

A quantity representing Planck's constant, defined as exactly 6.626,070,15 × 10^-34 J × s.

k

Unitful.k

A quantity representing the Boltzmann constant, defined as exactly 1.380,649 × 10^-23 J / K.

me

Unitful.me

A quantity representing the rest mass of an electron, equal to 9.109,383,7015 × 10^-31 kg (the CODATA 2018 recommended value).

mn

Unitful.mn

A quantity representing the rest mass of a neutron, equal to 1.674,927,498,04 × 10^-27 kg (the CODATA 2018 recommended value).

mp

Unitful.mp

A quantity representing the rest mass of a proton, equal to 1.672,621,923,69 × 10^-27 kg (the CODATA 2018 recommended value).

q

Unitful.q

A quantity equal to the elementary charge, the charge of a single electron, with a value of exactly 1.602,176,634 × 10^-19 C. The letter q is used instead of e to avoid confusion with Euler's number.

ħ

Unitful.ħ

A quantity representing the reduced Planck constant, defined as h / 2π.

Φ0

Unitful.Φ0

A quantity representing the superconducting magnetic flux quantum, defined as h / (2 × q).

ε0, ϵ0

Unitful.ε0
-Unitful.ϵ0

A quantity representing the vacuum permittivity constant, defined as 1 / (μ0 × c^2).

μ0

Unitful.μ0

A quantity representing the vacuum permeability constant, defined as 4π × 10^-7 H / m.

μB

Unitful.μB

A quantity representing the Bohr magneton, equal to q × ħ / (2 × me).

σ

Unitful.σ

A quantity representing the Stefan-Boltzmann constant, defined as π^2 × k^4 / (60 × ħ^3 × c^2).

Metric (SI) Prefixes

PrefixNamePower of Ten
yyocto-24
zzepto-21
aatto-18
ffemto-15
ppico-12
nnano-9
μmicro-6
mmilli-3
ccenti-2
ddeci-1
dadeca1
hhecto2
kkilo3
Mmega6
Ggiga9
Ttera12
Ppeta15
Eexa18
Zzetta21
Yyotta24
+Unitful.ϵ0

A quantity representing the vacuum permittivity constant, defined as 1 / (μ0 × c^2).

μ0

Unitful.μ0

A quantity representing the vacuum permeability constant, defined as 4π × 10^-7 H / m.

μB

Unitful.μB

A quantity representing the Bohr magneton, equal to q × ħ / (2 × me).

σ

Unitful.σ

A quantity representing the Stefan-Boltzmann constant, defined as π^2 × k^4 / (60 × ħ^3 × c^2).

Metric (SI) Prefixes

PrefixNamePower of Ten
yyocto-24
zzepto-21
aatto-18
ffemto-15
ppico-12
nnano-9
μmicro-6
mmilli-3
ccenti-2
ddeci-1
dadeca1
hhecto2
kkilo3
Mmega6
Ggiga9
Ttera12
Ppeta15
Eexa18
Zzetta21
Yyotta24
diff --git a/dev/display/index.html b/dev/display/index.html index b58fd20c..862f7453 100644 --- a/dev/display/index.html +++ b/dev/display/index.html @@ -1,3 +1,3 @@ How units are displayed · Unitful.jl
GitHub

How units are displayed

By default, exponents on units or dimensions are indicated using Unicode superscripts on macOS and without superscripts on other operating systems. You can set the environment variable UNITFUL_FANCY_EXPONENTS to either true or false to force using or not using the exponents. You can also set the :fancy_exponent IO context property to either true or false to force using or not using the exponents.

Unitful.BracketStyle — Type
BracketStyle(x)
-BracketStyle(typeof(x))

BracketStyle specifies whether the numeric value of a Quantity is printed in brackets (and what kind of brackets). Three styles are defined:

  • NoBrackets(): this is the default, for example used for real numbers: 1.2 m
  • RoundBrackets(): used for complex numbers: (2.5 + 1.0im) V
  • SquareBrackets(): used for Level/Gain: [3 dB] Hz^-1
source
Unitful.abbr — Function

abbr(x) provides abbreviations for units or dimensions. Since a method should always be defined for each unit and dimension type, absence of a method for a specific unit or dimension type is likely an error. Consequently, we return ❓ for generic arguments to flag unexpected behavior.

source
Unitful.prefix — Function
prefix(x::Unit)

Returns a string representing the SI prefix for the power-of-ten held by this particular unit.

source
Base.show — Method
show(io::IO, x::Quantity)

Show a unitful quantity by calling showval on the numeric value, appending a space, and then calling show on a units object U().

source
Unitful.showval — Function
showval(io::IO, x::Number, brackets::Bool=true)

Show the numeric value x of a quantity. Depending on the type of x, the value may be enclosed in brackets (see BracketStyle). If brackets is set to false, the brackets are not printed.

source
Unitful.superscript — Function
superscript(i::Rational; io::Union{IO, Nothing} = nothing)

Returns exponents as a string.

This function returns the value as a string. It does not print to io. io is only used for IO context values. If io contains the :fancy_exponent property and the value is a Bool, this value will override the behavior of fancy exponents.

source
+BracketStyle(typeof(x))

BracketStyle specifies whether the numeric value of a Quantity is printed in brackets (and what kind of brackets). Three styles are defined:

source
Unitful.abbr — Function

abbr(x) provides abbreviations for units or dimensions. Since a method should always be defined for each unit and dimension type, absence of a method for a specific unit or dimension type is likely an error. Consequently, we return ❓ for generic arguments to flag unexpected behavior.

source
Unitful.prefix — Function
prefix(x::Unit)

Returns a string representing the SI prefix for the power-of-ten held by this particular unit.

source
Base.show — Method
show(io::IO, x::Quantity)

Show a unitful quantity by calling showval on the numeric value, appending a space, and then calling show on a units object U().

source
Base.show — Method
show(io::IO, x::Unitlike)

Call Unitful.showrep on each object in the tuple that is the type variable of a Unitful.Units or Unitful.Dimensions object.

source
Unitful.showrep — Function
showrep(io::IO, x::Unit)

Show the unit, prefixing with any decimal prefix and appending the exponent as formatted by Unitful.superscript.

source
showrep(io::IO, x::Dimension)

Show the dimension, appending any exponent as formatted by Unitful.superscript.

source
Unitful.showval — Function
showval(io::IO, x::Number, brackets::Bool=true)

Show the numeric value x of a quantity. Depending on the type of x, the value may be enclosed in brackets (see BracketStyle). If brackets is set to false, the brackets are not printed.

source
Unitful.superscript — Function
superscript(i::Rational; io::Union{IO, Nothing} = nothing)

Returns exponents as a string.

This function returns the value as a string. It does not print to io. io is only used for IO context values. If io contains the :fancy_exponent property and the value is a Bool, this value will override the behavior of fancy exponents.

source
diff --git a/dev/extending/index.html b/dev/extending/index.html index c6730238..5b769f86 100644 --- a/dev/extending/index.html +++ b/dev/extending/index.html @@ -5,4 +5,4 @@ function __init__() Unitful.register(YourModule) merge!(Unitful.promotion, localpromotion) -end

The definition of localpromotion must happen after all new units (dimensions) have been defined.

Type uniqueness

Currently, when the @dimension, @derived_dimension, @refunit, or @unit macros are used, some unique symbols must be provided which are used to differentiate types in dispatch. These are typically the names of dimensions or units (e.g. Length, Meter, etc.) One problem that could occur is that if multiple units or dimensions are defined with the same name, then they will be indistinguishable in dispatch and errors will result.

I don't expect a flood of units packages to come out, so probably the likelihood of name collision is pretty small. When defining units yourself, do take care to use unique symbols, perhaps with the aid of Base.gensym() if creating units at runtime. When making packages, look and see what symbols are used by existing units packages to avoid trouble.

Archaic or fictitious unit systems

In the rare event that you want to define physical units which are not convertible to SI units, you need to do a bit of extra work. To be clear, such a conversion should always exist, in principle. One can imagine, however, archaic or fictitious unit systems for which a precise conversion to SI units is unknown. For example, a cullishigay is one-third of a mudi, but only approximately 1.25 imperial bushels. There may be cases where you don't even have an approximate conversion to imperial bushels. At such a time, you may feel uncomfortable specifying the "base unit" of this hypothetical unit system in terms of an SI quantity, and may want to explicitly forbid any attempt to convert to SI units.

One can achieve this by defining new dimensions with the @dimension or @derived_dimension macros. The trick is to define dimensions that display suggestively like physical dimensions, like 𝐋*, 𝐓* etc., but are distinct as far as Julia's type system is concerned. Then, you can use @refunit to base units for these new dimensions without reference to SI. The result will be that attempted conversion between the hypothetical unit system and SI will fail with a DimensionError, so be sure you provide some hints in how your new dimensions are displayed to avoid confusing users. It would be confusing to throw a DimensionError when attempting to convert between lengths which are incompatible in the sense of the previous paragraph, when both lengths display their dimension as 𝐋.

+end

The definition of localpromotion must happen after all new units (dimensions) have been defined.

Type uniqueness

Currently, when the @dimension, @derived_dimension, @refunit, or @unit macros are used, some unique symbols must be provided which are used to differentiate types in dispatch. These are typically the names of dimensions or units (e.g. Length, Meter, etc.) One problem that could occur is that if multiple units or dimensions are defined with the same name, then they will be indistinguishable in dispatch and errors will result.

I don't expect a flood of units packages to come out, so probably the likelihood of name collision is pretty small. When defining units yourself, do take care to use unique symbols, perhaps with the aid of Base.gensym() if creating units at runtime. When making packages, look and see what symbols are used by existing units packages to avoid trouble.

Archaic or fictitious unit systems

In the rare event that you want to define physical units which are not convertible to SI units, you need to do a bit of extra work. To be clear, such a conversion should always exist, in principle. One can imagine, however, archaic or fictitious unit systems for which a precise conversion to SI units is unknown. For example, a cullishigay is one-third of a mudi, but only approximately 1.25 imperial bushels. There may be cases where you don't even have an approximate conversion to imperial bushels. At such a time, you may feel uncomfortable specifying the "base unit" of this hypothetical unit system in terms of an SI quantity, and may want to explicitly forbid any attempt to convert to SI units.

One can achieve this by defining new dimensions with the @dimension or @derived_dimension macros. The trick is to define dimensions that display suggestively like physical dimensions, like 𝐋*, 𝐓* etc., but are distinct as far as Julia's type system is concerned. Then, you can use @refunit to base units for these new dimensions without reference to SI. The result will be that attempted conversion between the hypothetical unit system and SI will fail with a DimensionError, so be sure you provide some hints in how your new dimensions are displayed to avoid confusing users. It would be confusing to throw a DimensionError when attempting to convert between lengths which are incompatible in the sense of the previous paragraph, when both lengths display their dimension as 𝐋.

diff --git a/dev/highlights/index.html b/dev/highlights/index.html index 67ae5ec9..aecee093 100644 --- a/dev/highlights/index.html +++ b/dev/highlights/index.html @@ -24,4 +24,4 @@ julia> Diagonal([-1.0u"c^2", 1.0, 1.0, 1.0]);

Logarithmic units

julia> uconvert(u"mW*s", 20u"dBm/Hz")
 100.0 s mW

Units with rational exponents

julia> 1.0u"V/sqrt(Hz)"
 1.0 V Hz^-1/2

Exact conversions respected

julia> uconvert(u"ft",1u"inch")
-1//12 ft
+1//12 ft diff --git a/dev/index.html b/dev/index.html index 439ff45a..f446c449 100644 --- a/dev/index.html +++ b/dev/index.html @@ -14,4 +14,4 @@ julia> mod(1hr+3minute+5s, 24s) 17 s

One useful interactive function is being able to convert to preferred (in this case SI) units. 

julia> upreferred(F/m)
-A^2 s^4 kg^-1 m^-3
Note

Quantities in °C or ⁠°F always unit-convert under an affine transformation that takes their relative scales into account. To avoid ambiguities that can lead to incorrect results, the units °C and °F cannot be used in Unitful to represent temperature differences. Fortunately, 1°C - 0°C == 1K and 1°F - 0°F == 1Ra, so the absolute temperature scales Kelvin (K) and Rankine (Ra) can be used easily to represent temperature differences.

See test/runtests.jl for more usage examples.

The logo is a pictorial representation of the International Prototype of the Kilogram, which was the standard definition of one kilogram from 1889 to 2019, when it was replaced by a definition based on the Planck constant, the speed of light, and the ground-state hyperfine transition frequency of ¹³³Cs.

+A^2 s^4 kg^-1 m^-3
Note

Quantities in °C or ⁠°F always unit-convert under an affine transformation that takes their relative scales into account. To avoid ambiguities that can lead to incorrect results, the units °C and °F cannot be used in Unitful to represent temperature differences. Fortunately, 1°C - 0°C == 1K and 1°F - 0°F == 1Ra, so the absolute temperature scales Kelvin (K) and Rankine (Ra) can be used easily to represent temperature differences.

See test/runtests.jl for more usage examples.

The logo is a pictorial representation of the International Prototype of the Kilogram, which was the standard definition of one kilogram from 1889 to 2019, when it was replaced by a definition based on the Planck constant, the speed of light, and the ground-state hyperfine transition frequency of ¹³³Cs.

diff --git a/dev/logarithm/index.html b/dev/logarithm/index.html index 7709b11b..e83f584f 100644 --- a/dev/logarithm/index.html +++ b/dev/logarithm/index.html @@ -35,7 +35,7 @@ julia> dB(10mW,mW,true) ERROR: ArgumentError: when passing a final Bool argument, this can only be used with dimensionless numbers. -[...]

Logarithmic quantities with no reference level specified

Logarithmic quantities with no reference level specified typically represent some amount of gain or attenuation, i.e. a ratio which is dimensionless. These can be constructed as, for example, 10*dB, which displays similarly (10 dB). The type of this kind of logarithmic quantity is:

Unitful.Gain — Type
struct Gain{L, S, T<:Real} <: LogScaled{L}

A logarithmic scale-based gain or attenuation factor. This type has one field, val::T. For example, given a gain of 20dB, we have val===20. This type differs from Unitful.Level in that val is stored after computing the logarithm.

source

One might expect that any gain / attenuation factor should be convertible to a pure number, that is, to x == y/z if you had 10*log10(x) dB. However, it turns out that in dB, a ratio of powers is defined as 10*log10(y/z), but a ratio of voltages or other root-power quantities is defined as 20*log10(y/z). Clearly, converting back from decibels to a real number is ambiguous, and so we have not implemented automatic promotion to avoid incorrect results. You can use Unitful.uconvertp to interpret a Gain as a ratio of power quantities (hence the p in uconvertp), or Unitful.uconvertrp to interpret as a ratio of root-power (field) quantities.

"Dimensionful" logarithmic quantities?

In this package, quantities with units like dBm are considered to have the dimension of power, even though the expression P(dBm) = 10*log10(P/1mW) is dimensionless and formed from a dimensionless ratio. Practically speaking, these kinds of logarithmic quantities are fungible whenever they share the same dimensions, so it is more convenient to adopt this convention (people refer to dBm/Hz as a power spectral density, etc.) Presumably, one would like to have 10dBm isa Unitful.Power for dispatch too. Therefore, in the following discussion, we will shamelessly (okay, with some shame) speak of dimensionful logarithmic quantities, or Levels for short:

Unitful.Level — Type
struct Level{L, S, T<:Union{Real, AbstractQuantity{<:Real}}} <: LogScaled{L}

A logarithmic scale-based level. Details about the logarithmic scale are encoded in L <: LogInfo. S is a reference quantity for the level, not a type. This type has one field, val::T, and the log of the ratio val/S is taken. This type differs from Unitful.Gain in that val is a linear quantity.

source

Actually, the defining characteristic of a Level is that it has a reference level, which may or may not be dimensionful. It usually is, but is not in the case of e.g. dBFS.

Finally, for completeness we note that both Level and Gain are subtypes of LogScaled:

Unitful.LogScaled — Type
abstract type LogScaled{L<:LogInfo} <: Number end

Abstract supertype of Unitful.Level and Unitful.Gain. It is only used in promotion to put levels and gains onto a common log scale.

source

Multiplication rules

Multiplying a dimensionless logarithmic quantity by a pure number acts as like it does for linear quantities:

julia> 3u"dB" * 2
+[...]

Logarithmic quantities with no reference level specified

Logarithmic quantities with no reference level specified typically represent some amount of gain or attenuation, i.e. a ratio which is dimensionless. These can be constructed as, for example, 10*dB, which displays similarly (10 dB). The type of this kind of logarithmic quantity is:

Unitful.Gain — Type
struct Gain{L, S, T<:Real} <: LogScaled{L}

A logarithmic scale-based gain or attenuation factor. This type has one field, val::T. For example, given a gain of 20dB, we have val===20. This type differs from Unitful.Level in that val is stored after computing the logarithm.

source

One might expect that any gain / attenuation factor should be convertible to a pure number, that is, to x == y/z if you had 10*log10(x) dB. However, it turns out that in dB, a ratio of powers is defined as 10*log10(y/z), but a ratio of voltages or other root-power quantities is defined as 20*log10(y/z). Clearly, converting back from decibels to a real number is ambiguous, and so we have not implemented automatic promotion to avoid incorrect results. You can use Unitful.uconvertp to interpret a Gain as a ratio of power quantities (hence the p in uconvertp), or Unitful.uconvertrp to interpret as a ratio of root-power (field) quantities.

"Dimensionful" logarithmic quantities?

In this package, quantities with units like dBm are considered to have the dimension of power, even though the expression P(dBm) = 10*log10(P/1mW) is dimensionless and formed from a dimensionless ratio. Practically speaking, these kinds of logarithmic quantities are fungible whenever they share the same dimensions, so it is more convenient to adopt this convention (people refer to dBm/Hz as a power spectral density, etc.) Presumably, one would like to have 10dBm isa Unitful.Power for dispatch too. Therefore, in the following discussion, we will shamelessly (okay, with some shame) speak of dimensionful logarithmic quantities, or Levels for short:

Unitful.Level — Type
struct Level{L, S, T<:Union{Real, AbstractQuantity{<:Real}}} <: LogScaled{L}

A logarithmic scale-based level. Details about the logarithmic scale are encoded in L <: LogInfo. S is a reference quantity for the level, not a type. This type has one field, val::T, and the log of the ratio val/S is taken. This type differs from Unitful.Gain in that val is a linear quantity.

source

Actually, the defining characteristic of a Level is that it has a reference level, which may or may not be dimensionful. It usually is, but is not in the case of e.g. dBFS.

Finally, for completeness we note that both Level and Gain are subtypes of LogScaled:

Unitful.LogScaled — Type
abstract type LogScaled{L<:LogInfo} <: Number end

Abstract supertype of Unitful.Level and Unitful.Gain. It is only used in promotion to put levels and gains onto a common log scale.

source

Multiplication rules

Multiplying a dimensionless logarithmic quantity by a pure number acts as like it does for linear quantities:

julia> 3u"dB" * 2
 6 dB
 
 julia> 2 * 0u"dB"
@@ -100,17 +100,17 @@
 40.0 dΠ (1 V)
 
 julia> @dΠ π*W/1W
-10.0 dΠ (1 W)
source

API

Unitful.linear — Function
linear(x::Quantity)
+10.0 dΠ (1 W)
source

API

Unitful.linear — Function
linear(x::Quantity)
 linear(x::Level)
-linear(x::Number) = x

Returns a quantity equivalent to x but without any logarithmic scales.

It is important to note that this operation will error for Quantity{<:Gain} types. This is for two reasons:

  • 20dB could be interpreted as either a power or root-power ratio.
  • Even if -20dB/m were interpreted as, say, 0.01/m, this means something fundamentally different than -20dB/m. 0.01/m cannot be used to calculate exponential attenuation.
source
Unitful.reflevel — Function
reflevel(x::Level{L,S})
+linear(x::Number) = x

Returns a quantity equivalent to x but without any logarithmic scales.

It is important to note that this operation will error for Quantity{<:Gain} types. This is for two reasons:

  • 20dB could be interpreted as either a power or root-power ratio.
  • Even if -20dB/m were interpreted as, say, 0.01/m, this means something fundamentally different than -20dB/m. 0.01/m cannot be used to calculate exponential attenuation.
source
Unitful.reflevel — Function
reflevel(x::Level{L,S})
 reflevel(::Type{Level{L,S}})
 reflevel(::Type{Level{L,S,T}})

Returns the reference level, e.g.

julia> reflevel(3u"dBm")
-1 mW
source
Unitful.uconvertp — Function
uconvertp(u::Units, x)
+1 mW
source
Unitful.uconvertp — Function
uconvertp(u::Units, x)
 uconvertp(u::MixedUnits, x)

Generically, this is the same as Unitful.uconvert. In cases where unit conversion would be ambiguous without further information (e.g. uconvert(dB, 10)), uconvertp presumes ratios are of power quantities.

It is important to note that careless use of this function can lead to erroneous calculations. Consider Quantity{<:Gain} types: it is tempting to use this to transform -20dB/m into 0.1/m, however this means something fundamentally different than -20dB/m. Consider what happens when you try to compute exponential attenuation by multiplying 0.1/m by a length.

Examples:

julia> using Unitful
 
 julia> uconvertp(u"dB", 10)
 10.0 dB
 
 julia> uconvertp(NoUnits, 20u"dB")
-100.0
source
Unitful.uconvertrp — Function
uconvertrp(u::Units, x)
-uconvertrp(u::MixedUnits, x)

In most cases, this is the same as Unitful.uconvert. In cases where unit conversion would be ambiguous without further information (e.g. uconvert(dB, 10)), uconvertrp presumes ratios are of root-power quantities.

It is important to note that careless use of this function can lead to erroneous calculations. Consider Quantity{<:Gain} types: it is tempting to use this to transform -20dB/m into 0.01/m, however this means something fundamentally different than -20dB/m. Consider what happens when you try to compute exponential attenuation by multiplying 0.01/m by a length.

source
+100.0source
Unitful.uconvertrp — Function
uconvertrp(u::Units, x)
+uconvertrp(u::MixedUnits, x)

In most cases, this is the same as Unitful.uconvert. In cases where unit conversion would be ambiguous without further information (e.g. uconvert(dB, 10)), uconvertrp presumes ratios are of root-power quantities.

It is important to note that careless use of this function can lead to erroneous calculations. Consider Quantity{<:Gain} types: it is tempting to use this to transform -20dB/m into 0.01/m, however this means something fundamentally different than -20dB/m. Consider what happens when you try to compute exponential attenuation by multiplying 0.01/m by a length.

source
diff --git a/dev/manipulations/index.html b/dev/manipulations/index.html index 1e43861f..a4b918ce 100644 --- a/dev/manipulations/index.html +++ b/dev/manipulations/index.html @@ -12,7 +12,7 @@ Quantity{Float64, 𝐋 𝐓^-1, Unitful.FreeUnits{(m, s^-1), 𝐋 𝐓^-1, nothing}} julia> u"ħ" -1.0545718176461565e-34 J ssource
Unitful.register — Function
register(unit_module::Module)

Makes Unitful aware of units defined in a new unit module, including making the @u_str macro work with these units. By default, Unitful is itself a registered module. Note that Main is not, so if you define new units at the REPL, you will probably want to do Unitful.register(Main).

Example:

# somewhere in a custom units package...
+1.0545718176461565e-34 J s
source
Unitful.register — Function
register(unit_module::Module)

Makes Unitful aware of units defined in a new unit module, including making the @u_str macro work with these units. By default, Unitful is itself a registered module. Note that Main is not, so if you define new units at the REPL, you will probably want to do Unitful.register(Main).

Example:

# somewhere in a custom units package...
 module MyUnitsPackage
 using Unitful
 
@@ -20,24 +20,24 @@
     ...
     Unitful.register(MyUnitsPackage)
 end
-end #module
source

Dimension and unit inspection

We define a function dimension that turns, for example, acre^2 or 1*acre^2 into 𝐋^4. We can usually add quantities with the same dimension, regardless of specific units (FixedUnits cannot be automatically converted, however). Note that dimensions cannot be determined by powers of the units: ft^2 is an area, but so is ac^1 (an acre).

There is also a function unit that turns, for example, 1*acre^2 into acre^2. You can then query whether the units are FreeUnits, FixedUnits, etc.

Unitful.unit — Function
unit(x::Quantity{T,D,U}) where {T,D,U}
+end #module
source

Dimension and unit inspection

We define a function dimension that turns, for example, acre^2 or 1*acre^2 into 𝐋^4. We can usually add quantities with the same dimension, regardless of specific units (FixedUnits cannot be automatically converted, however). Note that dimensions cannot be determined by powers of the units: ft^2 is an area, but so is ac^1 (an acre).

There is also a function unit that turns, for example, 1*acre^2 into acre^2. You can then query whether the units are FreeUnits, FixedUnits, etc.

Unitful.unit — Function
unit(x::Quantity{T,D,U}) where {T,D,U}
 unit(x::Type{Quantity{T,D,U}}) where {T,D,U}

Returns the units associated with a Quantity or Quantity type.

Examples:

julia> unit(1.0u"m") == u"m"
 true
 
 julia> unit(typeof(1.0u"m")) == u"m"
-true
source
unit(x::Number)

Returns the NoUnits object to indicate that ordinary numbers have no units. The unit is displayed as an empty string.

Examples:

julia> typeof(unit(1.0))
+true
source
unit(x::Number)

Returns the NoUnits object to indicate that ordinary numbers have no units. The unit is displayed as an empty string.

Examples:

julia> typeof(unit(1.0))
 Unitful.FreeUnits{(), NoDims, nothing}
 
 julia> typeof(unit(Float64))
 Unitful.FreeUnits{(), NoDims, nothing}
 
 julia> unit(1.0) == NoUnits
-true
source
unit(x::Dates.FixedPeriod)
+true
source
unit(x::Dates.FixedPeriod)
 unit(x::Type{<:Dates.FixedPeriod})

Return the units that correspond to a particular period.

Examples

julia> unit(Second(15)) == u"s"
 true
 
 julia> unit(Hour) == u"hr"
-true
source
Unitful.dimension — Function
dimension(x::Unit)

Returns a Unitful.Dimensions object describing the given unit x.

source
dimension(x::Number)
+true
source
Unitful.dimension — Function
dimension(x::Unit)

Returns a Unitful.Dimensions object describing the given unit x.

source
dimension(x::Number)
 dimension(x::Type{T}) where {T<:Number}

Returns a Unitful.Dimensions{()} object to indicate that ordinary numbers are dimensionless. This is a singleton, which we export as NoDims. The dimension is displayed as an empty string.

Examples:

julia> typeof(dimension(1.0))
 Unitful.Dimensions{()}
 
@@ -45,19 +45,19 @@
 Unitful.Dimensions{()}
 
 julia> dimension(1.0) == NoDims
-true
source
dimension(u::Units{U,D}) where {U,D}

Returns a Unitful.Dimensions object corresponding to the dimensions of the units, D. For a dimensionless combination of units, a Unitful.Dimensions{()} object is returned (NoDims).

Examples:

julia> dimension(u"m")
+true
source
dimension(u::Units{U,D}) where {U,D}

Returns a Unitful.Dimensions object corresponding to the dimensions of the units, D. For a dimensionless combination of units, a Unitful.Dimensions{()} object is returned (NoDims).

Examples:

julia> dimension(u"m")
 𝐋
 
 julia> typeof(dimension(u"m"))
 Unitful.Dimensions{(Unitful.Dimension{:Length}(1//1),)}
 
 julia> dimension(u"m/km")
-NoDims
source
dimension(x::Quantity{T,D}) where {T,D}
+NoDims
source
dimension(x::Quantity{T,D}) where {T,D}
 dimension(::Type{Quantity{T,D,U}}) where {T,D,U}

Returns a Unitful.Dimensions object D corresponding to the dimensions of quantity x. For a dimensionless Unitful.Quantity, a Unitful.Dimensions{()} object is returned (NoDims).

Examples:

julia> dimension(1.0u"m")
 𝐋
 
 julia> typeof(dimension(1.0u"m/μm"))
-Unitful.Dimensions{()}
source

Unit stripping

Unitful.ustrip — Function
ustrip(u::Units, x::Quantity)
+Unitful.Dimensions{()}
source

Unit stripping

Unitful.ustrip — Function
ustrip(u::Units, x::Quantity)
 ustrip(T::Type, u::Units, x::Quantity)

Convert x to units u using uconvert and return the number out the front of the resulting quantity. If T is supplied, also convert the resulting number into type T.

This function is mainly intended for compatibility with packages that don't know how to handle quantities.

julia> ustrip(u"m", 1u"mm") == 1//1000
 true
 
@@ -65,12 +65,12 @@
 true

ustrip supports InverseFunctions.inverse:

julia> using InverseFunctions: inverse
 
 julia> inverse(Base.Fix1(ustrip, u"m"))(5)
-5 m
source
ustrip(x::Number)
+5 m
source
ustrip(x::Number)
 ustrip(x::Quantity)

Returns the number out in front of any units. The value of x may differ from the number out front of the units in the case of dimensionless quantities, e.g. 1m/mm != 1. See uconvert and the example below. Because the units are removed, information may be lost and this should be used with some care — see ustrip(u,x) for a safer alternative.

julia> ustrip(2u"μm/m") == 2
 true
 
 julia> uconvert(NoUnits, 2u"μm/m") == 2//1000000
-true
source
ustrip(x::Array{Q}) where {Q <: Quantity}

Strip units from an Array by reinterpreting to type T. The resulting Array is a not a copy, but rather a unit-stripped view into array x. Because the units are removed, information may be lost and this should be used with some care.

This function is provided primarily for compatibility purposes; you could pass the result to PyPlot, for example.

julia> a = [1u"m", 2u"m"]
+true
source
ustrip(x::Array{Q}) where {Q <: Quantity}

Strip units from an Array by reinterpreting to type T. The resulting Array is a not a copy, but rather a unit-stripped view into array x. Because the units are removed, information may be lost and this should be used with some care.

This function is provided primarily for compatibility purposes; you could pass the result to PyPlot, for example.

julia> a = [1u"m", 2u"m"]
 2-element Vector{Quantity{Int64, 𝐋, Unitful.FreeUnits{(m,), 𝐋, nothing}}}:
  1 m
  2 m
@@ -83,21 +83,21 @@
 julia> a[1] = 3u"m"; b
 2-element reinterpret(Int64, ::Vector{Quantity{Int64, 𝐋, Unitful.FreeUnits{(m,), 𝐋, nothing}}}):
  3
- 2
source
ustrip(A::Diagonal)
+ 2
source
ustrip(A::Diagonal)
 ustrip(A::Bidiagonal)
 ustrip(A::Tridiagonal)
-ustrip(A::SymTridiagonal)

Strip units from various kinds of matrices by calling ustrip on the underlying vectors.

source

Unit multiplication

Base.:* — Method
*(a0::Units, a::Units...)

Given however many units, multiply them together. This is actually handled by a few different methods, since we have FreeUnits, ContextUnits, and FixedUnits.

Collect Unitful.Unit objects from the type parameter of the Unitful.Units objects. For identical units including SI prefixes (i.e. cm ≠ m), collect powers and sort uniquely by the name of the Unit. The unique sorting permits easy unit comparisons.

Examples:

julia> u"kg*m/s^2"
+ustrip(A::SymTridiagonal)

Strip units from various kinds of matrices by calling ustrip on the underlying vectors.

source

Unit multiplication

Base.:* — Method
*(a0::Units, a::Units...)

Given however many units, multiply them together. This is actually handled by a few different methods, since we have FreeUnits, ContextUnits, and FixedUnits.

Collect Unitful.Unit objects from the type parameter of the Unitful.Units objects. For identical units including SI prefixes (i.e. cm ≠ m), collect powers and sort uniquely by the name of the Unit. The unique sorting permits easy unit comparisons.

Examples:

julia> u"kg*m/s^2"
 kg m s^-2
 
 julia> u"m/s*kg/s"
 kg m s^-2
 
 julia> typeof(u"m/s*kg/s") == typeof(u"kg*m/s^2")
-true
source
Base.:* — Method
*(a0::Dimensions, a::Dimensions...)

Given however many dimensions, multiply them together.

Collect Unitful.Dimension objects from the type parameter of the Unitful.Dimensions objects. For identical dimensions, collect powers and sort uniquely by the name of the Dimension.

Examples:

julia> u"𝐌*𝐋/𝐓^2"
+true
source
Base.:* — Method
*(a0::Dimensions, a::Dimensions...)

Given however many dimensions, multiply them together.

Collect Unitful.Dimension objects from the type parameter of the Unitful.Dimensions objects. For identical dimensions, collect powers and sort uniquely by the name of the Dimension.

Examples:

julia> u"𝐌*𝐋/𝐓^2"
 𝐋 𝐌 𝐓^-2
 
 julia> u"𝐋*𝐌/𝐓^2"
 𝐋 𝐌 𝐓^-2
 
 julia> typeof(u"𝐋*𝐌/𝐓^2") == typeof(u"𝐌*𝐋/𝐓^2")
-true
source
+truesource diff --git a/dev/newunits/index.html b/dev/newunits/index.html index 53a15164..b2c8b2de 100644 --- a/dev/newunits/index.html +++ b/dev/newunits/index.html @@ -18,4 +18,4 @@ julia> @unit M "M" Molar 1u"mol/L" true; julia> 1u"mM" -1 mM

A note for the experts: Some care should be taken if explicitly creating Unitful.Units objects. The ordering of Unitful.Unit objects inside a tuple matters for type comparisons. Using the unary multiplication operator on the Units object will return a "canonically sorted" Units object. Indeed, this is how we avoid ordering issues when multiplying quantities together.

Defining units in precompiled packages

See Precompilation.

Useful functions and macros

Unitful.@dimension — Macro
@dimension(symb, abbr, name, autodocs=false)

Creates new dimensions. name will be used like an identifier in the type parameter for a Unitful.Dimension object. symb will be a symbol defined in the namespace from which this macro is called that is bound to a Unitful.Dimensions object. For most intents and purposes it is this object that the user would manipulate in doing dimensional analysis. The symbol is not exported.

This macro extends Unitful.abbr to display the new dimension in an abbreviated format using the string abbr.

Type aliases are created that allow the user to dispatch on Unitful.Quantity, Unitful.Level and Unitful.Units objects of the newly defined dimension. The type alias for quantities or levels is simply given by name, and the type alias for units is given by name*"Units", e.g. LengthUnits. Note that there is also LengthFreeUnits, for example, which is an alias for dispatching on FreeUnits with length dimensions. The aliases are not exported. If autodocs == true, docstrings will be automatically generated for these aliases.

Unitful 1.10

Documenting the resulting dimension symbol by adding a docstring before the @dimension call requires Unitful 1.10 or later. The autodocs argument also requires Unitful 1.10 or later.

Finally, if you define new dimensions with @dimension you will need to specify a preferred unit for that dimension with Unitful.preferunits, otherwise promotion will not work with that dimension. This is done automatically in the @refunit macro.

Returns the Dimensions object to which symb is bound.

Usage example from src/pkgdefaults.jl: @dimension 𝐋 "𝐋" Length

source
Unitful.@derived_dimension — Macro
@derived_dimension(name, dims, autodocs=false)

Creates type aliases to allow dispatch on Unitful.Quantity, Unitful.Level, and Unitful.Units objects of a derived dimension, like area, which is just length squared. The type aliases are not exported. If autodocs == true, docstrings will be automatically generated for these aliases.

Unitful 1.10

The autodocs argument requires Unitful 1.10 or later.

dims is a Unitful.Dimensions object.

Returns nothing.

Usage examples:

  • @derived_dimension Area 𝐋^2 gives Area and AreaUnit type aliases
  • @derived_dimension Speed 𝐋/𝐓 gives Speed and SpeedUnit type aliases
source
Unitful.@refunit — Macro
@refunit(symb, abbr, name, dimension, tf, autodocs=false)

Define a reference unit, typically SI. Rather than define conversion factors between each and every unit of a given dimension, conversion factors are given between each unit and a reference unit, defined by this macro.

This macro extends Unitful.abbr so that the reference unit can be displayed in an abbreviated format. If tf == true, this macro generates symbols for every power of ten of the unit, using the standard SI prefixes. A dimension must be given (Unitful.Dimensions object) that specifies the dimension of the reference unit. If autodocs == true, autogenerated docstrings for SI-prefixed units will be added. This option has no effect when tf == false.

Unitful 1.10

Documenting the resulting unit by adding a docstring before the @refunit call requires Unitful 1.10 or later. The autodocs argument also requires Unitful 1.10 or later.

In principle, users can use this macro, but it probably does not make much sense to do so. If you define a new (probably unphysical) dimension using @dimension, then this macro will be necessary. With existing dimensions, you will almost certainly cause confusion if you use this macro. One potential use case would be to define a unit system without reference to SI. However, there's no explicit barrier to prevent attempting conversions between SI and this hypothetical unit system, which could yield unexpected results.

Note that this macro will also choose the new unit (no power-of-ten prefix) as the default unit for promotion given this dimension.

Returns the Unitful.FreeUnits object to which symb is bound.

Usage example: @refunit m "m" Meter 𝐋 true

This example, found in src/pkgdefaults.jl, generates km, m, cm, ...

source
Unitful.@unit — Macro
@unit(symb,abbr,name,equals,tf,autodocs=false)

Define a unit. Rather than specifying a dimension like in @refunit, equals should be a Unitful.Quantity equal to one of the unit being defined. If tf == true, symbols will be made for each power-of-ten prefix. If autodocs == true, autogenerated docstrings for SI-prefixed units will be added. This option has no effect when tf == false.

Unitful 1.10

Documenting the resulting unit by adding a docstring before the @unit call requires Unitful 1.10 or later. The autodocs argument also requires Unitful 1.10 or later.

Returns the Unitful.FreeUnits object to which symb is bound.

Usage example: @unit mi "mi" Mile (201168//125)*m false

This example will not generate kmi (kilomiles).

source
Unitful.@affineunit — Macro
@affineunit(symb, abbr, offset)

Macro for easily defining affine units. offset gives the zero of the relative scale in terms of an absolute scale; the scaling is the same as the absolute scale. Example: @affineunit °C "°C" (27315//100)K is used internally to define degrees Celsius.

Unitful 1.10

Documenting the resulting unit by adding a docstring before the @affineunit call requires Unitful 1.10 or later.

source

Internals

Unitful.@prefixed_unit_symbols — Macro
@prefixed_unit_symbols(symb,name,dimension,basefactor,autodocs=false)

Not called directly by the user. Given a unit symbol and a unit's name, will define units for each possible SI power-of-ten prefix on that unit. If autodocs == true, it will automatically generate docstrings for these units.

Unitful 1.10

Documenting the resulting unit by adding a docstring before the @prefixed_unit_symbols call requires Unitful 1.10 or later. The autodocs argument also requires Unitful 1.10 or later.

Example: @prefixed_unit_symbols m Meter 𝐋 (1.0,1) true results in nm, cm, m, km, ... all getting defined in the calling namespace, with docstrings automatically defined for SI-prefixed units.

source
Unitful.@unit_symbols — Macro
@unit_symbols(symb,name)

Not called directly by the user. Given a unit symbol and a unit's name, will define units without SI power-of-ten prefixes.

Unitful 1.10

Documenting the resulting unit by adding a docstring before the @unit_symbols call requires Unitful 1.10 or later.

Example: @unit_symbols ft Foot 𝐋 results in ft getting defined but not kft.

source
Unitful.basefactor — Function
basefactor(x::Unit)

Specifies conversion factors to reference units. It returns a tuple. The first value is any irrational part of the conversion, and the second value is a rational component. This segregation permits exact conversions within unit systems that have no rational conversion to the reference units.

source
+1 mM

A note for the experts: Some care should be taken if explicitly creating Unitful.Units objects. The ordering of Unitful.Unit objects inside a tuple matters for type comparisons. Using the unary multiplication operator on the Units object will return a "canonically sorted" Units object. Indeed, this is how we avoid ordering issues when multiplying quantities together.

Defining units in precompiled packages

See Precompilation.

Useful functions and macros

Unitful.@dimension — Macro
@dimension(symb, abbr, name, autodocs=false)

Creates new dimensions. name will be used like an identifier in the type parameter for a Unitful.Dimension object. symb will be a symbol defined in the namespace from which this macro is called that is bound to a Unitful.Dimensions object. For most intents and purposes it is this object that the user would manipulate in doing dimensional analysis. The symbol is not exported.

This macro extends Unitful.abbr to display the new dimension in an abbreviated format using the string abbr.

Type aliases are created that allow the user to dispatch on Unitful.Quantity, Unitful.Level and Unitful.Units objects of the newly defined dimension. The type alias for quantities or levels is simply given by name, and the type alias for units is given by name*"Units", e.g. LengthUnits. Note that there is also LengthFreeUnits, for example, which is an alias for dispatching on FreeUnits with length dimensions. The aliases are not exported. If autodocs == true, docstrings will be automatically generated for these aliases.

Unitful 1.10

Documenting the resulting dimension symbol by adding a docstring before the @dimension call requires Unitful 1.10 or later. The autodocs argument also requires Unitful 1.10 or later.

Finally, if you define new dimensions with @dimension you will need to specify a preferred unit for that dimension with Unitful.preferunits, otherwise promotion will not work with that dimension. This is done automatically in the @refunit macro.

Returns the Dimensions object to which symb is bound.

Usage example from src/pkgdefaults.jl: @dimension 𝐋 "𝐋" Length

source
Unitful.@derived_dimension — Macro
@derived_dimension(name, dims, autodocs=false)

Creates type aliases to allow dispatch on Unitful.Quantity, Unitful.Level, and Unitful.Units objects of a derived dimension, like area, which is just length squared. The type aliases are not exported. If autodocs == true, docstrings will be automatically generated for these aliases.

Unitful 1.10

The autodocs argument requires Unitful 1.10 or later.

dims is a Unitful.Dimensions object.

Returns nothing.

Usage examples:

  • @derived_dimension Area 𝐋^2 gives Area and AreaUnit type aliases
  • @derived_dimension Speed 𝐋/𝐓 gives Speed and SpeedUnit type aliases
source
Unitful.@refunit — Macro
@refunit(symb, abbr, name, dimension, tf, autodocs=false)

Define a reference unit, typically SI. Rather than define conversion factors between each and every unit of a given dimension, conversion factors are given between each unit and a reference unit, defined by this macro.

This macro extends Unitful.abbr so that the reference unit can be displayed in an abbreviated format. If tf == true, this macro generates symbols for every power of ten of the unit, using the standard SI prefixes. A dimension must be given (Unitful.Dimensions object) that specifies the dimension of the reference unit. If autodocs == true, autogenerated docstrings for SI-prefixed units will be added. This option has no effect when tf == false.

Unitful 1.10

Documenting the resulting unit by adding a docstring before the @refunit call requires Unitful 1.10 or later. The autodocs argument also requires Unitful 1.10 or later.

In principle, users can use this macro, but it probably does not make much sense to do so. If you define a new (probably unphysical) dimension using @dimension, then this macro will be necessary. With existing dimensions, you will almost certainly cause confusion if you use this macro. One potential use case would be to define a unit system without reference to SI. However, there's no explicit barrier to prevent attempting conversions between SI and this hypothetical unit system, which could yield unexpected results.

Note that this macro will also choose the new unit (no power-of-ten prefix) as the default unit for promotion given this dimension.

Returns the Unitful.FreeUnits object to which symb is bound.

Usage example: @refunit m "m" Meter 𝐋 true

This example, found in src/pkgdefaults.jl, generates km, m, cm, ...

source
Unitful.@unit — Macro
@unit(symb,abbr,name,equals,tf,autodocs=false)

Define a unit. Rather than specifying a dimension like in @refunit, equals should be a Unitful.Quantity equal to one of the unit being defined. If tf == true, symbols will be made for each power-of-ten prefix. If autodocs == true, autogenerated docstrings for SI-prefixed units will be added. This option has no effect when tf == false.

Unitful 1.10

Documenting the resulting unit by adding a docstring before the @unit call requires Unitful 1.10 or later. The autodocs argument also requires Unitful 1.10 or later.

Returns the Unitful.FreeUnits object to which symb is bound.

Usage example: @unit mi "mi" Mile (201168//125)*m false

This example will not generate kmi (kilomiles).

source
Unitful.@affineunit — Macro
@affineunit(symb, abbr, offset)

Macro for easily defining affine units. offset gives the zero of the relative scale in terms of an absolute scale; the scaling is the same as the absolute scale. Example: @affineunit °C "°C" (27315//100)K is used internally to define degrees Celsius.

Unitful 1.10

Documenting the resulting unit by adding a docstring before the @affineunit call requires Unitful 1.10 or later.

source

Internals

Unitful.@prefixed_unit_symbols — Macro
@prefixed_unit_symbols(symb,name,dimension,basefactor,autodocs=false)

Not called directly by the user. Given a unit symbol and a unit's name, will define units for each possible SI power-of-ten prefix on that unit. If autodocs == true, it will automatically generate docstrings for these units.

Unitful 1.10

Documenting the resulting unit by adding a docstring before the @prefixed_unit_symbols call requires Unitful 1.10 or later. The autodocs argument also requires Unitful 1.10 or later.

Example: @prefixed_unit_symbols m Meter 𝐋 (1.0,1) true results in nm, cm, m, km, ... all getting defined in the calling namespace, with docstrings automatically defined for SI-prefixed units.

source
Unitful.@unit_symbols — Macro
@unit_symbols(symb,name)

Not called directly by the user. Given a unit symbol and a unit's name, will define units without SI power-of-ten prefixes.

Unitful 1.10

Documenting the resulting unit by adding a docstring before the @unit_symbols call requires Unitful 1.10 or later.

Example: @unit_symbols ft Foot 𝐋 results in ft getting defined but not kft.

source
Unitful.basefactor — Function
basefactor(x::Unit)

Specifies conversion factors to reference units. It returns a tuple. The first value is any irrational part of the conversion, and the second value is a rational component. This segregation permits exact conversions within unit systems that have no rational conversion to the reference units.

source
diff --git a/dev/temperature/index.html b/dev/temperature/index.html index c30f264c..24d6e64f 100644 --- a/dev/temperature/index.html +++ b/dev/temperature/index.html @@ -10,5 +10,5 @@ julia> 32u"°F" * 2 ERROR: AffineError: an invalid operation was attempted with affine quantities: 32 °F*2 [...]

There is a general mechanism for making units that indicate quantities should unit-convert under some affine transformation. While the usual use case is for relative scale temperatures, nothing in the implementation limits it as such. Accordingly, relative scale temperatures are considered to be Unitful.AffineQuantity objects with dimensions of temperature. The units on "affine quantities" are Unitful.AffineUnits objects.

Making your own affine units typically requires two steps. First, define the absolute unit using the Unitful.@unit macro. Second, use the Unitful.@affineunit macro to make a corresponding affine unit. As an example, this is how Ra and °F are implemented:

@unit Ra "Ra" Rankine (5//9)*K false
-@affineunit °F "°F" (45967//100)Ra

The preferred unit for promoting temperatures is usually K when using Unitful.FreeUnits.

Unitful.AffineUnits — Type
AffineUnits{N,D,A} = Units{N,D,A} where A<:Affine

Useful for dispatching on unit objects that indicate a quantity should affine-transform under unit conversion, like absolute temperatures. Not exported.

source
Unitful.AffineQuantity — Type
AffineQuantity{T,D,U} = AbstractQuantity{T,D,U} where U<:AffineUnits

Useful for dispatching on quantities that affine-transform under unit conversion, like absolute temperatures. Not exported.

source
Unitful.ScalarUnits — Type
ScalarUnits{N,D} = Units{N,D,nothing}

Useful for dispatching on unit objects that indicate a quantity should transform in the usual scalar way under unit conversion. Not exported.

source
Unitful.ScalarQuantity — Type
ScalarQuantity{T,D,U} = AbstractQuantity{T,D,U} where U<:ScalarUnits

Useful for dispatching on quantities that transform in the usual scalar way under unit conversion. Not exported.

source
Unitful.absoluteunit — Function
absoluteunit(::Units)
-absoluteunit(::Quantity)

Given a unit or quantity, which may or may not be affine (e.g. °C), return the corresponding unit on the absolute temperature scale (e.g. K). Passing a Unitful.ContextUnits object will return another ContextUnits object with the same promotion unit, which may be an affine unit, so take care.

source
+@affineunit °F "°F" (45967//100)Ra

The preferred unit for promoting temperatures is usually K when using Unitful.FreeUnits.

Unitful.AffineUnits — Type
AffineUnits{N,D,A} = Units{N,D,A} where A<:Affine

Useful for dispatching on unit objects that indicate a quantity should affine-transform under unit conversion, like absolute temperatures. Not exported.

source
Unitful.AffineQuantity — Type
AffineQuantity{T,D,U} = AbstractQuantity{T,D,U} where U<:AffineUnits

Useful for dispatching on quantities that affine-transform under unit conversion, like absolute temperatures. Not exported.

source
Unitful.ScalarUnits — Type
ScalarUnits{N,D} = Units{N,D,nothing}

Useful for dispatching on unit objects that indicate a quantity should transform in the usual scalar way under unit conversion. Not exported.

source
Unitful.ScalarQuantity — Type
ScalarQuantity{T,D,U} = AbstractQuantity{T,D,U} where U<:ScalarUnits

Useful for dispatching on quantities that transform in the usual scalar way under unit conversion. Not exported.

source
Unitful.absoluteunit — Function
absoluteunit(::Units)
+absoluteunit(::Quantity)

Given a unit or quantity, which may or may not be affine (e.g. °C), return the corresponding unit on the absolute temperature scale (e.g. K). Passing a Unitful.ContextUnits object will return another ContextUnits object with the same promotion unit, which may be an affine unit, so take care.

source
diff --git a/dev/trouble/index.html b/dev/trouble/index.html index 96789fc4..908de25c 100644 --- a/dev/trouble/index.html +++ b/dev/trouble/index.html @@ -2,4 +2,4 @@ Troubleshooting · Unitful.jl
GitHub

Troubleshooting

Why do unit conversions yield rational numbers sometimes?

We use rational numbers in this package to permit exact conversions between different units where possible. As an example, one inch is exactly equal to 2.54 cm. However, in Julia, the floating-point 2.54 is not equal to 254//100. As a consequence, 1inch != 2.54cm, because Unitful respects exact conversions. To test for equivalence, instead use ≈ (\approx tab-completion).

But I want a floating point number...

float(x) is defined for Unitful.Quantity types, and is forwarded to the underlying numeric type (units are not affected).

We may consider adding an option in the defaults to turn on/off use of Rational numbers. They permit exact conversions, but they aren't preferred as a result type in much of Julia Base (consider that inv(2) === 0.5, not 1//2).

Exponentiation

Most operations with this package should in principle suffer little performance penalty if any at run time. An exception to this is rule is exponentiation. Since units and their powers are encoded in the type signature of a Unitful.Quantity object, raising a Quantity to some power, which is just some run-time value, necessarily results in different result types. This type instability could impact performance:

julia> square(x) = (p = 2; x^p)
 square (generic function with 1 method)

In Julia, constant literal integers are lowered specially for exponentiation. (See Julia PR #20530 for details.) In this case, type stability can be maintained:

julia> square(x) = x^2
 square (generic function with 1 method)

Because the functions inv, sqrt, and cbrt are raising a Quantity to a fixed power (-1, 1/2, and 1/3, respectively), we can use a generated function to ensure type stability in these cases. Also note that squaring a Quantity can be type-stable if done as x*x.

Promotion with dimensionless numbers

Most of the time, you are only permitted to do sensible operations in Unitful. With dimensionless numbers, some of the safe logic breaks down. Consider for instance that μm/m and rad are both dimensionless units, but kind of have nothing to do with each other. It would be a little weird to add them. Nonetheless, we permit this to happen since they have the same dimensions. Otherwise, we would have to special-case operations for two dimensionless quantities rather than dispatching on the empty dimension.

The result of addition and subtraction with dimensionless but unitful numbers is always a pure number with no units. With angles, 1 rad is essentially just 1, giving sane behavior:

julia> π/2*u"rad"+90u"°"
-3.141592653589793

Broken display of dimension characters in the REPL

On some terminals with some fonts, dimension characters such as 𝐌 are displayed as an empty box. Setting a wider font spacing in your terminal settings can solve this problem.

I have a different problem

Please raise an issue. This package is in development and there may be bugs. Feature requests may also be considered and pull requests are welcome.

+3.141592653589793

Broken display of dimension characters in the REPL

On some terminals with some fonts, dimension characters such as 𝐌 are displayed as an empty box. Setting a wider font spacing in your terminal settings can solve this problem.

I have a different problem

Please raise an issue. This package is in development and there may be bugs. Feature requests may also be considered and pull requests are welcome.

diff --git a/dev/types/index.html b/dev/types/index.html index 81512d49..bee30dd1 100644 --- a/dev/types/index.html +++ b/dev/types/index.html @@ -1,8 +1,8 @@ -Types · Unitful.jl
GitHub

Types

Overview

We define a Unitful.Unit{U,D} type to represent a unit (U is a symbol, like :Meter, and D keeps track of dimensional information). Fields of a Unit object keep track of a rational exponents and a power-of-ten prefix. We don't allow arbitrary floating point exponents of units because they probably aren't very useful. The prefixes on units (e.g. nm or km) may help to avoid overflow issues and general ugliness.

Usually, the user interacts only with Units objects, not Unit objects. This is because generically, more than one unit is needed to describe a quantity. An abstract type Unitful.Units{N,D,A} is defined, where N is always a tuple of Unit objects, D is a Unitful.Dimensions{N} object such as 𝐋, the object representing the length dimension, and A is a translation for affine quantities.

Subtypes of Unitful.Units{N,D,A} are used to implement different behaviors for how to promote dimensioned quantities. The concrete subtypes have no fields and are therefore immutable singletons. Currently implemented subtypes of Unitful.Units{N,D,A} include Unitful.FreeUnits{N,D,A}, Unitful.ContextUnits{N,D,P,A}, and Unitful.FixedUnits{N,D,A}. Units defined in the Unitful.jl package itself are all Unitful.FreeUnits{N,D,A} objects.

Finally, we define physical quantity types as Quantity{T<:Number, D, U}, where D :: Dimensions and U <: Units. By putting units in the type signature of a quantity, staged functions can be used to offload as much of the unit computation to compile-time as is possible. By also having the dimensions explicitly in the type signature, dispatch can be done on dimensions: isa(1u"m", Unitful.Length) == true. This works because Length is a type alias for some subset of Unitful.Quantity subtypes.

API

Quantities

Unitful.AbstractQuantity — Type
abstract type AbstractQuantity{T,D,U} <: Number end

Represents a generic quantity type, whose dimensions and units are specified in the type signature. The dimensions and units are allowed to be the empty set, in which case a dimensionless, unitless number results.

The type parameter T represents the numeric backing type. The type parameters D :: Unitful.Dimensions and U <: Unitful.Units. Of course, the dimensions follow from the units, but the type parameters are kept separate to permit convenient dispatch on dimensions.

source
Unitful.DimensionlessQuantity — Type
DimensionlessQuantity{T,U} = AbstractQuantity{T, NoDims, U}

Useful for dispatching on Unitful.Quantity types that may have units but no dimensions. (Units with differing power-of-ten prefixes are not canceled out.)

Example:

julia> isa(1.0u"mV/V", DimensionlessQuantity)
-true
source

Units and dimensions

Unitful.Unitlike — Type
abstract type Unitlike end

Represents units or dimensions. Dimensions are unit-like in the sense that they are not numbers but you can multiply or divide them and exponentiate by rationals.

source
Unitful.Units — Type
abstract type Units{N,D,A} <: Unitlike end

Abstract supertype of all units objects, which can differ in their implementation details. A is a translation for affine quantities; for non-affine quantities it is nothing.

source
Unitful.FreeUnits — Type
struct FreeUnits{N,D,A} <: Units{N,D,A}

Instances of this object represent units, possibly combinations thereof. These behave like units have behaved in previous versions of Unitful, and provide a basic level of functionality that should be acceptable to most users. See Basic promotion mechanisms in the docs for details.

Example: the unit m is actually a singleton of type Unitful.FreeUnits{(Unitful.Unit{:Meter, 𝐋}(0, 1//1),), 𝐋, nothing}. After dividing by s, a singleton of type Unitful.FreeUnits{(Unitful.Unit{:Meter, 𝐋}(0, 1//1), Unitful.Unit{:Second, 𝐓}(0, -1//1)), 𝐋/𝐓, nothing} is returned.

source
Unitful.ContextUnits — Type
struct ContextUnits{N,D,P,A} <: Units{N,D,A}

Instances of this object represent units, possibly combinations thereof. It is in most respects like FreeUnits{N,D,A}, except that the type parameter P is again a FreeUnits{M,D} type that specifies a preferred unit for promotion. See Advanced promotion mechanisms in the docs for details.

source
Unitful.FixedUnits — Type
struct FixedUnits{N,D,A} <: Units{N,D,A} end

Instances of this object represent units, possibly combinations thereof. These are primarily intended for use when you would like to disable automatic unit conversions. See Advanced promotion mechanisms in the docs for details.

source
Unitful.Dimensions — Type
struct Dimensions{N} <: Unitlike

Instances of this object represent dimensions, possibly combinations thereof.

source
Unitful.Unit — Type
struct Unit{U,D}
+Types · Unitful.jl
GitHub
Types
Overview
We define a Unitful.Unit{U,D} type to represent a unit (U is a symbol, like :Meter, and D keeps track of dimensional information). Fields of a Unit object keep track of a rational exponents and a power-of-ten prefix. We don't allow arbitrary floating point exponents of units because they probably aren't very useful. The prefixes on units (e.g. nm or km) may help to avoid overflow issues and general ugliness.
Usually, the user interacts only with Units objects, not Unit objects. This is because generically, more than one unit is needed to describe a quantity. An abstract type Unitful.Units{N,D,A} is defined, where N is always a tuple of Unit objects, D is a Unitful.Dimensions{N} object such as 𝐋, the object representing the length dimension, and A is a translation for affine quantities.
Subtypes of Unitful.Units{N,D,A} are used to implement different behaviors for how to promote dimensioned quantities. The concrete subtypes have no fields and are therefore immutable singletons. Currently implemented subtypes of Unitful.Units{N,D,A} include Unitful.FreeUnits{N,D,A}, Unitful.ContextUnits{N,D,P,A}, and Unitful.FixedUnits{N,D,A}. Units defined in the Unitful.jl package itself are all Unitful.FreeUnits{N,D,A} objects.
Finally, we define physical quantity types as Quantity{T<:Number, D, U}, where D :: Dimensions and U <: Units. By putting units in the type signature of a quantity, staged functions can be used to offload as much of the unit computation to compile-time as is possible. By also having the dimensions explicitly in the type signature, dispatch can be done on dimensions: isa(1u"m", Unitful.Length) == true. This works because Length is a type alias for some subset of Unitful.Quantity subtypes.
API
Quantities
Unitful.AbstractQuantity — Type
abstract type AbstractQuantity{T,D,U} <: Number end
Represents a generic quantity type, whose dimensions and units are specified in the type signature.  The dimensions and units are allowed to be the empty set, in which case a dimensionless, unitless number results.
The type parameter T represents the numeric backing type. The type parameters D :: Unitful.Dimensions and U <: Unitful.Units. Of course, the dimensions follow from the units, but the type parameters are kept separate to permit convenient dispatch on dimensions.
source
Unitful.DimensionlessQuantity — Type
DimensionlessQuantity{T,U} = AbstractQuantity{T, NoDims, U}
Useful for dispatching on Unitful.Quantity types that may have units but no dimensions. (Units with differing power-of-ten prefixes are not canceled out.)
Example:
julia> isa(1.0u"mV/V", DimensionlessQuantity)
+true
source
Units and dimensions
Unitful.Unitlike — Type
abstract type Unitlike end
Represents units or dimensions. Dimensions are unit-like in the sense that they are not numbers but you can multiply or divide them and exponentiate by rationals.
source
Unitful.Units — Type
abstract type Units{N,D,A} <: Unitlike end
Abstract supertype of all units objects, which can differ in their implementation details. A is a translation for affine quantities; for non-affine quantities it is nothing.
source
Unitful.FreeUnits — Type
struct FreeUnits{N,D,A} <: Units{N,D,A}
Instances of this object represent units, possibly combinations thereof. These behave like units have behaved in previous versions of Unitful, and provide a basic level of functionality that should be acceptable to most users. See Basic promotion mechanisms in the docs for details.
Example: the unit m is actually a singleton of type Unitful.FreeUnits{(Unitful.Unit{:Meter, 𝐋}(0, 1//1),), 𝐋, nothing}. After dividing by s, a singleton of type Unitful.FreeUnits{(Unitful.Unit{:Meter, 𝐋}(0, 1//1), Unitful.Unit{:Second, 𝐓}(0, -1//1)), 𝐋/𝐓, nothing} is returned.
source
Unitful.ContextUnits — Type
struct ContextUnits{N,D,P,A} <: Units{N,D,A}
Instances of this object represent units, possibly combinations thereof. It is in most respects like FreeUnits{N,D,A}, except that the type parameter P is again a FreeUnits{M,D} type that specifies a preferred unit for promotion. See Advanced promotion mechanisms in the docs for details.
source
Unitful.FixedUnits — Type
struct FixedUnits{N,D,A} <: Units{N,D,A} end
Instances of this object represent units, possibly combinations thereof. These are primarily intended for use when you would like to disable automatic unit conversions. See Advanced promotion mechanisms in the docs for details.
source
Unitful.Dimensions — Type
struct Dimensions{N} <: Unitlike
Instances of this object represent dimensions, possibly combinations thereof.
source
Unitful.Unit — Type
struct Unit{U,D}
     tens::Int
     power::Rational{Int}
-end
Description of a physical unit, including powers-of-ten prefixes and powers of the unit. The name of the unit is encoded in the type parameter U as a symbol, e.g. :Meter, :Second, :Gram, etc. The type parameter D is a Dimensions{N} object, for instance Unit{:Meter, 𝐋} or Unit{:Liter, 𝐋^3}. Note that the dimension information refers to the unit, not powers of the unit.
Unit{U,D} objects are almost never explicitly manipulated by the user. They are collected in a tuple, which is used for the type parameter N of a Units{N,D,A} object.
source
Unitful.Dimension — Type
struct Dimension{D}
+end
Description of a physical unit, including powers-of-ten prefixes and powers of the unit. The name of the unit is encoded in the type parameter U as a symbol, e.g. :Meter, :Second, :Gram, etc. The type parameter D is a Dimensions{N} object, for instance Unit{:Meter, 𝐋} or Unit{:Liter, 𝐋^3}. Note that the dimension information refers to the unit, not powers of the unit.
Unit{U,D} objects are almost never explicitly manipulated by the user. They are collected in a tuple, which is used for the type parameter N of a Units{N,D,A} object.
source
Unitful.Dimension — Type
struct Dimension{D}
     power::Rational{Int}
-end
Description of a dimension. The name of the dimension D is a symbol, e.g. :Length, :Time, :Mass, etc.
Dimension{D} objects are collected in a tuple, which is used for the type parameter N of a Dimensions{N} object.
source

+end

Description of a dimension. The name of the dimension D is a symbol, e.g. :Length, :Time, :Mass, etc.

Dimension{D} objects are collected in a tuple, which is used for the type parameter N of a Dimensions{N} object.

source