QuanityKind and Altitudes

[jasonbeach]

I've just started really looking through the documentation on mp-units and really got my curiosity piqued when I read about quantity point kinds and altitudes, since tracking the datum of an altitude tends to be a challenge. The glide computer example illustrates this well--the datum is hard-coded assumed to be MSL, but not all altitudes are MSL. Is there a way to track and ideally automatically convert between different datums? Common datums in UAV autonomy (my use-case) are MSL (Mean Sea Level), HAE (Height above WGS84 Ellipsoid), HAL (height above launch), AGL (above ground level or height above terrain). Inadvertently mixing altitudes with different datums is a fruitful source of bugs. One challenge to converting between them is the offsets to convert between them are not fixed (can't be done at compile time) and in some cases it changes depending on your geographic location (Geoid undulation which is offset between HAE and MSL varies depending on your location.) I guess at a minimum it would be at least be nice to be able to have a compile time error if you mix altitudes with two different datums. Is that possible?

I believe @chiphogg was looking at a more general case of this in tracking coordinate frames that say a vector is referenced to. I'm curious what the state of that is.

[mpusz]

One challenge to converting between them is the offsets to convert between them are not fixed (can't be done at compile time)

mp-units library is designed to have no overhead, and that is why it requires all the conversion information at compile time. Runtime conversions (i.e. for exchanging currencies) are not supported by it. But it is not impossible. You can define two unrelated families of types (i.e. for different origins) and provide custom conversion functions that would do the work at runtime.

I guess at a minimum it would be at least be nice to be able to have a compile time error if you mix altitudes with two different datums. Is that possible?

Sure! This should be the default ;-)

Please see slide 106 from my recent presentation on the V2 framework: https://github.com/train-it-eu/conf-slides/blob/master/2023.04%20-%20ACCU%202023/mp-units%20-%20Lessons%20learned%20and%20a%20new%20library%20design.pdf. I hope that it will answer your remaining questions. If not, I would be happy to answer them here 😃

[jasonbeach]

That's very interesting. The case shown works for compile time because the 432m reference of ZRH_ground_level is fixed. This is not always the case. A common altitude for UAVs is HAL or Height above launch. The reference is an msl altitude (just like ZRH_afe is referenced to ZRH_ground_level), it just gets set whenever the UAV takes off on a flight and so isn't known at compile time.

The conversion between HAE (height above wgs84 ellipsoid) and MSL is similar, except that instead of the reference being the ground MSL altitude at takeoff, it's computed from a geoid model such as the egm-96 or egm-2008 geoid (GeographicLib makes this very easy...you give it the latitude, longitude and a flag that indicates whether you're going from MSL to HAE or HAE to MSL and it give's you back the offset between the two, called Geoid Undulation). You then just add or subtract that offset from your altitude to convert it. It's a process begging for a units library 😃.

I haven't worked my way through the whole slide deck--is V2 out or still a work in progress?

[JohelEGP]

is V2 out or still a work in progress?

See #454 (comment).

[mpusz]

@jasonbeach, as I mentioned, the library framework can do only as much. The conversions have to be known at compile time. However, as I stated, you can easily add runtime conversion functions to your projects. For example you can do it this way:

#include <mp_units/iostream.h>
#include <mp_units/quantity_point.h>
#include <mp_units/systems/international/international.h>
#include <mp_units/systems/isq/space_and_time.h>
#include <mp_units/systems/si/unit_symbols.h>
#include <iostream>

using namespace mp_units;

// clang-format off
inline constexpr struct mean_sea_level : absolute_point_origin<isq::altitude> {} mean_sea_level;
inline constexpr struct height_above_launch : absolute_point_origin<isq::altitude> {} height_above_launch;
// clang-format on

using msl_altitude = quantity_point<isq::altitude[si::metre], mean_sea_level>;
using hal_altitude = quantity_point<isq::altitude[si::metre], height_above_launch>;

static_assert(!std::equality_comparable_with<msl_altitude, hal_altitude>);

class unmanned_aerial_vehicle {
  msl_altitude current_ = 0 * si::metre;
  msl_altitude launch_ = current_;
public:
  void take_off(msl_altitude alt) { launch_ = alt; }
  msl_altitude take_off() const { return launch_; }

  void current(msl_altitude alt) { current_ = alt; }
  msl_altitude current() const { return current_; }

