mp-units/latest/blog/2026/06/29/why-a-quantity-has-a-character/

[giscus[bot]]

mp-units/latest/blog/2026/06/29/why-a-quantity-has-a-character/

The quantities and units library for C++

https://mpusz.github.io/mp-units/latest/blog/2026/06/29/why-a-quantity-has-a-character/

[chiphogg]

Sorry I couldn't finish getting my feedback in before you posted! I'll leave it as comments now. I'm assuming each comment gets its own thread, so I'll post them separately.

[mpusz]

No need to apologize at all. Thank you for taking the time, even after the post went out. The article is materially better for it, and I have revised it (there is now a dated revision note under the intro) to fold everything below in. Splitting comments into separate threads was perfect. It let me act on each point independently.

[chiphogg]

The force/mass example in the beginning came across as alienating, because you're stating as absolute fact something that actually depends on the system in use. In particular, the "pound" is a unit of force in common US engineering practice. It's why PSI is a measure of pressure, and foot-pounds is a measure of torque (just like newton-meters). I'm not sure it helps your case to lead with an example that will distract a significant portion of your audience. (Although as for myself, I did enjoy the slight rabbit hole of research it motivated for me!)

[mpusz]

Isn't it "pound-force" (lbf) and some people just simplify its name to "pound"? Naming is hard 😜 I will do more research and possibly revise the article. Thanks!

[chiphogg]

Again: depends on the system. There are systems where "pounds" are force only, systems where "pounds" are mass only, and systems where the full names are "pounds force" and "pounds mass"! 😅

IMO, the name "pounds" by itself is so error prone that it's unwise to provide it. Au has only pounds_force and pounds_mass. Admittedly, when I made this call, I was much like your anonymous engineer from Croydon: I thought pounds was "really" only a force, and provided the mass version just to head off confusion! I certainly learned something from this article.

[mpusz]

You were right, and this fixed the opening. I no longer state the pound as a fact. The section "The problem is not the dimension" now presents it as genuinely system-dependent: in the gravitational foot-pound-force units common in US engineering, the pound routinely names a force (lbf), which is exactly why psi is a pressure and foot-pounds a torque, while the international (avoirdupois) pound anchored to SI is a unit of mass. I turned that ambiguity into the motivation for explicit quantity typing rather than a "someone was wrong" aside. And for what it's worth, mp-units already draws the line you draw in Au: pound/lb is the (mass) international pound with pound_mass as an explicit alias, while pound_force/lbf and poundal are separate force units — so the bare name defaults to the definitionally-correct meaning without hiding the distinction. Thank you, this made the intro both more accurate and more persuasive.

[chiphogg]

Now, for scope. I see the value in limiting scope and excluding bivectors, pseudoscalars, and the rest, but I think there's a real downside too: it creates barriers for geometric algebra users to adopt the library. "No ISQ quantity needs the distinction": sure, because the ISQ throws away information about grade in projecting it down to order. Geometric algebra users, whose existing programs are written to restore that lost information, will have a hard time adopting mp-units.

To see the problem, note that the grade-to-order mapping strongly depends on the spatial dimension. Consider bivector quantities such as angular velocity, angular momentum, and torque: what "order" are they?

• In 2D, they have one component, so we can treat them as pseudoscalars (thus becoming "scalars" in our hierarchy).
• In 3D, they become pseudovectors (which we would treat as "vectors")
• In 4D, with 6 independent components, they must be treated as tensors.

In fact, the "tensor" formulation is the most general, because it works in all spatial dimensions. It's also a very practical formulation, because the antisymmetric matrix representation of angular velocity is a bread-and-butter choice in robotics and rigid body dynamics. But the ISO has locked in the choice of "vector" character, which is only correct in 3D! It's true that the rank-ordered behavior that the blog post describes for the order (i.e., a lower order fills a higher) means that the 2D case would work too, because the scalar representation is automatically valid for vector character. However, that same policy has a worse consequence: it means the tensor representation --- the most generally correct one, and the standard choice in rigid body dynamics --- is the only one we can't use.

This is a direct consequence of two decisions: baking "character" into the library, and the (again, reasonable) choice to limit scope to the ISO's named characters. I think limiting scope is a good thing, generally: but when combined with the character feature, it actually prevents some users from migrating to the library. This scope limitation without character wouldn't have that effect.

Granted, users can always define their own quantities for angular momentum, etc., and give them tensor character. But they'd have to do that for every bivector quantity they touch, and each one drops out of the built-in ISQ hierarchy, losing interoperability with anyone using the standard quantity specs. It also forces them to redefine derived-quantity relationships that are built in to the library using those specs, such as $L = I \omega$. So, for geometric algebra users to "migrate" to mp-units, they would need to redefine a parallel version of the library machinery for a huge chunk of the ISQ.

