New library design

[mpusz]

Hi,

As you know, I have been working on a new library design for a while. It took me longer than I initially thought, as it started with #281 but ended up with a much deeper rework. It still is not done, and I am far from determining the final design.

Here are some rough ideas as the source for discussion: https://godbolt.org/z/ddPWhcKW3. quantity will, of course, get Rep as the second argument in the final design.

Everyone, your feedback at this stage is greatly appreciated! 😃 Please answer in the threads below or create a new one for a discussion on a new idea.

This will break our user's code in many places, so it is a really serious change. Before we merge the changes to mainline, I want to make sure the change is for the better and not for the worse. Please upvote whatever you like here or provide feedback on why it is not the case. Maybe we can improve that...

[mpusz]

quantity gets reference by value because it will be possible to specify things like:

quantity<metre / second> speed(123);

and this will result with a type like: units::quantity<derived_reference<mp-units::isq::si::metre, per<mp-units::isq::si::second>>{}>.

[mpusz]

Dimensions will be used by values as well:

struct dim_length : base_dimension<"L"> {};
struct dim_time : base_dimension<"T"> {};

struct dim_frequency : decltype(1 / dim_time{}) {};
struct dim_area : decltype(dim_length{} * dim_length{}) {};
struct dim_volume : decltype(dim_area{} * dim_length{}) {};
struct dim_speed : decltype(dim_length{} / dim_time{}) {};
struct dim_acceleration : decltype(dim_speed{} / dim_time{}) {};

[mpusz]

Here is some dimensional analysis that works already in my code:

static_assert(is_of_type<1 / dim_time{}, derived_dimension<dim_one, per<dim_time>>>);
static_assert(is_of_type<1 / (1 / dim_time{}), dim_time>);

static_assert(is_of_type<dim_one{} * dim_time{}, dim_time>);
static_assert(is_of_type<dim_time{} * dim_one{}, dim_time>);
static_assert(is_of_type<dim_one{} * (1 / dim_time{}), derived_dimension<dim_one, per<dim_time>>>);
static_assert(is_of_type<1 / dim_time{} * dim_one{}, derived_dimension<dim_one, per<dim_time>>>);

static_assert(is_of_type<dim_length{} * dim_time{}, derived_dimension<dim_length, dim_time>>);
static_assert(is_of_type<dim_length{} * dim_length{}, derived_dimension<pow<dim_length, 2>>>);

static_assert(is_of_type<dim_length{} * dim_length{} * dim_time{}, derived_dimension<pow<dim_length, 2>, dim_time>>);
static_assert(is_of_type<dim_length{} * dim_time{} * dim_length{}, derived_dimension<pow<dim_length, 2>, dim_time>>);

static_assert(is_of_type<dim_length{} * (dim_time{} * dim_length{}), derived_dimension<pow<dim_length, 2>, dim_time>>);
static_assert(is_of_type<dim_time{} * (dim_length{} * dim_length{}), derived_dimension<pow<dim_length, 2>, dim_time>>);

static_assert(is_of_type<1 / dim_time{} * dim_length{}, derived_dimension<dim_length, per<dim_time>>>);
static_assert(is_of_type<1 / dim_time{} * dim_time{}, dim_one>);

static_assert(is_of_type<dim_time{} / dim_one{}, dim_time>);
static_assert(is_of_type<1 / dim_time{} / dim_one{}, derived_dimension<dim_one, per<dim_time>>>);

static_assert(is_of_type<dim_length{} / dim_time{} * dim_time{}, dim_length>);
static_assert(is_of_type<1 / dim_time{} * (1 / dim_time{}), derived_dimension<dim_one, per<pow<dim_time, 2>>>>);
static_assert(is_of_type<1 / (dim_time{} * dim_time{}), derived_dimension<dim_one, per<pow<dim_time, 2>>>>);
static_assert(is_of_type<1 / (1 / (dim_time{} * dim_time{})), derived_dimension<pow<dim_time, 2>>>);

