Introduction

mp-units is a Modern C++ library that provides compile-time dimensional analysis and unit/quantity manipulation. The initial versions of the library were inspired by the std::chrono::duration but with each release, the interfaces diverged from the original to provide a better user experience.

Info

A brief introduction to the library's interfaces and the rationale for changes in version 2.0 of mp-units were provided in detail by Mateusz Pusz in the "The Power of C++ Templates With mp-units: Lessons Learned & a New Library Design" talk at the C++ on Sea 2023 conference.

Open Source

mp-units is Free and Open Source, with a permissive MIT license. Check out the source code and issue tracking (for questions and support, reporting bugs, suggesting feature requests and improvements) at https://github.com/mpusz/mp-units.

With the User's Experience in Mind

Most of the critical design decisions in the library are dictated by the requirement of providing the best user experience possible. Other C++ physical units libraries are "famous" for their enormous and hard-to-understand error messages (one line of the error log often does not fit on one slide). The ultimate goal of mp-units is to improve this and make compile-time errors and debugging as easy and user-friendly as possible.

To achieve this goal, several techniques are applied:

• usage of C++20 concepts that improve compile-times and the readability of error messages when compared to the traditional template metaprogramming with SFINAE,
• usage of strong types for framework entities (instead of type aliases),
• usage of symbolic expressions to improve the readability of generated types,
• limiting the number of template arguments to the bare minimum.

Important: It is all about errors

In many generic C++ libraries, compile-time errors do not happen often. It is hard to break std::string or std::vector in a way that won't compile with a huge error log. Physical quantities and units libraries are different. Generation of compile-time errors is the main reason to use such a library.

Key Features

Feature	Description
Safety	- The affine space strong types (quantity and quantity_point) - Compile-time checked conversions of quantities and units - Unique support for many quantities of the same kind - Type-safe equations on scalar, vector, and tensor quantities and their units - Value-preserving conversions
Performance	- All the compile-time logic implemented as immediate (consteval) functions - As fast or even faster than working with fundamental types - No space size overhead needed to implement high-level abstractions
Great User Experience	- Optimized for readable compilation errors and great debugging experience - Efficient and composable way to specify a unit of choice - Value-based dimension, unit, and quantity equations
Feature Rich	- Systems of Quantities - Systems of Units - Scalar, vector, and tensor quantities - The affine space - Different models of the universe (e.g. natural units systems) - Strong dimensionless quantities - Strong angular system - Supports any unit's magnitude (huge, small, floating-point) - Faster-than-lightspeed constants - Highly adjustable text-output formatting
Easy to Extend	- Each entity can be defined with a single line of code - User can easily extend the systems with custom dimensions, quantities, and units
Low Standardization Cost	- Small number of predefined entities thanks to their composability - No external dependencies (assuming full C++20 support) - No macros in the user interface (besides portability and standard-compliance issues) - Possibility to be standardized as a freestanding part of the C++ Standard Library