Bikeshedding `reference` and `Reference`

[mpusz]

For a longer time, we knew that a reference is a bad name for the entity we have in the code that encapsulates QuantitySpec and Unit. According to ISO and SI terminology, reference is "a measurement unit, a measurement procedure, or a reference material".

The name is also unfortunate because we already have std::reference in the C++ Standard Library which would be an issue in case the library gets standardized.

---

Here are simple examples of the current design:

constexpr AssociatedUnit auto my_unit = si::metre;
constexpr reference<isq::height, si::metre> my_ref = isq::height[si::metre];

A current Reference concept is satisfied by both my_unit and my_rep as both of them allow us to create a quantity when we multiply a number by them:

Quantity auto q1 = 42 * my_unit;
Quantity auto q2 = 42 * my_ref;

Operations on references:

• can be compared
• can be multiplied and divided
• we can do pow, sqrt, and cbrt on them
• we can check their convertibility
• we can get a common reference when we provide a list of them

Reference is also the first template parameter of a quantity class template:

https://github.com/mpusz/mp-units/blob/24803a96cc6a0441b10eecc12f514df613ee6f30/src/core/include/mp-units/quantity.h#L85-L86

It is probably time to look for a better name for this wrapper.

My understanding is that this thing describes all meta-information about the quantity besides its number.

[mpusz]

A related question might be "do we want to decompose Reference in the quantity template parameters?". Instead of having a Reference there, we could have two QuantitySpec and Unit. This has some side effects:

Expression	Now	Then
42 * m	quantity<si::metre(), int>	quantity<kind_of_<isq::length>(), si::metre(), int>
42 * isq::height[m]	quantity<reference<isq::height(), si::metre()>(), int>	quantity<isq::height(), si::metre(), int>

NOTE: I do not think it is possible to have two "versions" of quantity class templates taking 2 or 3 parameters depending on the type of Reference.

[mpusz]

Here are some rough ideas from me:

• descriptor
• quantity_descriptor
• recipe

I am not a native speaker so I hope that others will have better ideas :wink:

[JohelEGP]

Also consider that quantity_spec has that name because we couldn't think of anything better.

I have a suggestion, which unfortunately uses C++ terms.

The ISO/IEC 80000 series define quantities, and their coherent units. So we could say that in master, what we call

• quantity_spec is a quantity definition,
• reference is an instance of a defined quantity (adds the unit), and
• quantity represents an actual quantity value (adds the representation type).

[JohelEGP]

NOTE: I do not think it is possible to have two "versions" of quantity class templates taking 2 or 3 parameters depending on the type of Reference.

That's right. The kind of template parameter has to match in partial specializations. quantity<value, type> and quantity<value, value, type> is not possible to specify.

[JohelEGP]

Here's some more context.

The ISO/IEC 80000 series define quantities, and their coherent units. So we could say that in master, what we call

• quantity_spec is a quantity definition,
• reference is an instance of a defined quantity (adds the unit), and
• quantity represents an actual quantity value (adds the representation type).

• Quantity definition: I think quantity_spec also defines the coherent unit. It certainly has a formula from which it can infer it. This is necessary to determine the valid units it can use.

• Quantity instance: With reference, we add the actual unit to be used.

• Quantity value: quantity is an actual quantity value. What we add to reference is the number. The representation type isn't really relevant, as it could be bignum. It also has the operations to actually behave like a number.

There is a difference between these last two. The value adds the number. For example, in tables, it is common for a column to be labeled with the instance, and for the rows to only have numbers (which represent the numerical quantity value for the given instance).

[mpusz]

I think quantity_spec also defines the coherent unit.

No, it does not and should not. Systems of Quantities should not imply any units and I really want to keep the distinction between definitions of systems of quantities (current quantity_spec) and systems of units (all the units) that may be defined in the terms of system of quantities.

See:

• https://jcgm.bipm.org/vim/en/1.3.html
• https://jcgm.bipm.org/vim/en/1.13.html.

Quantity type is not about the unit but about a physical "phenomenon" and this is what current quantity_spec describes. Then various systems of units can specify a unit for that "phenomenon" (SI, CGS, natural units, etc).

[JohelEGP]

I think quantity_spec also defines the coherent unit.

No, it does not and should not.

Right. When you actually make a reference out of it, is when the library has the opportunity to make sure that the unit is valid for the quantity_spec.

[mpusz]

Yes, and that works only for AssociatedUnits. Otherwise, we need to define system_reference to specify which unit is being used to measure a specific quantity in the system:

https://github.com/mpusz/mp-units/blob/24803a96cc6a0441b10eecc12f514df613ee6f30/src/systems/natural/include/mp-units/systems/natural/natural.h#L39-L47

[mpusz]

• Quantity definition:

I would be OK with renaming quantity_spec to quantity_def or quantity_definition.

• Quantity instance: With reference, we add the actual unit to be used.

I do not think "instance" is a good word here. In C++ instance means an object/variable of a type.

• Quantity value: quantity is an actual quantity value.

Yeah, I could see that. However, I am guessing that no one here wants to type quantity_value<si::metre, int>?

[JohelEGP]

Oh, I'm not suggesting renaming that.