1 Introduction

Several groups in the ISO C++ Committee reviewed the “P1935: A C++ Approach to Physical Units” [P1935R2] proposal in Belfast 2019 and Prague 2020. All those groups expressed interest in the potential standardization of such a library and encouraged further work. The authors also got valuable initial feedback that highly influenced the design of the V2 version of the [mp-units] library.

In the following years, the library’s authors focused on getting more feedback from the production about the design and developed version 2 of the [mp-units] library that resolves the issues raised by the users and Committee members. The features and interfaces of this version are close to being the best we can get with the current version of the C++ language standard.

This paper is authored by the [mp-units] library developers, the authors of other actively maintained similar libraries on the market, and other active members of the C++ physical quantities and units community who have worked on this subject for many years. We join our forces to say with one voice that we deeply care about standardizing such features as a part of the C++ Standard Library. Based on our long and broad experience in the subject, we agree that the interfaces we will provide in the upcoming proposals are the best we can get today in the C++ language.

During the Kona 2023 ISO C++ Committee meeting, we got repeating feedback that there should be one big, unified paper with all the contents inside. Addressing this requirement, this paper adds a detailed design description and also includes the most important parts of [P2980R1], [P2981R1], and [P2982R1]. With this, we assume that [P2981R1] and [P2982R1] are superseded by this paper. The plan and scope described in [P2980R1] might still be updated based on the current progress and feedback from the upcoming discussions.

Note: This paper is incomplete and many chapters are still missing. It is published to gather early feedback and possibly get acceptance for the major design decisions of the library. More details will arrive in the next revisions of this paper.

2 Terms and definitions

This document consistently uses the official metrology vocabulary defined in the [ISO/IEC Guide 99] and [JCGM 200:2012].

3 Impact on the C++ standard

This change is purely additive. It does not change, fix, or break any of the existing tools in the C++ standard library.

3.1 Interaction with std::chrono types and std::ratio

The only interaction of this proposal with the C++ standard facilities is the compatibility mode with std::chrono types (duration and time_point) described in [Compatibility with std::chrono::duration and std::chrono::time_point].

We should also mention the potential confusion of users with having two different ways to deal with time abstractions in the C++ standard library. If this proposal gets accepted:

• std::chrono abstractions together with std::ratio should be used primarily to deal with calendars and threading facilities,
• abstractions introduced in this proposal should be used in all other use cases (e.g. physical quantities equations).

3.2 Dependencies on other proposals

The features in this chapter are heavily used in the library but are not domain-specific. Having them standardized (instead of left as exposition-only) could not only improve this library’s specification, but also serve as an essential building block for tools in other domains that we can get in the future from other authors.

4 About authors

4.1 Dominik Berner

Dominik is a strong believer that the C++ language can provide very high safety guarantees when programming through strong typing; a type error caught during compilation saves hours of debugging. For the last 15 years, he has mainly coded in C++ and actively follows its evolution through the new standards.

When working on regulated projects at Med-Tech, there usually were very tight requirements on which data types were to be used for what, which turned out to be lists of primitives to be memorized by each developer. However, throughout his career, Dominik spent way too many hours debugging and fixing issues caused by these types being incorrect. In an attempt to bring a closer semantic meaning to these lists, he eventually wrote [SI library] as a side project.

While [SI library] provides many useful features, such as type-safe conversion between physical quantities as well as zero-overhead computation for values of the same units, there are some shortcomings which would require major rework. Instead of creating yet another library, Dominik decided to join forces with the other authors of this paper to push for standardizing support for more type-safety for physical quantities. He hopes that this will eventually lead to a safer and more robust C++ and open many more opportunities for the language.

4.2 Johel Ernesto Guerrero Peña

