From 9f9d897dbf902727caae86adcd2fd0fc4c0830ef Mon Sep 17 00:00:00 2001 From: Roland Conybeare Date: Wed, 8 May 2024 22:13:35 -0400 Subject: [PATCH] xo-unit: streamline unit spec + docs --- docs/CMakeLists.txt | 2 +- docs/development.rst | 18 +++++++ docs/implementation.rst | 18 +++++-- docs/index.rst | 1 + include/xo/unit/scaled_unit.hpp | 95 ++++++++++++++++++--------------- 5 files changed, 88 insertions(+), 46 deletions(-) create mode 100644 docs/development.rst diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt index ff7096ee..7e185091 100644 --- a/docs/CMakeLists.txt +++ b/docs/CMakeLists.txt @@ -3,7 +3,7 @@ xo_doxygen_collect_deps() xo_docdir_doxygen_config() xo_docdir_sphinx_config( - index.rst examples.rst glossary.rst install.rst implementation.rst + index.rst examples.rst glossary.rst install.rst implementation.rst development.rst quantity-reference.rst quantity-class.rst quantity-factoryfunctions.rst quantity-unitvars.rst unit-reference.rst unit-concept.rst unit-quantities.rst basis-unit-reference.rst basis-unit-class.rst basis-unit-constants.rst diff --git a/docs/development.rst b/docs/development.rst new file mode 100644 index 00000000..3b5d7207 --- /dev/null +++ b/docs/development.rst @@ -0,0 +1,18 @@ +.. _development: + +Miscellaneous development notes for *xo-unit*. + +How To... +========= + +Add Basis Unit +-------------- + +To add a basis unit for an existing dimension: + +#. add unit definition to the ``xo::qty::bu`` namespace in ``include/xo/unit/basis_unit.hpp`` +#. add call to ``bu_store::bu_establish_abbrev()`` from ``bu_store::bu_store``. +#. add ``natural_unit`` definition to ``xo::qty::nu`` namespace in ``include/xo/unit/natural_unit.hpp`` +#. add ``scaled_unit`` definition to ``xo::qty::u`` namespace in ``include/xo/unit/scaled_unit.hpp``. +#. add unit quantity to ``xo::qty::qty`` namespace in ``include/xo/unit/quantity.hpp`` +#. add factory function to ``xo::qty::qty`` namespace in ``include/xo/unit/quantity.hpp`` diff --git a/docs/implementation.rst b/docs/implementation.rst index 46952feb..da71bd15 100644 --- a/docs/implementation.rst +++ b/docs/implementation.rst @@ -15,7 +15,9 @@ Abstraction tower for *xo-unit* components. | natural_unit | +-----------------------+ | bpu | - +-----------------------+ + +-----------+ | + | bu_store | | + +-----------+-----------+ | basis_unit | +-----------------------+ | dimension | @@ -50,6 +52,12 @@ Abstraction tower for *xo-unit* components. A power of a basis unit. Has a single dimension. +- bu_store: + + Associates basis units with abbreviations. + + For example ``bu::kilogram`` => ``"kg"`` + - basis_unit: see :doc:`basis-unit-reference`. A unit with a single dimension and scale. @@ -184,11 +192,15 @@ Worked example using :cpp:class:`xo::qty::quantity` .. code-block:: cpp :linenos: - namespace su = xo::qty::su; + namespace u = xo::qty::u; // (123*7.55) ng.km.min^-2 ==> 2.57958e-10kg.m.s^-2 - quantity qty3b = qty3.rescale_ext(); + constexpr auto newton = u::kilogram * u::meter / (u::second * u::second); + + quantity qty3b = qty3; + + // quantity qty3b = qty3.rescale_ext(); .. uml:: :caption: quantity 928.65 ng.km.min^-2 diff --git a/docs/index.rst b/docs/index.rst index ad724f8d..e8b40b09 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -33,6 +33,7 @@ runtime (since we can't construct new c++ types at runtime). install examples implementation + development unit-quantities quantity-reference unit-reference diff --git a/include/xo/unit/scaled_unit.hpp b/include/xo/unit/scaled_unit.hpp index 20f4025f..8e75c0f0 100644 --- a/include/xo/unit/scaled_unit.hpp +++ b/include/xo/unit/scaled_unit.hpp @@ -70,53 +70,64 @@ namespace xo { * quantity velocity; */ - constexpr auto picogram = detail::su_promote(nu::picogram); - constexpr auto nanogram = detail::su_promote(nu::nanogram); - constexpr auto microgram = detail::su_promote(nu::microgram); - constexpr auto milligram = detail::su_promote(nu::milligram); - constexpr auto gram = detail::su_promote(nu::gram); - constexpr auto kilogram = detail::su_promote(nu::kilogram); - constexpr auto tonne = detail::su_promote(nu::tonne); - constexpr auto kilotonne = detail::su_promote(nu::kilotonne); - constexpr auto megatonne = detail::su_promote(nu::megatonne); - constexpr auto gigatonne = detail::su_promote(nu::gigatonne); + constexpr auto + su_from_bu(const basis_unit & bu, + const power_ratio_type & power = power_ratio_type(1)) + { + return detail::su_promote(natural_unit::from_bu(bu, power)); + } - constexpr auto picometer = detail::su_promote(nu::picometer); - constexpr auto nanometer = detail::su_promote(nu::nanometer); - constexpr auto micrometer = detail::su_promote(nu::micrometer); - constexpr auto millimeter = detail::su_promote(nu::millimeter); - constexpr auto meter = detail::su_promote(nu::meter); - constexpr auto kilometer = detail::su_promote(nu::kilometer); - constexpr auto megameter = detail::su_promote(nu::megameter); - constexpr auto gigameter = detail::su_promote(nu::gigameter); + constexpr auto picogram = su_from_bu(detail::bu::picogram); + constexpr auto nanogram = su_from_bu(detail::bu::nanogram); + constexpr auto microgram = su_from_bu(detail::bu::microgram); + constexpr auto milligram = su_from_bu(detail::bu::milligram); + constexpr auto gram = su_from_bu(detail::bu::gram); + constexpr auto kilogram = su_from_bu(detail::bu::kilogram); + constexpr auto tonne = su_from_bu(detail::bu::tonne); + constexpr auto kilotonne = su_from_bu(detail::bu::kilotonne); + constexpr auto megatonne = su_from_bu(detail::bu::megatonne); + constexpr auto gigatonne = su_from_bu(detail::bu::gigatonne); - constexpr auto lightsecond = detail::su_promote(nu::lightsecond); - constexpr auto astronomicalunit = detail::su_promote(nu::astronomicalunit); + constexpr auto picometer = su_from_bu(detail::bu::picometer); + constexpr auto nanometer = su_from_bu(detail::bu::nanometer); + constexpr auto micrometer = su_from_bu(detail::bu::micrometer); + constexpr auto millimeter = su_from_bu(detail::bu::millimeter); + constexpr auto meter = su_from_bu(detail::bu::meter); + constexpr auto kilometer = su_from_bu(detail::bu::kilometer); + constexpr auto megameter = su_from_bu(detail::bu::megameter); + constexpr auto gigameter = su_from_bu(detail::bu::gigameter); - constexpr auto inch = detail::su_promote(nu::inch); - constexpr auto foot = detail::su_promote(nu::foot); - constexpr auto yard = detail::su_promote(nu::yard); - constexpr auto mile = detail::su_promote(nu::mile); + constexpr auto lightsecond = su_from_bu(detail::bu::lightsecond); + constexpr auto astronomicalunit = su_from_bu(detail::bu::astronomicalunit); - constexpr auto picosecond = detail::su_promote(nu::picosecond); - constexpr auto nanosecond = detail::su_promote(nu::nanosecond); - constexpr auto microsecond = detail::su_promote(nu::microsecond); - constexpr auto millisecond = detail::su_promote(nu::millisecond); - constexpr auto second = detail::su_promote(nu::second); - constexpr auto minute = detail::su_promote(nu::minute); - constexpr auto hour = detail::su_promote(nu::hour); - constexpr auto day = detail::su_promote(nu::day); - constexpr auto week = detail::su_promote(nu::week); - constexpr auto month = detail::su_promote(nu::month); - constexpr auto year = detail::su_promote(nu::year); - constexpr auto year250 = detail::su_promote(nu::year250); - constexpr auto year360 = detail::su_promote(nu::year360); - constexpr auto year365 = detail::su_promote(nu::year365); + constexpr auto inch = su_from_bu(detail::bu::inch); + constexpr auto foot = su_from_bu(detail::bu::foot); + constexpr auto yard = su_from_bu(detail::bu::yard); + constexpr auto mile = su_from_bu(detail::bu::mile); - constexpr auto volatility_30d = detail::su_promote(nu::volatility_30d); - constexpr auto volatility_250d = detail::su_promote(nu::volatility_250d); - constexpr auto volatility_360d = detail::su_promote(nu::volatility_360d); - constexpr auto volatility_365d = detail::su_promote(nu::volatility_365d); + constexpr auto picosecond = su_from_bu(detail::bu::picosecond); + constexpr auto nanosecond = su_from_bu(detail::bu::nanosecond); + constexpr auto microsecond = su_from_bu(detail::bu::microsecond); + constexpr auto millisecond = su_from_bu(detail::bu::millisecond); + constexpr auto second = su_from_bu(detail::bu::second); + constexpr auto minute = su_from_bu(detail::bu::minute); + constexpr auto hour = su_from_bu(detail::bu::hour); + constexpr auto day = su_from_bu(detail::bu::day); + constexpr auto week = su_from_bu(detail::bu::week); + constexpr auto month = su_from_bu(detail::bu::month); + constexpr auto year = su_from_bu(detail::bu::year); + constexpr auto year250 = su_from_bu(detail::bu::year250); + constexpr auto year360 = su_from_bu(detail::bu::year360); + constexpr auto year365 = su_from_bu(detail::bu::year365); + + constexpr auto volatility_30d = su_from_bu(detail::bu::month, + power_ratio_type(-1,2)); + constexpr auto volatility_250d = su_from_bu(detail::bu::year250, + power_ratio_type(-1,2)); + constexpr auto volatility_360d = su_from_bu(detail::bu::year360, + power_ratio_type(-1,2)); + constexpr auto volatility_365d = su_from_bu(detail::bu::year365, + power_ratio_type(-1,2)); } namespace detail {