atmoos / quantities Goto Github PK

Bump the core project Atmoos.Quantities to .Net 8

Each quantity should implement:

• IMultiplicativeIdentity
• IAdditiveIdentity

These two interfaces would be required to truly allow for generic algorithm implementations using the Quantities library.

The values would be 1 for the multiplicative identity and 0 for the additive identity, each using the corresponding SI unit.

We had inconsistent creation behaviour of quantities:

• Most quantities (e.g. Length) are created without any allocations
  • This is consistent with the fact that all quantities are structs.
• Some quantities (e.g Velocity) incurred an allocation when created
  • Which is unexpected given all quantities are structs.

Goal: Find a way to consistently create all quantities without allocations.

Please explain the relation between:

• Quant
• Injector (type injection)
• Builder & Map

Update the core project Atmoos.Quantities to .Net 8.

Currently there is a reasonably well defined .editorconfig in place. It's not consistently followed.
A dotnet format is in order with some manual cleaning up here and there.

Add logo to repo and include in nuget packaging.

Currently, if I want to create say one meter, I always need to write: Length.Of(1, Si<Metre>()).

This is semantically clean but a tad verbose. Hence create two convenience libraries

• Atmoos.Quantities.Convenience
• Atmoos.Quantities.Units.Convenience

that would expose types that'd enable the following syntax:

Length oneMetre = 1 * m;

Velocity oneKpH = 1 * km/h;

// similary,
var oneSecond = 1 * s;
var threeOhm = 3 * Ω;

Add a Normalise(): String method.

Scenario: Say you have a length instance of 78'167 μm. This is an unwieldy representation for humans to read. More natural forms of the same length would be 78.167 mm or 7.817 cm, where the latter value has been rounded.

Tasks:

• Find a good name for that method ("Normalised", "DisplayValue", "HumanReadable", etc. could be other names)
• Decide whether the value should or should not be rounded to max. three digits
• Find an implementation that efficiently computes the normalization for values in the metric system
• For the imperial system decide whether:
  • To not implement this functionality
  • To convert the value to a metric value that can be normalised
  • To convert the value to the "best" representation within the same system (This may open up a can of worms...)

Note also the example in the readme: 3'456 Km/d => 40 m/s

• Is that a good normalization? (people are more used to Km/h)
• Compound Quantities will be hard to reasonably normalise...

Converting Knots to Kilometres per Hour results in catastrophic loss of precision. This must be fixed.

Release version 1.0 of the Quantities.Serialization.Newtonsoft library.

The ScalarBuilder used for serialization has quite a bit of copy paste code that is used together with reflection.

Find a better way to create and invoke the generic methods needed to create (inject) the scalar measures.

The concrete quantity structs would ideally not have any dependencies to any concrete units, only to unit interfaces.

I have no clue how to accomplish as this collides square on with #6 . Possibly a very interesting design problem to work on.

Each value should be able to be serialized and de-serialized.

Implementation properties:

• Serialization must retain the internal representation (enabling true round robins)
  • i.e.: a length of 24.23 feet must retain it's representation of feet
• An implementation must be compatible with System.Text as well as Newtonsoft (i.e. any serialization library)

Some concepts are non-intuitive. Add How-To or best practices for following topic:

• Distinction Quantity vs. Unit
• Create new units
  • linear units (eg. metre -> feet)
  • with focus on combined quantities (velocity)
    • better not define FooLengthPerBarTime velocity unit
    • but define both a FooLength length unit and a BarTime time unit, then use "Per" method to combine them
• Using variables to capture units
• Point out the existence of the Units nuget at the point where I describe creation of new units.

Release version 1.0 of the Quantities.Units library.

As I've started other projects in the Atmoos namespace, it's prudent to include the quantities too.

Release version 1.0 of the Quantities.Serialization.Text.Json library.

Enable continuos deployment to nuget on every merge to master/main.

• Create "atmoos" organisation on nuget.
• Auto increment version on merge to master/main.
  • Done the other way round: csproj is master and version is extracted from there.