Johel got interested in the units domain while writing his first hundred lines of game development. He got up to opening the game window, so this milestone was not reached until years later. Instead, he looked for the missing piece of abstraction, called “pixel” in the GUI framework, but modeled as an int. He found out about [nholthaus/units], and got fascinated with the idea of a library that succinctly allows expressing his domain’s units (https://github.com/nholthaus/units/issues/124#issuecomment-390773279).

Johel became a contributor to [nholthaus/units] v3 from 2018 to 2020. He improved the interfaces and implementations by remodeling them after std::chrono::duration. This included parameterizing the representation type with a template parameter instead of a macro. He also improved the error messages by mapping a list of types to an user-defined name.

By 2020, Johel had been aware of [mp-units] v0 quantity<dim_length, length, int>, put off by its verbosity. But then, he watched a talk by Mateusz Pusz on [mp-units]. It described how good error messages was a stake in the ground for the library. Thanks to his experience in the domain, Johel was convinced that [mp-units] was the future.

Since 2020, Johel has been contributing to [mp-units]. He added quantity_point, the generalization of std::chrono::time_point, closing #1. He also added quantity_kind, which explored the need of representing distinct quantities of the same dimension. To help guide its evolution, he’s been constantly pointing in the direction of [JCGM 200:2012] as a source of truth. And more recently, to [ISO/IEC 80000], also helping interpret it.

Computing systems engineering graduate. (C++) programmer since 2014. Lives at HEAD with C++Next and good practices. Performs in-depth code reviews of familiarized code bases. Has an eye for identifying automation opportunities, and acts on them. Mostly at https://github.com/JohelEGP/.

4.3 Charles Hogg

Chip Hogg is a Staff Software Engineer on the Motion Planning Team at Aurora Innovation, the self-driving vehicle company that is developing the Aurora Driver. After obtaining his PhD in Physics from Carnegie Mellon in 2010, he was a postdoctoral researcher and then staff scientist at the National Institute of Standards and Technology (NIST), doing Bayesian data analysis. He joined Google in 2012 as a software engineer, leaving in 2016 to work on autonomous vehicles at Uber’s Advanced Technologies Group (ATG), where he stayed until their acquisition by Aurora in 2021.

Chip built his first C++ units library at Uber ATG in 2018, where he first developed the concept of unit-safe interfaces. At Aurora in 2021, he ported over only the test cases, writing a new and more powerful units library from scratch. This included novel features such as vector space magnitudes, and an adaptive conversion policy which guards against overflow in integers.

He soon realized that there was a much broader need for Aurora’s units library. No publicly available units library for C++14 or C++17 could match its ergonomics, developer experience, and performance. This motivated him to create [Au] in 2022: a new, zero-dependency units library, which was a drop-in replacement for Aurora’s original units library, but offered far more composable interfaces, and was built on simpler, stronger foundations. Once Au proved its value internally, Chip migrated it to a separate repository and led the open-sourcing process, culminating in its public release in 2023.

While Au provides excellent ergonomics and robustness for pre-C++20 users, Chip also believes the C++ community would benefit from a standard units library. For that reason, he has joined forces with the [mp-units] project, contributing code and design ideas.

4.4 Nicolas Holthaus

Nicolas graduated Summa Cum Laude from Northwestern University with a B.S. in Computer Engineering. He worked for several years at the United States Naval Air Warfare Center - Manned Flight Simulator - designing real-time C++ software for aircraft survivability simulation. He has subsequently continued in the field at various start-ups, MIT Lincoln Laboratory, and most recently, STR (Science and Technology Research).

Nicolas became obsessed with dimensional analysis as a high school JETS team member after learning that the $125M Mars Climate Orbiter was destroyed due to a simple feet-to-meters miscalculation. He developed the widely adopted C++ [nholthaus/units] library based on the findings of the 2002 white paper “Dimensional Analysis in C++” by Scott Meyers. Astounded that no one smarter had already written such a library, he continued with units 2.0 and 3.0 based on modern C++. Those libraries have been extensively adopted in many fields, including modeling & simulation, agriculture, and geodesy.

In 2023, recognizing the limits of units, he joined forces with Mateusz Pusz in his effort to standardize his evolutionary dimensional analysis library, with the goal of providing the highest-quality dimensional analysis to all C++ users via the C++ standard library.

4.5 Roth Michaels

Roth Michaels is a Principal Software Engineer at Native Instruments, a leading manufacturer of audio, and music, software and hardware. Working in this domain, he has been involved with the creation of ad hoc typed quantities/units for digital signal processing and GUI library use-cases. Seeing both the complexity of development and practical uses where developers need to leave the safety of these simple wrappers encouraged Roth to explore various quantity/units libraries to see if they would apply to this domain. He has been doing research into defining and using digital audio and music domain-specific quantities and units using first [mp-units] as proposed in [P1935R2] and the new V2 library described in this paper.

Before working for Native Instruments, Roth worked as a consultant in multiple industries using a variety of programming languages. He was involved with the Swift Evolution community in its early days before focusing primarily on C++ after joining iZotope and now Native Instruments.

Holding a degree in music composition, Roth has over a decade of experience working with quantities and units of measure related to music, digital signal processing, analog audio, and acoustics. He has joined the [mp-units] project as a domain expert in these areas and to provide perspective on logarithmic and non-linear quantity/unit relationships.

4.6 Mateusz Pusz

Mateusz got interested in the physical units subject while contributing to the [LK8000] Tactical Flight Computer Open Source project over 10 years ago. The project’s code was far from being “safe” in the C++ sense, and this is when Mateusz started to explore alternatives.

Through the following years, he tried to use several existing solutions, which were always far from being user-friendly, so he also tried to write a better framework a few times from scratch by himself.

Finally, with the availability of brand new Concepts TS in the gcc-7, the [mp-units] project was created. It was designed with safety and user experience in mind. After many years of working on the project, the [mp-units] library is probably the most modern and complete solution in the C++ market.

Through the last few years, Mateusz has put much effort into building a community around physical units. He provided many talks and workshops on this subject at various C++ conferences. He also approached the authors of other actively maintained libraries to get their feedback and invited them to work together to find and agree on the best solution for the C++ language. This paper is the result of those actions.

4.7 Vincent Reverdy

Vincent is an astrophysicist, computer scientist, and a member of the French delegation to the ISO C++ Committee, currently working as a full researcher at the French National Centre for Scientific Research (CNRS). He has been interested for years in units and quantities for programming languages to ensure higher levels of both expressivity and safety in computational physics codes. Back in 2019, he authored [P1930R0] to provide some context of what could be a quantity and unit library for C++.

After designing and implementing several Domain-Specific Language (DSL) demonstrators dedicated to units of measurements in C++, he became more interested in the theoretical side of the problem. Today, one of his research activities is dedicated to the mathematical formalization of systems of quantities and systems of units as an interdisciplinary problem between physics, mathematics, and computer science.

5 Motivation

This chapter describes why we believe that physical quantities and units should be part of a C++ Standard Library.

5.1 Safety

It is no longer only the space industry or experienced pilots that benefit from the autonomous operations of some machines. We live in a world where more and more ordinary people trust machines with their lives daily. In the near future, we will be allowed to sleep while our car autonomously drives us home from a late party. As a result, many more C++ engineers are expected to write life-critical software today than it was a few years ago. However, writing safety-critical code requires extensive training and experience, both of which are in short demand. While there exists some standards and guidelines such as MISRA C++ [MISRA C++] with the aim of enforcing the creation of safe code in C++, they are cumbersome to use and tend to shift the burden on the discipline of the programmers to enforce these. At the time of writing, the C++ language does not change fast enough to enforce safe-by-construction code.

One of the ways C++ can significantly improve the safety of applications being written by thousands of developers is by introducing a type-safe, well-tested, standardized way to handle physical quantities and their units. The rationale is that people tend to have problems communicating or using proper units in code and daily life. Numerous expensive failures and accidents happened due to using an invalid unit or a quantity type.

The most famous and probably the most expensive example in the software engineering domain is the Mars Climate Orbiter that in 1999 failed to enter Mars’ orbit and crashed while entering its atmosphere [Mars Orbiter]. This is one of many examples here. People tend to confuse units quite often. We see similar errors occurring in various domains over the years:

• On October 12, 1492, Christopher Columbus unintentionally discovered the sea route from Europe to America because, during his travel preparations, he mixed the Arabic mile with a Roman mile, which led to the wrong estimation of the equator and his expected travel distance [Columbus].
• In 1628, a new warship, Vasa, accidentally had an asymmetrical hull (being thicker on the port side than the starboard side), which was one of the reasons for her sinking less than a mile into her maiden voyage, resulting in the death of 30 people on board. This asymmetry could have been caused by the use of different systems of measurement, as archaeologists have found four rulers used by the workers who built the ship. Two were calibrated in Swedish feet, which had 12 inches, while the other two measured Amsterdam feet, which had 11 inches [Vasa].
• Air Canada Flight 143 ran out of fuel on July 23, 1983, at an altitude of 41 000 feet (12 000 metres), midway through the flight because the fuel had been calculated in pounds instead of kilograms by the ground crew [Gimli Glider].
• The British rock band Black Sabbath, during its Born Again tour in 1983, ordered a replica of Stonehenge as props for the scene. Unfortunately, they had to leave them in the storage area because, while submitting the order, their manager wrote dimensions down in meters when he meant feet, and so the stones didn’t fit the scene. “It cost a fortune to make, but there was not a building on Earth that you could fit it into” [Stonehenge].
• On April 15, 1999, Korean Air Cargo Flight 6316 crashed due to a miscommunication between pilots about the desired flight altitude [Flight 6316].
• In February 2001, the crew of the Moorpark College Zoo built an enclosure for Clarence the Tortoise with a weight of 250 pounds instead of 250 kilograms [Clarence].
• In December 2003, one of the roller coaster’s cars at Tokyo Disneyland’s Space Mountain attraction suddenly derailed due to a broken axle caused by confusion after upgrading the specification from imperial to metric units [Disney].
• During the construction of the Hochrheinbrücke bridge to connect the small German town of Laufenburg with Swiss Laufenburg, the construction team made a sign error that resulted in a discrepancy of 54 cm between the two outer ends of the bridge [Hochrheinbrücke].
• An American company sold a shipment of wild rice to a Japanese customer, quoting a price of 39 cents per pound, but the customer thought the quote was for 39 cents per kilogram [Wild Rice].
• On October 17, 2023, The Guardian published an article titled “Record Heat: Malawi swelters with temperatures nearly 68F above average” with many issues related to the affine space types and temperature units. Due to incorrect logic, probably during the translation of the article to the U.S. market, 20 °C above the average temperature was converted to 68 °F. The actual temperature increase was 32 °F, not 68 °F [The Guardian].
• A whole set of [Medication dose errors]…

The safety subject is so vast and essential by itself that we dedicated an entire Safety features chapter of this paper that discusses all the nuances in detail.

5.2 Vocabulary types

We standardized many library features mostly used in the implementation details (fmt, ranges, random-number generators, etc.). However, we believe that the most important role of the C++ Standard is to provide a standardized way of communication between different vendors.

Let’s imagine a world without std::string or std::vector. Every vendor has their version of it, and of course, they are highly incompatible with each other. As a result, when someone needs to integrate software from different vendors, it turns out to be an unnecessarily arduous task.

Introducing std::chrono::duration and std::chrono::time_point improved the interfaces a lot, but time is only one of many quantities that we deal with in our software on a daily basis. We desperately need to be able to express more quantities and units in a standardized way so different libraries get means to communicate with each other.

If Lockheed Martin and NASA could have used standardized vocabulary types in their interfaces, maybe they would not interpret pound-force seconds as newton seconds, and the [Mars Orbiter] would not have crashed during the Mars orbital insertion maneuver.

5.3 Certification

Mission and life-critical projects, or those for embedded devices, often have to obey the safety norms that care about software for safety-critical systems (e.g., ISO 61508 is a basic functional safety standard applicable to all industries, and ISO 26262 for automotive). As a result, their company policy often forbid third-party tooling that lacks official certification. Such certification requires a specification to be certified against, and those tools often do not have one. The risk and cost of self-certifying an Open Source project is too high for many as well.

Companies often have a policy that the software they use must obey all the rules MISRA provides. This is a common misconception, as many of those rules are intended to be deviated from. However, those deviations require rationale and documentation, which is also considered to be risky and expensive by many.

All of those reasons often prevent the usage of an Open Source product in a company, which is a huge issue, as those companies typically are natural users of physical quantities and units libraries.

Having the physical quantities and units library standardized would solve those issues for many customers, and would allow them to produce safer code for projects on which human life depends every single day.

5.4 Complex and complicated

Suppose vendors can’t use an Open Source library in a production project for the above reasons. They are forced to write their own abstractions by themselves. Besides being costly and time-consuming, it also happens that writing a physical quantities and units library by yourself is far from easy. Doing this is complex and complicated, especially for engineers who are not experts in the domain. There are many exceptional corner cases to cover that most developers do not even realize before falling into a trap in production. On the other hand, domain experts might find it difficult to put their knowledge into code and create a correct implementation in C++. As a result, companies either use really simple and unsafe numeric wrappers, or abandon the effort entirely and just use built-in types, such as float or int, to express quantity values, thus losing all semantic categorization. This often leads to safety issues caused by accidentally using values representing the wrong quantity or having an incorrect unit.

5.5 Extensibility

Many applications of a quantity and units library may need to operate on a combination of standard (e.g., SI) and domain-specific quantities and units. The complexity of developing domain-specific solutions highlights the value in being able to define new quantities and units that have all the expressivity and safety as those provided by the library.

Experience with writing ad hoc typed quantities without library support that can be combined with or converted to std::chrono::duration has shown the downside of bespoke solutions: If not all operations or conversions are handled, users will need to leave the safety of typed quantities to operate on primitive types.

The interfaces of the this library were designed with ease of extensibility in mind. Each definition of a dimension, quantity type, or unit typically takes only a single line of code. This is possible thanks to the extensive usage of C++20 class types as Non-Type Template Parameters (NTTP). For example, the following code presents how second (a unit of time in the [SI]) and hertz (a unit of frequency in the [SI]) can be defined:

inline constexpr struct second : named_unit<"s", kind_of<isq::time>> {} second;
inline constexpr struct hertz : named_unit<"Hz", 1 / second, kind_of<isq::frequency>> {} hertz;

5.6 Broad industry value

When people think about industries that could use physical quantities and unit libraries, they think of a few companies related to aerospace, autonomous cars, or embedded industries. That is all true, but there are many other potential users for such a library.

Here is a list of some less obvious candidates:

• Manufacturing,
• maritime industry,
• freight transport,
• military,
• astronomy,
• 3D design,
• robotics,
• audio,
• medical devices,
• national laboratories,
• scientific institutions and universities,
• all kinds of navigation and charting,
• GUI frameworks,
• finance (including HFT).

As we can see, the range of domains for such a library is vast and not limited to applications involving specifically physical units. Any software that involves measurements, or operations on counts of some standard or domain-specific quantities, could benefit from a zero-cost abstraction for operating on quantity values and their units. The library also provides affine space abstractions, which may prove useful in many applications.

5.7 Standardizing existing practice

Plenty of physical units libraries have been available to the public for many years. In 1998 Walter Brown provided an “Introduction to the SI Library of Unit-Based Computation” paper for the International Conference on Computing in High Energy Physics [CHEP’98]. It emphasizes the importance of strong types and static type-checking. After that, it describes a library modeling the [SI] to provide “strict compile-time type-checking without run-time overhead”.

It also states that at this time, “in numeric programming, programmers make heavy, near-exclusive, use of a language’s native numeric types (e.g., double)”. Today, twenty-five years later, plenty of “Modern C++” production code bases still use double to represent various quantities and units. It is high time to change this.

Throughout the years, we have learned the best practices for handling specific cases in the domain. Various products may have different scopes and support different C++ versions. Still, taking that aside, they use really similar concepts, types, and operations under the hood. We know how to do those things already.

The authors of this paper developed and delivered multiple successful C++ libraries for this domain. Libraries developed by them have more than 90% of all the stars on GitHub in the field of physical units libraries for C++. The [mp-units] library, which is the base of this proposal, has the most number of stars in this list, making it the most popular project in the C++ industry.

The authors joined forces and are working together to propose the best quantities and units library we can get with the latest version of the C++ language. They spend their private time and efforts hoping that the ISO C++ Committee will be willing to include such a feature in the C++ standard library.

6 Common smells when there is no library for quantities and units

In this chapter, we are going to review typical safety issues related to physical quantities and units in the C++ code when a proper library is not used. Even though all the examples come from the Open Source projects, expensive revenue-generating production source code often is similar.

6.1 The proliferation of double

It turns out that in the C++ software, most of our calculations in the physical quantities and units domain are handled with fundamental types like double. Code like below is a typical example here:

double GlidePolar::MacCreadyAltitude(double MCREADY,
                                     double Distance,
                                     const double Bearing,
                                     const double WindSpeed,
                                     const double WindBearing,
                                     double *BestCruiseTrack,
                                     double *VMacCready,
                                     const bool isFinalGlide,
                                     double *TimeToGo,
                                     const double AltitudeAboveTarget=1.0e6,
                                     const double cruise_efficiency=1.0,
                                     const double TaskAltDiff=-1.0e6);

Original code here.

There are several problems with such an approach: The abundance of double parameters makes it easy to accidentally switch values and there is no way of noticing such a mistake at compile-time. The code is not self-documenting in what units the parameters are expected. Is Distance in meters or kilometers? Is WindSpeed in meters per second or knots? Different code bases choose different ways to encode this information, which may be internally inconsistent. A strong type system would help answer these questions at the time the interface is written, and the compiler would verify it at compile-time.

6.2 The proliferation of magic numbers

There are a lot of constants and conversion factors involved in the quantity equations. Source code responsible for such computations is often trashed with magic numbers:

double AirDensity(double hr, double temp, double abs_press)
{
  return (1/(287.06*(temp+273.15)))*(abs_press - 230.617 * hr * exp((17.5043*temp)/(241.2+temp)));
}

Original code here.

Apart from the obvious readability issues, such code is hard to maintain, and it needs a lot of domain knowledge on the developer’s side. While it would be easy to replace these numbers with named constants, the question of which unit the constant is in remains. Is 287.06 in pounds per square inch (psi) or millibars (mbar)?

6.3 The proliferation of conversion macros

The lack of automated unit conversions often results in handwritten conversion functions or macros that are spread everywhere among the code base:

#ifndef PI
static const double PI = (4*atan(1));
#endif
#define EARTH_DIAMETER    12733426.0    // Diameter of earth in meters
#define SQUARED_EARTH_DIAMETER  162140137697476.0 // Diameter of earth in meters (EARTH_DIAMETER*EARTH_DIAMETER)
#ifndef DEG_TO_RAD
#define DEG_TO_RAD  (PI / 180)
#define RAD_TO_DEG  (180 / PI)
#endif

#define NAUTICALMILESTOMETRES (double)1851.96
#define KNOTSTOMETRESSECONDS (double)0.5144

#define TOKNOTS (double)1.944
#define TOFEETPERMINUTE (double)196.9
#define TOMPH   (double)2.237
#define TOKPH   (double)3.6

// meters to.. conversion
#define TONAUTICALMILES (1.0 / 1852.0)
#define TOMILES         (1.0 / 1609.344)
#define TOKILOMETER     (0.001)
#define TOFEET          (1.0 / 0.3048)
#define TOMETER         (1.0)

Original code here.

Again, the question of which unit the constant is in remains. Without looking at the code, it is impossible to tell from which unit TOMETER converts. Also, macros have the problem that they are not scoped to a namespace and thus can easily clash with other macros or functions, especially if they have such common names like PI or RAD_TO_DEG. A quick search through open source C++ code bases reveals that, for example, the RAD_TO_DEG macro is defined in a multitude of different ways – sometimes even within the same repository:

#define RAD_TO_DEG (180 / PI)
#define RAD_TO_DEG 57.2957795131
#define RAD_TO_DEG ( radians ) ((radians ) * 180.0 / M_PI)
#define RAD_TO_DEG 57.2957805f
...

Example search across multiple repositories

Multiple redefinitions in the same repository

Another safety issue occurring here is the fact that macro values can be deliberately tainted by compiler settings at built time and can acquire values that are not present in the source code. Human reviews won’t catch such issues.

Also, most of the macros do not follow best practices. Often, necessary parentheses are missing, processing in a preprocessor ends up with redundant casts, or some compile-time constants use too many digits for a value to be exact for a specific type (e.g., float).

6.4 Lack of consistency

If we not only lack strong types to isolate the abstractions from each other, but also lack discipline to keep our code consistent, we end up in an awful place:

void DistanceBearing(double lat1, double lon1,
                     double lat2, double lon2,
                     double *Distance, double *Bearing);

double DoubleDistance(double lat1, double lon1,
                      double lat2, double lon2,
                      double lat3, double lon3);

void FindLatitudeLongitude(double Lat, double Lon,
                           double Bearing, double Distance,
                           double *lat_out, double *lon_out);

double CrossTrackError(double lon1, double lat1,
                       double lon2, double lat2,
                       double lon3, double lat3,
                       double *lon4, double *lat4);

double ProjectedDistance(double lon1, double lat1,
                         double lon2, double lat2,
                         double lon3, double lat3,
                         double *xtd, double *crs);

Original code here.

Users can easily make errors if the interface designers are not consistent in ordering parameters. It is really hard to remember which function takes latitude or Bearing first and when a latitude or Distance is in the front.

6.5 Lack of a conceptual framework

The previous points mean that the fundamental types can’t be leveraged to model the different concepts of quantities and units frameworks. There is no shared vocabulary between different libraries. User-facing APIs use ad-hoc conventions. Even internal interfaces are inconsistent between themselves.

Arithmetic types such as int and double are used to model different concepts. They are used to represent any abstraction (be it a magnitude, difference, point, or kind) of any quantity type of any unit. These are weak types that make up weakly-typed interfaces. The resulting interfaces and implementations built with these types easily allow mixing up parameters and using operations that are not part of the represented quantity.

7 Design goals

The library facilities that we plan to propose in the upcoming papers is designed with the following goals in mind.

7.1 Compile-time safety

The most important property of any such a library is the safety it brings to C++ projects. The correct handling of physical quantities, units, and numerical values should be verifiable both by the compiler and by humans with manual inspection of each individual line.

In some cases, we are even eager to prioritize safe interfaces over the general usability experience (e.g., getters of the underlying raw numerical value will always require a unit in which the value should be returned in, which results in more typing and is sometimes redundant).

More information on this subject can be found in Safety features.

7.2 Performance

The library should be as fast or even faster than working with fundamental types. The should be no runtime overhead, and no space size overhead should be needed to implement higher-level abstractions.

7.3 Great user experience

The primary purpose of the library is to generate compile-time errors. If users did not introduce any bugs in the manual handling of quantities and units, the library would be of little use. This is why the library is optimized for readable compilation errors and great debugging experience.

The library is easy to use and flexible. The interfaces are straight-forward and safe by default. Users should be able to easily express any quantity and unit, which requires them to compose.

The above constraints imply the usage of special implementation techniques. The library will not only provide types, but also compile-time known values that will enable users to write easy to understand and efficient equations on quantities and units.

7.4 Scope

There are plenty of expectations from different parties regarding such a library. It should support at least:

• Any unit’s magnitude (huge, small, floating-point).
• Systems of Quantities.
• Systems of Units.
• The affine space.
• Highly adjustable text-output formatting.

Additionally, it would be good to also support the following features:

• Scalar, vector, and tensor quantities.
• Natural units systems.

7.5 Easy to extend

The library’s core framework does not assume the usage of any systems of quantities or units. It is fully generic and allow defining any system abstraction on top of it.

Most entities in the library can be defined with a single line of code without preprocessor macros. Users can easily extend provided systems with custom dimensions, quantities, and units.

7.6 Low standardization cost

The set of entities required for standardization should be limited to the bare minimum.

Most of the entities in systems definitions should be possible to implement with a single line of code.

Derived units do not need separate library types. Instead, they can be obtained through the composition of predefined named units. Units should not be associated with User-Defined Literals (UDLs), as it is the case with std::chrono::duration. UDLs do not compose, have very limited scope and functionality, and are expensive to standardize.

The user interface should have no preprocessor macros.

It should be possible for most proposed features (besides the text output) to be freestanding.

8 Quick domain introduction

This chapter provides a very brief introduction to the quantities and units domain. Please refer to [ISO/IEC 80000] and [SI] for more details.

Note: A more detailed graph of framework’s entities can be found in the Framework entities chapter.

8.1 Dimension

Dimension specifies the dependence of a quantity on the base quantities of a particular system of quantities. It is represented as a product of powers of factors corresponding to the base quantities, omitting any numerical factor.

Even though ISO does not officially define those, we find the below terms useful when discussing the domain and its C++ implementation:

• base dimension is the dimension of a base quantity,
• derived dimension is the dimension of a derived quantity.

As stated above, ISO does not mention a “base dimension” term. Nevertheless, it treats dimensions of base quantities in a special way by:

• assigning unique identifiers/symbols to all of them,
• stating that derived quantities have a dimension being a product of dimensions of base quantities.

For example:

• length (\(L\)), mass (\(M\)), time (\(T\)), electric current (\(I\)), thermodynamic temperature (\(Θ\)), amount of substance (\(N\)), and luminous intensity (\(J\)) are the base dimensions of the ISQ.
• A derived dimension of force in the ISQ is denoted by \(dim\;F = LMT^{–2}\).
• [ISO/IEC 80000] (part 13) provides traffic intensity quantity that is measured in erlangs but not in the unit one, which also implies that it should be introduced as a base quantity with its own dimension.

8.2 Quantity type

Dimension is not enough to describe a quantity. This is why [ISO/IEC 80000] provides hundreds of named quantity types. It turns out that there are many more quantity types in the ISQ than the named units in the [SI].

[ISO/IEC 80000] also defines the term kind of quantity as an aspect common to mutually comparable quantities. It explicitly says that two or more quantities cannot be added or subtracted unless they belong to the same category of mutually comparable quantities.

Quantities might be:

• of different dimensions (e.g., length, time, speed, power),
• of the same dimension but of a different kind (e.g., work vs. torque, frequency vs. activity, area vs. fuel consumption),
• of the same dimension and kind but still distinct (e.g., radius vs. width vs. height or potential energy vs. kinetic energy vs. thermodynamic energy).

Additionally, ISO explicitly specifies a quantity of dimension one, which is commonly known as a dimensionless quantity. It is a quantity for which all the exponents of the factors corresponding to the base quantities in its quantity dimension are zero. Typically, they represent ratios of two quantities of the same dimension or counts of things.

8.3 Quantity reference

[ISO/IEC 80000] defines a quantity as:

property of a phenomenon, body, or substance, where the property has a magnitude that can be expressed as a number and a reference.

NOTE 2 A reference can be a measurement unit, a measurement procedure, a reference material, or a combination of such.

The term “reference” is repeated several times in that ISO specification. For example:

• quantity value is defined as:

  Number and reference together expressing magnitude of a quantity.

• numerical quantity value is defined as:

  Number in the expression of a quantity value, other than any number serving as the reference

We realize that the term “reference” might be overloaded in the C++ domain. However, preserving the official metrology terminology here is still worth trying.

Measurement units are designated by conventionally assigned names and symbols.

Measurement units of quantities of the same quantity dimension may be designated by the same name and symbol even when the quantities are not of the same kind. For example, joule per kelvin and J/K are, respectively, the name and symbol of both a measurement unit of heat capacity and a measurement unit of entropy, which are generally considered to not be quantities of the same kind.

However, in some cases, special measurement unit names are restricted to be used with quantities of specific kind only. For example, the measurement unit ‘second to the power minus one’ (1/s) is called hertz (Hz) when used for frequencies and becquerel (Bq) when used for activities of radionuclides.

Measurement units of quantities of dimension one are numbers. In some cases, these measurement units are given special names, e.g., radian, steradian, and decibel, or are expressed by quotients such as millimole per mole equal to \(10^{−3}\) and microgram per kilogram equal to \(10^{−9}\).

8.4 Quantity

As stated above, [ISO/IEC 80000] defines a quantity as:

property of a phenomenon, body, or substance, where the property has a magnitude that can be expressed as a number and a reference.

The above means that a quantity abstraction should store a runtime value representing the quantity numerical value and a reference that might be represented as a unit. It is a common practice to embed a reference into the C++ type expressing the quantity so it does not occupy a space/storage at runtime.

It is also worth mentioning here that the distinction between a quantity and a quantity type is not clearly defined in [ISO/IEC 80000]. [ISO/IEC 80000] even explicitly states:

It is customary to use the same term, “quantity”, to refer to both general quantities, such as length, mass, etc., and their instances, such as given lengths, given masses, etc. Accordingly, we are used to saying both that length is a quantity and that a given length is a quantity, by maintaining the specification – “general quantity, \(Q\)” or “individual quantity, \(Q_a\)” – implicit and exploiting the linguistic context to remove the ambiguity.

To prevent such ambiguities in this document, we will consistently use the term:

• “quantity type” when we mean a general quantity,
• “quantity” when we mean the instance of a quantity that also stores its numerical value.

It is also worth mentioning here that [ISO/IEC 80000] does not distinguish between point and vector/interval quantities of The affine space.

9 API overview

This chapter is intended to be a short overview and present the proposed library’s final look and feel. We start with the most straightforward use cases and gradually introduce more complex abstractions. Thanks to that, the readers can assess the Teachability effort of this library by themselves.

More details about the design, rationale for it, and alternative syntaxes discussions can be found in the Design details and rationale chapter.

9.1 Unit-based quantities (simple mode)

Consistently with a Quantity definition, a quantity class template takes a reference and a representation type as parameters:

template<Reference auto R,
         RepresentationOf<get_quantity_spec(R).character> Rep = double>
class quantity;

9.1.1 Constructing a quantity

If we want to set a value for a quantity, we always have to provide a number and a unit:

quantity<si::metre, int> q{42, si::metre};

In case a quantity class template should use exactly the same unit and a representation type as provided in the initializer, it is recommended to use CTAD:

quantity q{42, si::metre};

Please, note that double is used as a default representation type, so the following does not result with a quantity of integral representation type:

quantity<si::metre> q2{42, si::metre};

This is why CTAD usage is recommended when the user wants to prevent potential conversion and just deduce the quantity class template parameters from the initializer. This often prevents unneeded conversions that can affect runtime performance or memory footprint.

CTAD-based spelling is shorter but is still quite verbose. Consider having to write:

quantity q = quantity{1, si::kilo<si::metre>} + quantity{200, si::metre};

This is why the library offers an alternative way to construct a quantity.

The [SI] says:

The value of the quantity is the product of the number and the unit. The space between the number and the unit is regarded as a multiplication sign (just as a space between units implies multiplication).

Following the above, the value of a quantity can also be created by multiplying a number with a predefined unit:

quantity q = 42 * si::metre;

The above creates an instance of quantity<si::metre(), int>. It is worth noting here that the syntax with the reversed order of arguments is invalid and will not compile (e.g., we can’t write si::metre * 42).

The same can be obtained using an optional unit symbol:

using namespace si::unit_symbols;

quantity q = 42 * m;

Unit symbols introduce a lot of short identifiers into the current scope, which is why they are opt-in. A user has to explicitly “import” them from a dedicated unit_symbols namespace.

[SI] specifies 7 base and 22 coherent derived units with special names. Additionally, it specifies 24 prefixes. There are also non-SI units accepted for use with SI. Some of them are really popular, for example, minute, hour, day, degree, litre, hectare, tonne. All of those entities compose to allow the creation of a vast number of various derived units.

For example, we can create a quantity of speed with either:

quantity speed1 = 60 * si::kilo<si::metre> / non_si::hour;
quantity speed2 = 60 * km / h;

In case a complex derived unit is used a lot in the project, for convenience, a user can quickly provide a nicely named wrapper for it with:

constexpr auto kmph = si::kilo<si::metre> / non_si::hour;
quantity speed3 = 60 * kmph;

The library is optimized to generate short and easy-to-understand types that highly improve the analysis of compile-time errors and debugging experience. All of the above definitions will create an instance of the type quantity<derived_unit<si::kilo_<si::metre>, per<non_si::hour>>{}, int>>. As we can see, the type generation is optimized to be easily understood even by non-experts in the domain. The library tries to keep the type’s readability as close to English as possible.

9.1.2 Typical operations on quantities

Various quantities can be multiplied or divided to obtain other derived quantities. Quantities of the same kind can be added, subtracted, and compared to each other. Quantities can also be easily printed with output streams or formatting facilities.

quantity dist1 = 80 * km;
quantity dist2 = 105 * km;
quantity duration = 2 * h;
quantity speed_limit = 100 * km / h;

if ((dist1 + dist2) / duration < speed_limit)
  std::cout << "Thanks for driving within the speed limit of " << speed_limit << " :-)\n";
else
  std::println("Slow down! The speed limit here is {}!", speed_limit);

The above prints:

Thanks for driving within the speed limit of 100 km/h :-)

