Lightweight & Blazing Fast

Type-Safe Unit Conversions Made Simple

A modern .NET library for effortless unit conversions with physics-based dimensional operations. 22 measurement types, 80+ physical constants, fluent API, and 100% type-safe.

QuickStart.cs
using Metricly.Core;
using Metricly.Core.Operations;
using Metricly.Core.Constants;

// Fluent, readable conversions
var distance = 5.Kilometers();
Console.WriteLine(distance.ToMiles());  // 3.106855

// Physics-based calculations
var mass = 10.Kilograms();
var g = PhysicalConstants.StandardGravity;
var force = mass.ToForce(g);  // 98.1 N

// 22 measurement types + 80+ constants
var c = PhysicalConstants.SpeedOfLight;  // 299,792,458 m/s

Why Choose Metricly?

Built with modern .NET in mind, optimized for performance and developer experience

Type-Safe

Strongly typed measurements prevent runtime errors and catch mistakes at compile time

Blazing Fast

Zero allocations, aggressive inlining, and compile-time constants for optimal performance

Fluent API

Intuitive extension methods make code readable: 5.Kilometers().ToMiles()

Arithmetic Operations

Natural math operations: add, subtract, multiply, divide measurements safely

Physics-Based

Dimensional operations for real-world calculations: F=ma, E=mc², Ohm's Law, and more

Physical Constants

80+ fundamental constants: speed of light, gravity, Avogadro's number, and more

22 Measurement Types

Comprehensive coverage: length, mass, time, temperature, electrical, and more

Well Documented

Extensive documentation, examples, and XML comments for IntelliSense support

Zero Dependencies

Pure .NET, no external dependencies, easy to integrate into any project

Quick Installation

Get started in seconds with NuGet Package Manager

1

Package Manager Console

NuGet\Install-Package Metricly -Version 0.1.3-beta.1
2

.NET CLI

dotnet add package Metricly --version 0.1.3-beta.1
3

Import and Use

using Metricly.Core;

var distance = 100.Meters();
Console.WriteLine(distance.ToFeet());

Complete Documentation

Everything you need to master Metricly

Basic Conversions

Metricly provides a fluent API for creating and converting measurements. Use extension methods to create values, then convert them to any compatible unit.

using Metricly.Core;

// Length conversions
var distance = 5.Kilometers();
Console.WriteLine(distance.ToMiles());      // 3.106855
Console.WriteLine(distance.ToMeters());     // 5000

// Temperature conversions
var temp = 100.Celsius();
Console.WriteLine(temp.ToFahrenheit());      // 212
Console.WriteLine(temp.ToKelvin());         // 373.15

// Mass conversions
var weight = 75.Kilograms();
Console.WriteLine(weight.ToPounds());       // 165.347
Console.WriteLine(weight.ToGrams());        // 75000

Arithmetic Operations

Perform natural arithmetic operations on measurements. The library ensures type safety and automatic unit handling.

using Metricly.Core;

// Addition and subtraction
var total = 1.Kilometers() + 500.Meters();
Console.WriteLine(total.ToKilometers());  // 1.5

var remaining = 42.Kilometers() - 10.Kilometers();
Console.WriteLine(remaining.ToKilometers());  // 32

// Multiplication and division by scalars
var triple = 5.Meters() * 3;
Console.WriteLine(triple.ToMeters());      // 15

var half = 10.Kilograms() / 2;
Console.WriteLine(half.ToKilograms());    // 5

// Ratio calculations
var ratio = 100.Kilometers() / 50.Kilometers();
Console.WriteLine(ratio);                  // 2.0

// Comparison operators
if (100.Meters() > 50.Meters())
{
    Console.WriteLine("100m is greater");
}

Dimensional Operations

Metricly v0.1.0 introduces physics-based dimensional operations. Perform real-world calculations using extension methods that enforce dimensional correctness at compile time.

Kinematics

using Metricly.Core;
using Metricly.Core.Operations;

// Speed = Distance / Time
var distance = 100.Meters();
var time = 10.Seconds();
var speed = distance.ToSpeed(time);
Console.WriteLine($"Speed: {speed.ToKilometersPerHour()} km/h");

// Distance = Speed × Time
var speed2 = 60.KilometersPerHour();
var time2 = 2.Hours();
var distance2 = speed2.ToDistance(time2);
Console.WriteLine($"Distance: {distance2.ToKilometers()} km");

