# Introduction
Unitment supports dynamic unit management so users can focus on what matters.
**Install:**
To get started, [download](https://www.python.org/downloads/) and install python, then open your terminal and run the following pip command:
`pip install unitment`
**Example**:
```
from unitment import Unit,Measure
distance = Measure("25 m")
time = Measure("5 s")
speed = distance / time
print(speed)
```
Above is a simple script using unitment. Save this text to file as `example.py`.
Open the terminal wherever you saved the file, then run `python example.py`.
You can imagine how to edit the script for your own purpose.
____________________________________________________________
____________________________________________________________
# Basics Features
Unitment's core feature is **Dynamic Unit Management.** This allows users to use *any* units on the fly.
This includes arbitrary units like fish, rocks, pizza, happiness, etc. Users don't even need to define their units!
Unitment is ideal for scripting. It's **Intuitive and Adaptive**, so that even novice coders can use it.
Measures can be defined several intuitive ways: `Measure("5 m")`, `Measure(5,"m")`, `Measure(value=5,units="m")`, etc.
Adaptive typing makes coding more forgiving: `Measure("25 m")/Measure("5 s")`, `Measure("25 m")/"5s"`, etc.
- **Spaces Required**
- `"ms"` is milliseconds
- `"m s"` is meter seconds
- **Unit Conversions**
- Metric is Pre-Defined.
- Simplify with `measure.simplify()`
- Convert with `measure.convert(unit)`
- Abnormal Unit Dictionaries (*optional*)
- `Unit.IMPERIAL_UNITS`
- `Unit.PRESSURE_UNITS`
Again, users never *need* to define units in unitment.
Still, a unit-dictionaries argument in instantiation or conversion can be convenient for automatic conversion to metric.
In-fact, all math in unitment is converted to base-units before preformed.
This prevents silly errors like multiplying the Celsius temperature instead of the Kelvin temperature,
but it requires users to understand whether they intend to add 1°C or 1K.
**Other Operations.**
In addition to the standard math operators, convert, and simplify; unitment the following functions:
`measure.is_simplified()`, `measure.sin()`, `measure.cos()`, `measure.exp()`, `measure.root()`, `measure.sqrt()`, `measure.log(base)`, `measure.ln()`, `measure.log10()`, and `measure1.approx(measure2)`.
____________________________________________________________
# Intermediate Features
**What about NumPy?**
NumPy is a popular package for doing math with matricies.
It's useful both for its widely-known notation and its efficient speed.
If you're using NumPy for its widely-known notation, simply add the argument `dtype=numpy.dtype(Measure)` in your NumPy array.
If you're using NumPy for its efficient speed, never use non-standard number types.
Use this module as a parser and converter then use `float(measure)` to convert to standard floats.
To that end a useful line of code might be:
```
# Step-By-Step
list_of_measures = [ Measure(str_measure) for str_measure in list_of_str_measures ]
list_of_measures_in_unit = [ measure.convert(unit) for measure in list_of_measures ]
list_of_floats_in_unit = [ float(measure) for measure in list_of_measures_in_unit ]
# All at Once
list_of_floats_in_unit = [float(Measure(str_measure).convert(unit)) for str_measure in list_of_str_measures]
```
**Conversions to Non-Metric Units**
One common gripe about the `convert` function is that it doesn't propagate unit definitions.
This results in situations where a conversion of inches to feet might be interpreted as an attempt to convert inches to femto-tonnes, resulting in an error: `Measure("12 in",Unit.IMPERIAL_UNITS).convert("ft")` throws a UnitException for incompatible units.
This is because the user failed to re-define `"ft"` in the conversion function.
The proper way to convert to any non-metric unit is to define the unit in either convert or in the passed unit: `Measure("12 in",Unit.IMPERIAL_UNITS).convert("ft",Unit.IMPERIAL_UNITS)` or `Measure("12 in",Unit.IMPERIAL_UNITS).convert(Unit("ft",Unit.IMPERIAL_UNITS))`.
____________________________________________________________
____________________________________________________________
Consider supporting unitment on [patreon](https://www.patreon.com/user?u=83796428).
____________________________________________________________
____________________________________________________________
# Technical Features
- Unit Compatibility. This module works with *almost any* units.
While metric units are used by default, imperial units are defined as a class constant (`Measure("degF",Unit.IMPERIAL_UNITS)`).
Arbitrary units can be used as their own (non-physical) dimension without being explicitly defined - albeit without prefixes, conversion-functions, or decompositions.
More advanced units can easily be loaded or defined for automatic conversion to base-units and the unit definitions propagate with the units themselves.
Indeed, some advanced units (pH, Celsius) are already defined.
- Intuitive Instantiation. Units and Measures are made with easy constructors in this package: e.g. `Measure("5 m")`, `Measure(5,"m")`, `Measure(value=5,units="m")`, etc.
Users needn't familiarize themselves with a cluttered or convoluted namespace or even understand much python or coding in general.
Again, the goal is to allow the users to focus on their maths in abstract-terms that maintain perspective on their problem, rather than dragging unit-hell into coding.
- Math in Dimensions. Each Unit and Measure automatically decomposes and simplifies to base-unit form prior to preforming mathematical operations.
This allows math to be done in terms of the actual base-dimensions, which is crucial for some units (e.g. ℃).
Where possible, the original units are retained for the final result.
As a result, users needn't think in terms of units after they've been defined.
Users may focus on doing math in the more abstract terms or at the level of the dimension.
- Propagation of Error. Propagation of error is built into every operator.
While this is a worst-case (non-abstract) error calculation, it helps users gain a grasp on the reliability-of and precision-needed-for their system.
- Low Over-head. A lot of effort was put into preventing the module from being slow.
While it could be faster at cost of code maintainability or usability, it is quite fast for what it does.
Moreover, the module's only dependencies are in the Python Standard Library (Mostly the `math` and `decimal` modules).
Overall, this module is well suited for scripting purposes.
All that said, the choice of unit management module does depend on use-case.
The general advise for users is to use this module for scripting simple math or conversions.
While this module may work for surprisingly complicated things, we recommend removing units altogether for advanced applications.
In such cases, this module may still be useful as a parser.
## Measure
`Measure` is the primary class in this package. Measures have a value, a unit, and an error. The error is often implied.
This class reflects the logical structure in its properties: `value`, `units`, and `error`. Likewise, the error is inferred if not explicitly provided.
The value and unit properties are numbers. The unit is defined more extensively below.
**Instantiation:**
This class is built to be instantiated casually and intuitively, e.g. `Measure("25 m")`, so reasonable string inputs should be processed as expected.
That said, care should be taken to leave a space between symbols as milliseconds (`"ms"`) are quite different from meter seconds (`"m s"`).
Beyond that, the parser is fairly robust. It is generally capable of handling exponents and error notations.
The class can also be instantiated with the keywords `value`, `error`, and `unit` or `units`.
**Dominant:** The Measure class dominates in mathematical operations, so a float * Measure = Measure.
For very large programs with very large numbers of operations, this will slow down the program.
For maximum efficiency, it's always better to use this package as a parser and converter then cast the measure as a float.
For example:
x_raw = "2583 cm"
x_meters = float(Measure(x_raw).convert("m"))
### Value
The class will accept and Number or would-be number as a value. This includes Decimals, floats, ints, and strings that can be converted to decimals.
Internally the class will preserve Decimals until it encounters a float mathematical operations, at which point all internal values will convert to floats.
If inputting the value as an argument rather than a keyword or parsed string, the first number will be considered the value, the second the error.
### Error
**Definition of Error:** This module defines error as the square root of the variance: the standard deviation.
**Numerical Error Assumption:**
Since the module is not context-aware, propagation of error occurs with the assumption of numerical (and thus non-canceling) inputs for every operation.
This worse-case assumption is used because the module cannot be aware of its analytical context.
For example, analytically one knows that a - b + b = a.
Without context-awareness, the 'big-picture' cannot be observed and the module must operate numerically.
The module (like most code) sees (a-b), solves this as c, sees (c+b), and solves that. Propagation of error occurs at each step.
As a result, extra propagation of error occurs where none should exist in analytical contexts.
**Propagation of Error Equations:**
The propagation of error equation (the taylor-series expansion of the statistical moments) for a function with two inputs is as follows:
var(f) = (∂f/∂x)<sup>2</sup> var(x) + (∂f/∂x) (∂f/∂y) covar(x) + (∂f/∂y)<sup>2</sup> var(y)
Since the module is not context-aware, it must assume independent inputs; thus, this equation is more appropriate:
var(f) = (∂f/∂x)<sup>2</sup> var(x) + (∂f/∂y)<sup>2</sup> var(y)
That is the equation used by the module. For edification of the reader, this equation can be extended to multi-input function as follows:
var(f) = Σ (∂f/∂xi)<sup>2</sup> var(x<sub>i</sub>)
**Propagation of Error Failures:**
Since each of these are essentially the same equation all-be-it in slightly different contexts, they share the requirements of taylor-series expansions.
Namely, the functions must be sufficiently differentiable and the approximations must be sufficiently local.
The floor, ceil, and round functions are not sufficiently differentiable for the taylor series expansions for the moments to be valid.
Given this and that most users would not be using them in a mathematically rigorous context, these functions do not propagate error properly.
The modulo function is defined in terms of the floor function (i.e. x % y = x-y*floor(x/y)); thus, it also does not propagate error properly.
Other non-linear functions (such as log) are likely accurate locally (for very small errors), but are at greater risk of inaccuracies as values increase.
**Implied Errors:**
For implied errors of given values (i.e. `Measure(10.0,"m")`), the module gives it's best guess by converting the value to a string.
This can produce incorrect results with floats (e.g. `Measure(float(10),"m")`).
As such, if concerned with error inputting values as strings or Decimal is recommended when not defining the error explicitly with keywords.
### Restrictions on Mathematics
Restrictions are put on the mathematics due to the presence of units. These should all be fairly intuitive.
The most obvious restriction is that measurements with different units cannot be added together.
One can use a simple taylor series to show that this restriction implies that units must cancel in exponents.
## Units
Units are labels for self-consistent chunks of dimensions.
These dimensions can be physical, non-physical, or even complex abstractions.
Despite the possible dimensions, units have a consistent logic-structure.
This allows them to be defined and categorized by complexity:
- **Base Unit:** Base Units are singular and cannot be converted into other units. Examples: `"m"`, `"fish"`.
- **Derived Unit:** Derived Units are singular but can be converted into other units. Examples: `"cm"`, `"J"`.
- **Compound Unit:** Compound Units are multiple logically related units. Examples: `"cm / fish"`, `"J / m"`
The `Unit` class is for base, derived, or compound units with multiple base-dimensions and/or magnitude modifiers.
Here, the term "symbol" or "symbols" refers to a singular unit (base-unit or derived-unit) regardless of the length of the string.
To that end, the class is ultimately composed of a tuple of string symbols, a magnitude, and up-to one conversion function.
**Instantiation:**
This class is built to be instantiated casually and intuitively, e.g. `Unit("m")`, so reasonable string inputs should be processed as expected.
That said, care should be taken to leave a space between symbols as milliseconds (`"ms"`) are quite different from meter seconds (`"m s"`).
Of-course, the class can also be instantiated more formally. Unit has three keywords for defining symbols: `numerators` and `denominators`, or `symbols`.
These keywords accept tuples of string-units, e.g. `("m","s")`, or tuples of string-unit exponent tuple pairs, e.g. `( ("m",1), ("s",-1) )`.
The keyword `magnitude` accepts numbers to define the magnitude of a unit.
As an example, each of the following instantiated units have the same symbols
Unit("m/s")
Unit("m s^-1")
Unit(numerators=("m",),denominators=("s",))
Unit(numerators=(("m",1),),denominators=(("s",1),))
Unit(symbols=(("m",1),("s",-1),))
As an example, each of the following instantiated units have the same magnitudes:
Unit("1e6 fish")
Unit("fish", magnitude=1e6)
Unit("1000000 fish")
Unit("10^6 fish")
### Defining Units
Generally, users do not need to define custom units. If a user wants to use some arbitrary unit such as `Unit("fish")`, the module is fully capable of managing that.
It is also trivial to add magnitudes to arbitrary units (e.g. `Unit("10^6 fish")`), so some users may find it simpler to replace prefixes `.replace("Mfish","10^6 fish")`.
Moreover, the module has a number of predefined sets of non-standard units `Unit.IMPERIAL_UNITS`, `Unit.PRESSURE_UNITS`, `Unit.CONCENTRATION_UNITS` that can be loaded into the Unit or Measure class with an additional argument or the keywords `defs` or `definitions`.
u = Unit("ft",Unit.IMPERIAL_UNITS)
m = Measure("3 ft",Unit.IMPERIAL_UNITS)
While arbitrary units are handled on the fly, some users may need to define custom units when dealing with non-standard derived units or prefixed units.
Of course units are handled dynamically in the module, so units only need to be defined for simplifications, decompositions, or conversions.
Again, metric units are defined by default, so defining units is generally unnecessary. Still, users can define arbitrary derived or prefixed units:
weird_unit_dict = {
# Symbol Mult Base-Symbol Function
'mu' : ( Decimal("1e-3"), (('u',1),), None),
'ku' : ( Decimal("1e3"), (('u',1),), None),
}
x = Measure("5 ku",weird_unit_dict).convert("u")
y = Measure("5 ku",weird_unit_dict).convert("mu",weird_unit_dict)
If defining a derived unit in terms of metric units it's worth noting that the module considers metric base units to be units without a prefix (except kg).
This is important. Any unit defined in terms of prefixed-metric base-units (except kg's) may have unexpected behavior. kg, not g, is considered the base unit of mass.
weird_unit_dict = {
# Symbol Mult Base-Symbol Function
'u' : ( Decimal(1), (('kg',-1),), None),
'v' : ( Decimal("1e3"), (('s',-2),), None),
}
x = Measure("5 u",weird_unit_dict).convert("kg-1")
x = Measure("5 v",weird_unit_dict).convert("s-2")
**Context Dependent Units:**
Some function units, most notably the Decibel (dB) or Bel (B), have a context dependent meaning; thus, the user is responsible for defining them prior to use.
The Decibel has multiple definitions depending on whether it is a power (`10*((val/ref).log10)`) or amplitude (`20*((val/ref).log10)`) measurement.
Moreover, the reference (`ref`) is extremely context specific. For example, a milli-watt microbel (uBmW) is a context independent power measurement defined with respect to a milli-watt reference.
Despite its context independence, it is considered obscure and non-metric (even when using a metric reference); thus, the user is responsible for defining such units prior to use.
To define a context dependent unit the magnitude, base units, and selector-conversion functions are required.
The selector function simply determines the behavior (the conversion functions used) given the exponent.
The conversion functions are to and from base units. As an example:
def DECIBEL_SELECTOR(exponent):
"""
In non-under-water Acoustics the decible is defined as follows:
dB = 20 log10( value / 20 uPa )
In base units:
dB = 20 log10( value / (20e-6 kg^1 m^-1 s^-2 ) )
To reverse this calculation solve for the initial value:
value = 10^(dB / 20) * 20e-6 kg^1 m^-1 s^-2
"""
# Decibel Functions
def NUMERATOR_FROM_DECIBEL_TO_BASE(val):
val,scale,ref = unitment._type_corrections_(val,Decimal("20"),Decimal("20e-6"))
return 10**(val/scale) * ref
def NUMERATOR_TO_DECIBEL_FROM_BASE(val):
val,scale,ref = unitment._type_corrections_(val,Decimal("20"),Decimal("20e-6"))
return scale * (val/ref).log10()
# Most Function Units behave like normal units when on the denominator.
def DENOMINATOR_FROM_DECIBEL_TO_BASE(val):
return val
def DENOMINATOR_TO_DECIBEL_FROM_BASE(val):
return val
# Select & Return Correct Function
if(exponent == 0): return (lambda x:x,lambda x:x)
if(exponent == 1): return ( NUMERATOR_FROM_DECIBEL_TO_BASE , NUMERATOR_TO_DECIBEL_FROM_BASE )
if(exponent == -1): return ( DENOMINATOR_FROM_DECIBEL_TO_BASE , DENOMINATOR_TO_DECIBEL_FROM_BASE )
else:
raise ValueError(f"Failed to Decompose: Exponent of dB != 1,0,-1. Cannot Deconvolute.")
dB_dict = {
# Symbol Mult Base-Symbol Function
'dB' : ( 1, (('kg',1),('m',-1),('s',-2)), DECIBEL_SELECTOR),
}
x = Measure("5 dB",dB_dict).convert("uPa")
***If you make your a unit dictionary you'd like included in the package, please reach out to me.***
____________________________________________________________
# Frequently Asked Questions
## What Types of numbers does it work with?
Thoroughly tested with Decimals, ints, floats. Might work with complex numbers from cmath, but not tested.
It might not fail with other Numbers, but no guarantees.
## Propagation (Domination) of the Measure class.
When using the measure in maths you may find that most things convert to the measure class in the final result.
Sometimes this makes sense, a scalar times a measure should be a measure. Other times this may seem annoying, as in unitless values.
Unitless Measures are returned to help track the propagation of error.
One can always access the value via the value property or by casting the measure as a float.
## How does the module handle Celsius and Fahrenheit?
Just like every other unit, Celsius and Fahrenheit are decomposed (into Kelvin) prior to any math being done.
Most unit managers do not do this because it is difficult to code addition into conversion functions.
This module manages the difficult part; however, certain non-base units are invalid because they cannot be decomposed: e.g. `Measure("10 degC m")` will throw an error.
The reason is the module cannot know what portion of the unit belongs to each component: e.g. `Measure("2 m") * Measure("5 degC") != Measure("5 m") * Measure("2 degC")`.
Notice the module doesn't fail calculating `Measure("2 m") * Measure("5 degC")`. It simply doesn't back-convert to Celsius.
Note: The unit "C" is reserved for Coulomb, but the module recognizes the degrees symbol.
## Can the module be made Faster?
One thing you can do to improve speed is to decompose units or simplify measures as early as possible.
The Decompose, Convert, and Simplify functions remove unit definitions, and propagation of unit-definitions slows the module.
This is not an issue for purely metric units because they are the default (thus never passed in propagation).
The notable down side in removing the unit definitions is that you'll have to re-introduce the definitions if you intend to use them later.
Raw data
{
"_id": null,
"home_page": "",
"name": "unitment",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "measure,measurement,measurements,measures,unit,units",
"author": "",
"author_email": "\"Tristin Alexander S.\" <trystyn.alxander@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/2d/6c/5b82d4cdcb84901a02af0b0a8a931e364a9de27927ba518ca7c0526e7213/unitment-0.0.9.tar.gz",
"platform": null,
"description": "# Introduction\n\nUnitment supports dynamic unit management so users can focus on what matters.\n\n\n**Install:**\nTo get started, [download](https://www.python.org/downloads/) and install python, then open your terminal and run the following pip command:\n\n`pip install unitment` \n\n**Example**:\n\n```\nfrom unitment import Unit,Measure\n\ndistance = Measure(\"25 m\")\ntime = Measure(\"5 s\")\nspeed = distance / time\nprint(speed)\n```\n\nAbove is a simple script using unitment. Save this text to file as `example.py`. \nOpen the terminal wherever you saved the file, then run `python example.py`. \nYou can imagine how to edit the script for your own purpose.\n\n____________________________________________________________ \n____________________________________________________________ \n\n# Basics Features\n\nUnitment's core feature is **Dynamic Unit Management.** This allows users to use *any* units on the fly. \nThis includes arbitrary units like fish, rocks, pizza, happiness, etc. Users don't even need to define their units! \n\nUnitment is ideal for scripting. It's **Intuitive and Adaptive**, so that even novice coders can use it.\nMeasures can be defined several intuitive ways: `Measure(\"5 m\")`, `Measure(5,\"m\")`, `Measure(value=5,units=\"m\")`, etc.\nAdaptive typing makes coding more forgiving: `Measure(\"25 m\")/Measure(\"5 s\")`, `Measure(\"25 m\")/\"5s\"`, etc.\n\n- **Spaces Required**\n - `\"ms\"` is milliseconds\n - `\"m s\"` is meter seconds\n- **Unit Conversions**\n - Metric is Pre-Defined.\n - Simplify with `measure.simplify()`\n - Convert with `measure.convert(unit)`\n - Abnormal Unit Dictionaries (*optional*)\n - `Unit.IMPERIAL_UNITS`\n - `Unit.PRESSURE_UNITS`\n\nAgain, users never *need* to define units in unitment. \n\nStill, a unit-dictionaries argument in instantiation or conversion can be convenient for automatic conversion to metric.\nIn-fact, all math in unitment is converted to base-units before preformed. \nThis prevents silly errors like multiplying the Celsius temperature instead of the Kelvin temperature, \nbut it requires users to understand whether they intend to add 1\u00b0C or 1K.\n\n**Other Operations.** \nIn addition to the standard math operators, convert, and simplify; unitment the following functions: \n`measure.is_simplified()`, `measure.sin()`, `measure.cos()`, `measure.exp()`, `measure.root()`, `measure.sqrt()`, `measure.log(base)`, `measure.ln()`, `measure.log10()`, and `measure1.approx(measure2)`.\n\n\n\n____________________________________________________________\n\n# Intermediate Features\n\n**What about NumPy?**\nNumPy is a popular package for doing math with matricies. \nIt's useful both for its widely-known notation and its efficient speed.\nIf you're using NumPy for its widely-known notation, simply add the argument `dtype=numpy.dtype(Measure)` in your NumPy array.\nIf you're using NumPy for its efficient speed, never use non-standard number types. \nUse this module as a parser and converter then use `float(measure)` to convert to standard floats. \nTo that end a useful line of code might be:\n\n```\n# Step-By-Step\nlist_of_measures = [ Measure(str_measure) for str_measure in list_of_str_measures ]\nlist_of_measures_in_unit = [ measure.convert(unit) for measure in list_of_measures ]\nlist_of_floats_in_unit = [ float(measure) for measure in list_of_measures_in_unit ]\n# All at Once\nlist_of_floats_in_unit = [float(Measure(str_measure).convert(unit)) for str_measure in list_of_str_measures]\n```\n\n**Conversions to Non-Metric Units**\n\nOne common gripe about the `convert` function is that it doesn't propagate unit definitions. \nThis results in situations where a conversion of inches to feet might be interpreted as an attempt to convert inches to femto-tonnes, resulting in an error: `Measure(\"12 in\",Unit.IMPERIAL_UNITS).convert(\"ft\")` throws a UnitException for incompatible units.\nThis is because the user failed to re-define `\"ft\"` in the conversion function. \nThe proper way to convert to any non-metric unit is to define the unit in either convert or in the passed unit: `Measure(\"12 in\",Unit.IMPERIAL_UNITS).convert(\"ft\",Unit.IMPERIAL_UNITS)` or `Measure(\"12 in\",Unit.IMPERIAL_UNITS).convert(Unit(\"ft\",Unit.IMPERIAL_UNITS))`.\n\n\n____________________________________________________________\n____________________________________________________________\n\n\nConsider supporting unitment on [patreon](https://www.patreon.com/user?u=83796428).\n\n____________________________________________________________\n____________________________________________________________\n\n\n\n# Technical Features\n\n - Unit Compatibility. This module works with *almost any* units. \n While metric units are used by default, imperial units are defined as a class constant (`Measure(\"degF\",Unit.IMPERIAL_UNITS)`). \n Arbitrary units can be used as their own (non-physical) dimension without being explicitly defined - albeit without prefixes, conversion-functions, or decompositions. \n More advanced units can easily be loaded or defined for automatic conversion to base-units and the unit definitions propagate with the units themselves.\n Indeed, some advanced units (pH, Celsius) are already defined.\n \n - Intuitive Instantiation. Units and Measures are made with easy constructors in this package: e.g. `Measure(\"5 m\")`, `Measure(5,\"m\")`, `Measure(value=5,units=\"m\")`, etc.\n Users needn't familiarize themselves with a cluttered or convoluted namespace or even understand much python or coding in general. \n Again, the goal is to allow the users to focus on their maths in abstract-terms that maintain perspective on their problem, rather than dragging unit-hell into coding. \n \n - Math in Dimensions. Each Unit and Measure automatically decomposes and simplifies to base-unit form prior to preforming mathematical operations.\n This allows math to be done in terms of the actual base-dimensions, which is crucial for some units (e.g. \u2103). \n Where possible, the original units are retained for the final result. \n As a result, users needn't think in terms of units after they've been defined. \n Users may focus on doing math in the more abstract terms or at the level of the dimension. \n \n - Propagation of Error. Propagation of error is built into every operator.\n While this is a worst-case (non-abstract) error calculation, it helps users gain a grasp on the reliability-of and precision-needed-for their system.\n\n - Low Over-head. A lot of effort was put into preventing the module from being slow. \n While it could be faster at cost of code maintainability or usability, it is quite fast for what it does.\n Moreover, the module's only dependencies are in the Python Standard Library (Mostly the `math` and `decimal` modules). \n Overall, this module is well suited for scripting purposes. \n\nAll that said, the choice of unit management module does depend on use-case. \nThe general advise for users is to use this module for scripting simple math or conversions. \nWhile this module may work for surprisingly complicated things, we recommend removing units altogether for advanced applications. \nIn such cases, this module may still be useful as a parser. \n\n\n## Measure\n\n`Measure` is the primary class in this package. Measures have a value, a unit, and an error. The error is often implied. \nThis class reflects the logical structure in its properties: `value`, `units`, and `error`. Likewise, the error is inferred if not explicitly provided. \nThe value and unit properties are numbers. The unit is defined more extensively below.\n\n**Instantiation:** \nThis class is built to be instantiated casually and intuitively, e.g. `Measure(\"25 m\")`, so reasonable string inputs should be processed as expected.\nThat said, care should be taken to leave a space between symbols as milliseconds (`\"ms\"`) are quite different from meter seconds (`\"m s\"`).\nBeyond that, the parser is fairly robust. It is generally capable of handling exponents and error notations. \nThe class can also be instantiated with the keywords `value`, `error`, and `unit` or `units`.\n\n**Dominant:** The Measure class dominates in mathematical operations, so a float * Measure = Measure. \nFor very large programs with very large numbers of operations, this will slow down the program. \nFor maximum efficiency, it's always better to use this package as a parser and converter then cast the measure as a float.\n\nFor example:\n\n x_raw = \"2583 cm\"\n x_meters = float(Measure(x_raw).convert(\"m\"))\n\n### Value\n\nThe class will accept and Number or would-be number as a value. This includes Decimals, floats, ints, and strings that can be converted to decimals.\nInternally the class will preserve Decimals until it encounters a float mathematical operations, at which point all internal values will convert to floats. \nIf inputting the value as an argument rather than a keyword or parsed string, the first number will be considered the value, the second the error.\n\n### Error\n\n**Definition of Error:** This module defines error as the square root of the variance: the standard deviation.\n\n**Numerical Error Assumption:**\nSince the module is not context-aware, propagation of error occurs with the assumption of numerical (and thus non-canceling) inputs for every operation.\nThis worse-case assumption is used because the module cannot be aware of its analytical context.\nFor example, analytically one knows that a - b + b = a.\nWithout context-awareness, the 'big-picture' cannot be observed and the module must operate numerically.\nThe module (like most code) sees (a-b), solves this as c, sees (c+b), and solves that. Propagation of error occurs at each step.\nAs a result, extra propagation of error occurs where none should exist in analytical contexts.\n\n**Propagation of Error Equations:** \nThe propagation of error equation (the taylor-series expansion of the statistical moments) for a function with two inputs is as follows:\n\nvar(f) = (\u2202f/\u2202x)<sup>2</sup> var(x) + (\u2202f/\u2202x) (\u2202f/\u2202y) covar(x) + (\u2202f/\u2202y)<sup>2</sup> var(y)\n\nSince the module is not context-aware, it must assume independent inputs; thus, this equation is more appropriate:\n\nvar(f) = (\u2202f/\u2202x)<sup>2</sup> var(x) + (\u2202f/\u2202y)<sup>2</sup> var(y)\n\nThat is the equation used by the module. For edification of the reader, this equation can be extended to multi-input function as follows:\n\nvar(f) = \u03a3 (\u2202f/\u2202xi)<sup>2</sup> var(x<sub>i</sub>)\n\n**Propagation of Error Failures:** \nSince each of these are essentially the same equation all-be-it in slightly different contexts, they share the requirements of taylor-series expansions. \nNamely, the functions must be sufficiently differentiable and the approximations must be sufficiently local. \nThe floor, ceil, and round functions are not sufficiently differentiable for the taylor series expansions for the moments to be valid. \nGiven this and that most users would not be using them in a mathematically rigorous context, these functions do not propagate error properly. \nThe modulo function is defined in terms of the floor function (i.e. x % y = x-y*floor(x/y)); thus, it also does not propagate error properly. \nOther non-linear functions (such as log) are likely accurate locally (for very small errors), but are at greater risk of inaccuracies as values increase.\n\n**Implied Errors:**\nFor implied errors of given values (i.e. `Measure(10.0,\"m\")`), the module gives it's best guess by converting the value to a string.\nThis can produce incorrect results with floats (e.g. `Measure(float(10),\"m\")`). \nAs such, if concerned with error inputting values as strings or Decimal is recommended when not defining the error explicitly with keywords.\n\n\n### Restrictions on Mathematics\n\nRestrictions are put on the mathematics due to the presence of units. These should all be fairly intuitive.\nThe most obvious restriction is that measurements with different units cannot be added together. \nOne can use a simple taylor series to show that this restriction implies that units must cancel in exponents. \n\n## Units\n\nUnits are labels for self-consistent chunks of dimensions. \nThese dimensions can be physical, non-physical, or even complex abstractions. \nDespite the possible dimensions, units have a consistent logic-structure. \nThis allows them to be defined and categorized by complexity:\n\n- **Base Unit:** Base Units are singular and cannot be converted into other units. Examples: `\"m\"`, `\"fish\"`.\n- **Derived Unit:** Derived Units are singular but can be converted into other units. Examples: `\"cm\"`, `\"J\"`.\n- **Compound Unit:** Compound Units are multiple logically related units. Examples: `\"cm / fish\"`, `\"J / m\"`\n\nThe `Unit` class is for base, derived, or compound units with multiple base-dimensions and/or magnitude modifiers. \nHere, the term \"symbol\" or \"symbols\" refers to a singular unit (base-unit or derived-unit) regardless of the length of the string. \nTo that end, the class is ultimately composed of a tuple of string symbols, a magnitude, and up-to one conversion function.\n\n**Instantiation:**\nThis class is built to be instantiated casually and intuitively, e.g. `Unit(\"m\")`, so reasonable string inputs should be processed as expected.\nThat said, care should be taken to leave a space between symbols as milliseconds (`\"ms\"`) are quite different from meter seconds (`\"m s\"`).\nOf-course, the class can also be instantiated more formally. Unit has three keywords for defining symbols: `numerators` and `denominators`, or `symbols`. \nThese keywords accept tuples of string-units, e.g. `(\"m\",\"s\")`, or tuples of string-unit exponent tuple pairs, e.g. `( (\"m\",1), (\"s\",-1) )`. \nThe keyword `magnitude` accepts numbers to define the magnitude of a unit. \n\nAs an example, each of the following instantiated units have the same symbols\n\n Unit(\"m/s\")\n Unit(\"m s^-1\")\n Unit(numerators=(\"m\",),denominators=(\"s\",))\n Unit(numerators=((\"m\",1),),denominators=((\"s\",1),))\n Unit(symbols=((\"m\",1),(\"s\",-1),))\n\nAs an example, each of the following instantiated units have the same magnitudes:\n\n Unit(\"1e6 fish\")\n Unit(\"fish\", magnitude=1e6)\n Unit(\"1000000 fish\")\n Unit(\"10^6 fish\")\n\n### Defining Units\n\nGenerally, users do not need to define custom units. If a user wants to use some arbitrary unit such as `Unit(\"fish\")`, the module is fully capable of managing that. \nIt is also trivial to add magnitudes to arbitrary units (e.g. `Unit(\"10^6 fish\")`), so some users may find it simpler to replace prefixes `.replace(\"Mfish\",\"10^6 fish\")`.\nMoreover, the module has a number of predefined sets of non-standard units `Unit.IMPERIAL_UNITS`, `Unit.PRESSURE_UNITS`, `Unit.CONCENTRATION_UNITS` that can be loaded into the Unit or Measure class with an additional argument or the keywords `defs` or `definitions`.\n\n u = Unit(\"ft\",Unit.IMPERIAL_UNITS)\n m = Measure(\"3 ft\",Unit.IMPERIAL_UNITS)\n\nWhile arbitrary units are handled on the fly, some users may need to define custom units when dealing with non-standard derived units or prefixed units. \nOf course units are handled dynamically in the module, so units only need to be defined for simplifications, decompositions, or conversions.\nAgain, metric units are defined by default, so defining units is generally unnecessary. Still, users can define arbitrary derived or prefixed units:\n\n weird_unit_dict = {\n # Symbol Mult Base-Symbol Function\n 'mu' : ( Decimal(\"1e-3\"), (('u',1),), None),\n 'ku' : ( Decimal(\"1e3\"), (('u',1),), None),\n }\n x = Measure(\"5 ku\",weird_unit_dict).convert(\"u\")\n y = Measure(\"5 ku\",weird_unit_dict).convert(\"mu\",weird_unit_dict)\n\nIf defining a derived unit in terms of metric units it's worth noting that the module considers metric base units to be units without a prefix (except kg). \nThis is important. Any unit defined in terms of prefixed-metric base-units (except kg's) may have unexpected behavior. kg, not g, is considered the base unit of mass.\n\n weird_unit_dict = {\n # Symbol Mult Base-Symbol Function\n 'u' : ( Decimal(1), (('kg',-1),), None),\n 'v' : ( Decimal(\"1e3\"), (('s',-2),), None),\n }\n \n x = Measure(\"5 u\",weird_unit_dict).convert(\"kg-1\")\n x = Measure(\"5 v\",weird_unit_dict).convert(\"s-2\")\n\n**Context Dependent Units:**\nSome function units, most notably the Decibel (dB) or Bel (B), have a context dependent meaning; thus, the user is responsible for defining them prior to use.\nThe Decibel has multiple definitions depending on whether it is a power (`10*((val/ref).log10)`) or amplitude (`20*((val/ref).log10)`) measurement.\nMoreover, the reference (`ref`) is extremely context specific. For example, a milli-watt microbel (uBmW) is a context independent power measurement defined with respect to a milli-watt reference. \nDespite its context independence, it is considered obscure and non-metric (even when using a metric reference); thus, the user is responsible for defining such units prior to use. \n\nTo define a context dependent unit the magnitude, base units, and selector-conversion functions are required. \nThe selector function simply determines the behavior (the conversion functions used) given the exponent. \nThe conversion functions are to and from base units. As an example:\n\n def DECIBEL_SELECTOR(exponent):\n \"\"\"\n In non-under-water Acoustics the decible is defined as follows: \n dB = 20 log10( value / 20 uPa )\n In base units: \n dB = 20 log10( value / (20e-6 kg^1 m^-1 s^-2 ) )\n \n To reverse this calculation solve for the initial value: \n value = 10^(dB / 20) * 20e-6 kg^1 m^-1 s^-2\n \"\"\"\n \n # Decibel Functions\n def NUMERATOR_FROM_DECIBEL_TO_BASE(val):\n val,scale,ref = unitment._type_corrections_(val,Decimal(\"20\"),Decimal(\"20e-6\"))\n return 10**(val/scale) * ref\n def NUMERATOR_TO_DECIBEL_FROM_BASE(val):\n val,scale,ref = unitment._type_corrections_(val,Decimal(\"20\"),Decimal(\"20e-6\"))\n return scale * (val/ref).log10()\n # Most Function Units behave like normal units when on the denominator.\n def DENOMINATOR_FROM_DECIBEL_TO_BASE(val):\n return val\n def DENOMINATOR_TO_DECIBEL_FROM_BASE(val):\n return val\n \n # Select & Return Correct Function\n if(exponent == 0): return (lambda x:x,lambda x:x)\n if(exponent == 1): return ( NUMERATOR_FROM_DECIBEL_TO_BASE , NUMERATOR_TO_DECIBEL_FROM_BASE )\n if(exponent == -1): return ( DENOMINATOR_FROM_DECIBEL_TO_BASE , DENOMINATOR_TO_DECIBEL_FROM_BASE )\n else:\n raise ValueError(f\"Failed to Decompose: Exponent of dB != 1,0,-1. Cannot Deconvolute.\")\n \n dB_dict = {\n # Symbol Mult Base-Symbol Function\n 'dB' : ( 1, (('kg',1),('m',-1),('s',-2)), DECIBEL_SELECTOR),\n }\n \n x = Measure(\"5 dB\",dB_dict).convert(\"uPa\")\n\n\n***If you make your a unit dictionary you'd like included in the package, please reach out to me.***\n\n____________________________________________________________\n\n# Frequently Asked Questions\n\n\n## What Types of numbers does it work with?\n\nThoroughly tested with Decimals, ints, floats. Might work with complex numbers from cmath, but not tested. \nIt might not fail with other Numbers, but no guarantees. \n\n\n## Propagation (Domination) of the Measure class. \n\nWhen using the measure in maths you may find that most things convert to the measure class in the final result. \nSometimes this makes sense, a scalar times a measure should be a measure. Other times this may seem annoying, as in unitless values. \nUnitless Measures are returned to help track the propagation of error. \nOne can always access the value via the value property or by casting the measure as a float. \n\n## How does the module handle Celsius and Fahrenheit?\n\nJust like every other unit, Celsius and Fahrenheit are decomposed (into Kelvin) prior to any math being done. \nMost unit managers do not do this because it is difficult to code addition into conversion functions. \nThis module manages the difficult part; however, certain non-base units are invalid because they cannot be decomposed: e.g. `Measure(\"10 degC m\")` will throw an error.\nThe reason is the module cannot know what portion of the unit belongs to each component: e.g. `Measure(\"2 m\") * Measure(\"5 degC\") != Measure(\"5 m\") * Measure(\"2 degC\")`.\nNotice the module doesn't fail calculating `Measure(\"2 m\") * Measure(\"5 degC\")`. It simply doesn't back-convert to Celsius.\nNote: The unit \"C\" is reserved for Coulomb, but the module recognizes the degrees symbol. \n\n## Can the module be made Faster?\n\nOne thing you can do to improve speed is to decompose units or simplify measures as early as possible.\nThe Decompose, Convert, and Simplify functions remove unit definitions, and propagation of unit-definitions slows the module.\nThis is not an issue for purely metric units because they are the default (thus never passed in propagation). \nThe notable down side in removing the unit definitions is that you'll have to re-introduce the definitions if you intend to use them later. \n\n",
"bugtrack_url": null,
"license": "",
"summary": "Dynamic unit management.",
"version": "0.0.9",
"project_urls": {
"Bug Tracker": "https://github.com/TristynAlxander/unitment/issues",
"Homepage": "https://github.com/TristynAlxander/unitment"
},
"split_keywords": [
"measure",
"measurement",
"measurements",
"measures",
"unit",
"units"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9e4e0c55983bf1120e909077297699023248ac2dad7d00286c32a009f73e886d",
"md5": "f1e5f8dfb4dd343743a127df02f6d9dc",
"sha256": "9a1272629dc8932502a89ec7a2bee9ab828b4f230ecb291d3bafd65847f20ec5"
},
"downloads": -1,
"filename": "unitment-0.0.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f1e5f8dfb4dd343743a127df02f6d9dc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 34394,
"upload_time": "2024-02-18T06:32:34",
"upload_time_iso_8601": "2024-02-18T06:32:34.785344Z",
"url": "https://files.pythonhosted.org/packages/9e/4e/0c55983bf1120e909077297699023248ac2dad7d00286c32a009f73e886d/unitment-0.0.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2d6c5b82d4cdcb84901a02af0b0a8a931e364a9de27927ba518ca7c0526e7213",
"md5": "397e0702fc8c06be310723e6b2980c9b",
"sha256": "9e483548af428ebc835815a7647222617707115648b55bd1679df528f4375d80"
},
"downloads": -1,
"filename": "unitment-0.0.9.tar.gz",
"has_sig": false,
"md5_digest": "397e0702fc8c06be310723e6b2980c9b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 165686,
"upload_time": "2024-02-18T06:32:41",
"upload_time_iso_8601": "2024-02-18T06:32:41.903799Z",
"url": "https://files.pythonhosted.org/packages/2d/6c/5b82d4cdcb84901a02af0b0a8a931e364a9de27927ba518ca7c0526e7213/unitment-0.0.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-18 06:32:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "TristynAlxander",
"github_project": "unitment",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "unitment"
}
JSON
