ktsu.Semantics.Quantities 3.2.4

ktsu.Semantics.Quantities

A metadata-generated, type-safe physical quantity system built on a unified vector model, with compile-time dimensional analysis, generated unit conversions and physics operators, and centralized physical constants.

ktsu.Semantics.Quantities is one package in the ktsu.Semantics family. If you use a single numeric storage type throughout a project, the alias packages ktsu.Semantics.Quantities.Double, .Float, and .Decimal let you drop the generic argument and write Mass instead of Mass<double>.

Introduction

ktsu.Semantics.Quantities gives you physical quantities as types, so a Force cannot be added to a Speed and multiplying a Mass by an AccelerationMagnitude yields a ForceMagnitude at compile time. Every quantity is generic over its numeric storage type (Mass<double>, Speed<float>, Length<decimal>), and all values are stored in SI base units.

The type surface is generated. A single source of truth, dimensions.json, drives a Roslyn incremental generator that emits the quantity records, their From{Unit} factories with built-in conversions, the cross-dimensional physics operators, and the physical constants. That is roughly 72 physical dimensions and over 200 generated quantity types, all committed to source so the project compiles without first running the generator.

Every quantity is a vector, and the dimensionality of its direction space is part of the type.

IVectorN.Magnitude() (for N >= 1) returns the matching IVector0 quantity.

Features

• Compile-time dimensional safety: illegal combinations do not compile, and cross-dimensional operators produce the correct result type.
• Generated unit conversions: From{Unit} factories per declared unit (Mass.FromKilogram, Speed.FromMeterPerSecond, Length.FromFoot), converting to the SI base unit on construction, with In(unit) to convert back.
• Unified vector model: IVector0 through IVector4, with Magnitude(), Dot, Cross, Normalize, and typed cross-quantity results (Force3D.Dot(Displacement3D) returns Energy).
• Construction-time invariants: IVector0 magnitudes are guarded non-negative, and quantities where zero is unphysical (Wavelength, Period, HalfLife) are guarded strictly positive.
• Physical constants: PhysicalConstants with domain-grouped generic accessors that materialize into any T : INumber<T>.
• Generator diagnostics: metadata problems (SEM001-SEM005) are caught at build time.

Installation

Package Manager Console

Install-Package ktsu.Semantics.Quantities

.NET CLI

dotnet add package ktsu.Semantics.Quantities

Package Reference

<PackageReference Include="ktsu.Semantics.Quantities" Version="x.y.z" />

For a project that uses one storage type everywhere, reference an alias package instead (or in addition) so you can omit the generic argument. See storage-type aliases.

Usage Examples

Basic Example: magnitudes and operators

using ktsu.Semantics.Quantities;

Mass<double> m = Mass<double>.FromKilogram(2.0);
Speed<double> v = Speed<double>.FromMeterPerSecond(3.0);

MomentumMagnitude<double> p = m * v;   // Mass * Speed -> MomentumMagnitude
double kg = m.Value;                   // stored SI-base value

// arithmetic and comparison are inherited
Speed<double> faster = v + Speed<double>.FromMeterPerSecond(5.0);
bool ok = faster > v;

// construction-time guard: a negative magnitude throws ArgumentException
// Speed<double>.FromMeterPerSecond(-1.0);

Vector quantities

using ktsu.Semantics.Quantities;

Force3D<double> f = new() { X = 3.0, Y = 4.0, Z = 0.0 };
ForceMagnitude<double> mag = f.Magnitude();     // matching Vector0 quantity, value 5.0
Force3D<double> unit = f.Normalize();

Displacement3D<double> d = new() { X = 1.0, Y = 0.0, Z = 0.0 };
Energy<double> work = f.Dot(d);                 // typed dot: Force . Displacement = Energy
Torque3D<double> torque = f.Cross(d);           // typed cross: Force x Displacement = Torque
Momentum3D<double> impulse = f * Duration<double>.Create(2.0);

Physical constants

using ktsu.Semantics.Quantities;

// domain-grouped, materialized into the numeric type you ask for
double c = PhysicalConstants.Fundamental.SpeedOfLight<double>();   // 299_792_458 m/s
decimal R = PhysicalConstants.Chemistry.GasConstant<decimal>();    // 8.31446... J/(mol.K)

// generic accessors materialize into any T : INumber<T>
double g = PhysicalConstants.Generic.StandardGravity<double>();   // 9.80665
ForceMagnitude<double> weight = Mass<double>.FromKilogram(70.0) * AccelerationMagnitude<double>.Create(g);

API Reference

Hand-written runtime types

Generated quantity types

Each generated quantity is a partial record Name<T> where T : struct, INumber<T>. A typical IVector0 quantity such as Mass<T> exposes:

Vector quantities (Force3D<T>, Velocity2D<T>, ...) implement the matching IVectorN and add Magnitude() (returning the corresponding *Magnitude Vector0 quantity), Dot, Cross, and typed cross-quantity results.

Factory names use the singular lemma of each unit name verbatim (FromMeterPerSecond, FromRevolutionPerMinute). There is no pluralization step.

PhysicalConstants

• Domain-grouped: nested static classes with generic accessors, for example PhysicalConstants.Fundamental.SpeedOfLight<T>(), PhysicalConstants.ClassicalMechanics.StandardGravity<T>(), PhysicalConstants.Thermodynamics.WaterTriplePoint<T>(). Domain groups include Acoustics, AngularMechanics, Chemistry, ClassicalMechanics, FluidMechanics, Fundamental, NuclearPhysics, Optics, and Thermodynamics.
• Generic: PhysicalConstants.Generic.Name<T>() is a flat accessor over every constant, regardless of domain.
• Each constant is parsed from its metadata literal straight into T and cached per closed generic type, so the package carries no arbitrary-precision dependency and no rounding happens through an intermediate representation.

Architecture

The system is metadata-driven. The single source of truth is Semantics.SourceGenerators/Metadata/dimensions.json (alongside units.json, magnitudes.json, conversions.json, domains.json, and logarithmic.json). A Roslyn incremental generator emits one record per quantity, a From{Unit} factory per declared unit, the cross-dimensional * / / / Dot / Cross operators declared in the metadata, and the PhysicalConstants surface. Logarithmic-scale quantities (decibels, cents, pH) are generated separately because they do not obey linear arithmetic.

Generated output is committed to Generated/, so the project compiles without first running the generator. For the full design and an end-to-end "add a dimension" walk-through, see:

• Unified vector model strategy
• Source-generator workflow and schema
• Physics domains tour

Contributing

Contributions are welcome! Feel free to open issues or submit pull requests.

License

This project is licensed under the MIT License. See the LICENSE.md file for details.