mp-units – The Domain-Correct Quantities and Units Library for C++

🎯 Overview

mp-units is a Modern C++ (C++20 and later) library providing the full spectrum of compile-time safety for domain-specific quantities and units, from dimensional analysis to quantity kind safety, built on the ISO 80000 International System of Quantities (ISQ). It is a candidate for C++29 standardization (P3045), your chance to shape the future of C++.

#include <mp-units/systems/isq.h>
#include <mp-units/systems/si.h>

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

// Compile-time dimensional analysis — zero runtime overhead
static_assert(1 * km / (1 * s) == 1000 * m / s);

// Function signatures encode domain/physics, not just dimensions
void calculate_trajectory(quantity<isq::kinetic_energy[J]> e);

int main()
{
  quantity<isq::potential_energy[J]> Ep = 42 * J;
  quantity<isq::kinetic_energy[J]>   Ek = 123 * J;
  calculate_trajectory(Ek);         // ✅ correct
  // calculate_trajectory(Ep);      // ❌ potential energy ≠ kinetic energy (both in J)

  // quantity<Gy> q = 42 * Sv;      // ❌ absorbed dose ≠ dose equivalent (both J/kg)
}

What Sets mp-units Apart?

Beyond standard dimensional analysis and automatic unit conversions, mp-units provides additional safety levels:

• Quantity Kind Safety — mp-units pioneered this level: it distinguishes quantities that share the same dimension but represent fundamentally different physical concepts: frequency (Hz) ≠ radioactive activity (Bq), absorbed dose (Gy) ≠ dose equivalent (Sv), plane angle (rad) ≠ solid angle (sr). Dimensional analysis alone cannot catch these errors, mp-units prevents them at compile time.

• ISO 80000 (ISQ) Support — Built on the International System of Quantities, functions can require specific quantities: isq::height (not just any isq::length), isq::kinetic_energy (not just any isq::energy). The physics of your domain becomes part of the type system.

• Strongly-Typed Numerics for Any Domain — The quantity framework extends beyond physics: define semantically distinct types for item counts, financial values, identifiers, or any numeric abstraction that should never be silently mixed at compile time.

✅ Key Features

Safety

• Quantity kind safety: same dimension, different meaning → compile-time error
• Affine space strong types (quantity and quantity_point)
• Value-preserving conversions

Performance

• All dimensional analysis at compile time, zero runtime overhead
• Performance on par with (sometimes even better than) fundamental types

User Experience

• Optimized for readable, actionable compilation errors
• Expressive, composable unit expressions

Feature Rich

• Systems of Quantities and Units; scalar, vector, and tensor quantities
• Affine space, natural units, strong angular system
• Highly adjustable text output formatting

Easy to Extend

• Custom dimensions, quantities, and units in a single line of code

Low Adoption Cost

• No external dependencies · macro-free API · C++20 modules-ready · freestanding-capable

→ Full feature overview

📚 Documentation

Extensive project documentation covers everything from getting started to advanced usage:

• Getting Started – Get up and running quickly
• Tutorials – Step-by-step learning resources
• User's Guide – Comprehensive usage documentation
• Workshops – Hands-on practice exercises
• How-to Guides – Task-oriented recipes
• Examples – Real-world usage demonstrations
• Reference – Complete technical documentation
• Blog
  • Metrology – Design rationale and domain theory
  • Releases – Narrative release articles with examples and migration guidance
  • WG21 Updates – Standardization progress

→ Explore the full documentation

🔍 Try It Out

For advanced development or contributions, we provide a preconfigured cloud development environment with GitHub Codespaces:

Alternatives:

1. Navigate to the repository → "Code" → "Codespaces" → "Create codespace on master"
2. Use the preconfigured devcontainer and Docker image manually in your IDE

For detailed environment documentation, see .devcontainer/README.md.

🚀 Help Shape the Future of C++

mp-units is a candidate for ISO standardization for C++29. The technical case is documented in:

• P1935: A C++ Approach to Physical Units
• P2980: A motivation, scope, and plan for a quantities and units library
• P3045: Quantities and units library
• P4185: Completing the Mathematical Model for C++ Quantities and Units

We are actively seeking organizations and individuals interested in field‑trialing the library!

Your experience matters. Real-world testimonials demonstrate value to the ISO C++ Committee and help potential adopters decide. Whether you are using mp-units in production, research, or education:

• Organizations: Share your production deployments and success stories
• Academics: Report research applications and teaching experiences
• Developers: Tell us about your innovative use cases and benefits

🤝 Contributors

mp-units is made possible by our community of contributors!

Core Team

• Mateusz Pusz – Project founder and lead
• Johel Ernesto Guerrero Peña – Core maintainer
• Chip Hogg – Core maintainer

All Contributors

We appreciate every contribution, from code to documentation to community support.

See the Contributors Page for the complete list and recognition details.

Ready to contribute? Check out our Contributing Guide to get started! 🚀

💝 Support the Project

mp-units is developed as open source, with the goal of C++29 standardization. Your support helps sustain development and the standardization work.

Ways to support:

• ⭐ Star the repository – Show your appreciation and help others discover mp-units

• 💰 Become a sponsor – Financial support enables continued development

  

• 📢 Share your success story – Help demonstrate real-world value for standardization and other potential users

• 🤝 Contribute – Code, documentation, feedback, and community support