9.1.2.1 Unit conversions

If we want to change the unit of a current quantity, we can use .in(Unit) member function:

std::cout << "The total distance in meters is " << (dist1 + dist2).in(m) << "\n";

Trying to do the same for speed_limit is invalid and will result in a compile time error stating that the member function .in() was not found. This is caused by the fact that the scaling of an integral type by a rational or irrational factor is considered not value-preserving. To force such a conversion, we can use either a .force_in(Unit) member function or an explicit value_cast<Unit>(Quantity).

std::cout << "The speed limit in m/s is " << speed_limit.force_in(m / s) << "\n";
std::cout << "The speed limit in m/s is " << value_cast<m / s>(speed_limit) << "\n";

We will get a truncated value of 27 m/s in both cases.

To prevent truncation, we must explicitly change the quantity representation type to a value-preserving one with value_cast<Representation>(Quantity) overload. For example:

std::cout << "The speed limit in m/s is " << value_cast<double>(speed_limit).in(m / s) << "\n";

This time, we will see the following in the text output:

The speed limit in m/s is 27.7778 m/s

9.1.2.2 Obtaining a numerical value of a quantity

Last but not least, if we need to obtain the numerical value of a quantity and pass it to some the legacy unsafe interface, we can use either .numerical_value_in(Unit) or .force_numerical_value_in(Unit) member functions:

void legacy_check_speed_limit(int speed_in_km_per_h);

legacy_check_speed_limit(((dist1 + dist2) / duration).numerical_value_in(km / h));

Such a getter will explicitly enforce the usage of a correct unit required by the underlying interface, which reduces a significant number of safety-related issues.

numerical_value_in(Unit) always returns by value as a quantity value conversion may be required to adjust to the target unit. In case a user needs a reference to the underlying storage .numerical_value_ref_in(Unit) should be used:

