Metadata-Version: 2.4
Name: scifloat
Version: 3.0.0
Summary: Alternative float type for scientific measurements.
Author-email: Jan-Niklas Pippert <jnpippert@mpe.mpg.de>
License-Expression: MIT
Project-URL: Homepage, https://github.com/jnpippert/scifloat
Project-URL: Bug Tracker, https://github.com/jnpippert/scifloat/issues
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: matplotlib; extra == "dev"
Dynamic: license-file

# scifloat

Alternative to conventional floats used for scientific measurements.

```bash
pip install scifloat
```

## Quick start

```python
from scifloat.scifloat import scifloat

s = round(scifloat(1.2421, 0.0513))
print(s)          # 1.24 ± 0.06

a = round(scifloat(1.36551315, [0.0302, 0.00891]))
print(a)  # 1.37 +0.04 | -0.01
```

Nothing is rounded until you call `round()` — `scifloat(x, dx)` just stores the raw
value and error(s). `x` and `dx` can be ints, floats, or strings.

## The two rounding rules

1. **Errors round up**, to 2 significant digits if the leading digit is 1 or 2,
   otherwise to 1 (`0.0111` → `0.012`, `0.0513` → `0.06`).
2. **The value rounds** to the error's precision, using classic round-half-to-even
   (`1.35` → `1.4`, `1.25` → `1.2`).

For an asymmetric error, the coarser (fewer decimal places) side sets the shared
precision — pass `match_precision=False` to keep each side at its own precision instead.

## Arithmetic

`+ - * /` between two `scifloat`s propagate the errors in quadrature:

```python
x = scifloat(10.5, 0.3)
y = scifloat(2.0, 0.1)
print(round(x + y))  # 12.5 ± 0.4
print(round(x / y))  # 5.2 ± 0.4
```

## LaTeX export

```python
s.to_latex()
# '$\\num[parse-numbers=false]{1.24 \\pm 0.06}$'

s.to_latex(symbol="x_obs", unit=r"\meter")
# '$x_{\\mathrm{obs}} = \\SI[parse-numbers=false]{1.24 \\pm 0.06}{\\meter}$'
```

## More

See the [tutorial notebook](https://github.com/jnpippert/scifloat/blob/main/notebooks/tutorial.ipynb)
for a full walkthrough of both rounding rules, asymmetric errors, and every `to_latex()`
option.
