ertkit 0.1.0__tar.gz

ertkit-0.1.0/.git_archival.txt

@@ -0,0 +1,3 @@
+node: $Format:%H$
+node-date: $Format:%cI$
+describe-name: $Format:%(describe:tags=true,match=*[0-9]*)$

ertkit-0.1.0/.gitattributes

@@ -0,0 +1,2 @@
+* text=auto eol=lf
+.git_archival.txt export-subst

ertkit-0.1.0/.gitignore

@@ -0,0 +1,32 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+
+# Generated by hatch-vcs at build time
+src/ertkit/_version.py
+
+# Tools
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.hypothesis/
+
+# Documentation build output
+docs/_build/
+docs/auto_examples/
+docs/generated/
+docs/_generated/
+docs/sg_execution_times.rst
+
+# Editors and operating systems
+.DS_Store
+.idea/
+.vscode/

ertkit-0.1.0/.mailmap

@@ -0,0 +1 @@
+Abd'gafar Tunde Tiamiyu <abdgafartunde@gmail.com> abdgafartunde <abdgafartunde@gmail.com>

ertkit-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,57 @@
+# Hooks are updated monthly by pre-commit.ci when it is enabled for the
+# repository, and otherwise with `uv run pre-commit autoupdate` before each
+# release (CONTRIBUTING.md).
+ci:
+  autoupdate_schedule: monthly
+  autoupdate_commit_msg: "chore(deps): update pre-commit hooks"
+  autofix_commit_msg: "style: pre-commit fixes"
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: check-added-large-files
+      - id: check-case-conflict
+      - id: check-merge-conflict
+      - id: check-toml
+      - id: check-yaml
+      - id: end-of-file-fixer
+      - id: mixed-line-ending
+        args: [--fix=lf]
+      - id: trailing-whitespace
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.17.0
+    hooks:
+      - id: ruff-check
+        args: [--fix, --show-fixes, --exit-non-zero-on-fix]
+      - id: ruff-format
+
+  - repo: https://github.com/abravalheri/validate-pyproject
+    rev: v0.25
+    hooks:
+      - id: validate-pyproject
+
+  - repo: https://github.com/python-jsonschema/check-jsonschema
+    rev: 0.38.2
+    hooks:
+      - id: check-github-workflows
+      - id: check-dependabot
+
+  - repo: https://github.com/codespell-project/codespell
+    rev: v2.4.3
+    hooks:
+      - id: codespell
+        additional_dependencies: [tomli]
+
+  - repo: https://github.com/pre-commit/pygrep-hooks
+    rev: v1.10.0
+    hooks:
+      - id: rst-backticks
+      - id: rst-directive-colons
+      - id: rst-inline-touching-normal
+
+  - repo: https://github.com/zizmorcore/zizmor-pre-commit
+    rev: v1.30.1
+    hooks:
+      - id: zizmor

ertkit-0.1.0/.zenodo.json

@@ -0,0 +1,28 @@
+{
+  "upload_type": "software",
+  "title": "ertkit: resistivity inversion for groundwater exploration, with uncertainty and depth of investigation",
+  "creators": [
+    {
+      "name": "Tiamiyu, Abd'gafar Tunde",
+      "affiliation": "School of Mathematics, Jilin University",
+      "orcid": "0000-0003-1641-7196"
+    }
+  ],
+  "description": "ertkit is a Python package for inverting vertical electrical sounding (VES) data for groundwater exploration; 2.5-D electrical resistivity tomography (ERT) follows in later releases. Each result states what the data can resolve: a data error model and a fit to the noise level, linearized parameter uncertainty, sensitivity and a depth of investigation. Every release publishes a verification report generated by its test suite.",
+  "license": "mit",
+  "keywords": [
+    "vertical electrical sounding",
+    "electrical resistivity tomography",
+    "geophysics",
+    "groundwater",
+    "inverse problems",
+    "uncertainty quantification"
+  ],
+  "related_identifiers": [
+    {
+      "identifier": "https://abdgafartunde.github.io/ertkit/",
+      "relation": "isDocumentedBy",
+      "scheme": "url"
+    }
+  ]
+}

ertkit-0.1.0/CHANGELOG.md