void legacy_set_speed_limit(int* speed_in_km_per_h) { *speed_in_km_per_h = 100; }

quantity<km / h, int> speed_limit;
legacy_set_speed_limit(&speed_limit.numerical_value_ref_in(km / h));

This member function again requires a target unit to enforce safety. This overload does not participate in overload resolution if the provided unit has a different scaling factor than the current one.

9.2 Typed quantities (safer mode)

Simple mode is all about and just about units. In case we care about a specific quantity type, typed quantities should be preferred. Those store information not only about a unit but also about a specific quantity type we want to model.

There a few ways to obtain such a quantity:

quantity<isq::height[m], int> q1 = 42 * m;
quantity q2{42, isq::height[m]};
quantity q3 = 42 * isq::height[m];
quantity q4 = isq::height(42 * m);

All of the above cases use a slightly different approach to get the quantity, but all of them result in exactly the same quantity class template instantiation.

In the above examples, an expression of isq::height[m] is called a quantity reference and results in reference<isq::height, si::metre> class template instantiation.

Note: The identifier reference is being used in the [mp-units] library but definitely will need bikeshedding during the standardization process.

More about typed quantities can be found in the following chapters:

• Why do we need typed quantities? provides a detailed rationale.
• Systems of quantities describes their conversion and arithmetic rules.
• Constraining a derived unit to work only with a specific derived quantity provides a solution to the problem of units of quantities different kinds but the same dimension.

9.3 The affine space

The affine space has two types of entities:

• point - a position specified with coordinate values (e.g., location, address, etc.)
• vector - the difference between two points (e.g., shift, offset, displacement, duration, etc.)

The vector described here is specific to the affine space theory and is not the same thing as the quantity of a vector character that we discuss later (although, in some cases, those terms may overlap).

9.3.1 Operations in the affine space

Here are the primary operations one can do in the affine space:

• vector + vector -> vector
• vector - vector -> vector
• -vector -> vector
• vector * scalar -> vector
• scalar * vector -> vector
• vector / scalar -> vector
• point - point -> vector
• point + vector -> point
• vector + point -> point
• point - vector -> point

It is not possible to:

• add two points,
• subtract a point from a vector,
• multiply nor divide points with anything else.

9.3.2 Points are more common than most of us imagine

Point abstractions should be used more often in the C++ software. They are not only about temperature or time. Points are everywhere around us and should become more popular in the products we implement. They can be used to implement:

• temperature points,
• timestamps,
• daily mass readouts from the scale,
• altitudes of mountain peaks on a map,
• current speed displayed on a car’s speed-o-meter,
• today’s price of instruments on the market,
• and many more.

Improving the affine space’s Points intuition will allow us to write better and safer software.

9.3.3 Vector is modeled by quantity

Up until now, each time when we used a quantity in our code, we were modeling some kind of a difference between two things:

• the distance between two points
• duration between two time points
• the difference in speed (even if relative to 0)

As we already know, a quantity type provides all operations required for the vector type in an affine space.

9.3.4 Point is modeled by quantity_point and PointOrigin

In the library, the point abstraction is modeled by:

• the PointOrigin concept that specifies a measurement’s origin, and
• the quantity_point class template that specifies a point relative to a predefined origin.

9.3.4.1 quantity_point

The quantity_point class template specifies an absolute quantity measured from a predefined origin:

template<Reference auto R,
         PointOriginFor<get_quantity_spec(R)> auto PO = default_point_origin(R),
         RepresentationOf<get_quantity_spec(R).character> Rep = double>
class quantity_point;

As we can see above, the quantity_point class template exposes one additional parameter compared to quantity. The PO parameter satisfies a PointOriginFor concept and specifies the origin of our measurement scale. By default, it is initialized with a quantity’s zeroth point using the following rules:

• if the measurement unit of a quantity specifies its point origin in its definition (e.g., degree Celsius), then this point is being used,
• otherwise, an instantiation of zeroth_point_origin<QuantitySpec> is being used which provides a zeroth point for a specific quantity type.

9.3.4.2 Implicit point origin

Let’s assume that Alice goes for a trip driving a car. She likes taking notes about interesting places that she visits on the road. For every such item, she writes down:

• its name,
• a readout from the car’s odometer at the location,
• a current timestamp.

We can implement this in the following way:

using std::chrono::system_clock;

struct trip_log_item {
  std::string name;
  quantity_point<isq::distance[km]> odometer;
  quantity_point<si::second> timestamp;
};
using trip_log = std::vector<trip_log_item>;

trip_log log;

quantity_point timestamp_1{quantity{system_clock::now().time_since_epoch()}};
log.emplace_back("home", quantity_point{1356 * km}, timestamp_1);

// some time passes

quantity_point timestamp_2{quantity{system_clock::now().time_since_epoch()}};
log.emplace_back("castle", quantity_point{1401 * km}, timestamp_2);

This is an excellent example of where points are helpful. There is no doubt about the correctness of their usage in this scenario:

• adding two odometer readouts or two timestamps have no physical sense, and that is why we will expect a compile-time error when we try to perform such operations accidentally,
• subtracting two odometer readouts or timestamps is perfectly valid and results in a quantity storing the interval value between the two points.

Having such a database, we can print the trip log in the following way:

for (const auto& item : log) {
  std::cout << "POI: " << item.name << "\n";
  std::cout << "- Distance from home: " << item.odometer - log.front().odometer << "\n";
  std::cout << "- Trip duration from start: " << (item.timestamp - log.front().timestamp).in(non_si::minute) << "\n";
}

Moreover, if Alice had reset the car’s trip odometer before leaving home, we could have rewritten one of the previous lines like that:

std::cout << "Distance from home: " << item.odometer.quantity_from_zero() << "\n";

The above always returns a quantity measured from the “ultimate” zeroth point of a scale used for this specific quantity type.

Storing points is the most efficient representation we can choose in this scenario:

• to store a value, we read it directly from the instrument, and no additional transformation is needed,
• to print the absolute value (e.g., odometer), we have the value available right away,
• to get any relative quantity (e.g., distance from the start, distance from the previous point, etc.), we have to perform a single subtraction operation.

If we stored vectors in our database instead, we would have to pay at runtime for additional operations:

• to store a quantity, we would have to perform the subtraction right away to get the interval between the current value and some reference point,
• to print the absolute value, we would have to add the quantity to the reference point that we need to store somewhere in the database as well,
• to get a relative quantity, only the currently stored one is immediate; all other values will require at least one quantity addition operation.

Now, let’s assume that Bob, a friend of Alice, also keeps a log of his trips but he, of course, measures distances from his own home with the odometer in his car. Everything is fine as long as we deal with one trip at a time, but if we start to work with both at once, we may accidentally subtract points from different trips. The library will not prevent us from doing so.

The points from Alice’s and Bob’s trips should be considered separate, and to enforce it at compilation time, we need to introduce explicit origins.

9.3.4.3 Absolute point origin

The absolute point origin specifies the “zero” of our measurement’s scale. User can specify such an origin by deriving from the absolute_point_origin class template:

enum class actor { alice, bob };

template<actor A>
struct zeroth_odometer_t : absolute_point_origin<zeroth_odometer_t<A>, isq::distance> {};

template<actor A>
inline constexpr zeroth_odometer_t<A> zeroth_odometer;

Odometer is not the only one that can get an explicit point origin in our case. As timestamps are provided by the std::chrono::system_clock, their values are always relative to the epoch of this clock.

Now, we can refactor our database to benefit from the explicit points:

template<actor A>
struct trip_log_item {
  std::string point_name;
  quantity_point<si::kilo<si::metre>, zeroth_odometer<A>> odometer;
  quantity_point<si::second, chrono_point_origin<system_clock>> timestamp;
};

template<actor A>
using trip_log = std::vector<trip_log_item<A>>;

We also need to update the initialization part in our code. In the case of implicit zeroth origins, we could construct quantity_point directly from the value of a quantity. This is no longer the case. As a point can be represented with a vector from the origin, to improve the safety of the code we write, a quantity_point class template must be created with one of the following operations:

quantity_point qp1 = zeroth_odometer<actor::alice> + 1356 * km;
quantity_point qp2 = 1356 * km + zeroth_odometer<actor::alice>;
quantity_point qp3 = zeroth_odometer<actor::alice> - 1356 * km;

Although, the qp3 above does not have a physical sense in this specific scenario.

Note: It is not allowed to subtract a point from a vector thus 1356 * km - zeroth_odometer<actor::alice> is an invalid operation.

Similarly to creation of a quantity, if someone does not like the operator-based syntax to create a quantity_point, the same results can be achieved with a two-parameter constructor:

quantity_point qp4{1356 * km, zeroth_odometer<actor::alice>};

Also, as now our timestamps have a proper point origin provided in a type, we can simplify the previous code by directly converting std::chrono::time_point to our quantity_point type.

With all the above, we can refactor our initialization part to the following:

trip_log<actor::alice> alice_log;

alice_log.emplace_back("home", zeroth_odometer<actor::alice> + 1356 * km, system_clock::now());

// some time passes

alice_log.emplace_back("castle", zeroth_odometer<actor::alice> + 1401 * km, system_clock::now());

9.3.4.4 Point arithmetics

As another example, let’s assume we will attend the CppCon conference hosted in Aurora, CO, and we want to estimate the distance we will travel. We have to take a taxi to a local airport, fly to DEN airport with a stopover in FRA, and, in the end, get a cab to the Gaylord Rockies Resort & Convention Center:

constexpr struct home : absolute_point_origin<home, isq::distance> {} home;

quantity_point<isq::distance[km], home> home_airport = home + 15 * km;
quantity_point<isq::distance[km], home> fra_airport = home_airport + 829 * km;
quantity_point<isq::distance[km], home> den_airport = fra_airport + 8115 * km;
quantity_point<isq::distance[km], home> cppcon_venue = den_airport + 10.1 * mi;

As we can see above, we can easily get a new point by adding a quantity to an origin or another quantity point.

If we want to find out the distance traveled between two points, we simply subtract them:

quantity<isq::distance[km]> total = cppcon_venue - home;
quantity<isq::distance[km]> flight = den_airport - home_airport;

If we would like to find out the total distance traveled by taxi as well, we have to do a bit more calculations:

quantity<isq::distance[km]> taxi1 = home_airport - home;
quantity<isq::distance[km]> taxi2 = cppcon_venue - den_airport;
quantity<isq::distance[km]> taxi = taxi1 + taxi2;

Now, if we print the results:

std::cout << "Total distance:  " << total << "\n";
std::cout << "Flight distance: " << flight << "\n";
std::cout << "Taxi distance:   " << taxi << "\n";

we will see the following output:

Total distance:  8975.25 km
Flight distance: 8944 km
Taxi distance:   31.2544 km

Note: It is not allowed to subtract two point origins defined in terms of absolute_point_origin (e.g., home - home) as those do not contain information about the unit, so we are not able to determine a resulting quantity type.

9.3.4.5 Relative point origin

We often do not have only one ultimate “zero” point when we measure things.

For example, let’s assume that we have the following absolute point origin:

constexpr struct mean_sea_level : absolute_point_origin<mean_sea_level, isq::altitude> {} mean_sea_level;

If we want to model a trip to Mount Everest, measuring all daily hikes from the mean_sea_level might not be efficient. We may know that we are not good climbers, so all our climbs can be represented with an 8-bit integer type, allowing us to save memory in our database of climbs.

For this purpose, we can define a relative_point_origin in the following way:

constexpr struct everest_base_camp : relative_point_origin<mean_sea_level + 5364 * m> {} everest_base_camp;

The above can be used as an origin for subsequent Points:

constexpr quantity_point first_climb_alt = everest_base_camp + isq::altitude(std::uint8_t{42} * m);
static_assert(first_climb_alt.quantity_from(everest_base_camp) == 42 * m);
static_assert(first_climb_alt.quantity_from(mean_sea_level) == 5406 * m);
static_assert(first_climb_alt.quantity_from_zero() == 5406 * m);

As we can see above, the quantity_from() member function returns a relative distance from the provided point origin while the quantity_from_zero() returns the distance from the absolute point origin.

9.3.4.6 Converting between different representations of the same point

As we might represent the same point with vectors from various origins, the library provides facilities to convert the point to the quantity_point class templates expressed in terms of different origins.

For this purpose, we can either use:

• A converting constructor:

  constexpr quantity_point<isq::altitude[m], mean_sea_level, int> qp = first_climb_alt;
  static_assert(qp.quantity_ref_from(qp.point_origin) == 5406 * m);

• A dedicated conversion interface:

  constexpr quantity_point qp = first_climb_alt.point_for(mean_sea_level);
  static_assert(qp.quantity_ref_from(qp.point_origin) == 5406 * m);

It is only allowed to convert between various origins defined in terms of the same absolute_point_origin. Even if it is possible to express the same point as a vector from another absolute_point_origin, the library will not provide such a conversion. A custom user-defined conversion function will be needed to add this functionality.