[mpusz]

This was the sharpest scope point, and it reshaped several parts of the article. With it, I was able to make the piece honest about the cost instead of hand-waving it:

• "Two axes, not four values" now states that the grade-to-order mapping is dimension-dependent, that the ISQ fixes the 3D "vector" view of angular velocity, and that the general antisymmetric-tensor form (order 2) is therefore the one representation the vector slot cannot take. It credits this as a real barrier for rigid-body dynamics and robotics.
• "Trap 7: relax the vector slot to accept the tensor" records why the tempting fix fails: you cannot relax the slot for the bivector quantities alone without first teaching the library which quantities are bivectors, which is exactly the grade modeling we chose to leave out. Since character is part of a quantity's identity, the tensor form is a different quantity, related to the vector by an explicit dual (the hat and vee maps), not the same quantity in a larger storage space. The principle I landed on: do not widen a quantity to swallow a representation of a different grade.
• "Open questions" now poses the remaining design question directly: whether the library should ship a ready-made dual between an axial vector and its antisymmetric tensor without introducing geometric-algebra grades.
• The practical path for your audience is a new how-to guide, "Represent an axial vector as an antisymmetric tensor", which defines the tensor quantity and bridges it with the explicit hat/vee dual.

Thank you, this is exactly the load-bearing feedback the piece needed. I also bound the claim to 2D/3D as a result.

[chiphogg]

I do have a correctness concern about the character traits. Your numeric_field and tensor_order traits have sensible defaults, and the overrides for cases where they give the wrong answer (e.g., Eigen) are very simple. But doesn't this create ODR violation risk? numeric_field<Eigen::Vector3d> will have one definition in files that include the mp-units header, and another definition in any files that happen to forget it. And it's not only numeric_field: tensor_order has the same shape of problem, since the default implementation sees an Eigen column vector (an Nx1 matrix) as order 2, while the adapter says it's order 1. The pattern I know to prevent this kind of risk is one I learned from fmtlib: make the default definition not compile or produce a hard error for any types where we don't confidently know the answer. Au is following this approach in these kinds of cases. ODR violation is IFNDR, so this seems worth nailing down.

Thinking more about it: for numeric_field, it's not so much that we "don't confidently know" the answer; it's more that we confidently produce the wrong answer (misreading the real/imag presence on an Eigen vector to say that it is complex). Maybe there's a simple fix? Detecting the field type could depend on the detected order. If we detect vector or tensor order, then the presence of real()/imag() is no longer reliable as in the scalar case, and we should really be looking at the scalar type to determine the field. I don't think we're over-indexing on Eigen here: using the scalar type for a vector or tensor rep seems like the generically correct solution, and the existing value_type_t machinery already extracts that scalar type. Eigen exposes value_type, so it doesn't need another adapter here. (As a nice side effect, the result for the field stays stable even if the detected order disagrees, so we could probably get rid of the Eigen numeric_field override.) The one hole I see would be a scalar type that intends to represent a real field, but gratuitously has real()/imag() members so that it can satisfy generic callsites and act as a "degenerate complex" number. That seems like a small enough hole.

The order axis is a harder case. For libraries that model a vector as an Nx1 matrix, like Eigen, a vector and a matrix look the same, structurally --- same index operators, same scalar type return value. The only difference is their compile-time extents. So if we stick to the current purely structural probe (based on indexing), it seems to me that we can't detect the order without ODR violation risk. That means we'd need to detect extents, which really just relocates the ODR risk. I think that risk is likely manageable, but I did want to call it out. Oh, and I also wonder whether Eigen's convention that "an Nx1 or 1xN matrix is a vector" is universal, or whether other vector/matrix libraries might be more rigorous in separating the two categories. Overall, I won't say order detection is impossible, but it seems very hard. All I'll do here is clearly state the problem, and leave the solution to your creativity.

But in any case, yeah: it seems pretty important to eliminate opportunities for ODR violation, or at least minimize them in the most common practical cases.

[mpusz]

Thanks for raising this! I allowed myself to improve the initial design.

