Basic usage

This package extends Unitful.jl and the new dimension of angle inherits a lot of default behavior from Unitful.jl. You should read the Unitful.jl documentation first.

At its core, DimensionfulAngles defines:

The unit radᵃ is prefixable, and therefore defines many other units, which are documented in Prefixed units.

The units in this package are appended the superscript ᵃ to differentiate them from the units in Unitful.jl and UnitfulAngles.jl, which have the same name but are non-dimensional. The @ua_str provides an easier way to access these units without having to type the superscript ᵃ. For example, both of these are equivalent:

julia> using Unitful

julia> using DimensionfulAngles

julia> 1.3u"radᵃ"
1.3 rad

julia> 1.3ua"rad"
1.3 rad

The default u string can still be more convenient when defining quantities with mixed units, such as

julia> using Unitful

julia> using DimensionfulAngles

julia> 2.1u"radᵃ/s"
2.1 rad s⁻¹

Alternatively it might be convenient to import the units you are using directly, renaming units from DimensionfulAngles to remove the superscript ᵃ. For example:

julia> using Unitful

julia> using Unitful: m, s, kg

julia> using DimensionfulAngles: radᵃ as rad, °ᵃ as °

julia> 2.1rad / s
2.1 rad s⁻¹

Yet another way to import units is to import the default set of units, which includes all the default units from Unitful.jl but with angle units from DimensionfulAngles.jl. The units from DimensionfulAngles.jl are imported without the superscript ᵃ in their names. This is done as:

julia> using DimensionfulAngles.DefaultSymbols

One of the main advantage of defining an angle dimension is to be able to dispatch on angles. This behavior and useful aliases are completely inherited from Unitful.jl. The most basic usage uses the automatically defined alias DimensionfulAngles.Angle:

julia> using Unitful

julia> using DimensionfulAngles

julia> what_am_i(::Unitful.Length) = "I am a length."
what_am_i (generic function with 1 method)

julia> what_am_i(::DimensionfulAngles.Angle) = "I am an angle."
what_am_i (generic function with 2 methods)

julia> my_height = 6u"ft" + 1.0u"inch"
1.8542 m

julia> angle = 1.2ua"rad"
1.2 rad

julia> what_am_i(my_height)
"I am a length."

julia> what_am_i(angle)
"I am an angle."

Finally, we can convert quantities to or from Unitful (including UnitfulAngles) using an extension of uconvert with first argument :Unitful or :DimensionfulAngles.

Unitful.uconvert — Method
uconvert(s::Symbol, x::Quantity)

Convert between DimensionfulAngles and Unitful angles (non-dimensional, SI). The Symbol s is either :Unitful, to convert to Unitful angles, or DimensionfulAngles to convert to DimensionfulAngles angles. It converts angle units and the following derived units: sr, rpm, rps).

Astronomical units are not equivalent between these two packages

Astronomical units in DimensionfulAngles and UnitfulAngles are not equivalent, and are converted to compatible units first. See documentation for more information.

Example

julia> using Unitful, DimensionfulAngles

julia> ω = 3.2u"radᵃ/s"
3.2 rad s⁻¹

julia> ω̄ = uconvert(:Unitful, ω)
3.2 rad s⁻¹

julia> dimension(ω)
𝐀 𝐓⁻¹

julia> dimension(ω̄)
𝐓⁻¹

julia> dimension(uconvert(:DimensionfulAngles, ω̄))
𝐀 𝐓⁻¹

Note that astronomical units in DimensionfulAngles and UnitfulAngles are not equivalent and quantities containing these units are converted to compatible, non-astronomical, units first. Specifically, the UnitfulAngles units [mas, μas, pas] are converted to arcsecond, the DimensionfulAngles unit asᵃ and all its prefixed versions are converted to arcsecondᵃ, and the DimensionfulAngles units [ʰᵃ, ᵐᵃ, ˢᵃ] are converted to hourAngleᵃ. For example:

julia> θ = 1u"μas"
1 μas

julia> θ̄ = uconvert(:DimensionfulAngles, θ)
1//1000000″

julia> uconvert(:Unitful, 1u"ᵐᵃ")
1//60 hourAngle

Syntax

Contents:

DimensionfulAngles — Module

Extends Unitful.jl to include Angle as an independent dimension in order to facilitate dispatching.

See the Documentation for more information.

Not SI

Angle is not an SI base dimension.

Examples

julia> using DimensionfulAngles

julia> 1.0ua"turn"
1.0 τ

julia> 1.0ua"rad" - 1.0ua"°"
0.9825467074800567 rad

julia> cos(45ua"°")
0.7071067811865476
DimensionfulAngles.radᵃ — Constant
radᵃ

The radian, a unit of angle.

There are 2π rad in a circle. The radian is the SI unit of angle. Unlike Unitful.rad, which follows SI and is therefor dimensionless, radᵃ has dimensions of Angle. Accepts SI prefixes.

Dimension: DimensionfulAngles.𝐀.

Examples

julia> using DimensionfulAngles

julia> 1.0ua"rad" + 20.0ua"mrad"
1.02 rad
DimensionfulAngles.°ᵃ — Constant
°ᵃ

The degree, a unit of angle.

There are 360° in a circle. The degree is an SI-accepted unit of angle. Unlike Unitful.°, which follows SI and is therefor dimensionless, °ᵃ has dimensions of Angle. Does not accepts SI prefixes.

Dimension: DimensionfulAngles.𝐀.

Examples

julia> using DimensionfulAngles

julia> 1ua"°"
1°
DimensionfulAngles.θ₀ — Constant
θ₀

A quantity equal to the central angle of a plane circular sector whose arc length is equal to that of its radius. It has a value of exactly 1 rad or approximately 57.2958°. Used as the defining constant of Angle dimension in several proposed SI extension systems.

Dimensions: 𝐀.

See also DimensionfulAngles.radᵃ.

Examples

julia> using DimensionfulAngles

julia> θ₀
1//1 rad

julia> θ₀ |> ua"°"
57.29577951308232°

julia> 2.1ua"rad" / θ₀
2.1
DimensionfulAngles.@ua_str — Macro
macro ua_str(unit)

String macro to easily recall units with angular dimension located in the DimensionfulAngles package. Although all unit symbols in that package are suffixed with ᵃ, the suffix should not be used when using this macro.

Note that what goes inside must be parsable as a valid Julia expression.

Examples

julia> using DimensionfulAngles

julia> 1.0ua"turn"
1.0 τ

julia> 1.0ua"rad" - 1.0ua"°"
0.9825467074800567 rad
DimensionfulAngles.DefaultSymbols — Module

Imports default units into the workspace.

This replicates the behavior of Unitful.DefaultSymbols in Unitful.jl/src/pkgdefaults.jl but replaces Unitful Angles with DimensionfulAngles angles.

Examples

julia> using DimensionfulAngles.DefaultSymbols

will bring the following into the calling namespace:

  • Dimensions 𝐋,𝐌,𝐓,𝐈,𝚯,𝐉,𝐍 and 𝐀

  • Base and derived SI units, with SI prefixes

    • Candela conflicts with Base.cd so it is brought in as cdᵤ.

  • Degrees: °

All angles and derived units imported removing the ᵃ superscript.

Potential conflict with other packages

All angles are imported removing the ᵃ superscript. This means, e.g., ° == u"°ᵃ" instead of u"°". This may cause conflicts with other packages that assume angles are the dimensionless ones from Unitful.

Syntax provided by Unitful.jl

Prefixed units