diff --git a/docs/_static/img/concepts.png b/docs/_static/img/concepts.png deleted file mode 100644 index e8083e02..00000000 Binary files a/docs/_static/img/concepts.png and /dev/null differ diff --git a/docs/_static/img/concepts.svg b/docs/_static/img/concepts.svg new file mode 100644 index 00000000..1429ead5 --- /dev/null +++ b/docs/_static/img/concepts.svg @@ -0,0 +1,90 @@ +UnitDimensionkindDimensionpoint_kindKind, PointOriginpoint_originDimensionquantityDimension, Unit, Reprep number()quantity_pointPointOrigin, Unit, Repquantity relative()quantity_kindKind, Unit, Repquantity common()quantity_point_kindPointKind, Unit, Repquantity_kind relative() \ No newline at end of file diff --git a/docs/_static/img/dimensions.svg b/docs/_static/img/dimensions.svg new file mode 100644 index 00000000..5d6c4660 --- /dev/null +++ b/docs/_static/img/dimensions.svg @@ -0,0 +1,35 @@ +Dimensionbase_dimensionSymbol, UnitexponentDimension, Num, Denderived_dimensionUnit, Exponent...0..n \ No newline at end of file diff --git a/docs/_static/img/units.png b/docs/_static/img/units.png deleted file mode 100644 index 41296df3..00000000 Binary files a/docs/_static/img/units.png and /dev/null differ diff --git a/docs/_static/img/units.svg b/docs/_static/img/units.svg new file mode 100644 index 00000000..04639033 --- /dev/null +++ b/docs/_static/img/units.svg @@ -0,0 +1,122 @@ +Unitprefix_familyno_prefixprefixPrefixFamily, Symbol, Ratioscaled_unitUnitRatio, Unitprefixed_alias_unitUnit, Prefix, AliasUnitalias_unitUnit, Symbol, PrefixFamilynamed_derived_unitDimension, Symbol, PrefixFamily, Unit, Unit...derived_unitDimension, Unit, Unit...prefixed_unitPrefix, Unitnamed_scaled_unitSymbol, PrefixFamily, Ratio, Unitnamed_unitSymbol, PrefixFamilyunit \ No newline at end of file diff --git a/docs/framework/basic_concepts.rst b/docs/framework/basic_concepts.rst index bb3f9708..8b239c2f 100644 --- a/docs/framework/basic_concepts.rst +++ b/docs/framework/basic_concepts.rst @@ -6,50 +6,71 @@ Basic Concepts The most important concepts in the library are `Unit`, `Dimension`, `Quantity`, `QuantityPoint`, `QuantityKind`, and `QuantityPointKind`: -.. image:: /_static/img/concepts.png - :align: center + +.. raw:: html + + .. - http://www.nomnoml.com + https://www.planttext.com + + @startuml - [Dimension| - [base_dimension]<-[exponent] - [derived_dimension]<-[exponent] - [exponent]<-[derived_dimension] - ] + skinparam monochrome true + skinparam shadowing false + skinparam backgroundColor #fcfcfc - [Quantity| - [quantity] - ] + hide circle + hide members + show class methods - [QuantityPoint| - [quantity_point] - ] + package Unit <> [[../../framework/units.html]] { + } - [QuantityKind| - [quantity_kind] - ] + package Dimension <> [[../../framework/dimensions.html]] { + } - [QuantityPointKind| - [quantity_point_kind] - ] + abstract kind [[../../framework/quantity_kinds.html#kind-creation]] + abstract point_kind [[../../framework/quantity_kinds.html#quantity-point-kinds]] + abstract point_origin [[../../framework/quantity_points.html#point-origins]] - [Unit]<-[Dimension] - [Dimension]<-[Quantity] - [Unit]<-[Quantity] - [Quantity]<-[QuantityPoint] + class quantity [[../../framework/quantities.html]] { + rep number() + } + class quantity_point [[../../framework/quantity_points.html#construction]] { + quantity relative() + } + class quantity_kind [[../../framework/quantity_kinds.html#construction]] { + quantity common() + } + class quantity_point_kind [[../../framework/quantity_kinds.html#quantity-point-kinds]] { + quantity_kind relative() + } - [PointOrigin]<-[QuantityPoint] - [Dimension]<-[PointOrigin] - [PointOrigin]<-[PointKind] - [Kind]<-[QuantityKind] - [Dimension]<-[Kind] - [Quantity]<-[QuantityKind] + Unit <.. Dimension - [PointKind]<-[QuantityPointKind] - [Kind]<-[PointKind] - [QuantityKind]<-[QuantityPointKind] + Dimension <.. quantity + Unit <.. quantity + + Dimension <.. kind + Dimension <.. point_origin + point_origin <.. point_kind + kind <.. point_kind + + Unit <.. quantity_point + point_origin <.. quantity_point + quantity --* quantity_point + + Unit <.. quantity_kind + kind <.. quantity_kind + quantity --* quantity_kind + + Unit <.. quantity_point_kind + point_kind <.. quantity_point_kind + quantity_kind --* quantity_point_kind + + @enduml `Unit` is a basic building block of the library. Every dimension works with a concrete hierarchy of units. Such hierarchy defines a reference unit and diff --git a/docs/framework/dimensions.rst b/docs/framework/dimensions.rst index 9a01044f..2531dcf3 100644 --- a/docs/framework/dimensions.rst +++ b/docs/framework/dimensions.rst @@ -8,6 +8,14 @@ In the previous chapter we briefly introduced the notion of a physical Length, time, speed, area, energy are only a few examples of physical dimensions. +.. raw:: html + + + +.. + https://www.planttext.com + + Base Dimensions --------------- diff --git a/docs/framework/units.rst b/docs/framework/units.rst index 014e57a7..630a1154 100644 --- a/docs/framework/units.rst +++ b/docs/framework/units.rst @@ -15,6 +15,85 @@ Base quantities are expressed in terms of :term:`base units ` in terms of :term:`derived units `. +Class Hierarchy +--------------- + +All of the described here class templates to produce unit types inherit from some instance +of a `scaled_unit` class template: + +.. raw:: html + + + +.. + https://www.planttext.com + + @startuml + + skinparam monochrome true + skinparam shadowing false + skinparam backgroundColor #fcfcfc + + hide members + hide circle + + left to right direction + + package Unit <> [[../../framework/units.html]] { + abstract prefix_family [[../../framework/units.html#prefixed-unit]] + abstract no_prefix [[../../framework/units.html#named-scaled-units]] + abstract prefix [[../../framework/units.html#prefixed-unit]] + + prefix_family <|-- no_prefix + prefix_family <.. prefix + + ' prefix_family <.. named_unit + ' prefix_family <.. named_scaled_unit + ' prefix_family <.. named_derived_unit + ' prefix_family <.. alias_unit + + ' prefix <.. prefixed_unit + ' prefix <.. prefixed_alias_unit + + abstract scaled_unit + + abstract prefixed_alias_unit [[../../framework/units.html#aliased-units]] + abstract alias_unit [[../../framework/units.html#aliased-units]] + abstract named_derived_unit [[../../framework/units.html#derived-scaled-units]] + abstract derived_unit [[../../framework/units.html#derived-scaled-units]] + abstract prefixed_unit [[../../framework/units.html#prefixed-unit]] + abstract named_scaled_unit [[../../framework/units.html#named-scaled-units]] + abstract named_unit [[../../framework/units.html#base-units]] + abstract unit [[../../framework/units.html#derived-unnamed-units]] + + scaled_unit <|-- unit + scaled_unit <|-- named_unit + scaled_unit <|-- named_scaled_unit + scaled_unit <|-- prefixed_unit + scaled_unit <|-- derived_unit + scaled_unit <|-- named_derived_unit + scaled_unit <|-- alias_unit + scaled_unit <|-- prefixed_alias_unit + } + + @enduml + +`scaled_unit` is a class template used exclusively by the library's framework +and user should not instantiate it by him/her-self. However the user can sometimes +observe this type in case an unit/dimension conversion expression will end up with an +unknown/undefined unit type like in the below example:: + + using namespace units::isq::si::references; + + Length auto l = 100 * (km / h) * (10 * s); + +The type of ``l`` above will be +``si::length, long double>``. This is caused +by the fact that the library does not define a unit of a length quantity that has the +ratio ``10/36`` of a ``si::metre``. If such a unit was predefined we would see its concrete +type here instead. + + Base Units ---------- @@ -359,44 +438,6 @@ class template:: } -Class Hierarchy ---------------- - -All of the above class templates to produce unit types inherit from some instance -of a `scaled_unit` class template: - -.. image:: /_static/img/units.png - :align: center - -.. - http://www.nomnoml.com - - #direction: right - - [scaled_unit]<:-[unit] - [scaled_unit]<:-[named_unit] - [scaled_unit]<:-[named_scaled_unit] - [scaled_unit]<:-[prefixed_unit] - [scaled_unit]<:-[derived_unit] - [scaled_unit]<:-[named_derived_unit] - [scaled_unit]<:-[alias_unit] - [scaled_unit]<:-[prefixed_alias_unit] - -`scaled_unit` is a class template used exclusively by the library's framework -and user should not instantiate it by him/her-self. However the user can sometimes -observe this type in case an unit/dimension conversion expression will end up with an -unknown/undefined unit type like in the below example:: - - using namespace units::isq::si::references; - - Length auto l = 100 * (km / h) * (10 * s); - -The type of ``l`` above will be -``si::length, long double>``. This is caused -by the fact that the library does not define a unit of a length quantity that has the -ratio ``10/36`` of a ``si::metre``. If such a unit was predefined we would see its concrete -type here instead. - .. seealso:: To learn more about unknown units please refer to the