• Field axis: your instinct, read the field off the scalar element rather than the container, is what shipped. It removed the Eigen and Blaze numeric_field overrides entirely, because a real matrix's element is a plain double and classifies as real with no adapter. One correction to the recipe made it into the new "Trap 6": a naive recursive value_type chain walks straight through std::complex (whose own value_type is double), so a complex vector would come out real. The detection therefore reaches one element and tests real()/imag() on that, which stays correct and adapter-independent, closing the field-axis ODR hole you flagged. The trap credits your review by name.
• Order axis: you were right that it is harder, so I took the hard-error route. tensor_order's primary template is now left undefined for an ambiguous type (one that exposes both t[i] and t(i,j), the N×1 shape), so it has no default and must be specialized. Forgetting the adapter is now a clean compile error, SFINAE-friendly on both axes, rather than a silent divergent definition, so the hazard is gone rather than merely relocated. And to your question about whether the N×1 convention is universal: I checked, and Blaze keeps vectors (v[i] only) and matrices (m(i,j) only) structurally distinct, so it needs no order override at all. The hazard is Eigen-specific.

The customization-point section and "Trap 6" now describe this, and the reference docs match the shipped code. Thanks again 🙏.

[chiphogg]

Reading about your sequence of "traps" was really interesting and enlightening! I'm sure I won't be the only reader who really enjoyed getting a sneak peek into the evolution of this feature.

[mpusz]

Thank you, that section was the most fun to write. Your review actually added two more entries to it, Trap 6 (the field-detection dead end) and Trap 7 (the order-band dead end) 😉

[chiphogg]

Overall, I've changed my thinking on this. That's not to say I now think character is required. I don't, and I don't have any motivation to ever add it to Au (unlike some type of "quantity kind" support, which I would like to add to Au someday). Rather, I now understand that there are different basins in design space, and we've pursued separate ones.

Au fundamentally lives in the dimensional analysis only basin (again, with possible future extensions for basic "quantity kind" concepts). You've shown all kinds of mistakes that this basin can't catch. That's the downside. The upside is simplicity and generality. Dimensional analysis always applies. Moreover, it gives the most bang for the buck: we've already seen (CppCon 2023 Au talk) that in terms of actual mistakes people make across all domains, especially when weighted by cost, it is overwhelmingly "right dimension, wrong units". (Even though "wrong dimension" would be "worse", it's hard to find practical examples of it).

Again, that's the generic story, aggregated across all domains. Individual domains may be different. The power engineering example is a case in point. Admittedly, I do have some (very preliminary) ideas for how we would handle this with dimensional analysis only, but let's grant for argument's sake that this will turn out to be infeasible.

That's where a full quantities library --- characters and all --- will really shine. It seems to me that mp-units does an excellent job of meeting the power engineering domain's needs today, whereas dimension-only libraries like Au leave out really consequential use cases. That's the benefit.

The cost of this is all of the extra domain knowledge that we need to build in to the library. It's building all the extra machinery for how characters and quantities interact to produce other kinds of quantities. For example: although the blog post didn't explicitly say this, quantity kinds and characters mean you need to build explicit physics equations into the library, so that we can know the specific quantity type of the result. (Yes, Au wants some "quantity kind" implementation, but I'm hoping I can come up with a dumber one that gives the most bang for the buck; time will tell.) The "full quantity" approach does add real value, and we do users a service by including the most common cases, but the effect on the library's implementation scope is tremendous. And, as we've seen with the bivector case, it also raises strong barriers to real and valid existing use cases.

Whereas, dimensions and magnitudes are generic, they are always applicable, and they catch the most important errors.

So that's why I end up appreciating all of the work you're doing here, while not at all being tempted to follow in your footsteps. I see C++ units libraries as an ecosystem, each one acting as a laboratory for trying out ideas in practice. All the work you've done, deep-diving into the minutiae of ISO and ISQ quantity concepts, inventing creative and ergonomic new C++ interfaces that take advantage of all the latest modern standards, is a truly mind-boggling amount of work. (I know, because I've been privileged to have a front row seat over the past several years!) All of this work is what it takes for someone to explore the "full quantity definition" design space basin. Somebody had to do it, and I can tell you right now that it was never going to be me! 😅 From the carefully designed and implemented character ideas in this blog post, to the upcoming "absolute quantity" interfaces, to so much more, I can't wait to see how it all plays out in practice. I hope my comments here can help make your offering in this design basin, and the ecosystem overall, as strong as possible (especially for really scary error cases like the ODR violation).

[mpusz]

This is a generous and clarifying way to frame it, and I completely agree with the "different basins" picture. Even though you chose a different basin for Au, your comments made this article and the design materially better, the pound intro, the ODR fix on both axes, the honest bivector section, and two new traps. Thank you for the front-row-seat years and for challenging me and the design from time to time on things that don't look right at first sight. The offering in this basin is stronger for it. 🙏

[chiphogg]

I'm really excited to see all these improvements, to the library and to the article! 😃 I'm glad my review was helpful.

You're really putting your strongest foot forward here, and it'll be fascinating to see what we learn from real users over the next few years.