static_assert(is_of_type<dim_length{} / dim_time{} * (1 / dim_time{}), derived_dimension<dim_length, per<pow<dim_time, 2>>>>);
static_assert(is_of_type<dim_length{} / dim_time{} * (dim_length{} / dim_time{}), derived_dimension<pow<dim_length, 2>, per<pow<dim_time, 2>>>>);
static_assert(is_of_type<dim_length{} / dim_time{} * (dim_time{} / dim_length{}), dim_one>);

[mpusz]

Derived units and then derived references will be created in a similar way.

[mpusz]

Note that the quantity does get a dimension for now. It has good and bad sides.

Good:

• the type is shorter
• no repetition as the dimension can be derived from the reference (but as a derived type and not strongly and nicely named by the user like speed)

Bad:

• quantity::reference::type for derived quantities will return a derived dimension rather than nicely named like speed (but both will work quantity::reference::type{} == dim_speed{}, quantity_of<T, dim_speed>)
• No way to verify if the user provided the correct units for a quantity. For example, if the user does quantity<metre / second> but he/she meant to get the acceleration, it will not be validated. However, the following code will fail to compile:

quantity_of<dim_acceleration> auto acceleration = 123 * (metre / second);

• No way to create an alias as we had before for a quantity of a specific dimension (we will always have to type quantity<...> rather than length<...>):

template<UnitOf<dim_length> U, Representation Rep = double>
using length = quantity<dim_length, U, Rep>;  // not possible now as there is no first parameter

---

Should we provide more safety and more readable types like quantity<dim_speed, metre / second> on the cost of repetition?

[mpusz]

How about something like this?

Right, there are ways to hack it. Probably even nicer would be something like:

template<auto R>
  requires (typename R::dimension{} == isq::dim_time)
using time = quantity<R>;

However, the question here is, do we need such an alias at all?

[JohelEGP]

However, the question here is, do we need such an alias at all?

Doesn't the same apply today?

template<UnitOf<dim_length> U, Representation Rep = double>
using length = quantity<dim_length, U, Rep>;

That does the same. Which is to check that the unit is of the expected dimension.

[mpusz]

Right, but this alias originated to not be forced to type quantity<dim_length, ... all the time if we can just type length. Now as we do not provide the dimension as the first parameter maybe there is no need for such an alias. quantity checks the unit anyway:

template<Dimension D, UnitOf<D> U, Representation Rep = double>
class quantity;

[mpusz]

Anyway, I spent the entire day on this problem, and I think this starts to be my favorite solution:

Frequency auto freq1 = 20 * frequency[Hz];
Frequency auto freq2 = 20 / time[s];
quantity<frequency[Hz]> freq3(20);
quantity<frequency[1 / s]> freq4(20);
quantity<1 / time[s]> freq5(20);

Speed auto speed1 = 20 * speed[m / s];
Speed auto speed2 = 20 * (length[m] / time[s]);
quantity<speed[m / s]> speed3(20);
quantity<length[m] / time[s]> speed4(20);

[JohelEGP]

It's certainly redundant when the reference carries the dimension.

Should we provide more safety and more readable types like quantity<dim_speed, metre / second> on the cost of repetition?

In the current proposed design, that could look like:

auto dur3 = quantity<isq::dim_time[units::hour]>{};
print<decltype(dur3)>();

See https://godbolt.org/z/o9cGv1nPh.

You could also extend dimension's operator[] to also accept references. It'd be a no-op when the reference's dimension matches the dimension, and give back a nice type like dur2's: quantity<isq::dim_time[hour]>. Then quantity<dim_speed[metre / second]> could be a compile-time error.

[mpusz]

How do you feel about:

inline constexpr second second;

?

We could do the same to dimensions to not have to type dim_length{} all the time.

[mpusz]

The problem is the following:

1. Variables are really needed for a new design. We can ask users to put {} after every dimension unit, and reference types but it would be really nasty and a lot of boilerplate.
2. Short names have to be opt-in as they collide with a lot of code (especially on MSVC).

[JohelEGP]

As pointed out by #389 (reply in thread), I think it'd be OK suffix _t to the types.

[mpusz]