• Auto publish to nuget using a github workflow.
  • only publish when .csproj of respective projects have changed.

We should strive for coverage >= 90%.

Release version 1.0 of the Quantities library.

Implement remaining overloads:

• '>'
• '<'
• '>='
• '<='

Celsius currently implements IMetric, even though it is formally an si-derived unit. As it requires a transformation, we cannot implement it as an ISiUnit and ISiDerivedUnit has been deleted. This poses a dilemma: formally it is an si-derived unit, that currently "needs" to be implemented a metric unit.

Find a way to resolve this:

• Re-introduce ISiDerivedUnit.
• Let SI units also implement a transform function (ugly?)
  • relates to #4
• ...

Since the introduction of generalised transformations for all units, we see a loss of precision for units involving some offset. This is likely due to cancellation during addition/subtraction. The most striking examples can be found in the TemperatureTest.

We have the ability to control cancellation and should find a way to deal with it.

Some options:

• Use something like Double-Double (Dekker) precision throughout all computations.
• Merge the two polynomials into one single polynomial that represents the entire transformation from one unit to the next.

The file Measures.cs contains way too many measure implementations.

This concept needs to be revisited.

Currently a pair of methods have to be implemented on every implementation of a unit:

• ToSi(in Double self)
• FromSi(in Double value)

By definition FromSi must be the inverse of ToSi, rendering the former theoretically redundant.
Mathematically:
$$ToSi \circ FromSi \equiv \mathbb{1}$$

Idea: Make use of this and only require units to declare the ToSi method, then let "Quantities" figure out the inverse itself.

Rationale:

• Since we use static classes and functions for our measures this can be easily implemented without incuring any performance penalty
  • as the inversion can be done using C#'s static initialisation guarantees
• implementers of Units, won't manually have to check the the above identity holds.
  • This also eliminates frustration caused by loss of precision when testing the identity
  • We do it once in this library and users don't have to bother about it ever.
• Removes a source of implementation errors on all units
• Completely decouples implementations in the units from what the quantity library uses to compute transformations
  • Greatly improves maintainability for Quantities and user libraries alike
• Almost all quantities use polynomial transformations, which are very easy to invert.
• We can even use this to improve precision and performance of all conversions.
  • For all quantities there would be at most two function calls when converting from one unit to another
  • Conversion can make use of a type that offers higher precision than doubles invisible to any user.

Separate out the singular test project into two:

• Quantities.Test
  • that test everything in the core Quantities library.
• Quantities.Units.Test
  • that test everything in the Quantities.Units library.

This is to ensure clean separation of concerns and also dependencies. It is also a precursor to #77 .

Serialization is broken for inverted quantities. As an elegant solution, we should change the format of non-compound quantities to something resembling:

{
  "length": {
    "value": 4.2,
    "exponent": 1,
    "si": {
      "unit": "m"
    }
  }
}

The key being the added exponent, which simplifies both power measures (m³, etc.) but also inverse measures.

There are a couple of Units and Quantities that are each other's inverse. Examples include:

• Frequency $\leftrightarrow$ Time
  • $\mathsf{Hz} \leftrightarrow \mathsf{s}^{-1}$
• Conductance $\leftrightarrow$ Resistance
  • $\mathsf{S} \leftrightarrow \Omega^{-1}$

In order to represent these relations consistently, the notion of inversion of units and measures is required.

The benchmark exporter crashes when run on a windows machine.

The culprit is an open file handle that prevents a temporary file being moved into the position of the file it should be overwriting.

Bumps all projects dependent on Atmoos.Quantities to .Net8.0. These are:

• Atmoos.Quantities.Units
• Atmoos.Quantities.Serialization.Text.Json
• Atmoos.Quantities.Serialization.Newtonsoft

Find better naming:

• AmountOfInformation
• DataSize
• AmountOfData
• Information

Repro:

 Length nauticalMiles = Velocity.Of(4, NonStandard<Knot>()) * Time.Of(3, Si<Second>()); // 12 kn

Should be 12 nm (nautical miles)!

Add generation of the coverage report in the github action that runs the unit tests.

• Tutorial