Units | Physics Math

Representation and manipulation of physical units.

These are based on SI, and in particular the (Guide for the Use of the International System of Units (SI))https://physics.nist.gov/cuu/pdf/sp811.pdf(https://physics.nist.gov/cuu/pdf/sp811.pdf]) However, this does not try to be complete, and extends the set of base units somewhat to aid clarity (for example, 'cycles/revolutions') while preserving semantics and standardized presentation. Having units that map to SI '1' is not very helpful sometimes.

See the Units.Units namespace for definitions of individual units.

Index

Namespaces

Units

Enumerations

Primitive

Classes

Interfaces

Type aliases

Variables

Functions

Type aliases

Add

Add<A, B>: A extends 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 ? B extends 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 ? XADD[A][B] : XSUB[Negate][A] : B extends 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 ? XSUB[Negate<A>][B] : Negate<XADD[Negate<A>][Negate]>

Type parameters

A: number
B: number

CompleteTerms

CompleteTerms<A>: {}

Take a partial set of UnitTerms, and fills in the missing exponents with 0.

Type parameters

A: PUnitTerms

Type declaration

Divide

Divide<A, B>: A extends Unit<infer TA> ? B extends Unit<infer TB> ? Unit<DivideTerms<TA, TB>> : never : never

Divide two Unit types, A/B (by subtracting the exponents).

Type parameters

A: Unit
B: Unit

DivideTerms

DivideTerms<A, B>: {}

Divide two UnitTerms, A/B

Type parameters

A: PUnitTerms
B: PUnitTerms

Type declaration

Exponent

Exponent: -9 | -8 | -7 | -6 | -5 | -4 | -3 | -2 | -1 | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9

Our supported exponents. A finite list of exponents allows TypeScript to automatically type exponents as numeric literal types.

InvertTerms

InvertTerms<A>: {}

Invert a UnitTerms (by negating the exponents).

Type parameters

A: PUnitTerms

Type declaration

M

M<K, V>: {}

Type parameters

K: number
V: number

Type declaration

Multiply

Multiply<A, B>: A extends IUnitBase<infer TA> ? B extends IUnitBase<infer TB> ? Unit<MultiplyTerms<TA, TB>> : never : never

Multiply two Unit types (by adding the exponents).

Type parameters

A: IUnitBase
B: IUnitBase

MultiplyTerms

MultiplyTerms<A, B>: {}

Multiply two UnitTerms (by adding the exponents.)

Type parameters

A: PUnitTerms
B: PUnitTerms

Type declaration

Negate

Negate<A>: XNEGATE[A]

Type parameters

A: number

OrZero

OrZero<A>: A extends number ? A : 0

If not a number (e.g. undefined), the 0 type literal.

Type parameters

PUnitTerms

PUnitTerms: {}

An object of primitive UNIT: Exponent pairs that uniquely describes each type.

Type declaration

PrefixExponent

PrefixExponent: 24 | 21 | 18 | 15 | 12 | 9 | 6 | 3 | 2 | 1 | -1 | -2 | -3 | -6 | -9 | -12 | -15 | -18 | -21 | -24

PrefixName

PrefixSymbol

PrefixSymbol: "Y" | "Z" | "E" | "P" | "T" | "G" | "M" | "k" | "h" | "da" | "d" | "c" | "m" | "μ" | "u" | "n" | "p" | "f" | "a" | "z" | "y"

PrimitiveMap

PrimitiveMap: {}

Type of our PRIMITIVE_MAP map. This provides one key/value entry for each primitive, indexed by the UNIT enum.

Type declaration

Sub

Sub<A, B>: A extends 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 ? B extends 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 ? XSUB[B][A] : XADD[Negate][A] : B extends 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 ? Negate<XADD[Negate<A>][B]> : Negate<XSUB[Negate][Negate<A>]>

Type parameters

A: number
B: number

TermsOfUnit

TermsOfUnit: U extends Unit<infer T> ? CompleteTerms<T> : never

Type parameters

U: Unit

TermsOfUnitBase

TermsOfUnitBase: U extends IUnitBase<infer T> ? T : never

Type parameters

U: IUnitBase

UnitTerms

