diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt index 6714f686..297261a7 100644 --- a/docs/CMakeLists.txt +++ b/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" diff --git a/docs/defining_systems.rst b/docs/defining_systems.rst new file mode 100644 index 00000000..f40c9f8e --- /dev/null +++ b/docs/defining_systems.rst @@ -0,0 +1,9 @@ +Defining Systems +================ + +.. toctree:: + :maxdepth: 2 + + defining_systems/isq + defining_systems/si + defining_systems/angular_units diff --git a/docs/framework/angular_units.rst b/docs/defining_systems/angular_units.rst similarity index 77% rename from docs/framework/angular_units.rst rename to docs/defining_systems/angular_units.rst index a4303f84..9cfdeda4 100644 --- a/docs/framework/angular_units.rst +++ b/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 --------------------------------- diff --git a/docs/defining_systems/isq.rst b/docs/defining_systems/isq.rst new file mode 100644 index 00000000..3c243afd --- /dev/null +++ b/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 struct dim_time : base_dimension<"T", U> {}; + template struct dim_length : base_dimension<"L", U> {}; + template struct dim_mass : base_dimension<"M", U> {}; + template struct dim_electric_current : base_dimension<"I", U> {}; + template struct dim_thermodynamic_temperature : base_dimension<"Θ", U> {}; + template struct dim_amount_of_substance : base_dimension<"N", U> {}; + template 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. diff --git a/docs/defining_systems/si.rst b/docs/defining_systems/si.rst new file mode 100644 index 00000000..896a9ed2 --- /dev/null +++ b/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 {}; + struct dim_time : isq::dim_time {}; + template U, Representation Rep = double> + using time = quantity; + + struct metre : named_unit {}; + struct dim_length : isq::dim_length {}; + template U, Representation Rep = double> + using length = quantity; + + struct gram : named_unit {}; + struct kilogram : prefixed_unit {}; + struct dim_mass : isq::dim_mass {}; + template U, Representation Rep = double> + using mass = quantity; + + struct ampere : named_unit {}; + struct dim_electric_current : isq::dim_electric_current {}; + template U, Representation Rep = double> + using electric_current = quantity; + + struct kelvin : named_unit {}; + struct dim_thermodynamic_temperature : isq::dim_thermodynamic_temperature {}; + template U, Representation Rep = double> + using thermodynamic_temperature = quantity; + + struct mole : named_unit {}; + struct dim_amount_of_substance : isq::dim_amount_of_substance {}; + template U, Representation Rep = double> + using amount_of_substance = quantity; + + struct candela : named_unit {}; + struct dim_luminous_intensity : isq::dim_luminous_intensity {}; + template U, Representation Rep = double> + using luminous_intensity = quantity; + + } + + +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()> {}; + struct zepto : prefix()> {}; + struct atto : prefix()> {}; + struct femto : prefix()> {}; + struct pico : prefix()> {}; + struct nano : prefix()> {}; + struct micro : prefix()> {}; + struct milli : prefix()> {}; + struct centi : prefix()> {}; + struct deci : prefix()> {}; + struct deca : prefix()> {}; + struct hecto : prefix()> {}; + struct kilo : prefix()> {}; + struct mega : prefix()> {}; + struct giga : prefix()> {}; + struct tera : prefix()> {}; + struct peta : prefix()> {}; + struct exa : prefix()> {}; + struct zetta : prefix()> {}; + struct yotta : prefix()> {}; + + } + + +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 {}; + + } + +- :ref:`framework/quantities:Quantity References (Experimental)`:: + + namespace units::isq::si { + + namespace time_references { + + inline constexpr auto s = reference{}; + + } + + namespace references { + + using namespace time_references; + + } + +- :ref:`framework/quantities:Unit-Specific Aliases (Experimental)`:: + + namespace units::aliases::isq::si::inline time { + + template + using s = units::isq::si::time; + + } + +- :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(l)); + return time(static_cast(l)); + } + constexpr auto operator"" _q_s(long double l) { return time(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(), second> {}; + struct hour : named_scaled_unit(), minute> {}; + struct day : named_scaled_unit(), 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 + inline constexpr auto hyperfine_structure_transition_frequency = frequency(Rep{9'192'631'770}); + + template + inline constexpr auto speed_of_light = speed(299'792'458); + + template + inline constexpr auto planck_constant = energy(6.62607015e-34) * time(1); + + template + inline constexpr auto elementary_charge = electric_charge(1.602176634e-19); + + template + inline constexpr auto boltzmann_constant = energy(1.380649e-23) / thermodynamic_temperature(1); + + template + inline constexpr auto avogadro_constant = Rep(6.02214076e23) / amount_of_substance(1); + + template + inline constexpr auto luminous_efficacy = luminous_flux(683) / power(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. diff --git a/docs/framework.rst b/docs/framework.rst index 05866a96..952d66fc 100644 --- a/docs/framework.rst +++ b/docs/framework.rst @@ -22,5 +22,4 @@ Framework Basics framework/arithmetics framework/constants framework/conversions_and_casting - framework/angular_units framework/text_output diff --git a/docs/framework/dimensions.rst b/docs/framework/dimensions.rst index 524d1b8b..ff8e0051 100644 --- a/docs/framework/dimensions.rst +++ b/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: diff --git a/docs/framework/units.rst b/docs/framework/units.rst index af40ebd1..6a0b418a 100644 --- a/docs/framework/units.rst +++ b/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):: diff --git a/docs/index.rst b/docs/index.rst index 0cfb607f..45d40188 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -30,6 +30,7 @@ with a permissive `MIT license `_, International Organization for Standardization. -.. [Quincey] `"Angles in the SI: a detailed proposal for solving the problem" `_, Quincey, Paul (1 October 2021) +.. [SIBrochure] `The International System of Units (SI) `_, 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" `_, Quincey, Paul (1 October 2021).