From 8a87061c3a28780f4ddb55321b162a771c5fcbb5 Mon Sep 17 00:00:00 2001 From: Mateusz Pusz Date: Fri, 2 Sep 2022 20:09:50 +0200 Subject: [PATCH] docs: Angular Units chapter added --- docs/CMakeLists.txt | 5 +- docs/framework.rst | 1 + docs/framework/angular_units.rst | 100 +++++++++++++++++++++++++++++++ 3 files changed, 104 insertions(+), 2 deletions(-) create mode 100644 docs/framework/angular_units.rst diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt index 87801659..6714f686 100644 --- a/docs/CMakeLists.txt +++ b/docs/CMakeLists.txt @@ -82,6 +82,7 @@ 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" @@ -103,7 +104,7 @@ set(unitsSphinxDocs "${CMAKE_CURRENT_SOURCE_DIR}/reference/core/concepts.rst" "${CMAKE_CURRENT_SOURCE_DIR}/reference/core/customization_points.rst" "${CMAKE_CURRENT_SOURCE_DIR}/reference/core/downcasting.rst" - # "${CMAKE_CURRENT_SOURCE_DIR}/reference/core/functions.rst" + # "${CMAKE_CURRENT_SOURCE_DIR}/reference/core/functions.rst" "${CMAKE_CURRENT_SOURCE_DIR}/reference/core/metafunctions.rst" "${CMAKE_CURRENT_SOURCE_DIR}/reference/core/types.rst" "${CMAKE_CURRENT_SOURCE_DIR}/reference/core/types/dimensions.rst" @@ -119,7 +120,7 @@ set(unitsSphinxDocs "${CMAKE_CURRENT_SOURCE_DIR}/reference/core/types/utilities/basic_fixed_string.rst" "${CMAKE_CURRENT_SOURCE_DIR}/reference/core/types/utilities/basic_symbol_text.rst" "${CMAKE_CURRENT_SOURCE_DIR}/reference/core/types/utilities/ratio.rst" - # "${CMAKE_CURRENT_SOURCE_DIR}/reference/math.rst" + # "${CMAKE_CURRENT_SOURCE_DIR}/reference/math.rst" "${CMAKE_CURRENT_SOURCE_DIR}/reference/random.rst" "${CMAKE_CURRENT_SOURCE_DIR}/reference/systems.rst" "${CMAKE_CURRENT_SOURCE_DIR}/reference/systems/generic.rst" diff --git a/docs/framework.rst b/docs/framework.rst index 952d66fc..05866a96 100644 --- a/docs/framework.rst +++ b/docs/framework.rst @@ -22,4 +22,5 @@ Framework Basics framework/arithmetics framework/constants framework/conversions_and_casting + framework/angular_units framework/text_output diff --git a/docs/framework/angular_units.rst b/docs/framework/angular_units.rst new file mode 100644 index 00000000..905f125c --- /dev/null +++ b/docs/framework/angular_units.rst @@ -0,0 +1,100 @@ +.. namespace:: units + +Angular Units +============= + +Some background information +--------------------------- + +As per today's SI, both radian and steradian are dimensionless. This forces the convention to set the angle ``1 radian`` +equal to the number ``1`` within equations (similar to what natural units system does for ``c`` constant). + +Following `Wikipedia `_: + + Giacomo Prando says "the current state of affairs leads inevitably to ghostly appearances and disappearances of the radian + in the dimensional analysis of physical equations." For example, a mass hanging by a string from a pulley will rise or drop + by :math:`y=rθ`` centimeters, where :math:`r` is the radius of the pulley in centimeters and :math:`θ` is the angle + the pulley turns in radians. When multiplying :math:`r` by :math:`θ` the unit of radians disappears from the result. + Similarly in the formula for the angular velocity of a rolling wheel, :math:`ω=v/r`, radians appear in the units of + :math:`ω` but not on the right hand side. + Anthony French calls this phenomenon "a perennial problem in the teaching of mechanics". Oberhofer says that the typical + advice of ignoring radians during dimensional analysis and adding or removing radians in units according to convention + and contextual knowledge is "pedagogically unsatisfying". + +At least a dozen scientists have made proposals to treat the radian as a base unit of measure defining its own dimension of "angle", +as early as 1936 and as recently as 2022. This would bring the advantages of a physics-based, consistent, and logically-robust +unit system, with unambiguous units for all physical quantities. At the same time the only notable changes for typical +end-users would be: improved units for the quantities **torque**, **angular momentum** and **moment of inertia**. + +Paul Quincey in his proposal `"Angles in the SI: a detailed proposal for solving the problem" `_ states: + + The familiar units assigned to some angular quantities are based on equations that have adopted the radian convention, + and so are missing `rad`s that would be present if the complete equation is used. The physically-correct units are + those with the `rad`s reinstated. Numerical values would not change, and the physical meanings of all quantities would + also be unaffected. + +He proposes the following changes: + +- The **radian** would become either a new base unit or a 'complementary' unit +- The **steradian** would become a derived unit equal to :math:`1\:rad^2` +- The SI units for + + - **Torque** would change from :math:`N\:m` (= J) to :math:`J\:rad^{-1}` + - **Angular momentum** would change from :math:`J\:s` to :math:`J\:s\:rad^{-1}` (i.e. :math:`J/(rad/s)`) + - **Moment of inertia** would change from :math:`kg\:m^2` to :math:`kg\:m^2\:rad^{-2}` (i.e. :math:`J/(rad/s)^2`) + +- The option to omit the radian from the SI units for **angle**, **angular velocity**, **angular frequency**, + **angular acceleration**, and **angular wavenumber** would be removed, the only correct SI units being + :math:`rad`, :math:`rad/s`, :math:`rad/s`, :math:`rad/s^2` and :math:`rad/m` respectively. + + +Angular quantities in the library +--------------------------------- + +The mp-units library strives to define physically-correct quantities and their units to provide maximum help +to its users. As treating angle as a dimensional quantity can lead to many "trivial" mistakes in dimensional +analysis and calculation, it was decided to follow the above approach and treat angle as a base quantity +with a base unit of radian and solid angle as its derived quantity. + +As those the above (at least for now) not a part of :term:`SI`, the plain angle and solid +angle definitions can be found in the *units/generic* subdirectory. However, in the sake of correctness, +they are consistently used in the dimensional recipes of all angle-based :term:`SI` quantities like +torque or angular velocity. + + +Radians and degrees support +--------------------------- + +Thanks to :ref:`framework/magnitudes:Magnitudes` usage the library provides efficient strong types for all +angular types. This means that with the built-in support for magnitudes of :math:`\pi` we can provide +accurate conversions between radians and degrees. The library also provides common trigonometric functions +for angular quantities:: + + using namespace units::aliases::isq::si; + + auto velocity = km_per_h<>(110); + auto rate_of_climb = m_per_s<>(-0.63657); + auto glide_ratio = velocity / -rate_of_climb; + auto glide_angle = asin(1 / glide_ratio); + + std::cout << std::format("Glide ratio: {:%.1Q %q}\n", quantity_cast(glide_ratio)); + std::cout << "Glide angle:\n"; + std::cout << std::format(" - {:%.4Q %q}\n", glide_angle); + std::cout << std::format(" - {:%.2Q %q}\n", quantity_cast(glide_angle)); + std::cout << std::format(" - {:%.2Q %q}\n", quantity_cast(glide_angle)); + +The above program prints: + +.. code-block:: + + Glide ratio: 48.0 + Glide angle: + - 0.0208 rad + - 1.19 ° + - 1.33 ᵍ + +.. note:: + + The above ``velocity`` and ``rate_of_climb`` in the production code should be modelled as + :ref:`framework/quantity_kinds:Quantity Kinds`. + A better but longer code can be found in the :ref:`examples/basics/glide_computer:glide_computer` example.