Au: A C++14-compatible units library, by Aurora

Au (pronounced "ay yoo") is a C++ units library, by Aurora. What the <chrono> library did for time variables, Au does for all physical quantities (lengths, speeds, voltages, and so on). Namely:

• Catch unit errors at compile time, with no runtime penalty.
• Make unit conversions effortless to get right.
• Accelerate and improve your general developer experience.

In short: if your C++ programs handle physical quantities, Au will make you faster and more effective at your job. You'll find everything you need in our full documentation website.

Try it out on Compiler Explorer ("godbolt")!

Example

Imagine we need a utility function to convert (linear) road speed to revolutions per minute (RPM). Here's what we'd expect to see in raw C++:

// Speed must be m/s.  Radius must be meters.  Returns RPM.
float wheel_rpm(float v_mps, float r_m) {
    return v_mps / (2.0f * static_cast<float>(M_PI) * r_m) * 60.0f;
}

It's a mess of magic numbers, and it's ripe for multiply-vs-divide errors. The interface types are simple, but that's a two-edged sword: it means they'll let all kinds of inputs through, and the burden for checking is on the distant caller.

Now let's see how Au can add safety and simplify the code. (The includes, the using declarations that bring QuantityF and friends into scope, and a couple of unit aliases are all omitted here for brevity. The link at the end of this section gives the complete, compiling file.)

// The types state the units.  Nothing to remember; nothing to convert.
QuantityF<Rpm> wheel_rpm(QuantityF<MetersPerSecond> v, QuantityF<Meters> r) {
    return v * rad / r;
}

So: what changed?

• Both the inputs and outputs are robustly safe: callers can only pass a speed for the first argument, and a distance for the second.
• They're also more flexible: if you use different units --- say, if you pass (miles / hour)(55.0f), Au will automatically generate the correct conversion factor and apply it!
• Magic numbers are gone, and the new implementation, v * rad / r, simply tells the truth directly: rotational speed is proportional to linear speed, and the ratio rad / r --- "one radian per radius" --- is the conversion factor.
• There is no runtime performance penalty: all the dimensional checking and conversion factor generation happens at compile time.

See the full discussion page for this example, and many other examples.

Why Au?

There are many other C++ units libraries, several quite well established. Each of them offers some of the following properties, but only Au offers all of them:

• Wide compatibility with C++ versions (anything C++14 or newer).
• Easy installation in any project (including a customizable single-header option).
• Small compile time burden.
• Concise, readable typenames in compiler errors.

We also provide several totally new features, including fully unit-safe APIs, an adaptive "safety surface" that protects conversions against overflow, unit-aware rounding and inverse functions, and many more.

Forged in the crucible of Aurora's diverse, demanding use cases, Au has a proven track record of usability and reliability. This includes embedded and GPU support: Aurora's embedded teams have been first class customers since the library's inception, and Au now also works out of the box with CUDA.

To learn more about our place in the C++ units library ecosystem, see our detailed library comparison.

Getting started

Our installation instructions can have you up and running in minutes, in any project that supports C++14 or newer.

To use the library effectively, we recommend working through the tutorials, starting with Au 101: Quantity Makers. To get set up with the tutorials --- or, to contribute to the library --- check out our development guide.

As seen at CppCon 2021

At CppCon 2021, we presented the properties we found to be most important in units libraries, and advice on using them effectively. Because Au was designed from the ground up with these best practices in mind, it thoroughly exemplifies them. Check out the video below, and follow along with the slide deck if you like.

NOTE: This open-source version has been significantly improved from what was presented in the talk: both in its user interfaces, and under the hood! The one downside is that matrix and vector support hasn't yet been implemented. See #70 for more details, and subscribe to that issue to watch for progress.

...and, at CppCon 2023

After CppCon 2021, we found that telling people what to look for in a units library wasn't good enough, if they couldn't find one that met those criteria. We saw so many people struggling with problems that we had already solved robustly! So, we set about sharing our work. With a clean slate, we made a new library that was a drop-in replacement for Aurora's internal library, but with zero Aurora-internal dependencies, so that we could easily open source it. The result was Au, and we shared it at CppCon 2023. Check out the video below, and follow along with the slide deck if you like.