// Acceleration = Speed / Time
var finalSpeed = 20.MetersPerSecond();
var accelerationTime = 5.Seconds();
var acceleration = finalSpeed.ToAcceleration(accelerationTime);
Console.WriteLine($"Acceleration: {acceleration.ToMetersPerSecondSquared()} m/s²");

Dynamics

using Metricly.Core;
using Metricly.Core.Operations;
using Metricly.Core.Constants;

// Force = Mass × Acceleration (F = ma)
var mass = 10.Kilograms();
var gravity = PhysicalConstants.StandardGravity;
var force = mass.ToForce(gravity);
Console.WriteLine($"Force: {force.ToNewtons()} N");  // 98.1 N

// Work = Force × Distance
var pushForce = 100.Newtons();
var pushDistance = 5.Meters();
var work = pushForce.ToEnergy(pushDistance);
Console.WriteLine($"Work: {work.ToJ()} J");  // 500 J

// Torque = Force × Lever Arm
var wrenchForce = 50.Newtons();
var leverArm = 0.3.Meters();
var torque = wrenchForce.ToTorque(leverArm);
Console.WriteLine($"Torque: {torque.ToNewtonMeters()} N⋅m");

Electricity (Ohm's Law)

using Metricly.Core;
using Metricly.Core.Operations;

// Voltage = Current × Resistance (V = I × R)
var current = 2.Amperes();
var resistance = 10.Ohms();
var voltage = current.ToVoltage(resistance);
Console.WriteLine($"Voltage: {voltage.ToVolts()} V");  // 20 V

// Current = Voltage / Resistance (I = V / R)
var batteryVoltage = 12.Volts();
var circuitResistance = 100.Ohms();
var circuitCurrent = batteryVoltage.ToCurrent(circuitResistance);
Console.WriteLine($"Current: {circuitCurrent.ToMilliamperes()} mA");

// Power = Voltage × Current (P = V × I)
var power = voltage.ToPower(current);
Console.WriteLine($"Power: {power.ToWatts()} W");

Geometry

using Metricly.Core;
using Metricly.Core.Operations;

// Area = Length × Width
var length = 10.Meters();
var width = 5.Meters();
var area = length.ToArea(width);
Console.WriteLine($"Area: {area.ToSquareMeters()} m²");  // 50 m²

// Volume = Area × Height
var floorArea = 50.SquareMeters();
var height = 3.Meters();
var volume = floorArea.ToVolume(height);
Console.WriteLine($"Volume: {volume.ToCubicMeters()} m³");  // 150 m³

Complete Dimensional Operations Table

Category Formula Method Example
Kinematics Speed = Distance / Time distance.ToSpeed(time) 100m.ToSpeed(10s)
Distance = Speed × Time speed.ToDistance(time) 10mps.ToDistance(5s)
Acceleration = Speed / Time speed.ToAcceleration(time) 20mps.ToAcceleration(5s)
Dynamics Force = Mass × Acceleration mass.ToForce(acceleration) 10kg.ToForce(9.81mps²)
Work = Force × Distance force.ToEnergy(distance) 100N.ToEnergy(5m)
Torque = Force × Lever force.ToTorque(lever) 50N.ToTorque(0.3m)
Electricity Voltage = Current × Resistance current.ToVoltage(resistance) 2A.ToVoltage(10Ω)
Current = Voltage / Resistance voltage.ToCurrent(resistance) 12V.ToCurrent(100Ω)
Power = Voltage × Current voltage.ToPower(current) 12V.ToPower(2A)
Geometry Area = Length × Width length.ToArea(width) 10m.ToArea(5m)
Volume = Area × Height area.ToVolume(height) 50m².ToVolume(3m)
Other Density = Mass / Volume mass.ToDensity(volume) 1000kg.ToDensity(1m³)
Pressure = Force / Area force.ToPressure(area) 1000N.ToPressure(0.1m²)
Power = Energy / Time energy.ToPower(time) 1000J.ToPower(10s)

Energy Calculations

using Metricly.Core;
using Metricly.Core.Operations;
using Metricly.Core.Constants;

// Kinetic Energy: KE = ½mv²
var mass = 1000.Kilograms();
var speed = 20.MetersPerSecond();
var ke = DimensionalOperations.CalculateKineticEnergy(mass, speed);
Console.WriteLine($"Kinetic Energy: {ke.TokJ()} kJ");

// Potential Energy: PE = mgh
var height = 10.Meters();
var g = PhysicalConstants.StandardGravity;
var pe = DimensionalOperations.CalculatePotentialEnergy(mass, g, height);
Console.WriteLine($"Potential Energy: {pe.TokJ()} kJ");

Physical Constants

Metricly v0.1.0 includes 80+ fundamental physical constants. Access them through the PhysicalConstants class for accurate scientific calculations.

Universal Constants

using Metricly.Core.Constants;

// Speed of Light
var c = PhysicalConstants.SpeedOfLight;  // 299,792,458 m/s

// Gravitational Constant
var G = PhysicalConstants.GravitationalConstant;  // 6.67430×10⁻¹¹ N⋅m²/kg²

// Planck Constant
var h = PhysicalConstants.PlanckConstant;  // 6.62607015×10⁻³⁴ J⋅s

// Calculate time for light to travel from Sun to Earth
var sunDistance = PhysicalConstants.AstronomicalUnit;
var lightTime = sunDistance.ToTime(c);
Console.WriteLine($"Sun to Earth: {lightTime.ToMinutes():F2} minutes");

Constants Categories

Universal

  • SpeedOfLight - c = 299,792,458 m/s
  • GravitationalConstant - G
  • PlanckConstant - h

Electromagnetic

  • ElementaryCharge - e
  • MagneticConstant - μ₀
  • ElectricConstant - ε₀

Atomic & Quantum

  • AvogadroConstant - Nₐ
  • BoltzmannConstant - k
  • ElectronMass
  • ProtonMass
  • BohrRadius

Gravity & Astronomy

  • StandardGravity - g = 9.80665 m/s²
  • EarthMass
  • SolarMass
  • AstronomicalUnit - AU
  • LightYear

Thermodynamic

  • GasConstant - R
  • AbsoluteZero - 0 K
  • WaterDensity
  • StandardTemperature
  • StandardPressure

Planck Units

  • PlanckLength
  • PlanckTime
  • PlanckMass
  • PlanckTemperature

Real-World Example

using Metricly.Core;
using Metricly.Core.Operations;
using Metricly.Core.Constants;

// Calculate escape velocity from Earth
var earthMass = PhysicalConstants.EarthMass;
var earthRadius = PhysicalConstants.EarthRadius;
var G = PhysicalConstants.GravitationalConstant;

// v = √(2GM/r)
var escapeVelocity = Math.Sqrt(
    2 * G.BaseValue * earthMass.BaseValue / earthRadius.BaseValue
);
Console.WriteLine($"Escape velocity: {escapeVelocity:F0} m/s");
Console.WriteLine($"That's {(escapeVelocity / 1000):F1} km/s");

Measurement Types

Metricly v0.1.0 supports 22 different measurement types covering physics, engineering, computing, and everyday conversions.

Basic Measurements

Length

meters, kilometers, miles, feet, inches, nautical miles, astronomical units, light years, parsecs

Mass

grams, kilograms, pounds, ounces, metric tons, stones

Temperature

Celsius, Fahrenheit, Kelvin

Time

seconds, minutes, hours, days, weeks, months, years, centuries

Speed

m/s, km/h, mph, knots, feet per second

Area

square meters, hectares, acres, square miles, square feet

Volume

liters, gallons (US/Imperial), cubic meters, cups, tablespoons, pints, quarts

Physics & Engineering NEW

Force

Newton, kilonewton, pound-force, dyne, kilogram-force

Acceleration

m/s², standard gravity (g), ft/s², gal

Pressure

Pascal, atmospheres, PSI, Torr

Energy

joules, calories, watt-hours, BTU, electronvolts, foot-pounds

Power

watts, kilowatts, horsepower, megawatts

Torque

Newton-meter, foot-pound, inch-pound

Density

kg/m³, g/cm³, lb/ft³

Electrical Units NEW

Current

Ampere, milliampere, microampere, kiloampere

Voltage

Volt, millivolt, kilovolt, megavolt

Resistance

Ohm, kiloohm, megaohm

Other

Frequency

hertz with all SI prefixes (nano to yotta)

Data Size

bytes, KB/KiB, MB/MiB, GB/GiB, TB/TiB (decimal and binary)

Data Rate

bits/bytes per second with various prefixes

Fuel Consumption

km/L, L/100km, MPG (US/UK)

Angles

degrees, radians, gradians, arcminutes, arcseconds

Real-World Examples

Practical applications demonstrating Metricly's capabilities

Trip Calculator

Travel
// Calculate trip time and fuel consumption
var distance = 350.Kilometers();
var speed = 110.KilometersPerHour();
var fuelEfficiency = 15.KmPerLiter();

var travelTime = distance / speed.ToKilometersPerHour();
var fuelNeeded = distance.ToKilometers() / fuelEfficiency.ToKmPerLiter();

Console.WriteLine($"Distance: {distance.ToMiles():F1} miles");
Console.WriteLine($"Travel time: {travelTime:F1} hours");
Console.WriteLine($"Fuel needed: {fuelNeeded:F1} L");

Electrical Circuit Analysis

Physics
using Metricly.Core.Operations;

// Circuit with voltage source and resistors
var voltage = 12.Volts();
var resistor1 = 100.Ohms();
var resistor2 = 200.Ohms();

// Total resistance (series)
var totalResistance = resistor1 + resistor2;

// Calculate current (Ohm's Law: I = V / R)
var current = voltage.ToCurrent(totalResistance);
Console.WriteLine($"Current: {current.ToMilliamperes():F2} mA");

// Calculate power dissipation (P = V × I)
var power = voltage.ToPower(current);
Console.WriteLine($"Power: {power.ToWatts():F3} W");

Projectile Motion

Physics
using Metricly.Core.Operations;
using Metricly.Core.Constants;

// Calculate projectile motion
var initialSpeed = 20.MetersPerSecond();
var mass = 1.Kilograms();
var g = PhysicalConstants.StandardGravity;

// Calculate kinetic energy
var ke = DimensionalOperations.CalculateKineticEnergy(mass, initialSpeed);
Console.WriteLine($"Kinetic Energy: {ke.ToJ()} J");

// Maximum height: h = v²/(2g)
var maxHeight = (initialSpeed.BaseValue * initialSpeed.BaseValue) / 
                (2 * g.BaseValue);
Console.WriteLine($"Max height: {maxHeight:F2} m");

File Download Calculator

Computing
// Calculate download time
var fileSize = 4.7.GB();
var downloadSpeed = 100.MegabitsPerSecond();

var fileSizeMb = fileSize.ToMB();
var speedMBps = downloadSpeed.ToMegabytesPerSecond();

var timeSeconds = fileSizeMb / speedMBps;
var timeMinutes = timeSeconds / 60;

Console.WriteLine($"File size: {fileSize.ToGiB():F2} GiB");
Console.WriteLine($"Speed: {speedMBps:F1} MB/s");
Console.WriteLine($"ETA: {timeMinutes:F1} minutes");

Weather Station

Science
// Process weather data
var temperature = 22.Celsius();
var pressure = 1013.Pascal();
var windSpeed = 15.KilometersPerHour();

Console.WriteLine("=== Weather Report ===");
Console.WriteLine($"Temperature: {temperature.ToCelsius():F1}°C / {temperature.ToFahrenheit():F1}°F");
Console.WriteLine($"Pressure: {pressure.ToAtmospheres():F2} atm");
Console.WriteLine($"Wind: {windSpeed.ToMilesPerHour():F1} mph");

// Check for comfortable conditions
if (temperature >= 18.Celsius() && temperature <= 24.Celsius())
{
    Console.WriteLine("Comfortable temperature!");
}

Home Energy Monitor

Utilities
using Metricly.Core.Operations;

// Calculate monthly energy consumption
var dailyUsage = 15.kWh();
var monthlyUsage = dailyUsage * 30;

Console.WriteLine($"Monthly: {monthlyUsage.TokWh()} kWh");
Console.WriteLine($"In MJ: {monthlyUsage.ToMJ():F0} MJ");

// Calculate cost (example rate)
var costPerKwh = 0.15; // $0.15 per kWh
var monthlyCost = monthlyUsage.TokWh() * costPerKwh;
Console.WriteLine($"Monthly cost: ${monthlyCost:F2}");

// Compare appliances
var ac = 5.kWh();
var heater = 3.kWh();
var total = ac + heater;
var acPercentage = (ac / total) * 100;
Console.WriteLine($"AC is {acPercentage:F1}% of total");