UnitTerms: {}

An object with keys being the name of Primitive types and the values being exponents. All values are required; supply zero for values not supplied.

See PUnitTerms for a partial set where types can be left undefined.

Type declaration

XADD

XADD: [[0, 1, 2, 3, 4, 5, 6, 7, 8, 9], [1, 2, 3, 4, 5, 6, 7, 8, 9, 9], [2, 3, 4, 5, 6, 7, 8, 9, 9, 9], [3, 4, 5, 6, 7, 8, 9, 9, 9, 9], [4, 5, 6, 7, 8, 9, 9, 9, 9, 9], [5, 6, 7, 8, 9, 9, 9, 9, 9, 9], [6, 7, 8, 9, 9, 9, 9, 9, 9, 9], [7, 8, 9, 9, 9, 9, 9, 9, 9, 9], [8, 9, 9, 9, 9, 9, 9, 9, 9, 9], [9, 9, 9, 9, 9, 9, 9, 9, 9, 9]]

For addition of positive numbers, we let 9 stand for all larger numbers.

XNEGATE

XNEGATE: [0, -1, -2, -3, -4, -5, -6, -7, -8, -9] & M<-1, 1> & M<-2, 2> & M<-3, 3> & M<-4, 4> & M<-5, 5> & M<-6, 6> & M<-7, 7> & M<-8, 8> & M<-9, 9>

XSUB

XSUB: [[0, 1, 2, 3, 4, 5, 6, 7, 8, 9], [-1, 0, 1, 2, 3, 4, 5, 6, 7, 8 | 9], [-2, -1, 0, 1, 2, 3, 4, 5, 6, 7 | 8 | 9], [-3, -2, -1, 0, 1, 2, 3, 4, 5, 6 | 7 | 8 | 9], [-4, -3, -2, -1, 0, 1, 2, 3, 4, 5 | 6 | 7 | 8 | 9], [-5, -4, -3, -2, -1, 0, 1, 2, 3, 4 | 5 | 6 | 7 | 8 | 9], [-6, -5, -4, -3, -2, -1, 0, 1, 2, 3 | 4 | 5 | 6 | 7 | 8 | 9], [-7, -6, -5, -4, -3, -2, -1, 0, 1, 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9], [-8, -7, -6, -5, -4, -3, -2, -1, 0, 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9], [-9, -8 | -9, -7 | -8 | -9, -6 | -7 | -8 | -9, -5 | -6 | -7 | -8 | -9, -4 | -5 | -6 | -7 | -8 | -9, -3 | -4 | -5 | -6 | -7 | -8 | -9, -2 | -3 | -4 | -5 | -6 | -7 | -8 | -9, -1 | -2 | -3 | -4 | -5 | -6 | -7 | -8 | -9, 0 | -1 | -2 | -3 | -4 | -5 | -6 | -7 | -8 | -9]]

For subtraction of positive numbers, we have to allow for 9 standing in for larger numbers.

Variables

Const ALIASES

ALIASES: {}

Our defined aliases.

Type declaration

[k: string]: Unit & Alias

Const NAMED_UNITS

NAMED_UNITS: {}

A map from name to the Unit representing that unit.

Type declaration

[key: string]: Unit

Const ORDER

ORDER: {} = (i => {return {mass: i++,length: i++,angle: i++,solidAngle: i++,cycles: i++,amount: i++,current: i++,temperature: i++,time: i++,candela: i++};})(0)

A total order on units, for canonical display and key generation.

Type declaration

Const PREFIXES

