diff --git a/docs/Project.toml b/docs/Project.toml index 418f2c7b..fa0f1fc5 100644 --- a/docs/Project.toml +++ b/docs/Project.toml @@ -4,7 +4,9 @@ Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4" InverseFunctions = "3587e190-3f89-42d0-90ee-14403ec27112" Latexify = "23fbe1c1-3f47-55db-b15f-69d7ec21a316" Markdown = "d6f4376e-aef5-505a-96c1-9c027394607a" +OrderedCollections = "bac558e1-5e72-5ebc-8fee-abe8a469f55d" [compat] Documenter = "1" Latexify = "0.16" +OrderedCollections = "1.6" diff --git a/docs/make.jl b/docs/make.jl index e8f865d3..00efac12 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -1,11 +1,31 @@ using Documenter, Unitful, Dates +const ci = get(ENV, "CI", nothing) == "true" + +function check_defaultunits_version() + vfile = "docs/src/assets/vfile.txt" + r = readline(vfile) + docs_v = VersionNumber(r) + pkg_v = pkgversion(Unitful) + docs_v == pkg_v || error("Docs chapter on default units built with the wrong version of Unitful \ + (docs built for $docs_v vs current Unitful version $pkg_v). \ + Please run the script on the local computer with the proper Unitful version") + return nothing +end + +# on local computer, (re-)create the documentation file defaultunits.md +if !ci + ENV["UNITFUL_FANCY_EXPONENTS"] = false + include("make_def-units_docs.jl") + MakeDefUnitsDocs.make_chapter() +end + DocMeta.setdocmeta!(Unitful, :DocTestSetup, :(using Unitful)) makedocs( sitename = "Unitful.jl", - format = Documenter.HTML(prettyurls = get(ENV, "CI", nothing) == "true"), - warnonly = [:missing_docs], + format = Documenter.HTML(prettyurls = ci), + warnonly = [:missing_docs, :doctest], modules = [Unitful], workdir = joinpath(@__DIR__, ".."), pages = [ @@ -21,8 +41,12 @@ makedocs( "Interoperability with `Dates`" => "dates.md" "Extending Unitful" => "extending.md" "Troubleshooting" => "trouble.md" + "Pre-defined units and constants" => "defaultunits.md" "License" => "LICENSE.md" ] ) -deploydocs(repo = "github.com/PainterQubits/Unitful.jl.git") +if ci + check_defaultunits_version() + deploydocs(repo = "github.com/PainterQubits/Unitful.jl.git") +end diff --git a/docs/make_def-units_docs.jl b/docs/make_def-units_docs.jl new file mode 100644 index 00000000..141f7fa4 --- /dev/null +++ b/docs/make_def-units_docs.jl @@ -0,0 +1,292 @@ +module MakeDefUnitsDocs + +using Unitful, OrderedCollections + +mdfile = "docs/src/defaultunits.md" +mdheader = "docs/src/assets/defaultunits-header.md" +mdfooter = "docs/src/assets/defaultunits-footer.md" +mdlogunits = "docs/src/assets/defaultunits-logunits.md" +vfile = "docs/src/assets/vfile.txt" + +""" +# Examples +```julia-repl +julia> prefnamesvals() +OrderedCollections.OrderedDict{String, Tuple{String, Int64}} with 20 entries: + "y" => ("yocto", -24) + "z" => ("zepto", -21) + ⋮ => ⋮ +""" +function prefnamesvals() + prefixnames = Dict( + "Q" => "quetta", + "R" => "ronna", + "Y" => "yotta", + "Z" => "zetta", + "E" => "exa", + "P" => "peta", + "T" => "tera", + "G" => "giga", + "M" => "mega", + "k" => "kilo", + "h" => "hecto", + "da" => "deca", + "d" => "deci", + "c" => "centi", + "m" => "milli", + "μ" => "micro", + "n" => "nano", + "p" => "pico", + "f" => "femto", + "a" => "atto", + "z" => "zepto", + "y" => "yocto", + "r" => "ronto", + "q" => "quecto") + pd = Unitful.prefixdict + sxp = sort(collect(keys(pd))) + + return OrderedDict(pd[k] => (prefixnames[pd[k]], k) for k in sxp if pd[k] != "") +end + +regularid(n) = !startswith(string(n), r"#|@") + +uful_ids() = filter(regularid, names(Unitful; all=true)) + +docstr(n::Symbol) = Base.Docs.doc(Base.Docs.Binding(Unitful, n)) |> string + +isprefixed(u::Symbol) = occursin("A prefixed unit, equal", docstr(u)) + +isdocumented(n::Symbol) = !startswith(docstr(n), "No documentation found.") + +""" + getphysdims(uids::Vector{Symbol}) +Filters the list of `Unitful` identifiers to return those which denote physical dimensions (e.g. `Area`, `Power`) +""" +getphysdims(uids) = filter(isphysdim, uids) + +isphysdim(n::Symbol) = _isphysdim(getproperty(Unitful, n)) +_isphysdim(_) = false +_isphysdim(::Type{Union{Quantity{T,D,U}, Level{L,S,Quantity{T,D,U}} where {L,S}} where {T,U}}) where D = true + +""" +# Examples +```julia-repl +julia> getdim(Unitful.Area) +𝐋^2 +``` +""" +getdim(::Type{Union{Quantity{T,D,U}, Level{L,S,Quantity{T,D,U}} where {L,S}} where {T,U}}) where D = D +getdim(x::Symbol) = getdim(getproperty(Unitful, x)) + +""" +# Examples +```julia-repl +julia> getdimpars(Unitful.Power) +svec((Unitful.Dimension{:Length}(2//1), Unitful.Dimension{:Mass}(1//1), Unitful.Dimension{:Time}(-3//1))) +``` +""" +getdimpars(x) = getdimpars(getdim(x)) +getdimpars(::Unitful.Dimensions{N}) where N = N + +getdimpow(x) = only(getdimpars(x)).power + +isbasicdim(x) = length(getdimpars(x)) == 1 && getdimpow(x) == 1 + +function physdims_categories(physdims) + basicdims = Symbol[] + compounddims = Symbol[] + otherdims = Symbol[] + for d in physdims + try + if isbasicdim(d) + push!(basicdims, d) + else + push!(compounddims, d) + end + catch + push!(otherdims, d) + end + end + return (;basicdims, compounddims, otherdims, ) +end + +""" +# Examples +```julia-repl +julia> unitsdict(basicdims, uids) +OrderedCollections.OrderedDict{Symbol, Vector{Symbol}} with 7 entries: + :Amount => [:mol] + :Current => [:A] + :Length => [:angstrom, :ft, :inch, :m, :mi, :mil, :yd] + :Luminosity => [:cd, :lm] + :Mass => [:dr, :g, :gr, :kg, :lb, :oz, :slug, :u] + :Temperature => [:K, :Ra, :°C, :°F] + :Time => [:d, :hr, :minute, :s, :wk, :yr] +``` +""" +function unitsdict(physdims, uids) + ups = [] + for d in physdims + dm = getproperty(Unitful, d) + units = Symbol[] + for uname in uids + u = getproperty(Unitful, uname) + if (u isa Unitful.Units) + if (1*u isa dm) && (!isprefixed(uname) || uname == :g) && isdocumented(uname) # gram considered prefixed unit + push!(units, uname) + end + end + end + if !isempty(units) + sort!(units; by = x -> lowercase(string(x))) + unique!(nameofunit, units) # special cases: Liter, Angstrom + push!(ups, d => units) + end + end + return OrderedDict(sort!(ups)) +end + +function physconstants(uids) + ph_consts = [n for n in uids if + isconst(Unitful, n) && + !(getproperty(Unitful, n) isa Union{Type, Unitful.Units, Unitful.Dimensions, Module, Function}) && + isdocumented(n) ] + sort!(ph_consts) + return ph_consts +end + +function isnodims(u) + u isa Unitful.FreeUnits || return false + return dimension(u) == NoDims +end +isnodims(u::Symbol) = isnodims(getproperty(Unitful, u)) + +nodimsunits(uids) = [n for n in uids if isnodims(n) && isdocumented(n) && !isprefixed(n) && n != :NoUnits] + +removerefs(d) = replace(d, r"\[(`[\w\.]+\`)]\(@ref\)" => s"\1") + +""" + udoc(s) +Truncates documentation and removes references +""" +udoc(s) = match(r"(?ms)(.+)\n\nDimension: ", docstr(s)).captures[1] |> removerefs + +function nameofunit(u) + special = Dict(u"ha" => "Hectare", u"kg" => "Kilogram", u"°F" => "Degree Fahrenheit", u"°C" => "Degree Celcius") + u in keys(special) && return special[u] + return string(_nameofunit(u)) +end + +nameofunit(s::Symbol) = nameofunit(getproperty(Unitful, s)) + +_nameofunit(::Unitful.Units{N}) where N = _nameofunit(only(N)) +_nameofunit(::Unitful.Unit{U}) where U = U + +function make_subsection_text(uvec; isunit=true) + s = "" + for u in uvec + if isunit + n = nameofunit(u) + else + n = string(u) + end + d = udoc(u) + s *= "#### $n\n\n$d\n\n" + end + return s +end + +function make_simple_section_text(sectiontitle, uvec; isunit=true) + s = "## $sectiontitle\n\n" + s *= make_subsection_text(uvec; isunit) + return s +end + +function make_structured_section_text(sectiontitle, sectiondict) + s = "## $sectiontitle\n\n" + for (dim, uvec) in sectiondict + s *= "### $dim\n\n" + s *= make_subsection_text(uvec) + end + return s +end + +function makeprefixsection(pnv) + s = """ +## Metric (SI) Prefixes + +| Prefix | Name | Power of Ten | +|--------|--------|--------| +""" + for (k,v) in pnv + s *= "| $k | $(v[1]) | $(v[2]) |\n" + end + + return s +end + + +header() = read(mdheader, String) +footer() = read(mdfooter, String) +logunits() = read(mdlogunits, String) + +function makefulltext(sections, nodims_units, phys_consts) + s = header() * "\n\n" + for (sectiontitle, sectiondict) in sections + s *= make_structured_section_text(sectiontitle, sectiondict) + end + s *= make_simple_section_text("Dimensionless units", nodims_units) + s *= logunits() + s *= make_simple_section_text("Physical constants", phys_consts; isunit=false) + s *= makeprefixsection(prefnamesvals()) + s *= footer() + return s +end + +function write_unitful_v(vfile) + open(vfile, "w") do io + println(io, pkgversion(Unitful)) + end + return nothing +end + +function savetext(fulltext, mdfile) + open(mdfile,"w") do io + write(io, fulltext) + end + write_unitful_v(vfile) + return nothing +end + +""" + make_chapter(wr = true; verbose = false) +Generates the text of the `Pre-defined units and constants` documentation section +and writes it into the file if `wr==true` +""" +function make_chapter(wr = true; verbose = false) + uids = uful_ids() + + (;basicdims, compounddims) = uids |> getphysdims |> physdims_categories + + basic_units = unitsdict(basicdims, uids) + compound_units = unitsdict(compounddims, uids) + nodims_units = nodimsunits(uids) + sections = OrderedDict(["Base dimensions" => basic_units, + "Derived dimensions" => compound_units]) + phys_consts = physconstants(uids) + + fulltext = makefulltext(sections, nodims_units, phys_consts) + + wr && savetext(fulltext, mdfile) + + if verbose + return (;fulltext, sections, nodims_units, phys_consts) + else + return nothing + end +end + +export make_chapter + +end # module diff --git a/docs/src/assets/defaultunits-footer.md b/docs/src/assets/defaultunits-footer.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/src/assets/defaultunits-header.md b/docs/src/assets/defaultunits-header.md new file mode 100644 index 00000000..e2ac90ce --- /dev/null +++ b/docs/src/assets/defaultunits-header.md @@ -0,0 +1,16 @@ +# Pre-defined units and сonstants + +In the following, only non-prefixed units are listed. To get a more detailed information about a unit, and to get information about prefixed units, use `Julia` help, e.g. + +``` +help?> Unitful.kW + Unitful.kW + + A prefixed unit, equal to 10^3 W. + + Dimension: 𝐋² 𝐌 𝐓⁻³ + + See also: Unitful.W. +``` + +For prefixes, see [below](#Metric-(SI)-Prefixes). diff --git a/docs/src/assets/defaultunits-logunits.md b/docs/src/assets/defaultunits-logunits.md new file mode 100644 index 00000000..78d5add3 --- /dev/null +++ b/docs/src/assets/defaultunits-logunits.md @@ -0,0 +1,21 @@ +## Logarithmic units + +| Unit | Name | +|----------------|---------------------------------| +| `dB` | Decibel | +| `B` | Bel | +| `Np` | Neper | +| `cNp` | Centineper | + +### "Dimensionful" logarithmic units +| Unit | Reference level | +|----------------|---------------------------------| +| `dBHz` | 1Hz | +| `dBm` | 1mW | +| `dBV` | 1V | +| `dBu` | sqrt(0.6)V | +| `dBμV` | 1μV | +| `dBSPL` | 20μPa | +| `dBFS` | RootPowerRatio(1) | +| `dBΩ` | 1Ω | +| `dBS` | 1S | diff --git a/docs/src/assets/vfile.txt b/docs/src/assets/vfile.txt new file mode 100644 index 00000000..815d5ca0 --- /dev/null +++ b/docs/src/assets/vfile.txt @@ -0,0 +1 @@ +1.19.0 diff --git a/docs/src/defaultunits.md b/docs/src/defaultunits.md new file mode 100644 index 00000000..7d1325fe --- /dev/null +++ b/docs/src/defaultunits.md @@ -0,0 +1,965 @@ +# Pre-defined units and сonstants + +In the following, only non-prefixed units are listed. To get a more detailed information about a unit, and to get information about prefixed units, use `Julia` help, e.g. + +``` +help?> Unitful.kW + Unitful.kW + + A prefixed unit, equal to 10^3 W. + + Dimension: 𝐋² 𝐌 𝐓⁻³ + + See also: Unitful.W. +``` + +For prefixes, see [below](#Metric-(SI)-Prefixes). + + +## 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. + +#### Foot + +``` +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. + +#### Lumen + +``` +Unitful.lm +``` + +The lumen, an SI unit of luminous flux, defined as 1 cd × sr. + +### 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. + +### 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 + +| Unit | Name | +|----------------|---------------------------------| +| `dB` | Decibel | +| `B` | Bel | +| `Np` | Neper | +| `cNp` | Centineper | + +### "Dimensionful" logarithmic units +| Unit | Reference level | +|----------------|---------------------------------| +| `dBHz` | 1Hz | +| `dBm` | 1mW | +| `dBV` | 1V | +| `dBu` | sqrt(0.6)V | +| `dBμV` | 1μV | +| `dBSPL` | 20μPa | +| `dBFS` | RootPowerRatio(1) | +| `dBΩ` | 1Ω | +| `dBS` | 1S | +## 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 + +``` +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). + +#### ϵ0 + +``` +Unitful.ε0 +Unitful.ϵ0 +``` + +A quantity representing the vacuum permittivity constant, defined as 1 / (μ0 × c^2). + +## Metric (SI) Prefixes + +| Prefix | Name | Power of Ten | +|--------|--------|--------| +| y | yocto | -24 | +| z | zepto | -21 | +| a | atto | -18 | +| f | femto | -15 | +| p | pico | -12 | +| n | nano | -9 | +| μ | micro | -6 | +| m | milli | -3 | +| c | centi | -2 | +| d | deci | -1 | +| da | deca | 1 | +| h | hecto | 2 | +| k | kilo | 3 | +| M | mega | 6 | +| G | giga | 9 | +| T | tera | 12 | +| P | peta | 15 | +| E | exa | 18 | +| Z | zetta | 21 | +| Y | yotta | 24 |