forked from mpusz/mp-units
docs: "Defining Systems" chapter added
This commit is contained in:
Mateusz Pusz
@@ -46,6 +46,10 @@ set(unitsSphinxDocs
|
||||
"${CMAKE_CURRENT_SOURCE_DIR}/_static/img/units.svg"
|
||||
"${CMAKE_CURRENT_SOURCE_DIR}/_static/img/quantity_like.svg"
|
||||
"${CMAKE_CURRENT_SOURCE_DIR}/CHANGELOG.md"
|
||||
"${CMAKE_CURRENT_SOURCE_DIR}/defining_systems.rst"
|
||||
"${CMAKE_CURRENT_SOURCE_DIR}/defining_systems/angular_units.rst"
|
||||
"${CMAKE_CURRENT_SOURCE_DIR}/defining_systems/isq.rst"
|
||||
"${CMAKE_CURRENT_SOURCE_DIR}/defining_systems/si.rst"
|
||||
"${CMAKE_CURRENT_SOURCE_DIR}/design.rst"
|
||||
"${CMAKE_CURRENT_SOURCE_DIR}/design/directories.rst"
|
||||
"${CMAKE_CURRENT_SOURCE_DIR}/design/downcasting.rst"
|
||||
@@ -82,7 +86,6 @@ set(unitsSphinxDocs
|
||||
"${CMAKE_CURRENT_SOURCE_DIR}/examples/kalman_filter/kalman.rst"
|
||||
"${CMAKE_CURRENT_SOURCE_DIR}/faq.rst"
|
||||
"${CMAKE_CURRENT_SOURCE_DIR}/framework.rst"
|
||||
"${CMAKE_CURRENT_SOURCE_DIR}/framework/angular_units.rst"
|
||||
"${CMAKE_CURRENT_SOURCE_DIR}/framework/arithmetics.rst"
|
||||
"${CMAKE_CURRENT_SOURCE_DIR}/framework/basic_concepts.rst"
|
||||
"${CMAKE_CURRENT_SOURCE_DIR}/framework/constants.rst"
|
||||
|
||||
9
docs/defining_systems.rst
Normal file
9
docs/defining_systems.rst
Normal file
@@ -0,0 +1,9 @@
|
||||
Defining Systems
|
||||
================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
defining_systems/isq
|
||||
defining_systems/si
|
||||
defining_systems/angular_units
|
||||
@@ -59,6 +59,36 @@ Paul Quincey summarizes that with the above in action:
|
||||
can be measured in terms of the Planck constant.
|
||||
|
||||
|
||||
Angular quantities in the :term:`SI`
|
||||
------------------------------------
|
||||
|
||||
Even though the :term:`SI` somehow ignores the dimensionality of angle:
|
||||
|
||||
Plane and solid angles, when expressed in radians and steradians respectively, are in effect
|
||||
also treated within the SI as quantities with the unit one. The symbols :math:`rad`
|
||||
and :math:`sr` are written explicitly where appropriate, in order to emphasize that, for radians or
|
||||
steradians, the quantity being considered is, or involves the plane angle or solid angle
|
||||
respectively. For steradians it emphasizes the distinction between units of flux and intensity
|
||||
in radiometry and photometry for example. However, it is a long-established practice in
|
||||
mathematics and across all areas of science to make use of :math:`rad = 1` and :math:`sr = 1`.
|
||||
For historical reasons the radian and steradian are treated as derived units.
|
||||
|
||||
It also explicitly states:
|
||||
|
||||
The SI unit of frequency is hertz, the SI unit of angular velocity and angular frequency is
|
||||
radian per second, and the SI unit of activity is becquerel, implying counts per second.
|
||||
Although it is formally correct to write all three of these units as the reciprocal second, the
|
||||
use of the different names emphasizes the different nature of the quantities concerned. It is
|
||||
especially important to carefully distinguish frequencies from angular frequencies, because
|
||||
by definition their numerical values differ by a factor of :math:`2\pi`. Ignoring this fact may cause
|
||||
an error of :math:`2\pi`. Note that in some countries, frequency values are conventionally expressed
|
||||
using “cycle/s” or “cps” instead of the SI unit :math:`Hz`, although “cycle” and “cps” are not units
|
||||
in the SI. Note also that it is common, although not recommended, to use the term
|
||||
frequency for quantities expressed in :math:`rad/s`. Because of this, it is recommended that
|
||||
quantities called “frequency”, “angular frequency”, and “angular velocity” always be given
|
||||
explicit units of :math:`Hz` or :math:`rad/s`` and not :math:`s^{-1}`.
|
||||
|
||||
|
||||
Angular quantities in the library
|
||||
---------------------------------
|
||||
|
||||
48
docs/defining_systems/isq.rst
Normal file
48
docs/defining_systems/isq.rst
Normal file
@@ -0,0 +1,48 @@
|
||||
.. namespace:: units
|
||||
|
||||
International System of Quantities (ISQ)
|
||||
========================================
|
||||
|
||||
According to [ISO80000]_:
|
||||
|
||||
The system of quantities, including the relations among them the quantities used as the basis of the units of
|
||||
the SI, is named the **International System of Quantities**, denoted "ISQ", in all languages.
|
||||
|
||||
|
||||
Base dimensions and their symbols
|
||||
---------------------------------
|
||||
|
||||
According to the [SIBrochure]_:
|
||||
|
||||
Physical quantities can be organized in a system of dimensions, where the system used is
|
||||
decided by convention. Each of the seven base quantities used in the SI is regarded as
|
||||
having its own dimension. The symbols used for the base quantities and the symbols used
|
||||
to denote their dimension are shown in Table 3.
|
||||
|
||||
Following that the library provides the following definitions::
|
||||
|
||||
namespace units::isq {
|
||||
|
||||
template<Unit U> struct dim_time : base_dimension<"T", U> {};
|
||||
template<Unit U> struct dim_length : base_dimension<"L", U> {};
|
||||
template<Unit U> struct dim_mass : base_dimension<"M", U> {};
|
||||
template<Unit U> struct dim_electric_current : base_dimension<"I", U> {};
|
||||
template<Unit U> struct dim_thermodynamic_temperature : base_dimension<"Θ", U> {};
|
||||
template<Unit U> struct dim_amount_of_substance : base_dimension<"N", U> {};
|
||||
template<Unit U> struct dim_luminous_intensity : base_dimension<"J", U> {};
|
||||
|
||||
}
|
||||
|
||||
Base dimension symbols provided above are consistently defined by both [SIBrochure]_ and [ISO80000]_.
|
||||
|
||||
|
||||
Derived dimensions
|
||||
------------------
|
||||
|
||||
[SIBrochure]_ states:
|
||||
|
||||
Since the number of quantities is without limit, it is not possible to
|
||||
provide a complete list of derived quantities and derived units.
|
||||
|
||||
The authors of this library decided to limit the set of defined quantities to all
|
||||
quantities defined in the [ISO80000]_ series of documents.
|
||||
231
docs/defining_systems/si.rst
Normal file
231
docs/defining_systems/si.rst
Normal file
@@ -0,0 +1,231 @@
|
||||
.. namespace:: units
|
||||
|
||||
The International System of Units (SI)
|
||||
======================================
|
||||
|
||||
The :term:`SI` system is defined in the [SIBrochure]_ and standardizes units for quantities provided in
|
||||
the :term:`ISQ` system:
|
||||
|
||||
The SI is a consistent system of units for use in all aspects of life, including international
|
||||
trade, manufacturing, security, health and safety, protection of the environment, and in the
|
||||
basic science that underpins all of these. The system of quantities underlying the SI and the
|
||||
equations relating them are based on the present description of nature and are familiar to all
|
||||
scientists, technologists and engineers.
|
||||
|
||||
As the :term:`SI` is defined on top of the :term:`ISQ` the C++ namespace for all of its definitions
|
||||
is ``units::isq::si``.
|
||||
|
||||
Base units
|
||||
----------
|
||||
|
||||
Even though from 2019 the :term:`SI` system is defined in terms of the `Defining constants`_,
|
||||
base units still are really important. As the [SIBrochure]_ states:
|
||||
|
||||
Prior to the definitions adopted in 2018, the SI was defined through seven base units from
|
||||
which the derived units were constructed as products of powers of the base units. Defining
|
||||
the SI by fixing the numerical values of seven defining constants has the effect that this
|
||||
distinction is, in principle, not needed, since all units, base as well as derived units, may be
|
||||
constructed directly from the defining constants. Nevertheless, the concept of base and
|
||||
derived units is maintained because it is useful and historically well established, noting
|
||||
also that the ISO/IEC 80000 series of Standards specify base and derived quantities which
|
||||
necessarily correspond to the SI base and derived units defined here.
|
||||
|
||||
The base units and quantities of the :term:`SI` system are defined as follows::
|
||||
|
||||
namespace units::isq::si {
|
||||
|
||||
struct second : named_unit<second, "s"> {};
|
||||
struct dim_time : isq::dim_time<second> {};
|
||||
template<UnitOf<dim_time> U, Representation Rep = double>
|
||||
using time = quantity<dim_time, U, Rep>;
|
||||
|
||||
struct metre : named_unit<metre, "m"> {};
|
||||
struct dim_length : isq::dim_length<metre> {};
|
||||
template<UnitOf<dim_length> U, Representation Rep = double>
|
||||
using length = quantity<dim_length, U, Rep>;
|
||||
|
||||
struct gram : named_unit<gram, "g"> {};
|
||||
struct kilogram : prefixed_unit<kilogram, kilo, gram> {};
|
||||
struct dim_mass : isq::dim_mass<kilogram> {};
|
||||
template<UnitOf<dim_mass> U, Representation Rep = double>
|
||||
using mass = quantity<dim_mass, U, Rep>;
|
||||
|
||||
struct ampere : named_unit<ampere, "A"> {};
|
||||
struct dim_electric_current : isq::dim_electric_current<ampere> {};
|
||||
template<UnitOf<dim_electric_current> U, Representation Rep = double>
|
||||
using electric_current = quantity<dim_electric_current, U, Rep>;
|
||||
|
||||
struct kelvin : named_unit<kelvin, "K"> {};
|
||||
struct dim_thermodynamic_temperature : isq::dim_thermodynamic_temperature<kelvin> {};
|
||||
template<UnitOf<dim_thermodynamic_temperature> U, Representation Rep = double>
|
||||
using thermodynamic_temperature = quantity<dim_thermodynamic_temperature, U, Rep>;
|
||||
|
||||
struct mole : named_unit<mole, "mol"> {};
|
||||
struct dim_amount_of_substance : isq::dim_amount_of_substance<mole> {};
|
||||
template<UnitOf<dim_amount_of_substance> U, Representation Rep = double>
|
||||
using amount_of_substance = quantity<dim_amount_of_substance, U, Rep>;
|
||||
|
||||
struct candela : named_unit<candela, "cd"> {};
|
||||
struct dim_luminous_intensity : isq::dim_luminous_intensity<candela> {};
|
||||
template<UnitOf<dim_luminous_intensity> U, Representation Rep = double>
|
||||
using luminous_intensity = quantity<dim_luminous_intensity, U, Rep>;
|
||||
|
||||
}
|
||||
|
||||
|
||||
Derived units
|
||||
-------------
|
||||
|
||||
The [SIBrochure]_ states:
|
||||
|
||||
Derived units are defined as products of powers of the base units. When the numerical
|
||||
factor of this product is one, the derived units are called coherent derived units. The base
|
||||
and coherent derived units of the SI form a coherent set, designated the set of coherent SI
|
||||
units. The word “coherent” here means that equations between the numerical values of
|
||||
quantities take exactly the same form as the equations between the quantities themselves.
|
||||
Some of the coherent derived units in the SI are given special names. ... Together with the
|
||||
seven base units they form the core of the set of SI units. All other SI units are combinations
|
||||
of some of these 29 units.
|
||||
|
||||
|
||||
Unit prefixes
|
||||
-------------
|
||||
|
||||
According to [SIBrochure]_:
|
||||
|
||||
Prefixes may be used with any of the 29 SI units with special names with
|
||||
the exception of the base unit kilogram.
|
||||
|
||||
Here is a complete list of all the :term:`SI` prefixes supported by the library::
|
||||
|
||||
namespace si {
|
||||
|
||||
struct yocto : prefix<yocto, "y", mag_power<10, -24>()> {};
|
||||
struct zepto : prefix<zepto, "z", mag_power<10, -21>()> {};
|
||||
struct atto : prefix<atto, "a", mag_power<10, -18>()> {};
|
||||
struct femto : prefix<femto, "f", mag_power<10, -15>()> {};
|
||||
struct pico : prefix<pico, "p", mag_power<10, -12>()> {};
|
||||
struct nano : prefix<nano, "n", mag_power<10, -9>()> {};
|
||||
struct micro : prefix<micro, basic_symbol_text{"\u00b5", "u"},
|
||||
mag_power<10, -6>()> {};
|
||||
struct milli : prefix<milli, "m", mag_power<10, -3>()> {};
|
||||
struct centi : prefix<centi, "c", mag_power<10, -2>()> {};
|
||||
struct deci : prefix<deci, "d", mag_power<10, -1>()> {};
|
||||
struct deca : prefix<deca, "da", mag_power<10, 1>()> {};
|
||||
struct hecto : prefix<hecto, "h", mag_power<10, 2>()> {};
|
||||
struct kilo : prefix<kilo, "k", mag_power<10, 3>()> {};
|
||||
struct mega : prefix<mega, "M", mag_power<10, 6>()> {};
|
||||
struct giga : prefix<giga, "G", mag_power<10, 9>()> {};
|
||||
struct tera : prefix<tera, "T", mag_power<10, 12>()> {};
|
||||
struct peta : prefix<peta, "P", mag_power<10, 15>()> {};
|
||||
struct exa : prefix<exa, "E", mag_power<10, 18>()> {};
|
||||
struct zetta : prefix<zetta, "Z", mag_power<10, 21>()> {};
|
||||
struct yotta : prefix<yotta, "Y", mag_power<10, 24>()> {};
|
||||
|
||||
}
|
||||
|
||||
|
||||
Other definitions for names units
|
||||
---------------------------------
|
||||
|
||||
For all of the above units the library also provides:
|
||||
|
||||
- prefixed versions using SI prefixes::
|
||||
|
||||
namespace units::isq::si {
|
||||
|
||||
struct millisecond : prefixed_unit<millisecond, milli, second> {};
|
||||
|
||||
}
|
||||
|
||||
- :ref:`framework/quantities:Quantity References (Experimental)`::
|
||||
|
||||
namespace units::isq::si {
|
||||
|
||||
namespace time_references {
|
||||
|
||||
inline constexpr auto s = reference<dim_time, second>{};
|
||||
|
||||
}
|
||||
|
||||
namespace references {
|
||||
|
||||
using namespace time_references;
|
||||
|
||||
}
|
||||
|
||||
- :ref:`framework/quantities:Unit-Specific Aliases (Experimental)`::
|
||||
|
||||
namespace units::aliases::isq::si::inline time {
|
||||
|
||||
template<Representation Rep = double>
|
||||
using s = units::isq::si::time<units::isq::si::second, Rep>;
|
||||
|
||||
}
|
||||
|
||||
- :ref:`framework/quantities:User Defined Literals (Experimental)`::
|
||||
|
||||
namespace units::isq::si::inline literals {
|
||||
|
||||
constexpr auto operator"" _q_s(unsigned long long l)
|
||||
{
|
||||
gsl_ExpectsAudit(std::in_range<std::int64_t>(l));
|
||||
return time<second, std::int64_t>(static_cast<std::int64_t>(l));
|
||||
}
|
||||
constexpr auto operator"" _q_s(long double l) { return time<second, long double>(l); }
|
||||
|
||||
}
|
||||
|
||||
For some of the units, when accepted by the :term:`SI`, other non-standard scaled versions are also provided::
|
||||
|
||||
namespace units::isq::si {
|
||||
|
||||
struct minute : named_scaled_unit<minute, "min", mag<60>(), second> {};
|
||||
struct hour : named_scaled_unit<hour, "h", mag<60>(), minute> {};
|
||||
struct day : named_scaled_unit<day, "d", mag<24>(), hour> {};
|
||||
|
||||
}
|
||||
|
||||
|
||||
|
||||
|
||||
Defining constants
|
||||
------------------
|
||||
|
||||
[SIBrochure]_ states that:
|
||||
|
||||
The definition of the SI units is established in terms of a set of seven defining constants.
|
||||
The complete system of units can be derived from the fixed values of these defining
|
||||
constants, expressed in the units of the SI.
|
||||
|
||||
Those constants are provided in the *units/isq/si/constants.h* header file as::
|
||||
|
||||
namespace units::isq::si::si2019 {
|
||||
|
||||
template<Representation Rep = double>
|
||||
inline constexpr auto hyperfine_structure_transition_frequency = frequency<hertz, Rep>(Rep{9'192'631'770});
|
||||
|
||||
template<Representation Rep = double>
|
||||
inline constexpr auto speed_of_light = speed<metre_per_second, Rep>(299'792'458);
|
||||
|
||||
template<Representation Rep = double>
|
||||
inline constexpr auto planck_constant = energy<joule, Rep>(6.62607015e-34) * time<second, Rep>(1);
|
||||
|
||||
template<Representation Rep = double>
|
||||
inline constexpr auto elementary_charge = electric_charge<coulomb, Rep>(1.602176634e-19);
|
||||
|
||||
template<Representation Rep = double>
|
||||
inline constexpr auto boltzmann_constant = energy<joule, Rep>(1.380649e-23) / thermodynamic_temperature<kelvin, Rep>(1);
|
||||
|
||||
template<Representation Rep = double>
|
||||
inline constexpr auto avogadro_constant = Rep(6.02214076e23) / amount_of_substance<mole, Rep>(1);
|
||||
|
||||
template<Representation Rep = double>
|
||||
inline constexpr auto luminous_efficacy = luminous_flux<lumen, Rep>(683) / power<watt, Rep>(1);
|
||||
|
||||
}
|
||||
|
||||
.. note::
|
||||
|
||||
Please note the nested `si2019` namespace. It is introduced in case those constants were changed/updated
|
||||
by the :term:`SI` in the future.
|
||||
@@ -22,5 +22,4 @@ Framework Basics
|
||||
framework/arithmetics
|
||||
framework/constants
|
||||
framework/conversions_and_casting
|
||||
framework/angular_units
|
||||
framework/text_output
|
||||
|
||||
@@ -50,6 +50,20 @@ The quantities of derived dimensions are called
|
||||
quantities. This means that they are created by multiplying or dividing
|
||||
quantities of other dimensions.
|
||||
|
||||
The [SIBrochure]_ states:
|
||||
|
||||
All other quantities, with the exception of counts, are derived quantities, which may be
|
||||
written in terms of base quantities according to the equations of physics. The dimensions of
|
||||
the derived quantities are written as products of powers of the dimensions of the base
|
||||
quantities using the equations that relate the derived quantities to the base quantities.
|
||||
In general the dimension of any quantity :math:`Q` is written in the form of a dimensional product,
|
||||
|
||||
:math:`dim Q = T^\alpha L^\beta M^\gamma I^\delta \Theta^\varepsilon N^\zeta J^\eta`
|
||||
|
||||
where the exponents :math:`\alpha`, :math:`\beta`, :math:`\gamma`, :math:`\delta`, :math:`\varepsilon`,
|
||||
:math:`\zeta` and :math:`\eta`, which are generally small integers, which can be positive,
|
||||
negative, or zero, are called the dimensional exponents.
|
||||
|
||||
Looking at the previous code snippets the area, speed, or frequency are
|
||||
the examples of such quantities. Each derived quantity can be represented
|
||||
as a unique list of exponents of base quantities. For example:
|
||||
|
||||
@@ -260,6 +260,14 @@ example we can define ``si::kilometre`` as::
|
||||
as ``km²`` would be invalid).
|
||||
|
||||
|
||||
.. note::
|
||||
|
||||
[SIBrochure]_ states:
|
||||
|
||||
However, when prefixes are used with SI units, the resulting units are no
|
||||
longer coherent, because the prefix introduces a numerical factor other than one.
|
||||
|
||||
|
||||
Derived Units
|
||||
-------------
|
||||
|
||||
@@ -268,10 +276,21 @@ Derived Units
|
||||
names (i.e. ``N`` (newton)) or can be composed from the names of units of quantities
|
||||
used to define thier derived quantity (i.e. ``km/h``).
|
||||
|
||||
The [SIBrochure]_ states:
|
||||
|
||||
Derived units are defined as products of powers of the base units. When the numerical
|
||||
factor of this product is one, the derived units are called coherent derived units. The base
|
||||
and coherent derived units of the SI form a coherent set, designated the set of coherent SI
|
||||
units. The word “coherent” here means that equations between the numerical values of
|
||||
quantities take exactly the same form as the equations between the quantities themselves.
|
||||
|
||||
Derived Named Units
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The [SIBrochure]_ also says:
|
||||
|
||||
Some of the coherent derived units in the SI are given special names.
|
||||
|
||||
Derived named units have a unique symbol (i.e. ``N`` (newton) or ``Pa``
|
||||
(pascal)) and they are defined in the same way as base units (which
|
||||
always have to be a named unit)::
|
||||
|
||||
@@ -30,6 +30,7 @@ with a permissive `MIT license <https://github.com/mpusz/units/blob/master/LICEN
|
||||
introduction
|
||||
quick_start
|
||||
framework
|
||||
defining_systems
|
||||
use_cases
|
||||
design
|
||||
examples
|
||||
|
||||
@@ -2,4 +2,5 @@ References
|
||||
==========
|
||||
|
||||
.. [ISO80000] `ISO 80000-1:2009(E) "Quantities and units — Part 1: General" <https://www.iso.org/standard/30669.html>`_, International Organization for Standardization.
|
||||
.. [Quincey] `"Angles in the SI: a detailed proposal for solving the problem" <https://arxiv.org/pdf/2108.05704.pdf>`_, Quincey, Paul (1 October 2021)
|
||||
.. [SIBrochure] `The International System of Units (SI) <https://www.bipm.org/documents/20126/41483022/SI-Brochure-9-EN.pdf>`_, International Bureau of Weights and Measures (20 May 2019), ISBN 978-92-822-2272-0.
|
||||
.. [Quincey] `"Angles in the SI: a detailed proposal for solving the problem" <https://arxiv.org/pdf/2108.05704.pdf>`_, Quincey, Paul (1 October 2021).
|
||||
|
||||
Reference in New Issue
Block a user