PREFIXES: {} = ((t: {[K in PrefixSymbol]: [PrefixExponent, PrefixName, string?]} = {Y: [24, 'yotta'],Z: [21, 'zetta'],E: [18, 'exa'],P: [15, 'peta'],T: [12, 'tera'],G: [9, 'giga'],M: [6, 'mega'],k: [3, 'kilo'],h: [2, 'hecto'],da: [1, 'deka'],d: [-1, 'deci'],c: [-2, 'centi'],m: [-3, 'milli'],μ: [-6, 'micro', TeX`\mu`],u: [-6, 'micro', TeX`\mu`], // Alternative for typing-impaired.n: [-9, 'nano'],p: [-12, 'pico'],f: [-15, 'fempto'],a: [-18, 'atto'],z: [-21, 'zepto'],y: [-24, 'yocto']}) => {const pt: any = {};Object.keys(t).forEach(k => {const kk = k === 'u' ? 'μ' : k;const a = t[kk as PrefixSymbol] as [PrefixExponent, PrefixName, string?];const p = new Prefix(kk as PrefixSymbol, ...a)pt[k] = p;pt[p.exponent] = p;pt[p.name] = p;});return pt as {[K in PrefixSymbol|PrefixName|PrefixExponent]: Prefix};})()

Type declaration

Const PRIMITIVE_MAP

PRIMITIVE_MAP: Readonly<PrimitiveMap> = (() => {const val: PrimitiveMap = {} as PrimitiveMap;const defPrimitive = (u: Primitive, name: string, symbol: string, varName?: string,attributes: UnitAttributes = {}) => {const primitive = new PrimitiveUnit(u, name, symbol, varName, attributes);(val as any)[u] = primitive;primitive.names.push(u);return primitive;}defPrimitive(Primitive.time, 'second', 's', 't', {si_base: true});defPrimitive(Primitive.mass, 'kilogram', 'kg', 'm',{si_base: true, scale: 1000});defPrimitive(Primitive.length, 'meter', 'm', 'l', {si_base: true});defPrimitive(Primitive.amount, 'mole', 'mol', 'n', {si_base: true});defPrimitive(Primitive.cycles, 'cycle', 'cycle', 'c');defPrimitive(Primitive.angle, 'radian', 'rad', '𝜃');defPrimitive(Primitive.solidAngle, 'steridian', 'sr', undefined);defPrimitive(Primitive.current, 'ampere', 'A', 'A', {si_base: true});defPrimitive(Primitive.temperature, 'kelvin', 'K', 'T',{absolute: true, si_base: true});defPrimitive(Primitive.candela, 'candela', 'cd', 'c', {si_base: true})return val as PrimitiveMap;})()

A map from primitive name to its Unit instance.

Const RE_identifier

RE_identifier: RegExp = /[\p{L}\p{Pc}\p{Pd}\p{S}][\p{L}\p{Pc}\p{Pd}\p{S}\p{N}]*/u

Const RE_name

RE_name: RegExp = new RegExp(`(${RE_prefix_name.source})?(${RE_identifier.source})`, 'u')

Const RE_prefix_name

Const RE_prefix_name_concat

RE_prefix_name_concat: RegExp = new RegExp(`(${RE_prefix_name.source})${RE_whitespace_sep.source}(${RE_identifier.source})`, 'ug')

Const RE_prefix_symbol

RE_prefix_symbol: RegExp = /Y|Z|E|P|T|G|M|k|h|da|d|c|m|μ|u|n|p|f|a|z|y/

Const RE_symbol

RE_symbol: RegExp = new RegExp(`(${RE_prefix_symbol.source})?(${RE_identifier.source})`, 'u')

Const RE_whitespace

RE_whitespace: RegExp = /[\p{Z}\p{C}\p{M}]+/u

Const RE_whitespace_sep

RE_whitespace_sep: RegExp = /[\p{Z}\p{C}\p{M}\p{Pd}]+/u

Const SYMBOL_ALIASES

SYMBOL_ALIASES: {}

Type declaration

[k: string]: Unit & Alias

Const SYMBOL_UNITS

SYMBOL_UNITS: {}

A map from symbol for a Unit representing that unit.

Type declaration

[key: string]: Unit

Const TeX

TeX: raw = String.raw

String literal parser for LaTeX literals (avoids the need for quoting backslash).

Const UNITS

UNITS: {}

A map from unit key's string representation to the Unit instance.

Type declaration

[k: string]: Unit

Const primitiveKeys

primitiveKeys: Primitive[] = Object.keys(Primitive) as Primitive[]

Functions

Const defineAlias

defineAlias<T>(name: string, symbol: string | undefined, attributes: AliasAttributes, si: Unit<T>, scale: number, offset?: number, ...names: string[]): Unit<T> & Alias

- Defined in src/units.ts:475
Define a unit alias, which can convert to/from a corresponding standard unprefixed SI unit.

Type parameters
- T: UnitTerms
Parameters
- name: string
- symbol: string | undefined
- attributes: AliasAttributes
- si: Unit<T>
- scale: number
- Default value offset: number = 0
- Rest ...names: string[]
Returns Unit<T> & Alias

Const defineUnit

defineUnit<T>(key: T, attributes?: UnitAttributes, ...names: string[]): Unit<CompleteTerms<T>>

- Defined in src/units.ts:353
Define a derived type.

The numbers in the keys are exponents for primitive types. They are taken as type literals,

This ensures, for example, that the types of U.velocity and U.acceleration are distinct.
```
const U.velocity = defineUnit({distance: 1, time: -1});
const U.acceleration = defineUnit({distance: 1, time: -2});
```
Results in types of:
```
type U.velocity = Unit<{distance: 1, time: -1}>
type U.acceleration = Unit<{distance: 1, time: -2}>
```
Type parameters
- T: PUnitTerms
Parameters
- key: T
 
 The key defining the type composition
- Default value attributes: UnitAttributes = {}
 
 Additional attributes describing the type.
- Rest ...names: string[]
 
 Additional names to use for this type, e.g. newton.
Returns Unit<CompleteTerms<T>>

Const getUnit

getUnit(name: string, siOnly?: boolean): Unit<{}>

- Defined in src/units.ts:619
Get a unit by name.

To process a # + unit into standard unprefixed SI, do:
```
const [siVal, siUnit] = getUnit(unitName).toSI(val);
```
To just get the standard SI unit, do:
```
const siUnit = getUnit(unitName).si;
```
Parameters
- name: string
- Default value siOnly: boolean = false
 
 if true, only unscaled SI units are returned.
Returns Unit<{}>

Const isUnit

isUnit(u: any): u is Unit

- Defined in src/units.ts:670
Parameters
- u: any
Returns u is Unit

Const makeLookupKey

makeLookupKey(key: PUnitTerms): string

- Defined in src/primitive-units.ts:138
Turn the structured UnitTerms key into a string to do the lookup for unique types.

Parameters
- key: PUnitTerms
Returns string

Const orderUnits

orderUnits(a: Primitive, b: Primitive): 0 | 1 | -1

- Defined in src/primitive-units.ts:65
Comparison predicate for primitive units to allow sorting them into a canonical total order.

Parameters
- a: Primitive
- b: Primitive
Returns 0 | 1 | -1

Const parsePrefix

parsePrefix(u: string, siOnly?: boolean): Unit | null

- Defined in src/units.ts:566
Parse a prefixed expression into a suitable Alias. Returns null if not found.

Parameters
- u: string
- Default value siOnly: boolean = false
  
  true if only non-aliases should be considered.
Returns Unit | null

Index

Namespaces

Enumerations

Classes

Interfaces

Type aliases

Variables

Functions

Type aliases

Add

Type parameters

A: number

B: number

CompleteTerms

Type parameters

A: PUnitTerms

Type declaration

Divide

Type parameters

A: Unit

B: Unit

DivideTerms

Type parameters

A: PUnitTerms

B: PUnitTerms

Type declaration

Exponent

InvertTerms

Type parameters

A: PUnitTerms

Type declaration

M

Type parameters

K: number

V: number

Type declaration

Multiply

Type parameters

A: IUnitBase

B: IUnitBase

MultiplyTerms

Type parameters

A: PUnitTerms

B: PUnitTerms

Type declaration

Negate

Type parameters

A: number

OrZero

Type parameters

A

PUnitTerms

Type declaration

PrefixExponent

PrefixName

PrefixSymbol

PrimitiveMap

Type declaration

Sub

Type parameters

A: number

B: number

TermsOfUnit

Type parameters

U: Unit

TermsOfUnitBase

Type parameters

U: IUnitBase

UnitTerms

Type declaration

XADD

XNEGATE

XSUB

Variables

Const ALIASES

Type declaration

[k: string]: Unit & Alias

Const NAMED_UNITS

Type declaration

[key: string]: Unit