User's Guide

Consider 1 * Hz + 1 * Bq + 1 * Bd. Hertz measures frequency, becquerel measures activity, and baud measures modulation rate. All three share the dimension \(\mathsf{T}^{-1}\), so a library that checks only dimensions cannot reject the sum, yet adding them is meaningless. mp-units rejects it, because it models quantities the way ISO 80000 defines them.

The Tutorials teach how to write code with the library. This guide explains why the code looks the way it does: which problem a feature solves and which part of the model solves it. It is the explanation part of the documentation.

Much of that model comes from metrology. The library follows the International System of Quantities (ISQ) and uses the vocabulary that ISO and the BIPM define for measurement. Most C++ developers have never needed either, so the guide introduces the terms where they first matter, and the Glossary collects them in one place.

Who this guide is for

The guide assumes you know C++ and have written a few quantities with the library, for example by working through the Quick Start tutorials. It assumes no knowledge of ISO 80000.

Read it when you need to know why the library refuses a conversion, or how to model your own domain on top of it. Questions about design alternatives that were considered and rejected are answered in the FAQ.

Recommended reading path

1. Skim Terms and Definitions and keep the Glossary at hand.
2. Read the Framework Basics chapters in order. Each one builds on the ones before it.
3. Read the Systems chapters that match your application domain.
4. Turn to the Advanced Topics when you write your own representation type, need the complete conversion rules between quantity specifications, inspect types at compile time, or constrain generic code with the library's concepts.

You can also jump straight to a single chapter and follow its links back to the terms it relies on.

Guide Structure

Terms and Definitions

The metrology vocabulary used throughout the library and its documentation.

Framework Basics

The core model of mp-units, in the recommended reading order:

• Interface Introduction - How library entities are defined and spelled
• Design Overview - The entities of the library and how they relate
• Systems of Quantities - Quantity hierarchies and kinds
• Systems of Units - Units, prefixes, and how unit systems are organized
• Simple and Typed Quantities - Two ways to create a quantity
• Value Conversions - Converting the unit and the representation of a value
• Character of a Quantity - Scalar, vector, and tensor quantities
• safe_int<T> - Overflow-safe integer arithmetic wrapper
• Dimensionless Quantities - Ratios, counts, and quantities of dimension one
• Quantity Arithmetics - Mathematical operations on quantities
• Generic Interfaces - Writing functions that accept many quantity types
• Faster-than-lightspeed Constants - Physical constants as units, simplified at compile time
• The Affine Space - Points, differences, and origins
• Text Output - Formatting and printing quantities

Systems

The systems of quantities and units that ship with the library (SI, CGS, yard-pound, astronomical, natural units, and others), with guidance on choosing one for your domain.

Advanced Topics

Topics you need when you extend the library or write generic code against it:

• Representation Types - Requirements on numeric types and how to plug in your own
• Quantity Specification Conversions - The complete rules for converting between quantity specifications
• Type Introspection - Inspecting quantity types at compile time
• Concepts - The C++20 concepts the library defines

Other Resources

• Tutorials - Learning-oriented lessons for getting started
• How-to Guides - Task-oriented solutions to specific problems
• Workshops - Hands-on practice with advanced patterns
• Examples - Complete, runnable applications
• Reference - Information-oriented technical descriptions
• FAQ - Design decisions and the alternatives we rejected