Physical is a Units of Measurement system for the Swift programming language, built on top of ('s) Foundation's Measurement framework.
The project aims to make use of the developments in Dimensional Analysis and Unit/Measurement research to make writing code more appropriate for both trivial and complex real world calculations. Even if you don't think you are making such calculations in your code, you probably are. This can be your friend to help maintain readable, debuggable code.
The more real-world code that uses this package, the better we can optimize the whole system. Please file requests, ideally with real (or hoped-for) code, submit pull requests, and bring up areas that could improvement.
- Elegant syntax
- Fully composable system
- Extensive set of constants included
- Discoverable system via autocomplete
- Automatic precision tracking
- Runtime and/or Compiletime type checking
- Very light touch: No code rewriting required
- Extended set of dimensions and units
- Customizable dimensions and units
- Accelerated array operations
For a recent overview of the project, see this talk on the framework given at 360iDev 2022.
Physical is released under the MIT license.
If using Xcode, open a workspace or project and: File → Add Packages... → put in the URL of this project.
If editing your Package.swift by hand, add in this dependency info:
let package = Package(
...
targets: [
.target(name: "YourAwesomeProject", dependencies: ["Physical"]),
],
dependencies: [
.package(url: "https://github.com/hyperjeff/Physical.git", .branch("main")),
],
...
)Once you have either of the above set, just import Physical atop any file that you would like.
Physical extends the units supported by the Measurement framework's dimension set:
Acceleration, Angle, Area, ConcentrationMass,
Dispersion, Duration, ElectricCharge, ElectricCurrent,
ElectricPotentialDifference, ElectricResistance, Energy,
Frequency, FuelEfficiency, InformationStorage, Length,
Mass, Power, Pressure, Speed, Temperature, Volume
and adds these dimensions as well:
Activity, Amount, AngularSpeed, ElectricCapacitance,
ElectricConductance, ElectricInductance, Force,
IonizingRadiation, LuminousIntensity, LuminousFlux,
MagneticFlux, MagneticFluxDensity, SolidAngle
In addition, the entire system is customizable and expandable.
Simple creation and composition of units. One can then convert results into a more appropriate unit.
import Physical
var distance1 = 10.5.centimeters
let distance2 = 3.3.feet
distance1 + distance2
distance1 += 14.furlongs
distance1 < 3e-5.miles
let speed = 42.0.kilometersPerHour
distance2 / speed
(distance2 / speed).to(.hours)
distance2 / speed → .millisecondsNote: That's a real unicode arrow character → (U+2192), not ->. It's utterly unnecessary. If you don't want to use it or if you use a keyboard layout that doesn't include it, then you can use the .to() function instead. It's there if you want it.
To create a Physical object with any dimension, just daisy chain units, possibly with exponents. As well, one can force a unit to be in the denominator via / as below. Each unit also has a "per" variant.
let aForce = 1.kilograms.meters.seconds(-2)
aForce → .newtons
6.meters.seconds(-1)
6.meters/.seconds
6.meters.perSecond
12.metersPerSecondSquared
12.meters/.seconds/.seconds
12.m/.s(2)
12.meters.perSecond.perSecondThere are several (hopefully just the right amount of) ways to write a complicated set of units, and one can choose the ones that fit the situation and readability demands.
var density = 27.grams.centimeters(-3)
density = 27.grams.cubicCentimeters(-1)
density = 27.g.cm(-3)
density = 27.g/.cm(3)
density = 27.grams.perCubicCentimeter
density → .milligramsPerDeciliter
density → .gramsPerLiterOne can compose new kinds of Physical objects through standard algebra.
If the combination of items is impossible, the result is a Physical.notAThing, in analogy to NaN when such an impossible math result happens for floating point numbers. Any further use of this object in more equations infect those results in turn. You can check its status using .isNotAThing just as float point numbers have .isNaN. To find out why a variable has become not a thing, you can check its .errorStack which contains a history of its bad fortune since the first moment it became not a thing.
The ~ operator can be used to test commensurability. x ~ y means: Is x of the same dimension as y.
let force = 4.5.newtons // 4.5 N
let mass = 17.poundsMass // 17 lb
force + mass // Not a Thing
(force + mass) / 7.feet // Not a Thing
(force + mass).isNotAThing // true
(force + mass).errorStack // ["4.5 N + 17 lb"]
force.dimensionalDescription // L¹ M¹ T⁻²
mass.dimensionalDescription // M¹
let acceleration = force / mass // 0.58358 m / s²
acceleration → .gravity // 0.059488 g
acceleration ~ 1.gravity // true
1.gravity.withBasicUnits // 9.81 m / s²
force.withBasicUnits // 4.5 kg m / s²
mass * acceleration // 9.9208 lb m / s²
mass * acceleration → .newtons // 4.5 N
mass * acceleration → .joules // Not a Thing
mass * acceleration * 37.feet → .joules // 50.749 JTrig functions use units, contrary to what you might think. Physical provides both trig, exponent and inverse trig functions (normal and hyperbolic) that both wipe out a whole class of bugs ("do I multiply by π and divide by 180?"), but also makes your code, and reasoning about it, greatly improve. These functions are in addition to the standard trig functions and do not conflict with them.
Trig functions map angles to a real number. Inverse functions map real numbers back to angles.
These functions do not interfere with existing old school trig functions and will not contradict any existing algorithms. It's purely opt-in.
75° // 75 °
sin(75°) // 0.96593
asin(sin(75°)) // 1.309 rad
75° → .radians // 1.309 rad
asin(sin(75°)) → .degrees // 75 °
let θ₁ = (2.π/5).radians // 1.2566 rad
let θ₂ = θ₁ → .degrees // 72 °
let θ₃ = θ₁ → .revolutions // 0.2 rev
sin(θ₁) // 0.95106
sin(θ₂) // 0.95106
sin(θ₃) // 0.95106Note: The degree symbol is ° (⇧⌥8 on a US Standard keyboard) and not º (⌥0).
Special considerations must be given to temperature algebra because there are several scales (Celcius and Fahrenheit) that do not have a common zero temperature reference. Thankfully they are at least all linearly related. But there's also not just one zero-based scaling, there are two: Kelvin and Rankine, both supported, though Kelvin is the SI standard reference.
One can easily convert between them, but various algebraic operations will prevent equations from having a unique meaning, and these sums will become notAThing.
2.kelvin → .celsius // -271.2.celsius
25.celsius → .fahrenheit // 77 °F
2 * 100.kelvin // 200 K
2 * 100.celsius // Not a Thing
500.kelvin ^ 4 // 6.25e10 K⁴
500.fahrenheit ^ 4 // Not a Thing
30.fahrenheit < 30.celsius // trueTemperature differences are treated as different kinds of quantities, which expands their meaningful use. A temperature can be either explicitly designated as a difference or implicitly via a subtraction.
50.celsius - 20.celsius // 30.celsius
50.celsius - 20.celsius == 30.kelvin // false
50.celsius - 20.celsius == 30.kelvin.difference // true
50.celsius - 20.celsius == 54.fahrenheit.difference // true
50.fahrenheit + 30.celsius // Not a Thing
50.fahrenheit + 30.celsius.difference // 104 °F
let a = [68.12, 72.22, 120.5].celsius
let b = [30.31, 71.81, 90.33].celsius
a - b → .fahrenheit // [68.06, 0.738, 54.31] ∆°FDecibels are supported, and are always set relative to a reference value. The system supports many standard dB measures as well as allowing you to use arbitrary reference values. (There are no "pure" dB values.) A decibel is not considered unitless, as it represents a physical measure, relative to a reference value. One can freely convert back and forth as is convenient, but one may not use them in contexts where their unwrapped value wouldn't also make sense.
Keeping track of the factor of 2 for power vs non-power ratios is done automatically. (If you use custom non-power-based ratios, these will use the standard factor of 10 log₁₀(ratio) for calculations.)
Some standard measures in common use:
1.pascals.dBSPL // 93.98 dB SPL
30.watts.dBm // 44.77 dBm
30.watts.dBW // 14.77 dBWOne may use custom reference values as follows. (Reference values for custom dB measures shown in parentheses.)
let pressure = 43e-3.pascals
let dBPressure = pressure.dB(reference: 4e-3.newtons.perSquareMeter) // 20.63 dB (0.004 N/m²)
let energy = 10.watts
let dBEnergy = energy.dB(reference: 37.horsepower) // -34.41 dB (37 hp)Physical values that correspond to a dB measure as well as the reference value can be queried.
12.dBm.dBReference // 1 mW
12.dBm.dereferencedValue // 3.981 mW
12.dBK.dBReference // 1 K
12.dBK.dereferencedValue // 3.981 K
8.dBm.ratio // 6.3096
8.dBSPL.ratio // 2.5119
8.dBm ~ Power.self // true
14.dBSPL ~ Pressure.self // trueDecibel algebra works like normal algebra, and can mix with physical measures to quickly be useful in real world scenarios.
0.7.dBW - 21.dBW + 13.dBW // -7.3 dBW
10.watts + 0.7.dBW - 21.dBW + 13.dBW // 1.862 W
1.W + 10.mW.dB(reference: 1.mW) // 10 W
1.W + 10.mW.dB(reference: 2.mW) // 5 W
10.dB(reference: 1.mW) + 10.dB(reference: 2.mW) // 23.01 dBm
√(24.dBm * 600.ohms) → .volts // 12.28 V
12.dBSWL + 4.dBK // Not a ThingThere is much more to say on this topic.
Current issues: There is an issue with the negative - operation that requires numbers for decibels to be put in parentheses. For now be careful to include them or you'll get bad but working numbers. Ex: (-161).dBK.
Physical can work to describe whole arrays at once, also providing acceleration on calculations done on them for free. As well, a ramp function is included, akin to Numpy's linspace function. One can treat arrays an n-dimensional vectors as well, with support for rotating (for now) 2-d arrays.
let fileSizes = [1, 3, 14, -2].gigabytes // [1, 3, 14, -2] GB
let dataRate = 1.megabits.perSecond // 1 Mb / s
(fileSizes / dataRate → .hours) // [2.2222, 6.6667, 31.111, -4.4444] hr
(0.s...50.s).by(20.μs) // [0, 0.00002, 0.00004, ...] seconds
ramp(in: 0...1.pi, count: 27) // [0, 0.1208304866765305, ...]
ramp(in: 0...100, by: 3) // [0, 3, 6, ..., 99]
let angles = ramp(in: 0...1.pi, count: 27).radians.sigfigs(3)
4.meters.repeated(50) // [4, 4, ... ] meters
angles[7] // 0.84581 rad
sin(angles)[7] // 0.74851
var position = [0, 1].meters
var velocity = [0, 1].rotated(32°) * 110.milesPerHourExponents are of a special TieredNumber type, that is alternately an integer, a rational or of floating point value, and will gracefully degrade as needed. This allows equations to recover integer or rational exponents, providing better unit matching and accuracy of results.
let x = 4.76.meters
x^5 // 2,443.6 m⁵
(x^5) ^ 0.2 // 4.76 m
(x^5) ^ 0.2 → .yards // 5.2056 yd
let y = x ^ (3.0/7) // 1.9517 m^(3/7)
y^7 // 107.85 m³
y^7 → .cubicInches // 6.5814e6 in³
x^π // 134.51 m^3.141592653589793
(x^π) ^ (1/π) // 4.76 m^1.0
(x^π) ^ (1/π) → .yards // Not a Thing(Note in the last example that the Double exponent value meant that m^1.0 wasn't exact, and so wasn't commensurate with length.)
One can optionally (a pun!) use strong typing. If one wraps a Physical object with a strong type, the result is an optional. This is done with analogy to how Int(...) and Double(...) etc are optionals in the Swift standard library.
One can create a literal strong type, using the two argument init, Length(value, unit: .meters) (etc) which guarantees unit-correctness and does not produce an optional. A compile-time error will result if the type is selected incorrectly.
To use a strongly typed object with a dynamically-typed Physical object, one need only extract the physical content. (There is room for improvement here.)
Length(45.feet) // optionals, akin to Int("test")
Length(45.hectares) // nil
Length(45, unit: .hectares) // Compile-time error!
let sailHeight = Length(45, unit: .feet) // guaranteed type-correct
sailHeight.physical // retrieve dynamic Physical type
func orbitalRadiusOfChargeInMagneticField(
mass: Mass,
velocity: Speed,
charge: ElectricCharge,
magneticFluxDensity: MagneticFluxDensity) -> Length? {
Length(mass * velocity / (charge * magneticFluxDensity))
}Physical has a rich set of constants with both their units and presently known precision.
let G = Physical.Constants.gravitation
let sunMass = Physical.Constants.Astronomic.Sun.mass
let earthMass = Physical.Constants.Earth.mass
let earthRadius = Physical.Constants.Earth.meanRadius
func orbitHeight(period: Duration) -> Length {
return Length( ∛(G * earthMass * (period^2) / 4.π²) - earthRadius )!
}
let heightISS = orbitHeight(period: Duration(92, unit: .minutes)).physical
heightISS → .miles
func orbitalPeriod(height: Length) -> Duration {
Duration( √(4.π² * ((heightISS + earthRadius)^3) / (G * earthMass)) )!
}
let periodISS = orbitalPeriod(height: Length(254, unit: .miles)).physical
periodISS → .minutesA number of enhancements to float point numbers have been included.
6.pi // sugar
2.π // greek letter π
3.e // 3 * natural number
14.0 ^ 2 // instead of pow(14.0, 2)
√14
√(x + y) // longer expressions need parentheses
∛14 // silly but available
∜14
8√14 // 8th root of 14. can be any integer.
n√14
47% // 0.47
distance *= 2.1%Note: Both π and √ are typable on most keyboard layouts. (On a US Qwerty layout, they're ⌥p and ⌥v.)
Note: Non-ASCII characters all have ASCII equivalents, for those stuck on projects with 20th-century restrictions and Asciitarians.