It will be visible in the compilation errors, which is inconvenient :-(

Instead of:

quantity<reference<derived_dimension<length_dim, per<time_dim>>, derived_unit<metre, per<second>>>

we will have something like:

quantity<reference<derived_dimension<length_dim_t, per<time_dim_t>>, derived_unit<metre_t, per<second_t>>>

Personally, I like the first output more.

Note that definition like:

inline constexpr second second;

besides, being really unconventional, is allowed by the language and will not impact our users at all. A user is about to always work with values in the code and observe types in the compilation errors. Using the same nicely blends those two domains together.

[mpusz]

I could use a list of values instead of types as template parameters in the dervied_dimension and derived_unit but in such case the error would look like:

quantity<reference<derived_dimension<length_dim{}, per<time_dim{}>{}>{}, derived_unit<metre{}, per<second{}>{}>{}>>

which also is not that nice.

[JohelEGP]

That's convincing. This justification should definitely be part of the documentation.

[mpusz]

I am aware that the quantity could be specified as:

template<Reference auto& R>
struct quantity;

which would allow me to work on values and allow things like:

inline constexpr auto dim_speed = dim_length / dim_time;

rather than:

struct dim_speed : decltype(dim_length{} / dim_time{}) {};
inline constexpr dim_speed dim_speed;

but on the other hand, it is much harder to construct expression templates that are easy to understand with such an approach. @JohelEGP, I think you are working on something like that, right?

[JohelEGP]

@JohelEGP, I think you are working on something like that, right?

You're right.

[mpusz]

What do you think about the usage of the indexing operator usage to specify a unit?

[mpusz]

Unlike it is done in other libraries, the design still (the same as it is done currently) does not get a dimension for a unit type. I want to keep unit definitions separate (i.e. all ratios of time units) from binding them to specific dimensions. That way, I will not have to define that a minute is 60 seconds again if I decide to use seconds as well as the unit for length in some natural units system. There are some cases where different dimensions share the same unit and it should be easy to do the binding without the need to redefine all the units.

However, this again creates name conflicts. For example, in the code provided, we have a second as the name for a unit and for the reference in the SI system. It doesn't look nice. How we can improve that? In which namespace units should be defined (i.e. mp-units::units)? How to name a unit and reference instance to always know what we are dealing with? Maybe units should have some prefixes like dimensions have dim_....?

[mpusz]

Anyway, as I stated already, with the introduction of system_reference that creates an object that has the name of the dimension rather than unit the name conflict is resolved which was the main concern in this topic.

[mpusz]

Aren't the dimensions of length and position vector the same?

As I stated already, we can argue that those are different kinds of the same quantity. However, ISO defines them separately and assigns a different dimension symbol to each of them. Also, there are other quantities that probably should not just be kinds mostly because they result in the same dimension only because of "angular-ignorance" (i.e. "frequency" and "angular frequency").

[JohelEGP]

I think my concerns is about naming. (Disregard my desire for the nice-to-have assume-SI-units by default.)

However, ISO defines them separately and assigns a different dimension symbol to each of them.

They have different dimension symbols. But they have the same dimension L¹. Why does the code use dim_length and dim_position_vector?

Consider frequency, activity referred to a radionuclide, and a quantity of dimension T⁻¹. Conceptually, they all have the same dimension. However, in the current design, it seems they would need separate dim_-prefixed variables.

I think a more appropriately named abstraction for the currently dim_-prefixed variables would be "quantity name". There is a one-to-one correspondence between base dimensions and the names of base quantities.

In any case, you might want to use in operators and conversions these quantities with different names but equal dimension. In that case, the more special name should be specified in terms of the base dimensions. Otherwise, the new design will be unable to resolve #205.

[mpusz]

If we have a project that uses all of frequency, activity referred to a radionuclide, and a quantity of dimension T⁻¹, is it an error if we accidentally use an incorrect quantity value in the calculation? I assume yes, and that is why I said that those should be at least modeled as different kinds of the same quantity. If someone desires to model them as separate dimension types then we should not force redefining all units for a second similar dimension. With the new design, generally, there will be much less boilerplate to define the system.

[mpusz]

If I understand you correctly I think you would prefer to have something like:

struct length : system_reference<dim_length, metre> {};
inline constexpr length length;

struct position_vector : system_reference<dim_length, metre> {};
inline constexpr position_vector position_vector;

?

That is certainly one of the valid options here, and we may also consider going in this direction. In any case, both options provide the same safety because all the dimensions and units are equivalent so that they can be compared, added, and subtracted from each other.

The only way to make them not compatible is to introduce such quantities as having different kinds.

[mpusz]

In the discussion thread above, we touched on a very important point of compatibility of equivalent dimensions and units. Now, without the downcasting facility, we will have much more intermediate temporary types than before. Consider:

auto s = 100 * length[m] / (20 * time[s]) + 5 * speed[m/s];
auto f = 10 / (1 * time[s]) + 2 * frequency[Hz];

What should be the result of the above equations? Should both of them compile as they are, or maybe we should require explicit casts/conversions to derived types to make them work? For example, something like this:

auto s = quantity_cast<speed>(100 * length[m] / (20 * time[s])) + 5 * speed[m/s];
auto f = quantity_cast<frequency>(10 / (1 * time[s])) + 2 * frequency[Hz];

[mpusz]

@chiphogg qualifies too

You are right! Fixed 😉

[mpusz]

Please, show an example.

Without the ISQ usage we end up with something like this:

namespace si {
inline constexpr struct speed : system_reference<dim_length / dim_time, metre / second> {} speed;
inline constexpr struct power : system_reference<dim_mass * dim_length * dim_length / (dim_time * dim_time), watt> {} power;
}

namespace cgs {
inline constexpr struct speed : system_reference<dim_length / dim_time, centimetre / second> {} speed;
inline constexpr struct power : system_reference<dim_mass * dim_length * dim_length / (dim_time * dim_time), erg / second> {} power;
}

The sole purpose of the ISQ is to define dimensions/quantities without specifying units. This is why the idea is to make the isq namespace store dimensional equations for each quantity type.

With the current approach, we define the equations once in the isq namespace (dim_speed) and then reuse them to define SI or CGS system quantity as:

namespace isq{

namespace si {
inline constexpr struct speed : system_reference<dim_speed, metre / second> {} speed;
inline constexpr struct power : system_reference<dim_power, watt> {} power;
}

namespace cgs {
inline constexpr struct speed : system_reference<dim_speed, centimetre / second> {} speed;
inline constexpr struct power : system_reference<dim_power, erg / second> {} power;
}

}

which has the great benefit of not repeating yourself, which may only lead to bugs.

Having such names also allows us to check easily:

QuantityOf<isq::dim_speed> auto x = get_something();

The above just verifies the dimensional equation of the quantity while:

QuantityOf<si::speed> auto x = get_something();

will check not only the dimension but also if the quantity unit is compatible with the SI unit for speed (share the common reference with second).

Also, it allows full dimensional analysis without bothering about specific units or quantities:

static_assert(dim_length / dim_time == dim_speed);
static_assert(dim_energy / dim_time == dim_power);

which I think may be a strong feature by itself for some use cases (I was approached about such a feature on CppCon a few years ago by some people).

As the below does not work:

using dim_speed = decltype(dim_length / dim_time);  // derived_dimension<dim_length, per<dim_time>>
inline constexpr dim_speed dim_speed;

using dim_power = decltype(dim_energy / dim_time);  // derived_dimension<dim_mass, pow<dim_length, 2>, per<pow<dim_time, 2>>>
inline constexpr dim_power dim_power;

we can only do this:

inline constexpr struct dim_speed : decltype(dim_length / dim_time) {} dim_speed;
inline constexpr struct dim_power : decltype(dim_energy / dim_time) {} dim_power;

unless you have some idea how to make aliases case consistent with the rest of the framework?

Please note that the dim_power will not store dim_energy in the derived_dimension dimensional equation anymore (I got rid of such support yesterday).

Also, we can rename the entity to speed_dim if you think that helps (I am not a native speaker 😉) but please let me know if you prefer to be consistent and also have length_dim for base dimensions or keep the current dim_length for those.

Otherwise, we can just define base dimensions in the ISQ and then introduce class templates for system references like so:

namespace units::isq {

template<Unit U>
struct speed : system_reference<dim_length / dim_time, U> {};

template<Unit U>
struct power : system_reference<dim_mass * dim_length * dim_length / (dim_time * dim_time), U> {};  // notice that we have to use a long form of the equation here and cannot reuse dim_energy

namespace si {

inline constexpr struct speed : isq::speed<metre / second> {} speed;
inline constexpr struct power : isq::power<watt> {} power;

}

namespace cgs {

inline constexpr struct speed : isq::speed<centimetre / second> {} speed;
inline constexpr struct power : isq::power<erg / second> {} power;

}
}

Please note that with the above approach, we lost the support for easy dimensional analysis without bothering about units or quantity types and QuantityOf support. Actually it is really similar to what we have in the current library's design and which was one of my biggest reasons to refactor it in #281. This is why I decided that the other solution worked better and implemented it at first.

Feedback is really welcomed here 😉

[mpusz]

On some longer thought, even though not consistent, aliases for derived dimensions can somehow work. If we do something like:

using dim_speed_t = decltype(dim_length / dim_time);  // derived_dimension<dim_length, per<dim_time>>
inline constexpr dim_speed_t dim_speed;

using dim_power_t = decltype(dim_energy / dim_time);  // derived_dimension<dim_mass, pow<dim_length, 2>, per<pow<dim_time, 2>>>
inline constexpr dim_power_t dim_power;

the rest of the code will just work as the user (besides the dimension definition itself) interacts only with values. The compilation errors will also not be affected, as dim_speed_t will not be visible in the resulting type anyway (it is an alias to the derived_dimension instance). So if you think aliases better model the domain, please let me know.

[JohelEGP]

Also, it allows full dimensional analysis without bothering about specific units or quantities:

That's great. Let's keep it that way.

unless you have some idea how to make aliases case consistent with the rest of the framework?

From a standardization point of view, the "rest of the framework" looks like:

  // [pair.piecewise], pair piecewise construction
  struct piecewise_construct_t {
    explicit piecewise_construct_t() = default;
  };
  inline constexpr piecewise_construct_t piecewise_construct{};

  // in-place construction
  struct in_place_t {
    explicit in_place_t() = default;
  };
  inline constexpr in_place_t in_place{};

  template<class T>
    struct in_place_type_t {
      explicit in_place_type_t() = default;
    };
  template<class T> inline constexpr in_place_type_t<T> in_place_type{};

  template<size_t I>
    struct in_place_index_t {
      explicit in_place_index_t() = default;
    };
  template<size_t I> inline constexpr in_place_index_t<I> in_place_index{};

  // [default.sentinel], default sentinel
  struct default_sentinel_t;                                                        // freestanding
  inline constexpr default_sentinel_t default_sentinel{};                           // freestanding

  // [unreachable.sentinel], unreachable sentinel
  struct unreachable_sentinel_t;                                                    // freestanding
  inline constexpr unreachable_sentinel_t unreachable_sentinel{};                   // freestanding

  struct from_range_t { explicit from_range_t() = default; };                       // freestanding
  inline constexpr from_range_t from_range{};                                       // freestanding

Also, we can rename the entity to speed_dim if you think that helps (I am not a native speaker wink) but please let me know if you prefer to be consistent and also have length_dim for base dimensions or keep the current dim_length for those.

Turning all dim_ prefixes into _dim suffixes seems like an improvement to me. An alternative would be to drop the affix and nest them inside the namespace isq::dimensions.

The compilation errors will also not be affected, as dim_speed_t will not be visible in the resulting type anyway (it is an alias to the derived_dimension instance).

We could try using type aliases for all dimensions, and see how it goes. Things like quantity_cast<dim_speed>(1 * length[m]) might still expose it.

[mpusz]

That's great. Let's keep it that way.

Great!

From a standardization point of view, the "rest of the framework" looks like:

I am not sure how to understand that

Turning all dim_ prefixes into _dim suffixes seems like an improvement to me.

Will do it today.

Things like quantity_cast<dim_speed>(1 * length[m]) might still expose it.

I am not sure, as quantity_cast in a new design will take the thing by value.

[mpusz]

Should the quantity<derived_dimension<energy, per<time>>, derived_unit<joule, per<second>>, int> be implicitly convertible and comparable to the quantity<power, watt, int>?