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 safety level: 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 fully configured cloud development environment with GitHub Codespaces:

Alternatives:

1. Navigate to the repository → "Code" → "Codespaces" → "Create codespace on master"
2. Use the pre‑configured 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 future of dimensional analysis in C++! 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're 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 our 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 ambitious goal of C++29 standardization. Your support helps maintain development momentum and accelerate standardization efforts!

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