docs: "Defining Systems" chapter added

docs/CMakeLists.txt

@@ -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"

docs/defining_systems.rst

@@ -0,0 +1,9 @@
+Defining Systems
+================
+
+.. toctree::
+    :maxdepth: 2
+
+    defining_systems/isq
+    defining_systems/si
+    defining_systems/angular_units

docs/defining_systems/angular_units.rst

@@ -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
 ---------------------------------
 

docs/defining_systems/isq.rst

@@ -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.

docs/defining_systems/si.rst

@@ -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.

docs/framework.rst

@@ -22,5 +22,4 @@ Framework Basics
     framework/arithmetics
     framework/constants
     framework/conversions_and_casting
-    framework/angular_units
     framework/text_output

docs/framework/dimensions.rst

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

docs/framework/units.rst

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

docs/index.rst

@@ -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

docs/references.rst

@@ -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).