| Name | unitclass JSON |
| Version |
1.1.1
JSON |
| download |
| home_page | |
| Summary | Physical unit class suitable for calculations in the sciences. |
| upload_time | 2023-12-13 00:20:18 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.8 |
| license | |
| keywords |
unit
units
si
conversion
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# unitclass
`unitclass` is a physical unit class suitable for calculations in the sciences.
This library provides a `Unit` class that encapsulates a numerical value with a
physical unit. It is intended for both interactive and library use.
`unitclass` supports all [SI
units](https://www.nist.gov/pml/owm/metric-si/si-units) and prefixes, as well as
every reasonably common English/Imperial unit and other special units (e.g.
bytes and ppm).
## Usage Examples
`Unit()` takes strings or numbers and strings. Any number appended to a unit is
assumed to be an exponent. e.g. `m2` is `m²` and `in3` is `in³`. You can create
compound units with `*` and `/` operators, e.g. `N*m` or `ft/min`. There should
only be one division operator in a unit, but you can have any number of
multiplied units on the left and right sides of the division operator. e.g
`N*s2/m*kg` is interpreted as $\frac{N \cdot s^2}{m \cdot kg}$.
### Basic Usage
```python
>>> from unitclass import Unit
>>> Unit('1 in') # number and unit in a string
1 in
>>> Unit(1.0, 'in') # number and unit as separate arguments
1 in
>>> Unit(1, 'in', 'mm') # convert on-the-fly from one unit to another
25.4 mm
>>> a = Unit(1, 'in')
>>> b = Unit(1, 'ft')
>>> a*12 + b
24 in
```
#### Exponents
```python
>>> from unitclass import Unit
>>> Unit('1 m3')
1 m³
>>> Unit('1 in4')
1 in⁴
>>> Unit('1 m3').to('in3')
61023.7 in³
>>> Unit('10 in2') / Unit('1 in')
10 in
```
#### Compound Units
```python
>>> Unit('1 lbf*ft*s2')
1 lb·ft·s²
>>> Unit(100, 'ft/min')
100 ft/min
>>> Unit('1 N*s2/(m*kg)')
1 N·s²/(m·kg)
>>> Unit(100, 'ft') / Unit(1, 'min')
100 ft/min
```
#### Conversion
```python
>>> from unitclass import Unit
>>> Unit(1, 'in', 'mm') # convert on-the-fly from one unit to another
25.4 mm
>>> b = Unit(1, 'ft')
>>> b.to('in') # convert method
12 in
>>> b.to('mm')
304.8 mm
>>> Unit('1 N*m').to('in*lb')
8.85075 in·lb
>>> Unit(100, 'ft/min').to('mph')
1.13636 mph
>>> Unit(100, 'ft/min').to('kph')
1.8288 kph
```
### Listing/Searching Built-in Units
To see what units are available (output is abbreviated below):
```python
>>> import unitclass as uc
>>> uc.list_units()
s ->unit of time aliases: ['second', 'seconds', 'sec', 'secs']
...
```
You can also limit the search to a certain quantity:
```python
>>> import unitclass as uc
>>> uc.list_units(qty='data')
B ->unit of data aliases: ['byte', 'bytes']
KB ->unit of data aliases: ['kilobyte', 'kilobytes']
MB ->unit of data aliases: ['megabyte', 'megabytes']
GB ->unit of data aliases: ['gigabyte', 'gigabytes']
TB ->unit of data aliases: ['terabyte', 'terabytes']
PB ->unit of data aliases: ['petabyte', 'petabytes']
EB ->unit of data aliases: ['exabyte', 'exabytes']
```
*Tip: For a list of available quanities, use the function `list_quantities()`.
Example usage is below in the Custom Unit section.*
And you can search for a certain string in a unit or unit alias:
```python
>>> import unitclass as uc
>>> uc.list_units(qty='data', search='ga')
MB ->unit of data aliases: ['megabyte', 'megabytes']
GB ->unit of data aliases: ['gigabyte', 'gigabytes']
>>> uc.list_units(search='mile')
mi ->unit of length aliases: ['mile', 'miles', 'statutemile', 'statutemiles', 'smi']
nmi ->unit of length aliases: ['nauticalmile', 'nauticalmiles']
gmi ->unit of length aliases: ['geographicalmile', 'geographicalmiles']
mph ->unit of speed aliases: ['mileperhour']
```
### Simplifying and Expanding Units
The `expand()` method expands the unit to its fundamental units while
`simplify()` combines units to a single compound unit if one exists for the
given combination of units. For all options, type `help(Unit.expand)` or
`help(Unit.simplify)` at an interactive prompt.
```python
>>> a = Unit('1 W')/Unit('1 A')
>>> a
1 W/A
>>> a.expand()
1 m²·kg/(A·s³)
>>> a.simplify()
1 V
```
### Add Custom Unit
In the example below, a custom unit is being added. The unit measures the
quantity "length", the unit is called "blake", two aliases for that unit are
"blakes" and "bunits", and 1 blake equals 6 ft.
The fields are as follows: `<quantity>, <name>, <aliases>, <factor>, <factor unit>`
Once the custom unit is added, it can be used the same as any other built-in unit.
```python
>>> import unitclass as uc
>>> uc.add_unit("length", "blake", "blakes bunits", 6, 'ft')
>>> c = Unit(12, 'in', 'blakes')
>>> c
0.166667 blake
>>> Unit(12*12, 'in', 'blakes')
2 blake
```
You can also bulk load custom units from a CSV file. The CSV would take the same
form as the `add_unit()` function above. Here is an example CSV with two custom
units:
```csv
length, myin, myinch my_inch, 1/8.0, in
angle, myang,, 1/1e-12*sin(2*pi), rad
```
And then it is loaded with the `import_units()` method:
```python
>>> import unitclass as uc
>>> uc.import_units('customunits.csv')
```
When adding custom units, it is helpful to know what *quantities* are available.
(E.g. length, time, force, etc.) These are the quantities that are being
measured, or the categories of measurement, not the units themselves. To list
them all, use the `list_quantities()` method (the output has been abbreviated
below):
```python
>>> import unitclass as uc
>>> uc.list_quantities()
absorbed_dose
acceleration
amount
angle
angular speed
area
...
speed
time
torque
unitless
voltage
volume
```
### Converting without using the Unit class
You can skip creating a Unit class if you prefer to just do a quick conversion.
```python
>>> import unitclass as uc
>>> uc.convert(1, 'in', 'mm')
25.4
>>> uc.convert(55, 'mph', 'kph')
88.51391999999998
>>> uc.convert(40, 'lb/ft3', 'kg/m3')
640.7385327602261
```
## Caveats
### Force/Mass
Because people expect to convert from pounds to kilograms (i.e. force to mass), this library
will automatically handle conversion to/from forces and masses when explicit conversion is requested. This is accomplished by dividing or multiplying by the acceleration of gravity as needed, which makes conversion between force and mass intuitive for the layman
and convenient for the rest.
### Temperature
Because of the nature of the temperature scales, a simple multiplier does not
work, so temperature is handled independently of the other units. This leads to
a the limitations that you cannot have custom or compound units with
temperature. This is a rare use case, so fixing this limitation is a low
priority.
Raw data
{
"_id": null,
"home_page": "",
"name": "unitclass",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "unit,units,SI,conversion",
"author": "",
"author_email": "Blake Garretson <blake@blakeg.net>",
"download_url": "https://files.pythonhosted.org/packages/c7/4d/0bcf3e1667d3bcae654bebe0c230fcae5b3606a4f617ec2c7e691a9bf2b9/unitclass-1.1.1.tar.gz",
"platform": null,
"description": "# unitclass\n\n`unitclass` is a physical unit class suitable for calculations in the sciences.\nThis library provides a `Unit` class that encapsulates a numerical value with a\nphysical unit. It is intended for both interactive and library use.\n\n`unitclass` supports all [SI\nunits](https://www.nist.gov/pml/owm/metric-si/si-units) and prefixes, as well as\nevery reasonably common English/Imperial unit and other special units (e.g.\nbytes and ppm).\n\n## Usage Examples\n\n`Unit()` takes strings or numbers and strings. Any number appended to a unit is\nassumed to be an exponent. e.g. `m2` is `m\u00b2` and `in3` is `in\u00b3`. You can create\ncompound units with `*` and `/` operators, e.g. `N*m` or `ft/min`. There should\nonly be one division operator in a unit, but you can have any number of\nmultiplied units on the left and right sides of the division operator. e.g\n`N*s2/m*kg` is interpreted as $\\frac{N \\cdot s^2}{m \\cdot kg}$.\n\n### Basic Usage\n\n```python\n>>> from unitclass import Unit\n>>> Unit('1 in') # number and unit in a string\n1 in\n>>> Unit(1.0, 'in') # number and unit as separate arguments\n1 in\n>>> Unit(1, 'in', 'mm') # convert on-the-fly from one unit to another\n25.4 mm\n>>> a = Unit(1, 'in')\n>>> b = Unit(1, 'ft')\n>>> a*12 + b\n24 in\n\n```\n\n#### Exponents\n\n```python\n>>> from unitclass import Unit\n>>> Unit('1 m3')\n1 m\u00b3\n>>> Unit('1 in4')\n1 in\u2074\n>>> Unit('1 m3').to('in3')\n61023.7 in\u00b3\n>>> Unit('10 in2') / Unit('1 in')\n10 in\n\n```\n\n#### Compound Units\n\n```python\n>>> Unit('1 lbf*ft*s2')\n1 lb\u00b7ft\u00b7s\u00b2\n>>> Unit(100, 'ft/min')\n100 ft/min\n>>> Unit('1 N*s2/(m*kg)')\n1 N\u00b7s\u00b2/(m\u00b7kg)\n>>> Unit(100, 'ft') / Unit(1, 'min')\n100 ft/min\n\n```\n\n#### Conversion\n\n```python\n>>> from unitclass import Unit\n>>> Unit(1, 'in', 'mm') # convert on-the-fly from one unit to another\n25.4 mm\n>>> b = Unit(1, 'ft')\n>>> b.to('in') # convert method\n12 in\n>>> b.to('mm')\n304.8 mm\n>>> Unit('1 N*m').to('in*lb')\n8.85075 in\u00b7lb\n>>> Unit(100, 'ft/min').to('mph') \n1.13636 mph\n>>> Unit(100, 'ft/min').to('kph')\n1.8288 kph\n\n```\n\n### Listing/Searching Built-in Units\n\nTo see what units are available (output is abbreviated below):\n\n```python\n>>> import unitclass as uc\n>>> uc.list_units()\ns ->unit of time aliases: ['second', 'seconds', 'sec', 'secs']\n ...\n\n```\n\nYou can also limit the search to a certain quantity:\n\n```python\n>>> import unitclass as uc\n>>> uc.list_units(qty='data')\nB ->unit of data aliases: ['byte', 'bytes']\nKB ->unit of data aliases: ['kilobyte', 'kilobytes']\nMB ->unit of data aliases: ['megabyte', 'megabytes']\nGB ->unit of data aliases: ['gigabyte', 'gigabytes']\nTB ->unit of data aliases: ['terabyte', 'terabytes']\nPB ->unit of data aliases: ['petabyte', 'petabytes']\nEB ->unit of data aliases: ['exabyte', 'exabytes']\n\n```\n\n*Tip: For a list of available quanities, use the function `list_quantities()`.\nExample usage is below in the Custom Unit section.*\n\nAnd you can search for a certain string in a unit or unit alias:\n\n```python\n>>> import unitclass as uc\n>>> uc.list_units(qty='data', search='ga')\nMB ->unit of data aliases: ['megabyte', 'megabytes']\nGB ->unit of data aliases: ['gigabyte', 'gigabytes']\n>>> uc.list_units(search='mile')\nmi ->unit of length aliases: ['mile', 'miles', 'statutemile', 'statutemiles', 'smi']\nnmi ->unit of length aliases: ['nauticalmile', 'nauticalmiles']\ngmi ->unit of length aliases: ['geographicalmile', 'geographicalmiles']\nmph ->unit of speed aliases: ['mileperhour']\n\n```\n\n### Simplifying and Expanding Units\n\nThe `expand()` method expands the unit to its fundamental units while\n`simplify()` combines units to a single compound unit if one exists for the\ngiven combination of units. For all options, type `help(Unit.expand)` or\n`help(Unit.simplify)` at an interactive prompt.\n\n```python\n>>> a = Unit('1 W')/Unit('1 A')\n>>> a\n1 W/A\n>>> a.expand()\n1 m\u00b2\u00b7kg/(A\u00b7s\u00b3)\n>>> a.simplify()\n1 V\n\n```\n\n### Add Custom Unit\n\nIn the example below, a custom unit is being added. The unit measures the\nquantity \"length\", the unit is called \"blake\", two aliases for that unit are\n\"blakes\" and \"bunits\", and 1 blake equals 6 ft.\n\nThe fields are as follows: `<quantity>, <name>, <aliases>, <factor>, <factor unit>`\n\nOnce the custom unit is added, it can be used the same as any other built-in unit.\n\n```python\n>>> import unitclass as uc\n>>> uc.add_unit(\"length\", \"blake\", \"blakes bunits\", 6, 'ft')\n>>> c = Unit(12, 'in', 'blakes')\n>>> c\n0.166667 blake\n>>> Unit(12*12, 'in', 'blakes')\n2 blake\n\n```\n\nYou can also bulk load custom units from a CSV file. The CSV would take the same\nform as the `add_unit()` function above. Here is an example CSV with two custom\nunits:\n\n```csv\nlength, myin, myinch my_inch, 1/8.0, in\nangle, myang,, 1/1e-12*sin(2*pi), rad\n```\n\nAnd then it is loaded with the `import_units()` method:\n\n```python\n>>> import unitclass as uc\n>>> uc.import_units('customunits.csv')\n\n```\n\nWhen adding custom units, it is helpful to know what *quantities* are available.\n(E.g. length, time, force, etc.) These are the quantities that are being\nmeasured, or the categories of measurement, not the units themselves. To list\nthem all, use the `list_quantities()` method (the output has been abbreviated\nbelow):\n\n```python\n>>> import unitclass as uc\n>>> uc.list_quantities()\nabsorbed_dose\nacceleration\namount\nangle\nangular speed\narea\n ...\nspeed\ntime\ntorque\nunitless\nvoltage\nvolume\n\n```\n\n### Converting without using the Unit class\n\nYou can skip creating a Unit class if you prefer to just do a quick conversion.\n\n```python\n>>> import unitclass as uc\n>>> uc.convert(1, 'in', 'mm')\n25.4\n>>> uc.convert(55, 'mph', 'kph')\n88.51391999999998\n>>> uc.convert(40, 'lb/ft3', 'kg/m3')\n640.7385327602261\n\n```\n\n## Caveats\n\n### Force/Mass\n\nBecause people expect to convert from pounds to kilograms (i.e. force to mass), this library\nwill automatically handle conversion to/from forces and masses when explicit conversion is requested. This is accomplished by dividing or multiplying by the acceleration of gravity as needed, which makes conversion between force and mass intuitive for the layman\nand convenient for the rest.\n\n### Temperature\n\nBecause of the nature of the temperature scales, a simple multiplier does not\nwork, so temperature is handled independently of the other units. This leads to\na the limitations that you cannot have custom or compound units with\ntemperature. This is a rare use case, so fixing this limitation is a low\npriority.\n",
"bugtrack_url": null,
"license": "",
"summary": "Physical unit class suitable for calculations in the sciences.",
"version": "1.1.1",
"project_urls": {
"Bug Tracker": "https://github.com/blakegarretson/unitclass/issues",
"Homepage": "https://github.com/blakegarretson/unitclass"
},
"split_keywords": [
"unit",
"units",
"si",
"conversion"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "375b62275f08241eb8d07276011c6bd686a7c2f28d421a2dcd7db8b8eb5500ed",
"md5": "61375878dbdf7820fd9536195ded3a40",
"sha256": "5f69f06aa5c240cc15f2175cb06e51e7ad75a4f826573e50df1aa842a4a5832c"
},
"downloads": -1,
"filename": "unitclass-1.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "61375878dbdf7820fd9536195ded3a40",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 29700,
"upload_time": "2023-12-13T00:20:16",
"upload_time_iso_8601": "2023-12-13T00:20:16.601361Z",
"url": "https://files.pythonhosted.org/packages/37/5b/62275f08241eb8d07276011c6bd686a7c2f28d421a2dcd7db8b8eb5500ed/unitclass-1.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c74d0bcf3e1667d3bcae654bebe0c230fcae5b3606a4f617ec2c7e691a9bf2b9",
"md5": "31dd3848ca4e08f5fc2353dc33e58915",
"sha256": "123969f8e4a226c6dfe57ce68e99c6126f3d19deb2112dfa31c0865455f5fa77"
},
"downloads": -1,
"filename": "unitclass-1.1.1.tar.gz",
"has_sig": false,
"md5_digest": "31dd3848ca4e08f5fc2353dc33e58915",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 29298,
"upload_time": "2023-12-13T00:20:18",
"upload_time_iso_8601": "2023-12-13T00:20:18.603463Z",
"url": "https://files.pythonhosted.org/packages/c7/4d/0bcf3e1667d3bcae654bebe0c230fcae5b3606a4f617ec2c7e691a9bf2b9/unitclass-1.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-13 00:20:18",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "blakegarretson",
"github_project": "unitclass",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "unitclass"
}
