Skip to content

Interactive Learning: Tutorials and Workshops

The mp-units documentation has two new sections: tutorials and hands-on workshops for learning type-safe physical quantities and units. The tutorials start at the first quantity you create, and the workshops go on to the more advanced patterns.

Interactive Code Examples

All tutorials and workshops use embedded interactive code editors powered by Compiler Explorer. Each code example is a live editor that compiles and runs automatically as you type:

  • ✅ Edit and see results instantly: type code and watch it compile
  • ✅ Get immediate feedback: compiler diagnostics appear as you code
  • ✅ See program output: text output is shown directly below the editor
  • ✅ Experiment freely: try variations without leaving the documentation

There is nothing to install and nothing to set up.

Experience it yourself

In the tutorials, every code example appears as an embedded interactive editor. You can modify the code directly in the documentation page and see it compile and run instantly. For example, a speed calculation tutorial might show:

// ce-embed height=400 compiler=clang2110 flags="-std=c++23 -stdlib=libc++ -O3" mp-units=trunk
#include <mp-units/systems/si.h>
#include <iostream>

int main()
{
  using namespace mp_units;
  using namespace mp_units::si::unit_symbols;

  quantity distance = 100 * m;
  quantity time = 9.58 * s;
  quantity speed = distance / time;  // Automatically derives m/s

  std::cout << "Distance: " << distance << "\n";
  std::cout << "Time: " << time << "\n";
  std::cout << "Speed: " << speed << "\n";
}

Just edit the numbers or units in the embedded editor, and watch the output update automatically below the code.

Why the Examples Are Editable

The examples can be edited and run without leaving the page, so you can try the library while you read about it.

Immediate Experimentation

Try the embedded editor above:

  • Change distance to 200 * m and watch the speed update
  • Try adding an invalid operation like distance + time and see the compiler error instantly
  • Experiment with different units: distance = 100 * km still works perfectly

The compiler diagnostic appears immediately when you make a mistake, and it shows why the dimensions don't match. There is no separate tool to run.

Learn from Mistakes

Making mistakes is part of learning. With embedded interactive editors:

  • Type invalid operations and see compiler errors instantly
  • Read compiler diagnostics in context as you code
  • Fix errors and watch the program compile successfully
  • Build intuition through immediate feedback

Active Learning

A few things worth doing while you read:

  • Type the code yourself rather than only reading it
  • Experiment with variations: change values and try different units
  • Break things on purpose to find out where the boundaries are
  • See the results immediately, with no compile and run cycle of your own

Getting Started

Where to start depends on what you already know:

For Beginners

  1. Start with Tutorials: complete all 17 lessons (~4 hours)
  2. Try the Foundation Workshops: practice refactoring patterns
  3. Explore Examples: study complete applications
  4. Dive into specific topics in the User's Guide as needed

For Experienced Developers

  1. Skim Quick Start tutorials (30 min)
  2. Focus on Type Safety tutorials (~1 hour)
  3. Jump to Customization and Advanced Workshops
  4. Reference the Systems documentation for your domain

For Migration

  1. Read the relevant Migration Guide
  2. Complete the Workshop: Incremental Migration
  3. Reference Interoperability guides as needed

Tutorials

The 17 step-by-step tutorials (~4 hours in total) start at "Hello World" and cover the core features of the library. Each tutorial is meant to:

  • Build progressively: each lesson builds on the previous one
  • Teach by example: through working code rather than abstract theory
  • Provide instant feedback: interactive examples let you experiment immediately
  • End with key insights: every code example concludes with "What You Learned?" takeaways

Learning Path

1. Quick Start (~30 minutes)

Three short lessons to get started:

Who it is for

Developers who want to see what mp-units can do before going further.

2. Working with Units (~50 minutes)

Converting units and extracting values:

Who it is for

Anyone who needs to work with multiple unit systems or integrate with legacy APIs.

3. Type Safety (~65 minutes)

How compile-time dimensional analysis works:

Who it is for

Developers who want to eliminate runtime errors and write self-documenting code.

4. Affine Space (~90 minutes)

The distinction between points and quantities:

Who it is for

Anyone working with temperatures, timestamps, GPS coordinates, or any absolute measurements.

Workshops

After the tutorials there are 15 workshops. Each one presents a coding challenge taken from a real-world scenario and requires you to apply concepts from the User's Guide to solve it.

How Workshops Differ from Tutorials

In a workshop:

  • Exercise-driven: follow TODO: markers to implement the solutions yourself
  • Real-world scenarios: production-like code rather than toy examples
  • Progressive complexity: start with refactoring, advance to custom systems
  • Self-directed learning: review the User's Guide to find the solutions
  • Practical patterns: techniques you will use in actual projects

Workshop Progression

Foundation Workshops

Build essential skills through refactoring and practical patterns:

Who it is for

Integrating mp-units into existing codebases and working with legacy systems.

Extensions Workshops

Create domain-specific systems of quantities and units:

Who it is for

Building specialized systems for your domain: aviation, robotics, finance, data engineering, etc.

Advanced Workshops

More advanced patterns:

Who it is for

Advanced users working on complex systems requiring maximum type safety.

Community and Feedback

We would love to hear from you:

  • Questions? Join discussions in our GitHub Discussions
  • Found an issue? Report it on GitHub Issues
  • Success story? Share it on social media with #mpunits or #cplusplus
  • Suggestions? We are always looking to improve the learning resources

Help Us Improve

As you work through tutorials and workshops:

  • Let us know if something is unclear
  • Suggest additional exercises or topics
  • Share patterns you discover
  • Report broken Compiler Explorer examples

Try It Today

Open any tutorial or workshop and you will find interactive code editors embedded in the documentation. Start typing, and the code compiles automatically.

Start Learning →

Special thanks to Matt Godbolt and the rest of the Compiler Explorer team for making interactive learning possible.

Comments