Said another way, in the library, there is no way to spell how two distinct absolute_point_origin types relate to each other.

9.3.4.7 Temperature support

Another important example of relative point origins is support of temperature quantity points.

The [SI] definition in the library provides a few predefined point origins for this purpose:

namespace si {

inline constexpr struct absolute_zero : absolute_point_origin<absolute_zero, isq::thermodynamic_temperature> {} absolute_zero;
inline constexpr struct zeroth_kelvin : decltype(absolute_zero) {} zeroth_kelvin;

inline constexpr struct ice_point : relative_point_origin<quantity_point{273'150 * milli<kelvin>}> {} ice_point;
inline constexpr struct zeroth_degree_Celsius : decltype(ice_point) {} zeroth_degree_Celsius;

}

namespace usc {

inline constexpr struct zeroth_degree_Fahrenheit :
  relative_point_origin<si::zeroth_degree_Celsius - 32 * (mag<ratio{5, 9}> * si::degree_Celsius)> {} zeroth_degree_Fahrenheit;

}

The above is a great example of how point origins can be stacked on top of each other:

• usc::zeroth_degree_Fahrenheit is defined relative to si::zeroth_degree_Celsius
• si::zeroth_degree_Celsius is defined relative to si::zeroth_kelvin.

Note: Notice that while stacking point origins, we can use not only different representation types but also different units for origins and a point. In the above example, the relative point origin for degree Celsius is defined in terms of si::kelvin, while the quantity point for it will use si::degree_Celsius as a unit.

The temperature point origins defined above are provided explicitly in the respective units’ definitions:

namespace si {

inline constexpr struct kelvin :
    named_unit<"K", kind_of<isq::thermodynamic_temperature>, zeroth_kelvin> {} kelvin;
inline constexpr struct degree_Celsius :
    named_unit<basic_symbol_text{"°C", "`C"}, kelvin, zeroth_degree_Celsius> {} degree_Celsius;

}

namespace usc {

inline constexpr struct degree_Fahrenheit :
    named_unit<basic_symbol_text{"°F", "`F"}, mag<ratio{5, 9}> * si::degree_Celsius,
               zeroth_degree_Fahrenheit> {} degree_Fahrenheit;

}

Now let’s see how we can benefit from the above definitions. We have quite a few alternatives to choose from here. Depending on our needs or taste we can:

• be explicit about the unit and origin:

  quantity_point<si::degree_Celsius, si::zeroth_degree_Celsius> q1 = si::zeroth_degree_Celsius + 20.5 * deg_C;
  quantity_point<si::degree_Celsius, si::zeroth_degree_Celsius> q2 = {20.5 * deg_C, si::zeroth_degree_Celsius};
  quantity_point<si::degree_Celsius, si::zeroth_degree_Celsius> q3{20.5 * deg_C};

• specify a unit and use its zeroth point origin implicitly:

  quantity_point<si::degree_Celsius> q4 = si::zeroth_degree_Celsius + 20.5 * deg_C;
  quantity_point<si::degree_Celsius> q5 = {20.5 * deg_C, si::zeroth_degree_Celsius};
  quantity_point<si::degree_Celsius> q6{20.5 * deg_C};

• benefit from CTAD:

  quantity_point q7 = si::zeroth_degree_Celsius + 20.5 * deg_C;
  quantity_point q8 = {20.5 * deg_C, si::zeroth_degree_Celsius};
  quantity_point q9{20.5 * deg_C};

In all of the above cases, we end up with the quantity_point of the same type and value.

To play a bit more with temperatures, we can implement a simple room AC temperature controller in the following way:

constexpr struct room_reference_temp : relative_point_origin<quantity_point{21 * deg_C}> {} room_reference_temp;
using room_temp = quantity_point<isq::Celsius_temperature[deg_C], room_reference_temp>;

constexpr auto step_delta = isq::Celsius_temperature(0.5 * deg_C);
constexpr int number_of_steps = 6;

room_temp room_ref{};
room_temp room_low = room_ref - number_of_steps * step_delta;
room_temp room_high = room_ref + number_of_steps * step_delta;

std::println("Room reference temperature: {} ({}, {})\n",
             room_ref.quantity_from_zero(),
             room_ref.in(usc::degree_Fahrenheit).quantity_from_zero(),
             room_ref.in(si::kelvin).quantity_from_zero());

std::println("| {:<14} | {:^18} | {:^18} | {:^18} |",
             "Temperature", "Room reference", "Ice point", "Absolute zero");
std::println("|{0:=^16}|{0:=^20}|{0:=^20}|{0:=^20}|", "");

auto print = [&](std::string_view label, auto v) {
  std::println("| {:<14} | {:^18} | {:^18} | {:^18:N[.2f]} |", label,
               v - room_reference_temp, (v - si::ice_point).in(deg_C), (v - si::absolute_zero).in(deg_C));
};

print("Lowest", room_low);
print("Default", room_ref);
print("Highest", room_high);

The above prints:

Room reference temperature: 21 °C (69.8 °F, 294.15 K)

| Temperature    |   Room reference   |     Ice point      |   Absolute zero    |
|================|====================|====================|====================|
| Lowest         |       -3 °C        |       18 °C        |     291.15 °C      |
| Default        |        0 °C        |       21 °C        |     294.15 °C      |
| Highest        |        3 °C        |       24 °C        |     297.15 °C      |

More about temperatures can be found in the Potential surprises while working with temperatures chapter.

9.4 User-defined representation types

The library of physical quantities and units library should work with any custom representation type. Those can be used to:

• Improve safety (e.g., prevent overflows, restrict the range of accepted values, etc.),
• provide additional information (e.g., not only a quantity value but also the uncertainty of the measurement), and
• enable linear algebra usage.

As of right now, we have two other concurrent proposals to SG6 in this subject on the fly ([P2993] and [P3003R0]), so we do not provide any concrete requirements or recommendations here so far.

Based on the results of discussions on the mentioned proposals, we will provide correct guidelines in the next revisions of this paper.

By default all floating-point and integral (besides bool) types are treated as scalars.

9.5 Vector and tensor quantities

TBD

9.6 Logarithmic quantities and units

TBD

9.7 Generic Interfaces

Using a concrete unit in the interface often has a lot of sense. It is especially useful if we store the data internally in the object. In such a case, we have to select a specific unit anyway.

For example, let’s consider a simple storage tank:

class StorageTank {
  quantity<horizontal_area[m2]> base_;
  quantity<isq::height[m]> height_;
  quantity<isq::mass_density[kg / m3]> density_ = air_density;
public:
  constexpr StorageTank(const quantity<horizontal_area[m2]>& base, const quantity<isq::height[m]>& height) :
      base_(base), height_(height)
  {
  }

  // ...
};

As the quantities provided in the function’s interface are then stored in the class, there is probably no sense in using generic interfaces here.

9.7.1 The issues with unit-specific interfaces

However, in many cases, using a specific unit in the interface is counterproductive. Let’s consider the following function:

quantity<km / h> avg_speed(quantity<km> distance, quantity<h> duration)
{
  return distance / duration;
}

Everything seems fine for now. It also works great if we call it with:

quantity<km / h> s1 = avg_speed(220 * km, 2 * h);

However, if the user starts doing the following:

quantity<mi / h> s2 = avg_speed(140 * mi, 2 * h);
quantity<m / s> s3 = avg_speed(20 * m, 2 * s);

some issues start to be clearly visible:

1. The arguments must be converted to units mandated by the function’s parameters at each call. This involves potentially expensive multiplication/division operations at runtime.

2. After the function returns the speed in a unit of km/h, another potentially expensive multiplication/division operations have to be performed to convert the resulting quantity into a unit being the derived unit of the initial function’s arguments.

3. Besides the obvious runtime cost, some unit conversions may result in a data truncation, which means that the result will not be exactly equal to a direct division of the function’s arguments.

4. We have to use a floating-point representation type (the quantity class template by default uses double as a representation type) which is considered value preserving. Trying to use an integral type in this scenario will work only for s1, while s2 and s3 will fail to compile. Failing to compile is a good thing here as the library tries to prevent the user from doing a clearly wrong thing. To make the code compile, the user needs to use dedicated value_cast or force_in like this:

   quantity<mi / h> s2 = avg_speed(value_cast<km>(140 * mi), 2 * h);
   quantity<m / s> s3 = avg_speed((20 * m).force_in(km), (2 * s).force_in(h));

   But the above will obviously provide an incorrect behavior (e.g., division by 0 in the evaluation of s3).

9.7.2 Constraining function parameters with concepts

Much better generic code can be implemented using basic concepts provided with the library:

auto avg_speed(QuantityOf<isq::length> auto distance,
               QuantityOf<isq::time> auto duration)
{
  return isq::speed(distance / duration);
}

This explicitly states that the arguments passed by the user must not only satisfy a Quantity concept, but also that their quantity specification must be implicitly convertible to isq::length and isq::time, respectively. This no longer leaves room for error while still allowing the compiler to generate the most efficient code.

Please, note that now it is safe just to use integral types all the way, which again improves the runtime performance as the multiplication/division operations are often faster on integral rather than floating-point types.

9.7.3 Constraining the function return type

The above function template resolves all of the issues described before. However, we can do even better here by additionally constraining the return type:

QuantityOf<isq::speed> auto avg_speed(QuantityOf<isq::length> auto distance,
                                      QuantityOf<isq::time> auto duration)
{
  return isq::speed(distance / duration);
}

Doing so has two important benefits:

1. It informs the users of our interface about what to expect to be the result of a function invocation. It is superior to just returning auto, which does not provide any hint about the thing being returned there.
2. Such a concept constrains the type returned from the function. This means that it works as a unit test to verify if our function actually performs what it is supposed to do. If there is an error in the quantity equation, we will learn about it right away.

9.7.4 Constraining a variable on the stack

If we know exactly what the function does in its internals and if we know the exact argument types passed to such a function, we often know the exact type that will be returned from its invocation.

However, if we care about performance, we should often use the generic interfaces described in this chapter. A side effect is that we sometimes are unsure about the return type. Even if we know it today, it might change a week from now due to some code refactoring.

In such cases, we can again use auto to denote the type:

auto s1 = avg_speed(220 * km, 2 * h);
auto s2 = avg_speed(140 * mi, 2 * h);
auto s3 = avg_speed(20 * m, 2 * s);

In this case, it is probably OK to do so as the avg_speed function name explicitly provides the information on what to expect as a result.

In other scenarios where the returned quantity type is not so obvious, it is again helpful to constrain the type with a concept like so:

QuantityOf<isq::speed> auto s1 = avg_speed(220 * km, 2 * h);
QuantityOf<isq::speed> auto s2 = avg_speed(140 * mi, 2 * h);
QuantityOf<isq::speed> auto s3 = avg_speed(20 * m, 2 * s);

Again, this explicitly provides additional information about the quantity we are dealing with in the code, and it serves as a unit test checking if the “thing” returned from a function is actually what we expected here.

10 Usage examples

10.1 Basic quantity equations

Let’s start with a really simple example presenting basic operations that every physical quantities and units library should provide:

import mp_units;

using namespace mp_units;
using namespace mp_units::si::unit_symbols;

// simple numeric operations
static_assert(10 * km / 2 == 5 * km);

// conversions to common units
static_assert(1 * h == 3600 * s);
static_assert(1 * km + 1 * m == 1001 * m);

// derived quantities
static_assert(1 * km / (1 * s) == 1000 * m / s);
static_assert(2 * km / h * (2 * h) == 4 * km);
static_assert(2 * km / (2 * km / h) == 1 * h);

static_assert(2 * m * (3 * m) == 6 * m2);

static_assert(10 * km / (5 * km) == 2 * one);

static_assert(1000 / (1 * s) == 1 * kHz);

Try it in the Compiler Explorer.

10.2 Hello units

The next example serves as a showcase of various features available in the [mp-units] library.

import mp_units;
import std;

using namespace mp_units;

constexpr QuantityOf<isq::speed> auto avg_speed(QuantityOf<isq::length> auto d,
                                                QuantityOf<isq::time> auto t)
{
  return d / t;
}

int main()
{
  using namespace mp_units::si::unit_symbols;
  using namespace mp_units::international::unit_symbols;

  constexpr quantity v1 = 110 * km / h;
  constexpr quantity v2 = 70 * mph;
  constexpr quantity v3 = avg_speed(220. * isq::distance[km], 2 * h);
  constexpr quantity v4 = avg_speed(isq::distance(140. * mi), 2 * h);
  constexpr quantity v5 = v3.in(m / s);
  constexpr quantity v6 = value_cast<m / s>(v4);
  constexpr quantity v7 = value_cast<int>(v6);

  std::cout << v1 << '\n';                                        // 110 km/h
  std::cout << std::setw(10) << std::setfill('*') << v2 << '\n';  // ***70 mi/h
  std::cout << std::format("{:*^10}\n", v3);                      // *110 km/h*
  std::println("{:%N in %U}", v4);                                // 70 in mi/h
  std::println("{:{%N:.2f}%?%U}", v5);                            // 30.56 m/s
  std::println("{:{%N:.2f}%?{%U:n}}", v6);                        // 31.29 m s⁻¹
  std::println("{:%N}", v7);                                      // 31
}

Try it in the Compiler Explorer.

10.3 Storage tank

This example estimates the process of filling a storage tank with some contents. It presents:

• The importance of supporting more than one distinct quantity of the same kind,
• faster-than-lightspeed constants,
• how easy it is to add custom quantity types when needed, and
• interoperability with std::chrono::duration.

import mp_units;
import std;

// allows standard gravity (acceleration) and weight (force) to be expressed with scalar representation
// types instead of requiring the usage of Linear Algebra library for this simple example
template<class T>
  requires mp_units::is_scalar<T>
inline constexpr bool mp_units::is_vector<T> = true;

namespace {

using namespace mp_units;
using namespace mp_units::si::unit_symbols;

// add a custom quantity type of kind isq::length
inline constexpr struct horizontal_length : quantity_spec<isq::length> {} horizontal_length;

// add a custom derived quantity type of kind isq::area
// with a constrained quantity equation
inline constexpr struct horizontal_area : quantity_spec<horizontal_length * isq::width> {} horizontal_area;

inline constexpr auto g = 1 * si::standard_gravity;
inline constexpr auto air_density = isq::mass_density(1.225 * kg / m3);

class StorageTank {
  quantity<horizontal_area[m2]> base_;
  quantity<isq::height[m]> height_;
  quantity<isq::mass_density[kg / m3]> density_ = air_density;
public:
  constexpr StorageTank(const quantity<horizontal_area[m2]>& base, const quantity<isq::height[m]>& height) :
      base_(base), height_(height)
  {
  }