  hal_altitude hal() const { return current_ - launch_; }
};


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

  unmanned_aerial_vehicle uav;
  uav.take_off(6'000 * ft);
  uav.current(10'000 * ft);
  std::cout << "hal = " << uav.hal().relative() << "\n";

  msl_altitude ground_level = 123 * m;
  std::cout << "agl = " << uav.current() - ground_level << "\n";
}

and the output is:

hal = 1219.2 m
agl = 2925 m

Please let me know if the above addresses your use case.

[mpusz]

The above code compiles fine with gcc-12 on the V2 branch, so you can try it out.

BTW, it would be great to have an example application with your use case. Maybe you could prototype a simple POC for your needs and add it to the examples directory? Of course, I can help you if you need any assistance.

[mpusz]

Initial version added here: https://github.com/mpusz/units/blob/v2_framework/example/unmanned_aerial_vehicle.cpp

[jasonbeach]

That's a pretty good example. The relative/absolute semantics work well for HAL / MSL, but not so much for converting between MSL and HAE (height above ellipsoid) as they are both absolute altitudes, however writing a function to do that I think is perfectly acceptable. So overall I like this solution. Much better than my current solution which is to truck around the datum as an enum value (I have an altitude struct that has both the value and the datum and I've set it so it's impossible to set one without setting the other.)

[mpusz]

Great! Please feel welcome to extend this example in the repo if possible.

[chiphogg]

I believe @chiphogg was looking at a more general case of this in tracking coordinate frames that say a vector is referenced to. I'm curious what the state of that is.

Well, the short answer is that the state of it is "not done and not currently in progress". 😅 However, I do have some pretty clear ideas on the subject.

The first question is to do with how we handle conversions which might change at runtime. The usual conversions in a units library are immutable, and we get spoiled with these: we can assign a temperature in Fahrenheit to a variable in Celsius, say, and the compiler takes care of giving the correct result! Naturally, we might expect the same interfaces for runtime-adjustable conversions (say, dollars to euros). If we don't notice that this is an assumption, and question it, we end up with singletons and variable global state --- in short, madness.

A better solution is to have transformation objects which are templated on two frames/units/whatever. This forces you to pass them around as variables, which keeps everything clear and local. If you have a Quantity<Euros> and you want a Quantity<Dollars>, then you naturally need an ExchangeRate<Euros, Dollars>.

(Not that I'm suggesting units libraries should include currency in their scope --- perish the thought!)

So that's the strategy, IMO: make objects that know at compile time which frames they're dealing with, but use values known at run time to do the computation.

(I wrote this before reading @mpusz's response above, but I see it's entirely consistent with this strategy. A templated type would be for generic conversions, whereas the unmanned_aerial_vehicle class gives an example for specific concrete frames.)

[JohelEGP]

It's also hard to correctly, safely, and efficiently perform historical calculations, as the rates change over time.
Assuming there's an interface to change the rates at all.

[jasonbeach]

Or just use a function 😉

Well, but this example brings us back to global state, right?

That state (implemented via a static map inside the function) can't currently be edited, but even if it could, we're back to global variables and architectures that are hard to unit test.

Not necessarily...we could define a function as:

height_above_ellipsoid to_hae(mean_sea_level alt, radians lat, radians lon){
 const auto geoid_undulation = GeographicLibWhatsMyOffeset(lat, lon) * si::metres // do some lookup to GeographicLib that uses lat / lon to lookup
height_above_ellipsoid hae = alt +geoid_undulation //not sure if this is what it would look like
return hae;
}

where the lat and lon are provided at runtime. (I had been running g++7.5, but now have g++13 up and working so I can now actually play around with this.) The transformation object that @chiphogg mentions is pretty solid in that it captures the relationship at compile time even though the specific conversion value may not be known until runtime (and potentially even gives you the ability to keep a time history of values so that if a late conversion comes through it can use the correct conversion value.) I like it...just gotta figure out the best way to do it.

[mpusz]

That state (implemented via a static map inside the function) can't currently be edited, but even if it could, we're back to global variables and architectures that are hard to unit test.

This is, of course, a simplification. No matter if you are dealing with a transformation object or a function, you either need a state (either centralized or distributed) somewhere with the current exchange rate, or you have to do a network query every time to obtain the current rate from the exchange. As it is totally orthogonal property to quantities and units handling, it is not the task of this example to properly implement this.

[mpusz]

t's also hard to correctly, safely, and efficiently perform historical calculations, as the rates change over time.
Assuming there's an interface to change the rates at all.

It is just a matter of the interface and the database you choose to maintain.

[JohelEGP]

You're right. There's space to introduce the transformation object in the signature of

template<ReferenceOf<currency> auto To, ReferenceOf<currency> auto From, typename Rep>
quantity<To, Rep> exchange_to(quantity<From, Rep> q)