Metadata-Version: 2.5
Name: ertkit
Version: 0.1.0
Summary: Resistivity inversion for groundwater exploration (VES now, 2.5-D ERT planned), with uncertainty and depth of investigation.
Project-URL: Documentation, https://abdgafartunde.github.io/ertkit/
Project-URL: Source, https://github.com/abdgafartunde/ertkit
Project-URL: Issues, https://github.com/abdgafartunde/ertkit/issues
Project-URL: Changelog, https://github.com/abdgafartunde/ertkit/blob/main/CHANGELOG.md
Author: Abd'gafar Tunde Tiamiyu
License-Expression: MIT
License-File: LICENSE
Keywords: electrical resistivity tomography,geophysics,groundwater,inverse problems,uncertainty quantification,vertical electrical sounding
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Topic :: Scientific/Engineering :: Hydrology
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: libdlf>=0.3
Requires-Dist: numpy>=2.0
Requires-Dist: scipy>=1.16
Provides-Extra: plot
Requires-Dist: matplotlib>=3.10; extra == 'plot'
Description-Content-Type: text/markdown

# ertkit

[![PyPI](https://img.shields.io/pypi/v/ertkit.svg)](https://pypi.org/project/ertkit/)
[![CI](https://github.com/abdgafartunde/ertkit/actions/workflows/ci.yml/badge.svg)](https://github.com/abdgafartunde/ertkit/actions/workflows/ci.yml)
[![Docs](https://github.com/abdgafartunde/ertkit/actions/workflows/docs.yml/badge.svg)](https://abdgafartunde.github.io/ertkit/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/abdgafartunde/ertkit/blob/main/LICENSE)

**Resistivity imaging for groundwater exploration, with an honest account of
what the data can resolve.**

ertkit is a Python package for inverting vertical electrical sounding (VES)
data, with 2.5-D electrical resistivity tomography (ERT) to follow. Each
result comes with what is needed to judge it:

- a data error model, and a fit to the noise level rather than to every digit
  of the data;
- sensitivity and depth of investigation, so that unresolved parts of a model
  are marked as such;
- parameter uncertainty, with the range of equivalent models that fit the data
  equally well planned for release 0.2.

## Why another resistivity code?

Boreholes are often sited from resistivity models whose reliability was never
quantified. Open tools such as [pyGIMLi](https://www.pygimli.org),
[SimPEG](https://simpeg.xyz) and [ResIPy](https://gitlab.com/hkex/resipy)
already provide excellent modeling and inversion. ertkit focuses on three
things: making reliability the default output, publishing a verification
report with every release, and keeping the code small enough to teach from.
The [design document](https://abdgafartunde.github.io/ertkit/dev/design.html)
gives the full statement of need, the mathematics and the verification plan.

## Installation

```bash
pip install ertkit            # Python 3.12 or later
pip install "ertkit[plot]"    # with plotting (matplotlib)
```

## Quick start

```python
import numpy as np
import ertkit
from ertkit import ves

truth = ves.LayeredModel(resistivity=[150.0, 30.0, 800.0], thickness=[2.0, 15.0])
survey = ves.Survey.schlumberger(ab2=np.geomspace(2.5, 200.0, 22), mn2=0.5)
data = ves.Sounding.synthetic(truth, survey, ertkit.ErrorModel(relative=0.03), rng=5)
# Field data: data = ves.read_csv("sounding.csv")

fit = ves.invert_few_layer(data, n_layers=3, rng=0)
print(fit.summary())  # layers with uncertainty factors (x/), depths +- sd, fit

smooth = ves.invert_smooth(data)
print(f"depth of investigation: {smooth.doi:.0f} m")
```

The first `print` shows:

```text
LayerFit: chi2 = 16.1 for 22 data (target 17, ratio 0.947)
converged: True (`ftol` termination condition is satisfied.)

layer  resistivity (ohm m)    thickness (m)         depth (m)
    1      144.6 x/ 1.04          2.04 x/ 1.04           2.04 +- 0.075
    2      30.18 x/ 1.03          15.2 x/ 1.05           17.3 +- 0.69
    3      787.9 x/ 1.12      half-space
p-value: 0.517
```

Here `x/ 1.04` means "multiplied or divided by 1.04" (one standard
deviation).

## Status

Release 0.1 covers vertical electrical sounding: a layered-earth forward
model, few-layer inversion with linearized uncertainty, smooth inversion with
sensitivity and a depth of investigation, CSV input and plotting. Planned
releases:

| Release | Content |
|---|---|
| 0.1 | VES: layered-earth forward model, few-layer and smooth inversion, linearized uncertainty, sensitivity and depth of investigation |
| 0.2 | VES equivalence analysis |
| 0.3 | 2.5-D ERT forward modeling |
| 0.4 | ERT inversion with an error model and cumulative sensitivity |
| 0.5 | ERT depth of investigation and uncertainty maps |
| 0.6 | Field data formats and an end-to-end field example |
| 1.0 | Stable public API |

## Documentation

The documentation at <https://abdgafartunde.github.io/ertkit/> has the user
guide, worked examples, the API reference and the
[verification report](https://abdgafartunde.github.io/ertkit/verification.html),
generated by the test suite for each release.

## Contributing

Bug reports, questions and suggestions are welcome on the
[issue tracker](https://github.com/abdgafartunde/ertkit/issues). To work on
the code, install [uv](https://docs.astral.sh/uv/) and run:

```bash
git clone https://github.com/abdgafartunde/ertkit.git
cd ertkit
uv sync
uv run pytest
```

See the [contributing guide](https://github.com/abdgafartunde/ertkit/blob/main/CONTRIBUTING.md)
and the [Code of Conduct](https://github.com/abdgafartunde/ertkit/blob/main/CODE_OF_CONDUCT.md).

## Citing

Each release is archived on Zenodo with a DOI. Citation metadata are in
[CITATION.cff](https://github.com/abdgafartunde/ertkit/blob/main/CITATION.cff);
please also cite the methods ertkit implements.

## License

MIT; see [LICENSE](https://github.com/abdgafartunde/ertkit/blob/main/LICENSE).
