Naming conventions and terminology

[angularsen]

One thing I have repeatedly found tricky to name or describe, is how to refer to the concepts that Length and Force represent.

It is natural to refer to centimeters and newtons as units, or units of measure, but I always lacked a good name for their grouping/family. After some googling, it seems physical quantity is the correct term.

wiki/Units_of_measurement spells it out pretty well:

A unit of measurement is a definite magnitude of a quantity, defined and adopted by convention or by law, that is used as a standard for measurement of the same quantity.[1] Any other value of that quantity can be expressed as a simple multiple of the unit of measurement.

For example, length is a physical quantity. The metre is a unit of length that represents a definite predetermined length. When we say 10 metres (or 10 m), we actually mean 10 times the definite predetermined length called "metre".

Example :

You can convert between units of the same physical quantity.

Proposal (final, edited 2017-08-18)

• Quantities are represented by struct types like Length and Force and corresponding enum types LengthUnit and ForceUnit
• Units are represented by enum values like LengthUnit.Meter and ForceUnit.Newton
• Unit conversions are represented by instance properties, such as Length.Meters and Force.Newtons and custom conversion methods like Force.FromPressureByArea()
• Generic type parameters are named
  • TQuantity for unit struct types, such as Length
  • TUnitType for unit enum types, such as LengthUnit

Any thoughts on the matter?

I would like to go through the docs and source to ensure the wording is used consistently, as well as on future PR reviews.

Sources:
https://en.wikipedia.org/wiki/Physical_quantity
https://en.wikipedia.org/wiki/Units_of_measurement
https://en.wikipedia.org/wiki/Quantity
https://en.wikipedia.org/wiki/Metrology#Definition_of_units

[JKSnd]

Cool! I really like this idea. I took a quick look through the quantities that are currently defined to see if any wouldn't fit the "physical" descriptor. Most are, with the exception of Level, which I suppose is arguable.

I wonder if simply calling these top-level classes "quantities" would suffice?

[angularsen]

That makes sense to me, I can go with quantity.

[angularsen]

Added a bullet point for naming convention of generic type parameters.

[tongbong]

I am not fond of TQuantityEnum, I would rather use these names:

• TQuantity
• TQuantityType, IQuantityKind
• TQuantityUnit

I would keep Quantity in all names for more consistency.

[angularsen]

@tongbong Thanks for commenting.

I don't like the name TQuantityEnum either, but since C# generics don't have a way to constrain types to enums I figured this was maybe a bit more intuitive for the reader? I could go with Type though, it's also most often used for enum types.

How about this:

• TQuantity (struct type)
• TQuantityUnitType (enum type)
• TQuantityUnit (enum value)

The pairing of UnitType and Unit becomes more clear to me at least.

[phatcher]

Sorry to chip in, just found this library as I need something like this on a current project.

From metrology I believe the term is Dimension as in dimensional analysis.

In a library I wrote a while back I had three classes, Quantity, Unit and Measure - this allowed me to represent and convert between different units as long as they were representing the same underlying Measure.

Measure represented the seven base SI units {and held the integer exponents so length (m) was {1, 0, 0, 0, 0, 0, 0}, and so area (m^2) was {2, 0, 0, 0, 0, 0, 0} and speed (m/s) becomes {1, 0, 0, 0, 0, 0, 1}

Advantage of this is that each Unit is of one Measure and holds it conversion factor back to the base SI units, but you can easily see if you can convert between values, or what Units the result of a calculation are in.

[angularsen]

@phatcher You are most welcome to chip in! So, are you saying you would prefer the term dimension when referring to the concepts of Length and Mass?

Interesting take on the measure representation. Did you mean -1 for the last number in speed m/s ?

[phatcher]

@anjdreas Yes, the concept is that each of the 7 SI measures is a separate Dimension, then a Measure is some combinations of the exponents of those Dimensions - and yes I did mean -1 for the m/s.

Then Units become a Measure with a conversion factor/function - I used the conversion to the base SI units as it tends to minimise loss of precision when you round-trip and when you have more complicated Measures you also avoid compounding the error by storing a derived conversion factor rather than computing one from the individual units e.g. m/s to furlongs/fortnight has its own calculated conversion value.

I like your strong types, but I was having to store this in a database and also cope with arbitrary new units that might be created by users, which is why I have the more generic Units/Measure/Dimension - the original problem domain was commodity trading so we were trying to get to a single source of truth for handling trade units e.g. "barrels" which depending on the trade feed were US Barrels or Imperial Barrels :-)

Using the Measure idea we could then ensure that if we were expecting a volume we could validate that we had a volume and not an area or a unit of energy. The other nice thing is that basic operations such as multiply/divide are easily catered for as you just combine the Measures in the appropriate way.

The thing my scheme doesn't easily handle is arbitrary independent scalar units e.g. "lots" or more dynamic conversions such as currency

[angularsen]

This is all interesting, but how do you suggest we apply these naming conventions to this project? Ref the initial description of this issue.

[eriove]

