User's Guide¶

Welcome to the mp-units User's Guide! This comprehensive guide covers all library concepts in depth, providing a thorough understanding of type-safe physical quantities and units in C++.

What is the User's Guide?¶

The User's Guide is explanation-oriented documentation that deepens your understanding of the library's concepts, architecture, and design philosophy.

This guide:

✅ Explains concepts thoroughly with context and rationale
✅ Covers all library features systematically
✅ Provides deep technical understanding
✅ Can be read sequentially like a book

Prerequisites: Familiarity with library basics from Tutorials. The User's Guide builds on tutorial knowledge to provide comprehensive coverage of all concepts.

Guide Structure¶

Terms and Definitions ¶

Essential metrology vocabulary and definitions used throughout the library and documentation.

Framework Basics¶

Core concepts that form the foundation of mp-units:

Interface Introduction - Library API overview
Design Overview - Architecture and design principles
Systems of Quantities - Quantity hierarchies and relationships
Systems of Units - Unit systems and their organization
Simple and Typed Quantities - Two approaches to quantity creation
Value Conversions - Converting between representations
Character of a Quantity - Scalar, vector, and tensor quantities
Dimensionless Quantities - Handling ratios and counts
Quantity Arithmetics - Mathematical operations
Generic Interfaces - Writing flexible, type-safe code
Faster-than-lightspeed Constants - Compile-time constant handling
The Affine Space - Points, quantities, and origins
Type Introspection - Inspecting quantity types at compile time
Concepts - C++20 concepts used throughout the library
Text Output - Formatting and printing quantities

Systems ¶

Detailed documentation of available unit systems (SI, CGS, Imperial, astronomical units, natural units, etc.) with guidance on choosing the right one for your application domain.

How to Use This Guide?¶

Sequential Reading: Start with Terms and Definitions and progress through the Framework Basics chapters to build a complete mental model of the library.

Reference Reading: Jump directly to specific chapters when you need to understand a particular concept in depth.

Domain-Focused: After covering Framework Basics, explore the Systems chapter most relevant to your application domain.

When to Use the User's Guide?¶

Read the User's Guide when you:

Want deep understanding of library concepts
Need to know why something works a certain way
Are designing complex systems using mp-units
Want to master advanced features
Need comprehensive coverage of a topic

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