diff --git a/dev/.documenter-siteinfo.json b/dev/.documenter-siteinfo.json
index 78e3b508..f8f22940 100644
--- a/dev/.documenter-siteinfo.json
+++ b/dev/.documenter-siteinfo.json
@@ -1 +1 @@
-{"documenter":{"julia_version":"1.11.2","generation_timestamp":"2024-12-20T07:48:11","documenter_version":"1.8.0"}}
\ No newline at end of file
+{"documenter":{"julia_version":"1.11.2","generation_timestamp":"2024-12-20T08:47:24","documenter_version":"1.8.0"}}
\ No newline at end of file
diff --git a/dev/LICENSE/index.html b/dev/LICENSE/index.html
index a79d281e..944ff280 100644
--- a/dev/LICENSE/index.html
+++ b/dev/LICENSE/index.html
@@ -1,2 +1,2 @@
-License · Unitful.jl
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).
Settings
This document was generated with Documenter.jl version 1.8.0 on Friday 20 December 2024. Using Julia version 1.11.2.
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).
Settings
This document was generated with Documenter.jl version 1.8.0 on Friday 20 December 2024. Using Julia version 1.11.2.
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.
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.
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.
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,22 +21,22 @@
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.
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.
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 beforeUnitful.upreferredhas been called or quantities have been promoted.
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.
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).
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.
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).
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.
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.
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 beforeUnitful.upreferredhas been called or quantities have been promoted.
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.
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).
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.
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).
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
julia> [1.0u"m", 2.0u"cm"]
2-element Vector{Quantity{Float64, 𝐋, Unitful.FreeUnits{(m,), 𝐋, nothing}}}:
- 1.0 m
+ 1.0 m
0.02 m
julia> [1.0u"m", 2.0]
2-element Vector{Quantity{Float64}}:
1.0 m
- 2.0
In the first case, an array with a concrete type is created. Good performance should be attainable. The second case invokes promotion so that an array of concrete type can be created. The third case falls back to an abstract type, which cannot be stored efficiently and will incur a performance penalty. An additional benefit of having a concrete type is that we can dispatch on the dimensions of the array's elements:
julia> f(x::AbstractArray{T}) where {T<:Unitful.Length} = sum(x)
+ 2.0
In the first case, an array with a concrete type is created. Good performance should be attainable. The second case invokes promotion so that an array of concrete type can be created. The third case falls back to an abstract type, which cannot be stored efficiently and will incur a performance penalty. An additional benefit of having a concrete type is that we can dispatch on the dimensions of the array's elements:
julia> f(x::AbstractArray{T}) where {T<:Unitful.Length} = sum(x)
f (generic function with 1 method)
julia> f([1.0u"m", 2.0u"cm"])
@@ -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.
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.
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.
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.
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
Settings
This document was generated with Documenter.jl version 1.8.0 on Friday 20 December 2024. Using Julia version 1.11.2.