@@ -0,0 +1,84 @@
+# Changelog
+
+All notable changes to ertkit are recorded here. The format follows
+[Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/), and the
+project uses [semantic versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-15
+
+### Added
+
+- Project foundation (milestone 0.0): packaging with versions from git tags,
+  continuous integration on Linux, Windows and macOS, a documentation website,
+  a release pipeline using trusted publishing, and contributor guidelines.
+- Design document with the mathematics, the verification plan and the
+  engineering standards (`docs/dev/design.md`).
+- `ertkit.show_versions()` for bug reports.
+- VES forward model: `ves.LayeredModel`, `ves.Survey` (Schlumberger soundings
+  with finite and changing MN, and Wenner soundings), `ves.forward`,
+  `ves.potential`, and the building blocks `ves.resistivity_transform` and
+  `ves.hankel_j0` (Guptasarma and Singh 120-point filter).
+- `ErrorModel`: measurement errors on the transfer resistance, with a 3%
+  relative default that includes a modeling-error floor, and a warning when
+  the relative part looks like a percentage (above 0.5).
+- `ves.Sounding` (data with their error model; readings with R <= 0 or below
+  the noise level are removed with a `DataWarning` that lists their AB/2),
+  synthetic data with `Sounding.synthetic`, and CSV input and output with
+  `ves.read_csv` and `ves.write_csv` (explicit text encoding; empty
+  spreadsheet rows are skipped, and errors give the line and, for a file in
+  another encoding, how to read it).
+- Warning categories `ConvergenceWarning` and `DataWarning`.
+- Few-layer VES inversion, `ves.invert_few_layer`: log parameters, a
+  trust-region least-squares search from several starting models within
+  resolvable bounds, complex-step Jacobian, linearized uncertainty
+  (standard deviations, multiplicative factors, correlations, depths with
+  standard deviations), a goodness-of-fit p-value, and optional static-shift
+  factors per MN segment (`LayerFit.segment_mn2` maps them to MN/2). Each
+  start runs briefly and the best are continued until one converges, which
+  makes over-parameterized fits several times faster; a misfit that stays put
+  while the parameters drift along a ridge of equivalent models counts as
+  converged. Warnings: a poor fit (with a static-shift hint when there are
+  several MN segments, and a note that the uncertainties are then too small),
+  a fit closer than the errors imply, parameters at their search bounds (with
+  advice for each), and poorly determined parameters (uncertainty factor above
+  10). The fit with the smallest misfit over all starts is kept, and the
+  linearized covariance comes from the singular values of the weighted
+  Jacobian, so undetermined parameters get infinite uncertainty. Results are
+  `ves.LayerFit` objects, with read-only arrays.
+- Smooth (Occam) VES inversion, `ves.invert_smooth`: many layers with
+  logarithmically growing thicknesses, the target misfit chi2 = N_d with the
+  largest regularization weight that reaches it, the error-weighted
+  sensitivity of each layer, and the Oldenburg and Li depth of investigation
+  from two reference-model inversions that aim at the same misfit (the top of
+  the unresolved zone that reaches the bottom of the model, bridging resolved
+  gaps narrower than a factor of 2 in depth, so that it is stable against
+  overshoot of the reference models and against the number of layers). When
+  chi2 = N_d cannot be reached, the
+  model fits 1.1 times the smallest misfit instead, with a warning only if
+  that misfit is improbably large. Results are `ves.SmoothFit` objects.
+- Every result has normalized `residuals` and a readable `summary()`
+  (`ertkit.results.InversionResult`).
+- Plotting with matplotlib (`ertkit.plot.sounding`, `ertkit.plot.layered_model`;
+  install with `pip install "ertkit[plot]"`). Wenner fits are drawn as one
+  curve, and unbounded error bars are cut at the edges of the plot.
+- Documentation: a user guide for VES (including error-model guidance and
+  choosing the number of layers), six worked examples (few-layer inversion,
+  smooth inversion and depth of investigation, equivalence of a suppressed
+  layer, static shifts, reading CSV files, checking an installation), and a
+  verification report generated by the tests for every documentation build.
+- A weekly cross-check of the VES forward model against pyGIMLi and SimPEG
+  (with a different Hankel filter), also run before each release.
+- An honest-uncertainty test: over 1000 noise draws, the misfit and the
+  coverage of the linearized intervals match their theoretical values.
+- `arrays.geometric_factor` for any four-electrode array, including remote
+  electrodes.
+- Verification tests against the two-layer image series (contrasts from
+  1e-4 to 1e4) and the Lipschitz integral, and of the depth of investigation
+  against a detectable depth computed independently from the true model,
+  recorded in a verification report (`pytest -m verification
+  --verification-report=PATH`).
+
+[Unreleased]: https://github.com/abdgafartunde/ertkit/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/abdgafartunde/ertkit/releases/tag/v0.1.0

ertkit-0.1.0/CITATION.cff

@@ -0,0 +1,26 @@
+cff-version: 1.2.0
+message: "If you use ertkit in your work, please cite it as below, together with the methods it implements."
+title: "ertkit: resistivity inversion for groundwater exploration, with uncertainty and depth of investigation"
+type: software
+authors:
+  - family-names: Tiamiyu
+    given-names: "Abd'gafar Tunde"
+    orcid: "https://orcid.org/0000-0003-1641-7196"
+    affiliation: "School of Mathematics, Jilin University"
+version: "0.1.0"
+date-released: "2026-10-15"
+license: MIT
+repository-code: "https://github.com/abdgafartunde/ertkit"
+url: "https://abdgafartunde.github.io/ertkit/"
+abstract: >-
+  ertkit inverts vertical electrical sounding (VES) data for groundwater
+  exploration; 2.5-D electrical resistivity tomography (ERT) follows in later
+  releases. Each result comes with a data error model and a fit to the noise
+  level, linearized parameter uncertainty, sensitivity and a depth of
+  investigation.
+keywords:
+  - electrical resistivity tomography
+  - vertical electrical sounding
+  - groundwater
+  - inverse problems
+  - uncertainty quantification

ertkit-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,89 @@
+# Contributor Covenant 3.0 Code of Conduct
+
+## Our Pledge
+
+We pledge to make our community welcoming, safe, and equitable for all.
+
+We are committed to fostering an environment that respects and promotes the dignity, rights, and contributions of all individuals, regardless of characteristics including race, ethnicity, caste, color, age, physical characteristics, neurodiversity, disability, sex or gender, gender identity or expression, sexual orientation, language, philosophy or religion, national or social origin, socio-economic position, level of education, or other status. The same privileges of participation are extended to everyone who participates in good faith and in accordance with this Covenant.
+
+
+## Encouraged Behaviors
+
+While acknowledging differences in social norms, we all strive to meet our community's expectations for positive behavior. We also understand that our words and actions may be interpreted differently than we intend based on culture, background, or native language.
+
+With these considerations in mind, we agree to behave mindfully toward each other and act in ways that center our shared values, including:
+
+1. Respecting the **purpose of our community**, our activities, and our ways of gathering.
+2. Engaging **kindly and honestly** with others.
+3. Respecting **different viewpoints** and experiences.
+4. **Taking responsibility** for our actions and contributions.
+5. Gracefully giving and accepting **constructive feedback**.
+6. Committing to **repairing harm** when it occurs.
+7. Behaving in other ways that promote and sustain the **well-being of our community**.
+
+
+## Restricted Behaviors
+
+We agree to restrict the following behaviors in our community. Instances, threats, and promotion of these behaviors are violations of this Code of Conduct.
+
+1. **Harassment.** Violating explicitly expressed boundaries or engaging in unnecessary personal attention after any clear request to stop.
+2. **Character attacks.** Making insulting, demeaning, or pejorative comments directed at a community member or group of people.
+3. **Stereotyping or discrimination.** Characterizing anyone’s personality or behavior on the basis of immutable identities or traits.
+4. **Sexualization.** Behaving in a way that would generally be considered inappropriately intimate in the context or purpose of the community.
+5. **Violating confidentiality**. Sharing or acting on someone's personal or private information without their permission.
+6. **Endangerment.** Causing, encouraging, or threatening violence or other harm toward any person or group.
+7. Behaving in other ways that **threaten the well-being** of our community.
+
+### Other Restrictions
+
+1. **Misleading identity.** Impersonating someone else for any reason, or pretending to be someone else to evade enforcement actions.
+2. **Failing to credit sources.** Not properly crediting the sources of content you contribute.
+3. **Promotional materials**. Sharing marketing or other commercial content in a way that is outside the norms of the community.
+4. **Irresponsible communication.** Failing to responsibly present content which includes, links or describes any other restricted behaviors.
+
+
+## Reporting an Issue
+
+Tensions can occur between community members even when they are trying their best to collaborate. Not every conflict represents a code of conduct violation, and this Code of Conduct reinforces encouraged behaviors and norms that can help avoid conflicts and minimize harm.
+
+When an incident does occur, it is important to report it promptly. To report a possible violation, email the maintainer, Abd'gafar Tunde Tiamiyu, at abdgafartunde@yahoo.com. Reports are handled confidentially; if a report concerns the maintainer, you may instead contact GitHub Support.
+
+Community Moderators take reports of violations seriously and will make every effort to respond in a timely manner. They will investigate all reports of code of conduct violations, reviewing messages, logs, and recordings, or interviewing witnesses and other participants. Community Moderators will keep investigation and enforcement actions as transparent as possible while prioritizing safety and confidentiality. In order to honor these values, enforcement actions are carried out in private with the involved parties, but communicating to the whole community may be part of a mutually agreed upon resolution.
+
+
+## Addressing and Repairing Harm
+
+If an investigation by the Community Moderators finds that this Code of Conduct has been violated, the following enforcement ladder may be used to determine how best to repair harm, based on the incident's impact on the individuals involved and the community as a whole. Depending on the severity of a violation, lower rungs on the ladder may be skipped.
+
+1) Warning
+   1) Event: A violation involving a single incident or series of incidents.
+   2) Consequence: A private, written warning from the Community Moderators.
+   3) Repair: Examples of repair include a private written apology, acknowledgement of responsibility, and seeking clarification on expectations.
+2) Temporarily Limited Activities
+   1) Event: A repeated incidence of a violation that previously resulted in a warning, or the first incidence of a more serious violation.
+   2) Consequence: A private, written warning with a time-limited cooldown period designed to underscore the seriousness of the situation and give the community members involved time to process the incident. The cooldown period may be limited to particular communication channels or interactions with particular community members.
+   3) Repair: Examples of repair may include making an apology, using the cooldown period to reflect on actions and impact, and being thoughtful about re-entering community spaces after the period is over.
+3) Temporary Suspension
+   1) Event: A pattern of repeated violation which the Community Moderators have tried to address with warnings, or a single serious violation.
+   2) Consequence: A private written warning with conditions for return from suspension. In general, temporary suspensions give the person being suspended time to reflect upon their behavior and possible corrective actions.
+   3) Repair: Examples of repair include respecting the spirit of the suspension, meeting the specified conditions for return, and being thoughtful about how to reintegrate with the community when the suspension is lifted.
+4) Permanent Ban
+   1) Event: A pattern of repeated code of conduct violations that other steps on the ladder have failed to resolve, or a violation so serious that the Community Moderators determine there is no way to keep the community safe with this person as a member.
+   2) Consequence: Access to all community spaces, tools, and communication channels is removed. In general, permanent bans should be rarely used, should have strong reasoning behind them, and should only be resorted to if working through other remedies has failed to change the behavior.
+   3) Repair: There is no possible repair in cases of this severity.
+
+This enforcement ladder is intended as a guideline. It does not limit the ability of Community Managers to use their discretion and judgment, in keeping with the best interests of our community.
+
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public or other spaces. Examples of representing our community include using an official email address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+
+## Attribution
+
+This Code of Conduct is adapted from the Contributor Covenant, version 3.0, permanently available at [https://www.contributor-covenant.org/version/3/0/](https://www.contributor-covenant.org/version/3/0/).
+
+Contributor Covenant is stewarded by the Organization for Ethical Source and licensed under CC BY-SA 4.0. To view a copy of this license, visit [https://creativecommons.org/licenses/by-sa/4.0/](https://creativecommons.org/licenses/by-sa/4.0/)
+
+For answers to common questions about Contributor Covenant, see the FAQ at [https://www.contributor-covenant.org/faq](https://www.contributor-covenant.org/faq). Translations are provided at [https://www.contributor-covenant.org/translations](https://www.contributor-covenant.org/translations). Additional enforcement and community guideline resources can be found at [https://www.contributor-covenant.org/resources](https://www.contributor-covenant.org/resources). The enforcement ladder was inspired by the work of [Mozilla’s code of conduct team](https://github.com/mozilla/inclusion).

ertkit-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,125 @@
+# Contributing to ertkit
+
+Thank you for your interest in ertkit. Bug reports, questions, suggestions and
+pull requests are all welcome. Everyone taking part follows the
+[Code of Conduct](https://github.com/abdgafartunde/ertkit/blob/main/CODE_OF_CONDUCT.md).
+
+## Support
+
+ertkit is maintained by one researcher on a best-effort basis. Questions and
+bug reports go to the [issue tracker](https://github.com/abdgafartunde/ertkit/issues);
+a bug report should include the output of `ertkit.show_versions()`.
+
+## Development setup
+
+Install [uv](https://docs.astral.sh/uv/), then:
+
+```bash
+git clone https://github.com/abdgafartunde/ertkit.git
+cd ertkit
+uv sync                          # creates .venv with all development tools
+uv run pre-commit install        # runs the formatters and linters on commit
+```
+
+## Everyday commands
+
+| Task | Command |
+|---|---|
+| Tests | `uv run pytest` |
+| Tests with coverage | `uv run pytest --cov` |
+| Fast tests only | `uv run pytest -m "not slow"` |
+| Lint and format | `uv run pre-commit run --all-files` |
+| Type check | `uv run mypy` |
+| Verification report (for the docs) | `uv run pytest -m verification --verification-report=docs/_generated/verification.json` |
+| Documentation | `uv run sphinx-build -W --keep-going docs docs/_build/html` |
+
+Test markers: `slow` (long tests, skipped by the oldest-dependencies job),
+`verification` (checks that feed the verification report) and `crosscheck`
+(comparisons with pyGIMLi and SimPEG, run weekly).
+
+## Pull requests
+
+One pull request per feature or fix. Each pull request:
+
+- adds or updates tests, and states the justification for every numerical
+  tolerance next to it;
+- updates the documentation and adds an entry under `[Unreleased]` in
+  `CHANGELOG.md`;
+- passes all CI checks before it is merged (merges are squash merges).
+
+Numbers in the documentation are never typed by hand: they come from the
+example gallery, the verification report or named constants.
+
+## Code provenance
+
+No code is adapted from GPL-licensed projects such as ResIPy. Code adapted from
+permissively licensed projects (for example pyGIMLi, Apache-2.0) keeps their
+attribution. Digital filter coefficients come from libdlf, whose filter values
+are licensed CC BY 4.0 and are attributed in the documentation.
+
+## Use of AI tools
+
+Development uses AI assistance: Claude Code (Anthropic) helps write code,
+tests and documentation, and runs reviews of the mathematics, the code and the
+documentation before releases. The maintainer makes the design decisions and
+personally checks derivations, tolerances and the verification report before
+each release. Each release's notes summarize the AI assistance and what was
+checked by hand.
+
+## Documentation deployment
+
+The documentation is built for every pull request and push to `main`, and
+deployed when a release is published, so the website matches the latest
+release; a manual run of the Docs workflow redeploys it (for example after
+adding the DOI).
+
+## Maintainer's sign-off checklist
+
+Before each release the maintainer checks, personally:
+
+- the derivations behind the release's new methods, against the design
+  document and the cited papers;
+- that every tolerance in the verification report has a sound justification;
+- the verification report and the cross-check results of the release
+  candidate;
+- that the examples' text matches what they print;
+- the AI-assisted review's findings and how each was resolved.
+
+## Release checklist
+
+1. All CI checks pass on `main`, and the weekly cross-check workflow has been
+   run on the release candidate.
+2. The AI-assisted review is done and the maintainer's sign-off checklist
+   above is complete.
+3. `CHANGELOG.md`: rename `[Unreleased]` to `[X.Y.Z] - YYYY-MM-DD` and add a
+   new empty `[Unreleased]` section.
+4. `CITATION.cff`: set `version` and `date-released`. `README.md`: update the
+   status section.
+5. `uv run pre-commit autoupdate` has been run, unless pre-commit.ci keeps
+   the hooks current.
+6. A development build uploaded to TestPyPI (manual run of the `Release`
+   workflow) installs and imports correctly.
+7. Check that `.zenodo.json` is present, the Zenodo webhook is on, the PyPI
+   trusted publisher exists, and the `github-pages` environment allows tags
+   `v*`.
+8. Create the GitHub release with tag `vX.Y.Z`; its notes summarize the AI
+   assistance and what the maintainer checked by hand. The `Release` workflow
+   checks that the tag matches `CITATION.cff` and `CHANGELOG.md`, then uploads
+   to PyPI; Zenodo archives the release and issues a DOI, and the Docs
+   workflow deploys the documentation.
+9. After the release: add the DOI to `CITATION.cff`, the README and
+   `docs/citing.md`, then run the Docs workflow manually.
+
+## Repository review exceptions
+
+The repository is checked with the Scientific Python
+[repo-review](https://learn.scientific-python.org/development/guides/repo-review/).
+Three checks are deliberately not followed:
+
+- **PY007 (task runner).** The uv commands above play this role; a nox or tox
+  configuration would duplicate them.
+- **PC140 (type checker in pre-commit).** mypy runs as its own CI step from
+  the locked environment, where it sees numpy, scipy and their type stubs; in
+  pre-commit's isolated environment it would not.
+- **PC180 (Markdown formatter).** Markdown files contain LaTeX math that
+  formatters can rewrite in ways GitHub then renders wrongly.

ertkit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Abd'gafar Tunde Tiamiyu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ertkit-0.1.0/PKG-INFO

@@ -0,0 +1,156 @@
+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).