Documentation
¶
Overview ¶
Package unit provides a set of types and constants that facilitate the use of the International System of Units (SI).
The unit package provides two main functionalities: compile-time type-safe base SI units and common derived units; and a system for dynamically extensible user-defined units.
Static SI units ¶
This package provides a number of types representing either an SI base unit or a common combination of base units, named for the physical quantity it represents (Length, Mass, Pressure, etc.). Each type is defined from float64. The value of the float64 represents the quantity of that unit as expressed in SI base units (kilogram, metre, Pascal, etc.). For example,
height := 1.6 * unit.Metre acc := unit.Acceleration(9.8)
creates a variable named 'height' with a value of 1.6 metres, and a variable named 'acc' with a value of 9.8 metres per second squared. These types can be used to add compile-time safety to code. For example,
func unitVolume(t unit.Temperature, p unit.Pressure) unit.Volume {
...
}
func main(){
t := 300 * unit.Kelvin
p := 500 * unit.Kilo * unit.Pascal
v := unitVolume(p, t) // compile-time error
}
gives a compile-time error (temperature type does not match pressure type) while the corresponding code using float64 runs without error.
func float64Volume(temperature, pressure float64) float64 {
...
}
func main(){
t := 300.0 // Kelvin
p := 500000.0 // Pascals
v := float64Volume(p, t) // no error
}
Many types have constants defined representing named SI units (Metre, Kilogram, etc. ) or SI derived units (Pascal, Hz, etc.). The unit package additionally provides untyped constants for SI prefixes, so the following are all equivalent.
l := 0.001 * unit.Metre k := 1 * unit.Milli * unit.Metre j := unit.Length(0.001)
Additional SI-derived static units can also be defined by adding types that satisfy the Uniter interface described below.
Dynamic user-extensible unit system ¶
The unit package also provides the Unit type, a representation of a general dimensional value. Unit can be used to help prevent errors of dimensionality when multiplying or dividing dimensional numbers defined at run time. New variables of type Unit can be created with the New function and the Dimensions map. For example, the code
rate := unit.New(1 * unit.Milli, Dimensions{MoleDim: 1, TimeDim: -1})
creates a variable "rate" which has a value of 1e-3 mol/s. Methods of unit can be used to modify this value, for example:
rate.Mul(1 * unit.Centi * unit.Metre).Div(1 * unit.Milli * unit.Volt)
To convert the unit back into a typed float64 value, the From methods of the dimensional types should be used. From will return an error if the dimensions do not match.
var energy unit.Energy err := energy.From(acc)
Domain-specific problems may need custom dimensions, and for this purpose NewDimension should be used to help avoid accidental overlap between packages. For example, results from a blood test may be measured in "White blood cells per slide". In this case, NewDimension should be used to create a 'WhiteBloodCell' dimension. NewDimension takes in a string which will be used for printing that dimension, and will return a unique dimension number.
wbc := unit.NewDimension("WhiteBloodCell")
NewDimension should not be used, however, to create the unit of 'Slide', because in this case slide is just a measurement of liquid volume. Instead, a constant could be defined.
const Slide unit.Volume = 0.1 * unit.Micro * unit.Litre
Note that unit cannot catch all errors related to dimensionality. Different physical ideas are sometimes expressed with the same dimensions and unit is incapable of catching these mismatches. For example, energy and torque are both expressed as force times distance (Newton-metres in SI), but it is wrong to say that a torque of 10 N·m is the same as 10 J, even though the dimensions agree. Despite this, using the defined types to represent units can help to catch errors at compile-time. For example, using unit.Torque allows you to define a statically typed function like so
func LeverLength(apply unit.Force, want unit.Torque) unit.Length {
return unit.Length(float64(want)/float64(apply))
}
This will prevent an energy value being provided to LeverLength in place of a torque value.
Example (Horsepower) ¶
package main
import (
"fmt"
"gonum.org/v1/gonum/unit"
)
func main() {
// One mechanical horsepower ≡ 33,000 ft-lbf/min.
foot := unit.Length(0.3048)
pound := unit.Mass(0.45359237)
gravity := unit.Acceleration(9.80665)
poundforce := pound.Unit().Mul(gravity)
hp := ((33000 * foot).Unit().Mul(poundforce)).Div(unit.Minute)
fmt.Println("1 hp =", hp)
watt := unit.Power(1)
fmt.Println("W is equivalent to hp?", unit.DimensionsMatch(hp, watt))
}
Output: 1 hp = 745.6998715822701 kg m^2 s^-3 W is equivalent to hp? true
Index ¶
- Constants
- func DimensionsMatch(a, b Uniter) bool
- func SymbolExists(symbol string) bool
- type AbsorbedRadioactiveDose
- type Acceleration
- type Angle
- type Area
- type Capacitance
- type Charge
- type Conductance
- type Current
- type Dimension
- type Dimensions
- type Dimless
- type Energy
- type EquivalentRadioactiveDose
- type Force
- type Frequency
- type Inductance
- type Length
- type LuminousIntensity
- type MagneticFlux
- type MagneticFluxDensity
- type Mass
- type Mole
- type Power
- type Pressure
- type Radioactivity
- type Resistance
- type Temperature
- type Time
- type Torque
- type Unit
- func (u *Unit) Add(uniter Uniter) *Unit
- func (u *Unit) Copy() *Unit
- func (u *Unit) Dimensions() Dimensions
- func (u *Unit) Div(uniter Uniter) *Unit
- func (u *Unit) Format(fs fmt.State, c rune)
- func (u *Unit) Mul(uniter Uniter) *Unit
- func (u *Unit) SetValue(v float64)
- func (u *Unit) Unit() *Unit
- func (u *Unit) Value() float64
- type Uniter
- type Velocity
- type Voltage
- type Volume
Examples ¶
Constants ¶
const ( Yotta = 1e24 Zetta = 1e21 Exa = 1e18 Peta = 1e15 Tera = 1e12 Giga = 1e9 Mega = 1e6 Kilo = 1e3 Hecto = 1e2 Deca = 1e1 Deci = 1e-1 Centi = 1e-2 Milli = 1e-3 Micro = 1e-6 Nano = 1e-9 Pico = 1e-12 Femto = 1e-15 Atto = 1e-18 Zepto = 1e-21 Yocto = 1e-24 )
const ( Second Time = 1 Minute = 60 * Second Hour = 60 * Minute )
Variables ¶
This section is empty.
Functions ¶
func DimensionsMatch ¶
DimensionsMatch checks if the dimensions of two Uniters are the same.
func SymbolExists ¶
SymbolExists returns whether the given symbol is already in use.
Types ¶
type AbsorbedRadioactiveDose ¶
type AbsorbedRadioactiveDose float64
AbsorbedRadioactiveDose is a measure of absorbed dose of ionizing radiation in grays.
const Gray AbsorbedRadioactiveDose = 1
func (AbsorbedRadioactiveDose) AbsorbedRadioactiveDose ¶
func (a AbsorbedRadioactiveDose) AbsorbedRadioactiveDose() AbsorbedRadioactiveDose
AbsorbedRadioactiveDose allows AbsorbedRadioactiveDose to implement a AbsorbedRadioactiveDoseer interface.
func (AbsorbedRadioactiveDose) Format ¶
func (a AbsorbedRadioactiveDose) Format(fs fmt.State, c rune)
func (*AbsorbedRadioactiveDose) From ¶
func (a *AbsorbedRadioactiveDose) From(u Uniter) error
From converts the unit into the receiver. From returns an error if there is a mismatch in dimension.
func (AbsorbedRadioactiveDose) Unit ¶
func (a AbsorbedRadioactiveDose) Unit() *Unit
Unit converts the AbsorbedRadioactiveDose to a *Unit.
type Acceleration ¶
type Acceleration float64
Acceleration represents an acceleration in metres per second squared.
func (Acceleration) Acceleration ¶
func (a Acceleration) Acceleration() Acceleration
Acceleration allows Acceleration to implement a Accelerationer interface.
func (*Acceleration) From ¶
func (a *Acceleration) From(u Uniter) error
From converts the unit into the receiver. From returns an error if there is a mismatch in dimension.
func (Acceleration) Unit ¶
func (a Acceleration) Unit() *Unit
Unit converts the Acceleration to a *Unit.
type Angle ¶
type Angle float64
Angle represents an angle in radians.
const Rad Angle = 1
type Area ¶
type Area float64
Area represents an area in square metres.
type Capacitance ¶
type Capacitance float64
Capacitance represents an electrical capacitance in Farads.
const Farad Capacitance = 1
func (Capacitance) Capacitance ¶
func (cp Capacitance) Capacitance() Capacitance
Capacitance allows Capacitance to implement a Capacitancer interface.
func (*Capacitance) From ¶
func (cp *Capacitance) From(u Uniter) error
From converts the unit into the receiver. From returns an error if there is a mismatch in dimension.
func (Capacitance) Unit ¶
func (cp Capacitance) Unit() *Unit
Unit converts the Capacitance to a *Unit.
type Charge ¶
type Charge float64
Charge represents an electric charge in Coulombs.
const Coulomb Charge = 1
type Conductance ¶
type Conductance float64
Conductance represents an electrical conductance in Siemens.
const Siemens Conductance = 1
func (Conductance) Conductance ¶
func (co Conductance) Conductance() Conductance
Conductance allows Conductance to implement a Conductancer interface.
func (*Conductance) From ¶
func (co *Conductance) From(u Uniter) error
From converts the unit into the receiver. From returns an error if there is a mismatch in dimension.
func (Conductance) Unit ¶
func (co Conductance) Unit() *Unit
Unit converts the Conductance to a *Unit.
type Current ¶
type Current float64
Current represents a current in Amperes.
const Ampere Current = 1
type Dimension ¶
type Dimension int
Dimension is a type representing an SI base dimension or a distinct orthogonal dimension. Non-SI dimensions can be created using the NewDimension function, typically within an init function.
const ( CurrentDim Dimension LengthDim LuminousIntensityDim MassDim MoleDim TemperatureDim TimeDim // Other common SI Dimensions AngleDim // e.g. radians )
func NewDimension ¶
NewDimension creates a new orthogonal dimension with the given symbol, and returns the value of that dimension. The input symbol must not overlap with any of the any of the SI base units or other symbols of common use in SI ("kg", "J", etc.), and must not overlap with any other dimensions created by calls to NewDimension. The SymbolExists function can check if the symbol exists. NewDimension will panic if the input symbol matches an existing symbol.
NewDimension should only be called for unit types that are actually orthogonal to the base dimensions defined in this package. See the package-level documentation for further explanation.
Example ¶
package main
import (
"fmt"
"gonum.org/v1/gonum/unit"
)
func main() {
// Create a "trees" dimension
// Typically, this should be used within an init function
treeDim := unit.NewDimension("tree")
countPerArea := unit.New(0.1, unit.Dimensions{treeDim: 1, unit.LengthDim: -2})
fmt.Println(countPerArea)
}
Output: 0.1 tree m^-2
type Dimensions ¶
Dimensions represent the dimensionality of the unit in powers of that dimension. If a key is not present, the power of that dimension is zero. Dimensions is used in conjunction with New.
func (Dimensions) String ¶
func (d Dimensions) String() string
type Dimless ¶
type Dimless float64
Dimless represents a dimensionless constant.
type Energy ¶
type Energy float64
Energy represents a quantity of energy in Joules.
const Joule Energy = 1
type EquivalentRadioactiveDose ¶
type EquivalentRadioactiveDose float64
EquivalentRadioactiveDose is a measure of equivalent dose of ionizing radiation in sieverts.
const Sievert EquivalentRadioactiveDose = 1
func (EquivalentRadioactiveDose) EquivalentRadioactiveDose ¶
func (a EquivalentRadioactiveDose) EquivalentRadioactiveDose() EquivalentRadioactiveDose
EquivalentRadioactiveDose allows EquivalentRadioactiveDose to implement a EquivalentRadioactiveDoseer interface.
func (EquivalentRadioactiveDose) Format ¶
func (a EquivalentRadioactiveDose) Format(fs fmt.State, c rune)
func (*EquivalentRadioactiveDose) From ¶
func (a *EquivalentRadioactiveDose) From(u Uniter) error
From converts the unit into the receiver. From returns an error if there is a mismatch in dimension.
func (EquivalentRadioactiveDose) Unit ¶
func (a EquivalentRadioactiveDose) Unit() *Unit
Unit converts the EquivalentRadioactiveDose to a *Unit.
type Force ¶
type Force float64
Force represents a force in Newtons.
const Newton Force = 1
type Frequency ¶
type Frequency float64
Frequency represents a frequency in Hertz.
const Hertz Frequency = 1
type Inductance ¶
type Inductance float64
Inductance represents an electrical inductance in Henry.
const Henry Inductance = 1
func (*Inductance) From ¶
func (i *Inductance) From(u Uniter) error
From converts the unit into the receiver. From returns an error if there is a mismatch in dimension.
func (Inductance) Inductance ¶
func (i Inductance) Inductance() Inductance
Inductance allows Inductance to implement a Inductancer interface.
type Length ¶
type Length float64
Length represents a length in metres.
const Metre Length = 1
func (*Length) From ¶
From converts the unit into the receiver. From returns an error if there is a mismatch in dimension.
type LuminousIntensity ¶
type LuminousIntensity float64
Candela represents a luminous intensity in candela.
const Candela LuminousIntensity = 1
func (*LuminousIntensity) From ¶
func (j *LuminousIntensity) From(u Uniter) error
From converts the unit into the receiver. From returns an error if there is a mismatch in dimension.
func (LuminousIntensity) LuminousIntensity ¶
func (j LuminousIntensity) LuminousIntensity() LuminousIntensity
LuminousIntensity allows LuminousIntensity to implement a LuminousIntensityer interface.
func (LuminousIntensity) Unit ¶
func (j LuminousIntensity) Unit() *Unit
Unit converts the LuminousIntensity to a *Unit.
type MagneticFlux ¶
type MagneticFlux float64
MagneticFlux represents a magnetic flux in Weber.
const Weber MagneticFlux = 1
func (*MagneticFlux) From ¶
func (m *MagneticFlux) From(u Uniter) error
From converts the unit into the receiver. From returns an error if there is a mismatch in dimension.
func (MagneticFlux) MagneticFlux ¶
func (m MagneticFlux) MagneticFlux() MagneticFlux
MagneticFlux allows MagneticFlux to implement a MagneticFluxer interface.
func (MagneticFlux) Unit ¶
func (m MagneticFlux) Unit() *Unit
Unit converts the MagneticFlux to a *Unit.
type MagneticFluxDensity ¶
type MagneticFluxDensity float64
MagneticFluxDensity represents a magnetic flux density in Tesla.
const Tesla MagneticFluxDensity = 1
func (*MagneticFluxDensity) From ¶
func (m *MagneticFluxDensity) From(u Uniter) error
From converts the unit into the receiver. From returns an error if there is a mismatch in dimension.
func (MagneticFluxDensity) MagneticFluxDensity ¶
func (m MagneticFluxDensity) MagneticFluxDensity() MagneticFluxDensity
MagneticFluxDensity allows MagneticFluxDensity to implement a MagneticFluxDensityer interface.
func (MagneticFluxDensity) Unit ¶
func (m MagneticFluxDensity) Unit() *Unit
Unit converts the MagneticFluxDensity to a *Unit.
type Mass ¶
type Mass float64
Mass represents a mass in kilograms.
type Mole ¶
type Mole float64
Mole represents an amount in moles.
const Mol Mole = 1
type Power ¶
type Power float64
Power represents a power in Watts.
const Watt Power = 1
func (*Power) From ¶
From converts the unit into the receiver. From returns an error if there is a mismatch in dimension.
type Pressure ¶
type Pressure float64
Pressure represents a pressure in Pascals.
const Pascal Pressure = 1
func (*Pressure) From ¶
From converts the unit into the receiver. From returns an error if there is a mismatch in dimension.
type Radioactivity ¶
type Radioactivity float64
Radioactivity represents a rate of radioactive decay in becquerels.
const Becquerel Radioactivity = 1
func (*Radioactivity) From ¶
func (r *Radioactivity) From(u Uniter) error
From converts the unit into the receiver. From returns an error if there is a mismatch in dimension.
func (Radioactivity) Radioactivity ¶
func (r Radioactivity) Radioactivity() Radioactivity
Radioactivity allows Radioactivity to implement a Radioactivityer interface.
func (Radioactivity) Unit ¶
func (r Radioactivity) Unit() *Unit
Unit converts the Radioactivity to a *Unit.
type Resistance ¶
type Resistance float64
Resistance represents an electrical resistance, impedance or reactance in Ohms.
const Ohm Resistance = 1
func (*Resistance) From ¶
func (r *Resistance) From(u Uniter) error
From converts the unit into the receiver. From returns an error if there is a mismatch in dimension.
func (Resistance) Resistance ¶
func (r Resistance) Resistance() Resistance
Resistance allows Resistance to implement a Resistancer interface.
type Temperature ¶
type Temperature float64
Temperature represents a temperature in Kelvin.
const Kelvin Temperature = 1
func (*Temperature) From ¶
func (t *Temperature) From(u Uniter) error
From converts the unit into the receiver. From returns an error if there is a mismatch in dimension.
func (Temperature) Temperature ¶
func (t Temperature) Temperature() Temperature
Temperature allows Temperature to implement a Temperaturer interface.
func (Temperature) Unit ¶
func (t Temperature) Unit() *Unit
Unit converts the Temperature to a *Unit.
type Time ¶
type Time float64
Time represents a duration in seconds.
type Torque ¶
type Torque float64
Torque represents a torque in Newton metres.
const Newtonmetre Torque = 1
func (*Torque) From ¶
From converts the unit into the receiver. From returns an error if there is a mismatch in dimension.
type Unit ¶
type Unit struct {
// contains filtered or unexported fields
}
Unit represents a dimensional value. The dimensions will typically be in SI units, but can also include dimensions created with NewDimension. The Unit type is most useful for ensuring dimensional consistency when manipulating types with different units, for example, by multiplying an acceleration with a mass to get a force. See the package documentation for further explanation.
func New ¶
func New(value float64, d Dimensions) *Unit
New creates a new variable of type Unit which has the value and dimensions specified by the inputs. The built-in dimensions are always in SI units (metres, kilograms, etc.).
Example ¶
package main
import (
"fmt"
"gonum.org/v1/gonum/unit"
)
func main() {
// Create an angular acceleration of 3 rad/s^2
accel := unit.New(3.0, unit.Dimensions{unit.AngleDim: 1, unit.TimeDim: -2})
fmt.Println(accel)
}
Output: 3 rad s^-2
func (*Unit) Add ¶
Add adds the function argument to the receiver. Panics if the units of the receiver and the argument don't match.
func (*Unit) Copy ¶ added in v0.9.0
Copy returns a copy of the Unit that can be mutated without the change being reflected in the original value.
func (*Unit) Dimensions ¶
func (u *Unit) Dimensions() Dimensions
Dimensions returns a copy of the dimensions of the unit.
func (*Unit) Div ¶
Div divides the receiver by the argument changing the dimensions of the receiver as appropriate.
func (*Unit) Format ¶
Format makes Unit satisfy the fmt.Formatter interface. The unit is formatted with dimensions appended. If the power of the dimension is not zero or one, symbol^power is appended, if the power is one, just the symbol is appended and if the power is zero, nothing is appended. Dimensions are appended in order by symbol name with positive powers ahead of negative powers.
func (*Unit) Mul ¶
Mul multiply the receiver by the input changing the dimensions of the receiver as appropriate. The input is not changed.
type Uniter ¶
type Uniter interface {
Unit() *Unit
}
Uniter is a type that can be converted to a Unit.
type Velocity ¶
type Velocity float64
Velocity represents a velocity in metres per second.
type Voltage ¶
type Voltage float64
Voltage represents a voltage in Volts.
const Volt Voltage = 1
Source Files
¶
- absorbedradioactivedose.go
- acceleration.go
- angle.go
- area.go
- capacitance.go
- charge.go
- conductance.go
- current.go
- dimless.go
- doc.go
- energy.go
- equivalentradioactivedose.go
- force.go
- frequency.go
- inductance.go
- length.go
- luminousintensity.go
- magneticflux.go
- magneticfluxdensity.go
- mass.go
- mole.go
- power.go
- prefixes.go
- pressure.go
- radioactivity.go
- resistance.go
- temperature.go
- time.go
- torque.go
- unittype.go
- velocity.go
- voltage.go
- volume.go
Directories