  constexpr void set_contents_density(const quantity<isq::mass_density[kg / m3]>& density)
  {
    assert(density > air_density);
    density_ = density;
  }

  [[nodiscard]] constexpr QuantityOf<isq::weight> auto filled_weight() const
  {
    const auto volume = isq::volume(base_ * height_);
    const QuantityOf<isq::mass> auto mass = density_ * volume;
    return isq::weight(mass * g);
  }

  [[nodiscard]] constexpr quantity<isq::height[m]> fill_level(const quantity<isq::mass[kg]>& measured_mass) const
  {
    return height_ * measured_mass * g / filled_weight();
  }

  [[nodiscard]] constexpr quantity<isq::volume[m3]> spare_capacity(const quantity<isq::mass[kg]>& measured_mass) const
  {
    return (height_ - fill_level(measured_mass)) * base_;
  }
};


class CylindricalStorageTank : public StorageTank {
public:
  constexpr CylindricalStorageTank(const quantity<isq::radius[m]>& radius, const quantity<isq::height[m]>& height) :
      StorageTank(quantity_cast<horizontal_area>(std::numbers::pi * pow<2>(radius)), height)
  {
  }
};

class RectangularStorageTank : public StorageTank {
public:
  constexpr RectangularStorageTank(const quantity<horizontal_length[m]>& length, const quantity<isq::width[m]>& width,
                                   const quantity<isq::height[m]>& height) :
      StorageTank(length * width, height)
  {
  }
};

}  // namespace


int main()
{
  const quantity height = isq::height(200 * mm);
  auto tank = RectangularStorageTank(horizontal_length(1'000 * mm), isq::width(500 * mm), height);
  tank.set_contents_density(1'000 * kg / m3);

  const auto duration = std::chrono::seconds{200};
  const quantity fill_time = value_cast<int>(quantity{duration});  // time since starting fill
  const quantity measured_mass = 20. * kg;                         // measured mass at fill_time

  const quantity fill_level = tank.fill_level(measured_mass);
  const quantity spare_capacity = tank.spare_capacity(measured_mass);
  const quantity filled_weight = tank.filled_weight();

  const QuantityOf<isq::mass_change_rate> auto input_flow_rate = measured_mass / fill_time;
  const QuantityOf<isq::speed> auto float_rise_rate = fill_level / fill_time;
  const QuantityOf<isq::time> auto fill_time_left = (height / fill_level - 1 * one) * fill_time;

  const quantity fill_ratio = fill_level / height;

  std::println("fill height at {} = {} ({} full)", fill_time, fill_level, fill_ratio.in(percent));
  std::println("fill weight at {} = {} ({})", fill_time, filled_weight, filled_weight.in(N));
  std::println("spare capacity at {} = {}", fill_time, spare_capacity);
  std::println("input flow rate = {}", input_flow_rate);
  std::println("float rise rate = {}", float_rise_rate);
  std::println("tank full E.T.A. at current flow rate = {}", fill_time_left.in(s));
}

The above code outputs:

fill height at 200 s = 0.04 m (20% full)
fill weight at 200 s = 100 g₀ kg (980.665 N)
spare capacity at 200 s = 0.08 m³
input flow rate = 0.1 kg/s
float rise rate = 2e-04 m/s
tank full E.T.A. at current flow rate = 800 s

Try it in the Compiler Explorer.

10.4 Bridge across the Rhine

The following example codifies the history of a famous issue during the construction of a bridge across the Rhine River between the German and Swiss parts of the town Laufenburg [Hochrheinbrücke]. It also nicely presents how the Affine Space is being modeled in the library.

import mp_units;
import std;

using namespace mp_units;
using namespace mp_units::si::unit_symbols;

constexpr struct amsterdam_sea_level : absolute_point_origin<amsterdam_sea_level, isq::altitude> {
} amsterdam_sea_level;

constexpr struct mediterranean_sea_level : relative_point_origin<amsterdam_sea_level - 27 * cm> {
} mediterranean_sea_level;

using altitude_DE = quantity_point<isq::altitude[m], amsterdam_sea_level>;
using altitude_CH = quantity_point<isq::altitude[m], mediterranean_sea_level>;

template<auto R, typename Rep>
std::ostream& operator<<(std::ostream& os, quantity_point<R, altitude_DE::point_origin, Rep> alt)
{
  return os << alt.quantity_ref_from(altitude_DE::point_origin) << " AMSL(DE)";
}

template<auto R, typename Rep>
std::ostream& operator<<(std::ostream& os, quantity_point<R, altitude_CH::point_origin, Rep> alt)
{
  return os << alt.quantity_ref_from(altitude_CH::point_origin) << " AMSL(CH)";
}

template<auto R, typename Rep>
struct std::formatter<quantity_point<R, altitude_DE::point_origin, Rep>> : formatter<quantity<R, Rep>> {
  template<typename FormatContext>
  auto format(const quantity_point<R, altitude_DE::point_origin, Rep>& alt, FormatContext& ctx) const
  {
    formatter<quantity<R, Rep>>::format(alt.quantity_ref_from(altitude_DE::point_origin), ctx);
    return std::format_to(ctx.out(), " AMSL(DE)");
  }
};

template<auto R, typename Rep>
struct std::formatter<quantity_point<R, altitude_CH::point_origin, Rep>> : formatter<quantity<R, Rep>> {
  template<typename FormatContext>
  auto format(const quantity_point<R, altitude_CH::point_origin, Rep>& alt, FormatContext& ctx) const
  {
    formatter<quantity<R, Rep>>::format(alt.quantity_ref_from(altitude_CH::point_origin), ctx);
    return std::format_to(ctx.out(), " AMSL(CH)");
  }
};

int main()
{
  // expected bridge altitude in a specific reference system
  quantity_point expected_bridge_alt = amsterdam_sea_level + 330 * m;

  // some nearest landmark altitudes on both sides of the river
  // equal but not equal ;-)
  altitude_DE landmark_alt_DE = altitude_DE::point_origin + 300 * m;
  altitude_CH landmark_alt_CH = altitude_CH::point_origin + 300 * m;

  // artifical deltas from landmarks of the bridge base on both sides of the river
  quantity delta_DE = isq::height(3 * m);
  quantity delta_CH = isq::height(-2 * m);

  // artificial altitude of the bridge base on both sides of the river
  quantity_point bridge_base_alt_DE = landmark_alt_DE + delta_DE;
  quantity_point bridge_base_alt_CH = landmark_alt_CH + delta_CH;

  // artificial height of the required bridge pilar height on both sides of the river
  quantity bridge_pilar_height_DE = expected_bridge_alt - bridge_base_alt_DE;
  quantity bridge_pilar_height_CH = expected_bridge_alt - bridge_base_alt_CH;

  std::println("Bridge pillars height:");
  std::println("- Germany:     {}", bridge_pilar_height_DE);
  std::println("- Switzerland: {}", bridge_pilar_height_CH);

  // artificial bridge altitude on both sides of the river in both systems
  quantity_point bridge_road_alt_DE = bridge_base_alt_DE + bridge_pilar_height_DE;
  quantity_point bridge_road_alt_CH = bridge_base_alt_CH + bridge_pilar_height_CH;

  std::println("Bridge road altitude:");
  std::println("- Germany:     {}", bridge_road_alt_DE);
  std::println("- Switzerland: {}", bridge_road_alt_CH);

  std::println("Bridge road altitude relative to the Amsterdam Sea Level:");
  std::println("- Germany:     {}", bridge_road_alt_DE.quantity_from(amsterdam_sea_level));
  std::println("- Switzerland: {}", bridge_road_alt_CH.quantity_from(amsterdam_sea_level));
}

The above provides the following text output:

Bridge pillars height:
- Germany:     27 m
- Switzerland: 3227 cm
Bridge road altitude:
- Germany:     330 m AMSL(DE)
- Switzerland: 33027 cm AMSL(CH)
Bridge road altitude relative to the Amsterdam Sea Level:
- Germany:     330 m
- Switzerland: 33000 cm

Try it in the Compiler Explorer.

10.5 User defined quantities and units

Users can easily define new quantities and units for domain-specific use-cases. This example from digital signal processing domain will show how to define custom strongly typed dimensionless quantities, units for them, and how they can be converted to time measured in milliseconds:

import mp_units;
import std;

using namespace mp_units;

namespace ni {

// quantities
inline constexpr struct SampleCount : quantity_spec<dimensionless, is_kind> {} SampleCount;
inline constexpr struct SampleDuration : quantity_spec<isq::time> {} SampleDuration;
inline constexpr struct SamplingRate : quantity_spec<isq::frequency, SampleCount / isq::time> {} SamplingRate;

inline constexpr struct UnitSampleAmount : quantity_spec<dimensionless, is_kind> {} UnitSampleAmount;
inline constexpr auto Amplitude = UnitSampleAmount;
inline constexpr auto Level = UnitSampleAmount;
inline constexpr struct Power : quantity_spec<Level * Level> {} Power;

inline constexpr struct MIDIClock : quantity_spec<dimensionless, is_kind> {} MIDIClock;

inline constexpr struct BeatCount : quantity_spec<dimensionless, is_kind> {} BeatCount;
inline constexpr struct BeatDuration : quantity_spec<isq::time> {} BeatDuration;
inline constexpr struct Tempo : quantity_spec<isq::frequency, BeatCount / isq::time> {} Tempo;

// units
inline constexpr struct Sample : named_unit<"Smpl", one, kind_of<SampleCount>> {} Sample;
inline constexpr struct SampleValue : named_unit<"PCM", one, kind_of<UnitSampleAmount>> {} SampleValue;
inline constexpr struct MIDIPulse : named_unit<"p", one, kind_of<MIDIClock>> {} MIDIPulse;

inline constexpr struct QuarterNote : named_unit<"q", one, kind_of<BeatCount>> {} QuarterNote;
inline constexpr struct HalfNote : named_unit<"h", mag<2> * QuarterNote> {} HalfNote;
inline constexpr struct DottedHalfNote : named_unit<"h.", mag<3> * QuarterNote> {} DottedHalfNote;
inline constexpr struct WholeNote : named_unit<"w", mag<4> * QuarterNote> {} WholeNote;
inline constexpr struct EightNote : named_unit<"8th", mag<ratio{1, 2}> * QuarterNote> {} EightNote;
inline constexpr struct DottedQuarterNote : named_unit<"q.", mag<3> * EightNote> {} DottedQuarterNote;
inline constexpr struct QuarterNoteTriplet : named_unit<"qt", mag<ratio{1, 3}> * HalfNote> {} QuarterNoteTriplet;
inline constexpr struct SixteenthNote : named_unit<"16th", mag<ratio{1, 2}> * EightNote> {} SixteenthNote;
inline constexpr struct DottedEightNote : named_unit<"q.", mag<3> * SixteenthNote> {} DottedEightNote;

inline constexpr auto Beat = QuarterNote;

inline constexpr struct BeatsPerMinute : named_unit<"bpm", Beat / si::minute> {} BeatsPerMinute;
inline constexpr struct MIDIPulsePerQuarter : named_unit<"ppqn", MIDIPulse / QuarterNote> {} MIDIPulsePerQuarter;

namespace unit_symbols {

inline constexpr auto Smpl = Sample;
inline constexpr auto pcm = SampleValue;
inline constexpr auto p = MIDIPulse;

inline constexpr auto n_wd = 3 * HalfNote;
inline constexpr auto n_w = WholeNote;
inline constexpr auto n_hd = DottedHalfNote;
inline constexpr auto n_h = HalfNote;
inline constexpr auto n_qd = DottedQuarterNote;
inline constexpr auto n_q = QuarterNote;
inline constexpr auto n_qt = QuarterNoteTriplet;
inline constexpr auto n_8thd = DottedEightNote;
inline constexpr auto n_8th = EightNote;
inline constexpr auto n_16th = SixteenthNote;

}

quantity<BeatsPerMinute, float> GetTempo()
{
  return 110 * BeatsPerMinute;
}

quantity<MIDIPulsePerQuarter, unsigned> GetPPQN()
{
  return 960 * MIDIPulse / QuarterNote;
}

quantity<MIDIPulse, unsigned> GetTransportPos()
{
  return 15836 * MIDIPulse;
}

quantity<SamplingRate[si::hertz], float> GetSampleRate()
{
  return 44100.f * si::hertz;
}

}

int main()
{
  using namespace ni::unit_symbols;
  using namespace mp_units::si::unit_symbols;

  const auto sr1 = ni::GetSampleRate();
  const auto sr2 = 48000.f * Smpl / s;

  const auto samples = 512 * Smpl;

  const auto sampleTime1 = (samples / sr1).in(s);
  const auto sampleTime2 = (samples / sr2).in(ms);

  const auto sampleDuration1 = (1 / sr1).in(ms);
  const auto sampleDuration2 = (1 / sr2).in(ms);

  const auto rampTime = 35.f * ms;
  const auto rampSamples1 = value_cast<int>((rampTime * sr1).in(Smpl));
  const auto rampSamples2 = value_cast<int>((rampTime * sr2).in(Smpl));

  std::println("Sample rate 1 is: {}", sr1);
  std::println("Sample rate 2 is: {}", sr2);

  std::println("{} @ {} is {:{%N:.5f} %U}", samples, sr1, sampleTime1);
  std::println("{} @ {} is {:{%N:.5f} %U}", samples, sr2, sampleTime2);

  std::println("One sample @ {} is {:{%N:.5f} %U}", sr1, sampleDuration1);
  std::println("One sample @ {} is {:{%N:.5f} %U}", sr2, sampleDuration2);

  std::println("{} is {} @ {}", rampTime, rampSamples1, sr1);
  std::println("{} is {} @ {}", rampTime, rampSamples2, sr2);

  auto sampleValue = -0.4f * pcm;
  auto power1 = sampleValue * sampleValue;
  auto power2 = -0.2 * pow<2>(pcm);

  auto tempo = ni::GetTempo();
  auto reverbBeats = 1 * n_qd;
  auto reverbTime = reverbBeats / tempo;

  auto pulsePerQuarter = value_cast<float>(ni::GetPPQN());
  auto transportPosition = ni::GetTransportPos();
  auto transportBeats = (transportPosition / pulsePerQuarter).in(n_q);
  auto transportTime = (transportBeats / tempo).in(s);

  std::println("SampleValue is: {}", sampleValue);
  std::println("Power 1 is: {}", power1);
  std::println("Power 2 is: {}", power2);

  std::println("Tempo is: {}", tempo);
  std::println("Reverb Beats is: {}", reverbBeats);
  std::println("Reverb Time is: {}", reverbTime.in(s));
  std::println("Pulse Per Quarter is: {}", pulsePerQuarter);
  std::println("Transport Position is: {}", transportPosition);
  std::println("Transport Beats is: {}", transportBeats);
  std::println("Transport Time is: {}", transportTime);

  // auto error = 1 * Smpl + 1 * pcm + 1 * p + 1 * Beat;  // Compile-time error
}

The above code outputs:

Sample rate 1 is: 44100 Hz
Sample rate 2 is: 48000 Smpl/s
512 Smpl @ 44100 Hz is 0.01161 s
512 Smpl @ 48000 Smpl/s is 10.66667 ms
One sample @ 44100 Hz is 0.02268 ms
One sample @ 48000 Smpl/s is 0.02083 ms
35 ms is 1543 Smpl @ 44100 Hz
35 ms is 1680 Smpl @ 48000 Smpl/s
SampleValue is: -0.4 PCM
Power 1 is: 0.16000001 PCM²
Power 2 is: -0.2 PCM²
Tempo is: 110 bpm
Reverb Beats is: 1 q.
Reverb Time is: 0.8181818 s
Pulse Per Quarter is: 960 ppqn
Transport Position is: 15836 p
Transport Beats is: 16.495832 q
Transport Time is: 8.997726 s

Try it in the Compiler Explorer.

Note: More about this example can be found in “Exploration of Strongly-typed Units in C++: A Case Study from Digital Audio” CppCon 2023 talk by Roth Michaels.

11 Why do we need typed quantities?

11.1 Limitations of units-only solutions

Units-only is not a good design for a quantities and units library. It works to some extent, but plenty of use cases can’t be addressed, and for those that somehow work, we miss important safety improvements provided by additional abstractions in this chapter. But before we talk about those extensions, let’s first discuss some limitations of the units-only solution.

Note: The issues described below do not apply to the proposed library, because with the proposed interfaces, even if we decide to only use the simple mode, units are still backed up by quantity kinds under the framework’s hood.

11.1.1 No way to specify a quantity type in generic interfaces

A common requirement in the domain is to write unit-agnostic generic interfaces. For example, let’s try to implement a generic avg_speed function template that takes a quantity of any unit and produces the result. So if we call it with distance in km and time in h, we will get km / h as a result, but if we call it with mi and h, we expect mi / h to be returned.

template<Unit auto U1, typename Rep1, Unit auto U2, typename Rep2>
auto avg_speed(quantity<U1, Rep1> distance, quantity<U2, Rep2> time)
{
  return distance / time;
}

quantity speed = avg_speed(120 * km, 2 * h);

This function works but does not provide any type safety to the users. The function arguments can be easily reordered on the call site. Also, we do not get any information about the return type of the function and any safety to ensure that the function logic actually returns a quantity of speed.

With a units-only library, we have to write the function in the following way:

quantity<si::metre / si::second> avg_speed(quantity<si::metre> distance, quantity<si::second> time)
{
  return distance / time;
}

avg_speed(120 * km, 2 * h).in(km / h);

The above code decreased the performance because we always pay for the conversion at the function’s input and output. Moreover, we had to force double as a representation type to prevent narrowing, which can affect not only the performance, but also precision and memory footprint.

We could try to provide concepts like ScaledUnitOf<si::metre> that will try to constrain somehow the arguments, but it leads to even more problems with the unit definitions. For example, are Hz and Bq scaled versions of 1 / s? What about radian and steradian or a litre and a cubic meter?

11.1.2 Disjoint units of the same quantity type do not work

Sometimes, we need to define several units describing the same quantity but which do not convert to each other. A typical example can be a currency use case. A user may want to define EURO and USD as units of currency, but do not provide any predefined conversion factor and handle such a conversion at runtime with custom logic. In such a case, how we can specify that EURO and USD are quantities of the same type/dimension?

11.2 Limitations of dimensions

To prevent the above issues, most of the libraries on the market introduce dimension abstraction. Thanks to that, we could solve the first issue of the previous chapter with:

QuantityOf<dim_speed> auto avg_speed(QuantityOf<dim_length> auto distance, 
                                     QuantityOf<dim_time> auto time)
{
  return distance / time;
}

and the second one by specifying that both EURO and USD are units of dim_currency. This is a significant improvement but still has some issues.

Let’s first look again at the above solution. A domain expert seeing this code will immediately say there is no such thing as a speed dimension. The ISQ specifies only 7 dimensions with unique symbols assigned, and the dimensions of all the ISQ quantities are created as a vector product of those. For example, a quantity of speed has a dimension of \(L^1T^{-1}\). So, to be physically correct, the above code should be rewritten as:

QuantityOf<dim_length / dim_time> auto avg_speed(QuantityOf<dim_length> auto distance, 
                                                 QuantityOf<dim_time> auto time)
{
  return distance / time;
}

Most of the libraries on the market ignore this fact and try to model distinct quantities through their dimensions, giving a false sense of safety. A dimension is not enough to describe a quantity. This has been known for a long time now. The [Measurement Data] report from 1996 says explicitly, “Dimensional analysis does not adequately model the semantics of measurement data”.

In the following chapters, we will see a few use cases that can’t be solved with an approach that only relies on units or dimensions.

11.2.1 SI units of quantities of the same dimension but different kinds

The [SI] provides several units for distinct quantities of the same dimension but different kinds. For example:

• hertz (Hz) is a unit of frequency and becquerel (Bq) is a unit of activity. Both are defined as \(s^{-1}\), and have the same dimension of \(T^{-1}\).
• gray (Gy) is a unit of absorbed dose and sievert (Sv) is a unit of dose equivalent. Both are defined as \(m^2 s^{-2}\), and have the same dimension of \(L^2T^{-2}\)
• radian (rad) is a unit of plane angle defined as \(m/m\), and steradian (sr) is a unit of solid angle defined as \(m^2/m^2\). Both are quantities of dimension one, which also has its own units like one (1) and percent (%).

There are many more similar examples in [ISO/IEC 80000]. For example, storage capacity quantity can be measured in units of one, bit, octet, and byte.

The above conflicts can’t be solved with dimensions, and they yield many safety issues. For example, we can ask ourselves what should be the result of the following:

1. quantity q = 1 * Hz + 1 * Bq;
2. quantity<Gy> q = 42 * Sv;
3. bool b = (1 * rad + 1 * bit) == 2 * sr;

None of the above code should compile, but most of the libraries on the market happily accept it and provide meaningless results. Some of them decide not to define one or more of the above units at all to avoid potential safety issues. For example, the Au library does not define Sv to avoid mixing it up with Gy.

11.2.2 Derived quantities of the same dimension but different kinds

Even if some quantities do not have a specially assigned unit, they may still have a totally different physical meaning even if they share the same dimension:

• work vs. moment of force both of the same dimension \(L^2MT^{-2}\)
• fuel consumption expressed in \(\frac{l}{100\;km}\) vs. area expressed in \(m^2\) both of the same dimension \(L^2\)

Again, we don’t want to accidentally mix those.

11.2.3 Various quantities of the same dimension and kinds

Even if we somehow address all the above, there are still plenty of use cases that still can’t be safely implemented with such abstractions.

Let’s consider that we want to implement a freight transport application to position cargo in the container. In such a scenario, we need to be able to discriminate between length, width, and height of the package. Also, often, we can find a “This side up” arrow on the box.

A similar but also really important use case is in aviation. The current altitude is a totally different quantity than the distance to the destination. The same is true for forward speed and sink rate. We do not want to accidentally mix those.

When we deal with energy, we should be able to implicitly construct it from a proper product of any mass, length, and time. However, when we want to calculate gravitational potential energy, we may not want it to be implicitly initialized from any expression of matching dimensions. Such an implicit construction should be allowed only if we multiply a mass with acceleration of free fall and height. All other conversions should happen explicitly.

Yet another example comes from the audio industry. In the audio software, we want to treat specific counts (e.g., beats, samples) as separate quantities, but if we divide them, we should obtain a quantity convertible to frequency. The latter has the dimension of \(T^{-1}\), which prevents us from assigning dedicated dimensions to such counts.

The last example that we want to mention here comes from finance. This time, we need to model volume as a special quantity of currency. volume can be obtained by multiplying currency by the dimensionless market quantity. Of course, both currency and volume should be expressed in the same units (e.g., USD).

None of the above scenarios can be addressed with just units and dimensions. We need a better abstraction to safely implement them.

12 Systems of quantities and units

A system of quantities is a set of quantities together with a set of noncontradictory equations relating those quantities.

The International System of Quantities (ISQ) is a system of quantities based on the seven base quantities: length, mass, time, electric current, thermodynamic temperature, amount of substance, and luminous intensity. This system of quantities is published in [ISO/IEC 80000], “Quantities and units”.

A system of units is a set of base units and derived units, together with their multiples and submultiples, defined in accordance with given rules, for a given system of quantities.

The International System of Units (SI) is a system of units, based on the International System of Quantities, their names and symbols, including a series of prefixes and their names and symbols, together with rules for their use, adopted by the General Conference on Weights and Measures (CGPM).

12.1 Systems of quantities

The physical units libraries on the market typically only focus on modeling one or more systems of units. However, this is not the only system kind to model. Another, and maybe even more important, is a system of quantities. The most important example here is the International System of Quantities (ISQ) defined by [ISO/IEC 80000].

12.1.1 Quantities of the same kind

As it was described in Limitations of dimensions, dimension is not enough to describe a quantity. We need a better abstraction to provide safety to our calculations.

The [ISO/IEC Guide 99] says:

• Quantities may be grouped together into categories of quantities that are mutually comparable
• Mutually comparable quantities are called quantities of the same kind
• Two or more quantities cannot be added or subtracted unless they belong to the same category of mutually comparable quantities
• Quantities of the same kind within a given system of quantities have the same quantity dimension
• Quantities of the same dimension are not necessarily of the same kind

[ISO/IEC 80000] also explicitly notes:

Measurement units of quantities of the same quantity dimension may be designated by the same name and symbol even when the quantities are not of the same kind. For example, joule per kelvin and J/K are respectively the name and symbol of both a measurement unit of heat capacity and a measurement unit of entropy, which are generally not considered to be quantities of the same kind. However, in some cases special measurement unit names are restricted to be used with quantities of specific kind only. For example, the measurement unit ‘second to the power minus one’ (1/s) is called hertz (Hz) when used for frequencies and becquerel (Bq) when used for activities of radionuclides. As another example, the joule (J) is used as a unit of energy, but never as a unit of moment of force, i.e. the newton metre (N · m).

Those provide answers to all the issues mentioned above. More than one quantity may be defined for the same dimension:

• quantities of different kinds (e.g., frequency, modulation rate, activity)
• quantities of the same kind (e.g., length, width, altitude, distance, radius, wavelength, position vector)

Two quantities can’t be added, subtracted, or compared unless they belong to the same quantity kind.

12.1.2 System of quantities is not only about kinds

[ISO/IEC 80000] specifies hundreds of different quantities. Plenty of various kinds are provided, and often, each kind contains more than one quantity. It turns out that such quantities form a hierarchy of quantities of the same kind.

For example, here are all quantities of the kind length provided in [ISO/IEC 80000] (part 1):

Each of the above quantities expresses some kind of length, and each can be measured with meters, which is the unit defined by the [SI] for quantities of length. However, each has different properties, usage, and sometimes even a different character (position vector and displacement are vector quantities).

The below presents how such a hierarchy tree can be defined in the library:

inline constexpr struct dim_length : base_dimension<"L"> {} dim_length;

inline constexpr struct length : quantity_spec<dim_length> {} length;
inline constexpr struct width : quantity_spec<length> {} width;
inline constexpr auto breadth = width;
inline constexpr struct height : quantity_spec<length> {} height;
inline constexpr auto depth = height;
inline constexpr auto altitude = height;
inline constexpr struct thickness : quantity_spec<width> {} thickness;
inline constexpr struct diameter : quantity_spec<width> {} diameter;
inline constexpr struct radius : quantity_spec<width> {} radius;
inline constexpr struct radius_of_curvature : quantity_spec<radius> {} radius_of_curvature;
inline constexpr struct path_length : quantity_spec<length> {} path_length;
inline constexpr auto arc_length = path_length;
inline constexpr struct distance : quantity_spec<path_length> {} distance;
inline constexpr struct radial_distance : quantity_spec<distance> {} radial_distance;
inline constexpr struct wavelength : quantity_spec<length> {} wavelength;
inline constexpr struct position_vector : quantity_spec<length, quantity_character::vector> {} position_vector;
inline constexpr struct displacement : quantity_spec<length, quantity_character::vector> {} displacement;

In the above code:

• length takes the base dimension to indicate that we are creating a base quantity that will serve as a root for a tree of quantities of the same kind,
• width and following quantities are branches and leaves of this tree with the parent always provided as the argument to quantity_spec class template,
• breadth is an alias name for the same quantity as width.

Please note that some quantities may be specified by [ISO/IEC 80000] as vector or tensor quantities (e.g., displacement).

12.1.3 Converting between quantities of the same kind

Quantity conversion rules can be defined based on the same hierarchy of quantities of kind length.

1. Implicit conversions

   • Every width is a length.
   • Every radius is a width.

   static_assert(implicitly_convertible(isq::width, isq::length));
   static_assert(implicitly_convertible(isq::radius, isq::length));
   static_assert(implicitly_convertible(isq::radius, isq::width));

   Implicit conversions are allowed on copy-initialization:

   void foo(quantity<isq::length<m>> q);

   quantity<isq::width<m>> q1 = 42 * m;
   quantity<isq::length<m>> q2 = q1;  // implicit quantity conversion
   foo(q1);                           // implicit quantity conversion

2. Explicit conversions

   • Not every length is a width.
   • Not every width is a radius.

   static_assert(!implicitly_convertible(isq::length, isq::width));
   static_assert(!implicitly_convertible(isq::length, isq::radius));
   static_assert(!implicitly_convertible(isq::width, isq::radius));
   static_assert(explicitly_convertible(isq::length, isq::width));
   static_assert(explicitly_convertible(isq::length, isq::radius));
   static_assert(explicitly_convertible(isq::width, isq::radius));

   Explicit conversions are forced by passing the quantity to a call operator of a quantity_spec type:

   quantity<isq::length<m>> q1 = 42 * m;
   quantity<isq::height<m>> q2 = isq::height(q1);  // explicit quantity conversion

3. Explicit casts

   • height is never a width, and vice versa.
   • Both height and width are quantities of kind length.

   static_assert(!implicitly_convertible(isq::height, isq::width));
   static_assert(!explicitly_convertible(isq::height, isq::width));
   static_assert(castable(isq::height, isq::width));

   Explicit casts are forced with a dedicated quantity_cast function:

   quantity<isq::width<m>> q1 = 42 * m;
   quantity<isq::height<m>> q2 = quantity_cast<isq::height>(q1);  // explicit quantity cast

4. No conversion

   • time has nothing in common with length.

   static_assert(!implicitly_convertible(isq::time, isq::length));
   static_assert(!explicitly_convertible(isq::time, isq::length));
   static_assert(!castable(isq::time, isq::length));

   Even the explicit casts will not force such a conversion:

   void foo(quantity<isq::length[m]>);

   foo(quantity_cast<isq::length>(42 * s)); // Compile-time error

12.1.4 Comparing, adding, and subtracting quantities of the same kind

[ISO/IEC Guide 99] explicitly states that width and height are quantities of the same kind and as such they:

• are mutually comparable, and
• can be added and subtracted.

If we take the above for granted, the only reasonable result of 1 * width + 1 * height is 2 * length, where the result of length is known as a common quantity type. A result of such an equation is always the first common node in a hierarchy tree of the same kind. For example:

static_assert(common_quantity_spec(isq::width, isq::height) == isq::length);
static_assert(common_quantity_spec(isq::thickness, isq::radius) == isq::width);
static_assert(common_quantity_spec(isq::distance, isq::path_length) == isq::path_length);

quantity q = isq::thickness(1 * m) + isq::radius(1 * m);
static_assert(q.quantity_spec == isq::width);

One could argue that allowing to add or compare quantities of height and width might be a safety issue, but we need to be consistent with the requirements of [ISO/IEC 80000]. Moreover, from our experience, disallowing such operations and requiring an explicit cast to a common quantity in every single place makes the code so cluttered with casts that it nearly renders the library unusable.

Fortunately, the above-mentioned conversion rules make the code safe by construction anyway. Let’s analyze the following example:

inline constexpr struct horizontal_length : quantity_spec<isq::length> {} horizontal_length;

namespace christmas {

struct gift {
  quantity<horizontal_length[m]> length;
  quantity<isq::width[m]> width;
  quantity<isq::height[m]> height;
};

std::array<quantity<isq::length[m]>, 2> gift_wrapping_paper_size(const gift& g)
{
  const auto dim1 = 2 * g.width + 2 * g.height + 0.5 * g.width;
  const auto dim2 = g.length + 2 * 0.75 * g.height;
  return { dim1, dim2 };
}

}  // namespace christmas

int main()
{
  const christmas::gift lego = { horizontal_length(40 * cm), isq::width(30 * cm), isq::height(15 * cm) };
  auto paper = christmas::gift_wrapping_paper_size(lego);

  std::cout << "Paper needed to pack a lego box:\n";
  std::cout << "- " << paper[0] << " X " << paper[1] << "\n";  // - 1.05 m X 0.625 m
  std::cout << "- area = " << paper[0] * paper[1] << "\n";     // - area = 0.65625 m²
}

In the beginning, we introduce a custom quantity horizontal_length of a kind length, which then, together with isq::width and isq::height, are used to define the dimensions of a Christmas gift. Next, we provide a function that calculates the dimensions of a gift wrapping paper with some wraparound. The result of both those expressions is a quantity of isq::length, as this is the closest common quantity for the arguments used in this quantity equation.

Regarding safety, it is important to mention here, that thanks to the conversion rules provided above, it would be impossible to accidentally do the following:

void foo(quantity<horizontal_length[m]> q);

quantity<isq::width[m]> q1 = dim1;  // Compile-time error
quantity<isq::height[m]> q2{dim1};  // Compile-time error
foo(dim1);                          // Compile-time error

The reason of compilation errors above is the fact that isq::length is not implicitly convertible to the quantities defined based on it. To make the above code compile, an explicit conversion of a quantity type is needed:

void foo(quantity<horizontal_length[m]> q);

quantity<isq::width[m]> q1 = isq::width(dim1);
quantity<isq::height[m]> q2{isq::height(dim1)};
foo(horizontal_length(dim1));

To summarize, rules for addition, subtraction, and comparison of quantities improve the library usability, while the conversion rules enhance the safety of the library compared to the libraries that do not model quantity kinds.

12.1.5 Hierarchies of derived quantities

The same rules propagate to derived quantities. For example, we can define strongly typed horizontal length and area:

inline constexpr struct horizontal_length : quantity_spec<isq::length> {} horizontal_length;
inline constexpr struct horizontal_area : quantity_spec<isq::area, horizontal_length * isq::width> {} horizontal_area;

The first definition says that a horizontal_length is a more specialized quantity than isq::length and belongs to the same quantity kind. The second line defines a horizontal_area, which is a more specialized quantity than isq::area, so it has a more constrained recipe as well. Thanks to that:

static_assert(implicitly_convertible(horizontal_length, isq::length));
static_assert(!implicitly_convertible(isq::length, horizontal_length));
static_assert(explicitly_convertible(isq::length, horizontal_length));

static_assert(implicitly_convertible(horizontal_area, isq::area));
static_assert(!implicitly_convertible(isq::area, horizontal_area));
static_assert(explicitly_convertible(isq::area, horizontal_area));

static_assert(implicitly_convertible(isq::length * isq::length, isq::area));
static_assert(!implicitly_convertible(isq::length * isq::length, horizontal_area));
static_assert(explicitly_convertible(isq::length * isq::length, horizontal_area));

static_assert(implicitly_convertible(horizontal_length * isq::width, isq::area));
static_assert(implicitly_convertible(horizontal_length * isq::width, horizontal_area));

Unfortunately, derived quantity equations often do not automatically form a hierarchy tree. This is why sometimes it is not obvious what such a tree should look like. Also, the [ISO/IEC Guide 99] explicitly states:

The division of ‘quantity’ according to ‘kind of quantity’ is, to some extent, arbitrary.

The below presents some arbitrary hierarchy of derived quantities of kind energy:

Notice, that even though all of those quantities have the same dimension and can be expressed in the same units, they have different quantity equations used to create them implicitly:

• energy is the most generic one and thus can be created from base quantities of mass, length, and time. As those are also the roots of quantities of their kinds and all other quantities are implicitly convertible to them, it means that an energy can be implicitly constructed from any quantity having proper powers of mass, length, and time.

  static_assert(implicitly_convertible(isq::mass * pow<2>(isq::length) / pow<2>(isq::time), isq::energy));
  static_assert(implicitly_convertible(isq::mass * pow<2>(isq::height) / pow<2>(isq::time), isq::energy));

• mechanical_energy is a more “specialized” quantity than energy (not every energy is a mechanical_energy). It is why an explicit cast is needed to convert from either energy or the results of its quantity equation.

  static_assert(!implicitly_convertible(isq::energy, isq::mechanical_energy));
  static_assert(explicitly_convertible(isq::energy, isq::mechanical_energy));
  static_assert(!implicitly_convertible(isq::mass * pow<2>(isq::length) / pow<2>(isq::time), isq::mechanical_energy));
  static_assert(explicitly_convertible(isq::mass * pow<2>(isq::length) / pow<2>(isq::time), isq::mechanical_energy));

• gravitational_potential_energy is not only even more specialized one but additionally, it is special in a way that it provides its own “constrained” quantity equation. Maybe not every mass * pow<2>(length) / pow<2>(time) is a gravitational_potential_energy, but every mass * acceleration_of_free_fall * height is.

  static_assert(!implicitly_convertible(isq::energy, gravitational_potential_energy));
  static_assert(explicitly_convertible(isq::energy, gravitational_potential_energy));
  static_assert(!implicitly_convertible(isq::mass * pow<2>(isq::length) / pow<2>(isq::time), gravitational_potential_energy));
  static_assert(explicitly_convertible(isq::mass * pow<2>(isq::length) / pow<2>(isq::time), gravitational_potential_energy));
  static_assert(implicitly_convertible(isq::mass * isq::acceleration_of_free_fall * isq::height, gravitational_potential_energy));