I really like the concept with the array of SI unit exponents. That could be used for automatic generation of operator overloads. I don't have time to do an implementation of that right now, but I've always wanted to automate it but haven't been sure how. I'll create an issue/pull request once I have time to keep this issue focused.

[phatcher]

@anjdreas Sorry, re-reading the question I'd suggest

• TMeasure - Used for struct types such as Length and Force
• TMeasureType/Kind - Used for the enums such as LengthUnit
• TUnit - Used unit enum values, such as LengthUnit.Meter

Rationale is that though Length is a Dimension under my modelling, you are also include Force which is a Measure (since it's Nm => (kg m^2)/s^2)).

The TMeasureType/Kind follows the suggested pattern and then Meter really is a Unit - don't like the use of TQuantity as what we are representing isn't a quantity but a unit of measure

BTW I can ask this in another question if you prefer, but is there anyway of using this library generically as I for my current use-case I need to store values with an arbitrary unit in a database. I don't have the code for my old project (proprietary) which is why I was looking in the first place :-)

[angularsen]

@eriove It's absolutely interesting, but my feeble mind can't immediately see how to apply this in this project to cover our existing units. Could you draft up a design in a few textual bullet points?

@phatcher Thanks, it looks good, but I'm not sure if the term measure is a better fit than quantity. Intuitively from my layman's perspective, I could interpret measure to mean a measurement, like 1 cm and 10 kg. I revisited your link on metrology and found the definition of units with a table that lists a column Base quantity with values Length, Mass, Time, Electric current etc. So they also seem to apply the term quantity to these. I found no use of the term measure in the same article to refer to these concepts, other than "the ability to measure" and "unit of measure".

Then there is the quote from wiki on Units of measurement:

A unit of measurement is a definite magnitude of a quantity, defined and adopted by convention or by law, that is used as a standard for measurement of the same quantity.[1] Any other value of that quantity can be expressed as a simple multiple of the unit of measurement.

For example, length is a physical quantity. The metre is a unit of length that represents a definite predetermined length. When we say 10 metres (or 10 m), we actually mean 10 times the definite predetermined length called "metre".

To counter myself, I also did not initially find quantity intuitive - as for me that also refers to some measurement, like 10 kg of dirt, but I do find quantity or rather physical quantity to be used to describe the concepts of Length and Mass in the wiki articles I've read so far.

What do you think?

Sources:
https://en.wikipedia.org/wiki/Metrology#Definition_of_units
https://en.wikipedia.org/wiki/Physical_quantity
https://en.wikipedia.org/wiki/Units_of_measurement

[phatcher]

@anjdreas I think the problem is that there doesn't seem to be a word that separates the concept being measured from the units - quantity seems to be used interchangeably for both.

I thought Measure was used in the literature, but it looks like I'm mis-remembering a text book from a while back.

The issue is currently. Length is a Quantity, metre is a Unit and 10 m is a Quantity; which to me is confusing so the answer is to rename concept 1 or 3, so you could have

1. Length -> Quantity or Measure
2. Metre -> Unit
3. 10 m -> Quantity or Measurement

To remove the conceptual ambiguity one needs to go - which will confuse some people but only until they understand the issue.

[angularsen]

@phatcher I see what you're saying. I think I see a way to interpret this now:

It is troublesome that both the concept and the measurement of length is referred to as quantity. However, in Units.NET, we usually talk about the struct type Length and its units. When I talk about the struct type Length, I don't talk about the concept of length - a measurable, continuous quantity. I am talking about representing a quantity of length.

var distanceToAlphaCentauri = Length.FromLightYears(4.22);

This is the quantity of length for this distance. It is not necessarily a measurement in this context, but it was measured at some point. This may be splitting hairs, but I think the wording quantity fits more generally here.

So, although this wording is tricky, I think we can skip your point 1 and only care about the length units (enum) and the length quantities/measurements (struct). In the original post we also talk about enum types vs enum values in the context of generics, but I think those are simpler to reason about.

[angularsen]

Also, this was a nice read on the topic. It also has an "Examples" section.

https://en.wikipedia.org/wiki/Quantity

[angularsen]

So my updated suggestion is as follows:

Changes to original post:

• Physical quantities -> Quantities
• TQuantityEnum -> TUnitType

Updated section in original post:

Proposal

• Quantities are represented by struct types like Length and Force and corresponding enum types LengthUnit and ForceUnit
• Units are represented by enum values like LengthUnit.Meter and ForceUnit.Newton
• Unit conversions are represented by instance properties, such as Length.Meters and Force.Newtons and custom conversion methods like Force.FromPressureByArea()
• Generic type parameters are named
  • TQuantity for unit struct types, such as Length
  • TUnitType for unit enum types, such as LengthUnit

[phatcher]

@anjdreas Looks good

[angularsen]

I think we are getting somewhere, I'm happy with this.
Any closing comments?
cc @eriove @JKSnd

[JKSnd]

@anjdreas I'm happy with the updated proposal as well. Nice stuff.

[angularsen]

Alright, closing this.
Fixed in commit 4f7f072

I also realized that we're not using a generic type for unit enum values and it doesn't even make sense as its type is the enum. Removing TUnit from bullet list.