Skip to content

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 the version 2.0 of mp-units were provided in detail by Mateusz Pusz in the "mp-units: Lessons Learned and a New C++ Library Design" talk at the ACCU 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 do 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:

Important

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 it won't compile with a huge error log. Physical 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
- Natural units systems support
- 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 needed thanks to 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