Metadata-Version: 2.1
Name: nist
Version: 0.0.2
Summary: si type metric
Home-page: https://github.com/dsm-72/nist
Author: dsm-72
Author-email: sumner.magruder@yale.edu
License: Apache Software License 2.0
Keywords: nbdev jupyter notebook python byte bytes kilo tera giga unit dataclass strenum
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3.11
Classifier: License :: OSI Approved :: Apache Software License
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Provides-Extra: dev
License-File: LICENSE

# nist

<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

From the [National Institute of Standards and
Technology](https://www.nist.gov)’s [Office OF Weights and
Measures](https://www.nist.gov/pml/owm), one can find a handy list of
all the [metric
prefixes](https://www.nist.gov/pml/owm/metric-si-prefixes#:~:text=Prefix%20Total&text=Eight%20original%20SI%20prefixes%20were,from%20Greek%20and%20Latin%20numbers.):
e.g.

| Purpose                          | Name                       | Symbol | Factor       | Name         |
|----------------------------------|----------------------------|--------|--------------|--------------|
| larger quantities or whole units | quetta                     | Q      | $$10^{30}$$  | nonillion    |
|                                  | ronna                      | R      | $$10^{27}$$  | octillion    |
|                                  | yotta                      | Y      | $$10^{24}$$  | septillion   |
|                                  | …                          | …      | …            | …            |
|                                  | hecto Example: hectare     | h      | $$10^{2}$$   | hundred      |
|                                  | deka Example: dekameter    | da     | $$10^{1}$$   | ten          |
|                                  |                            |        | $$10^{o}$$   | one          |
|                                  | deci Example: decimeter    | da     | $$10^{-1}$$  | tenth        |
|                                  | centi Example: centigram   | h      | $$10^{-2}$$  | hundredth    |
|                                  | …                          | …      | …            | …            |
|                                  | yocto Example: yoctosecond | y      | $$10^{-24}$$ | septillionth |
|                                  | ronto                      | r      | $$10^{-27}$$ | octillionth  |
| smaller quantities or sub units  | quecto                     | q      | $$10^{-30}$$ | nonillionth  |

Oh how nice it would be to have a class like
[`unit`](https://dsm-72.github.io/nist/unit.html#unit) which we could
subclass and use as follows:

``` python
class second(unit): 
    name = 'second'

s1 = second(1)
s1, s1.kilo, s1.milli, s1.to(3), float(s1.to(3))
(1.0 S, 0.001 KS, 1000.0 mS, 0.001 KS, 0.001)
```

ah so easy to convert between and even have clean formatting.

## Install

``` sh
pip install nist
```

## Usage

### [`fact`](https://dsm-72.github.io/nist/fact.html#fact)

While each [`fact`](https://dsm-72.github.io/nist/fact.html#fact)
(factor) has `base: ClassVar[int] = 10`, `base` is actually an instance
variable.

``` python
>>> float(kilo()), float(kilo(base=2)), float(kilo(base=5)), float(kilo(base=10))

(1000.0, 8.0, 125.0, 1000.0)
```

In case that behavior is not obvious
[`fact`](https://dsm-72.github.io/nist/fact.html#fact) is really just a
named and explicilty signed exponent:

``` python
>>> kb = kilo(base=2)
>>> kb.abrv, kb.base, kb.expo, kb.sign, kb.ekey, float(kb)

('kilo', 2, 3, 1, 3, 8.0)
```

Each [`fact`](https://dsm-72.github.io/nist/fact.html#fact) uses `efmt`
for its representation by default `efmt` is True, but can be turned off
by setting `efmt` to False.

``` python
>>> (
    (decka(), hecto(), kilo(), mega(), giga(), tera()),
    (decka(showefmt=False), hecto(showefmt=False), kilo(showefmt=False), mega(showefmt=False), giga(showefmt=False), tera(showefmt=False))
)

((e+1, e+2, e+3, e+6, e+9, e+12), (F1P, F2P, F3P, F6P, F9P, F12P))
```

Actually we have three formats to work with:

``` python
>>> kilo().fstr, kilo(showbase=True).bstr, kilo(showbase=True).efmt

('F3P', '10^+3', 'e+3')
```

### [`unit`](https://dsm-72.github.io/nist/unit.html#unit)

The goal of the [`unit`](https://dsm-72.github.io/nist/unit.html#unit)
class is to make it easy to create units:

``` python
class second(unit): 
    name = 'second'

>>> s1 = second(1)
>>> s1, s1.kilo, s1.milli, s1.to(3), float(s1.to(3)), s1.shownumb


(1.0 S, 0.001 KS, 1000.0 mS, 0.001 KS, 0.001, True)
```

We can also explore all the different ways of viewing formats:

``` python
import pandas as pd

results = list()
factors = (tera, decka, deci, centi, milli, pico)
for fcls in factors:
    for flt in (1, 20, 0.03):
        for factrepr in {'abrv', 'name', 'symb'}:
            for shownumb in (True, False):
                for abrvunit in (True, False):
                    res = fmtunit(
                        org = flt, flt=flt / float(fcls()), unt = unit, fct = fcls,
                        factrepr=factrepr, shownumb=shownumb, abrvunit=abrvunit,
                        unitname='second', factname=None, ndig=3
                    )
                    
                    results.append(dict(
                        fname=fcls.name, flt=flt, res=res, org = flt / float(fcls()),
                        shownumb=shownumb, abrvunit=abrvunit, factrepr=factrepr
                    ))

df = pd.DataFrame(results).sort_values(by=['fname', 'res'])
df.head()
```

|     | fname     |  flt | res          | org | shownumb | abrvunit | factrepr |
|----:|:----------|-----:|:-------------|----:|:---------|:---------|:---------|
| 134 | hundredth | 0.03 | 0.03 S       |   3 | False    | True     | name     |
| 138 | hundredth | 0.03 | 0.03 S       |   3 | False    | True     | abrv     |
| 142 | hundredth | 0.03 | 0.03 S       |   3 | False    | True     | symb     |
| 143 | hundredth | 0.03 | 0.03 S       |   3 | False    | False    | symb     |
| 135 | hundredth | 0.03 | 0.03 seconds |   3 | False    | False    | name     |
