| // Copyright ©2013 The Gonum Authors. All rights reserved. |
| // Use of this source code is governed by a BSD-style |
| // license that can be found in the LICENSE file. |
| |
| //go:generate go run generate_unit.go |
| |
| // 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 a 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. |
| package unit // import "gonum.org/v1/gonum/unit" |
