adtlert 0.1.0__tar.gz

adtlert-0.1.0/.gitignore

@@ -0,0 +1,26 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+.DS_Store
+._*
+*:Zone.Identifier
+
+# Virtual environments
+.venv/
+.venv-resipy/
+.cache/
+.tmp_wine_bin/
+
+2d_resistivity_model/
+models_1year_1day/
+.codex/
+.agents/
+result/
+ProcessedData/
+
+# Local research workspace; publish curated scripts from example/ instead.
+paper/

adtlert-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pu Yang
+
+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.

adtlert-0.1.0/PKG-INFO

@@ -0,0 +1,262 @@
+Metadata-Version: 2.4
+Name: adtlert
+Version: 0.1.0
+Summary: Differentiable 2.5D and 3D electrical resistivity tomography on PyTorch
+Project-URL: Homepage, https://github.com/Vcholerae1/AD-TLERT
+Project-URL: Documentation, https://github.com/Vcholerae1/AD-TLERT#readme
+Project-URL: Repository, https://github.com/Vcholerae1/AD-TLERT
+Project-URL: Issues, https://github.com/Vcholerae1/AD-TLERT/issues
+Author-email: Pu Yang <165551159+Vcholerae1@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: electrical resistivity tomography,geophysics,inverse problems,pytorch,scientific computing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.11
+Requires-Dist: meshio>=5.3.5
+Requires-Dist: numpy<3,>=1.26
+Requires-Dist: scipy<2,>=1.16
+Requires-Dist: torch<3,>=2.10
+Provides-Extra: cuda12
+Requires-Dist: cupy-cuda12x<15,>=14; (sys_platform == 'linux') and extra == 'cuda12'
+Requires-Dist: nvidia-cudss-cu12<1,>=0.7.1.6; (sys_platform == 'linux') and extra == 'cuda12'
+Requires-Dist: nvmath-python[cu12]<2,>=0.8; (sys_platform == 'linux') and extra == 'cuda12'
+Provides-Extra: examples
+Requires-Dist: ipykernel>=7.2; extra == 'examples'
+Requires-Dist: joblib>=1.5; extra == 'examples'
+Requires-Dist: matplotlib>=3.10; extra == 'examples'
+Requires-Dist: pandas>=2.2; extra == 'examples'
+Requires-Dist: pftools>=1.3.14; extra == 'examples'
+Requires-Dist: pygimli<2,>=1.6; extra == 'examples'
+Requires-Dist: pyhydrogeophysx>=0.1; extra == 'examples'
+Requires-Dist: triangle>=20250106; extra == 'examples'
+Provides-Extra: terrain
+Requires-Dist: pftools>=1.3.14; extra == 'terrain'
+Requires-Dist: triangle>=20250106; extra == 'terrain'
+Description-Content-Type: text/markdown
+
+# AD-TLERT
+
+Differentiable 2.5D ERT and tetrahedral 3D DC forward tooling on Torch.
+
+The repository contains:
+
+- `adtlert/`: the core numerical implementation.
+- `example/single_time/`: ADTLERT/pyGIMLi forward examples and
+  ADTLERT/pyGIMLi/ResIPy single-time inversion examples.
+- `example/window_363/`: ADTLERT/pyGIMLi/ResIPy inversion examples for 365
+  time steps using 3-step sliding windows (363 windows).
+- `parflow_models/` and `resistivity_models_2d/`: input data used by the
+  examples.
+
+See [`example/README.md`](example/README.md) for commands and backend
+requirements.
+
+## Install
+
+Install the CPU/SciPy build from PyPI:
+
+```bash
+python -m pip install adtlert
+```
+
+CUDA 12 acceleration through NVIDIA cuDSS is an optional Linux extra:
+
+```bash
+python -m pip install "adtlert[cuda12]"
+```
+
+The CUDA driver must support CUDA 12, and only one CuPy CUDA variant may be
+installed in an environment. CPU-only installations do not install CuPy,
+cuDSS, or nvmath-python.
+
+For development from a checkout, use `uv`. The terrain examples read ParFlow
+PFB files and build Triangle inversion meshes:
+
+```bash
+uv sync --extra cuda12 --extra examples
+```
+
+## Core Forward API
+
+```python
+import torch
+
+from adtlert.forward import ERTForward2p5D
+
+forward = ERTForward2p5D.from_mesh_survey(mesh, survey)
+conductivity = torch.as_tensor(1.0 / resistivity, dtype=torch.float32)
+response = forward.solve(conductivity)
+
+rhoa = response.apparent_resistivity
+jacobian = forward.jacobian(conductivity)
+```
+
+For matrix-free differentiation, use the PyTorch autograd bridge. Its reverse
+pass calls `forward.vjp(...)`, while PyTorch forward AD calls
+`forward.jvp(...)`; no explicit Jacobian is materialized:
+
+```python
+from adtlert.forward import apparent_resistivity_autograd
+
+conductivity = conductivity.requires_grad_()
+rhoa = apparent_resistivity_autograd(conductivity, forward, currents=1.0)
+loss = data_misfit(rhoa, observed_rhoa)
+loss.backward()
+conductivity_gradient = conductivity.grad
+```
+
+True 3D DC forward modelling uses a tetrahedral mesh and three-coordinate
+electrodes. It follows pyGIMLi's 3D singularity-removal formulation, with an
+analytic half-space primary field and a mixed far-field boundary:
+
+```python
+from adtlert.forward import ERTForward3D
+from adtlert.mesh import Mesh3D
+from adtlert.survey import Survey
+
+mesh3d = Mesh3D.from_file("mesh3d.vtu")
+survey3d = Survey.from_arrays(electrode_xyz, abmn)
+forward3d = ERTForward3D.from_mesh_survey(mesh3d, survey3d)
+response3d, jacobian3d = forward3d.solve_with_jacobian(conductivity3d)
+```
+
+For topography, use quadratic tetrahedra and numerical geometric factors. The
+surface is inferred from upward-facing exterior triangles; pass
+`surface_face_mask=` to `Mesh3D.from_arrays` when boundary classification must
+be explicit:
+
+```python
+forward3d = ERTForward3D.from_mesh_survey(
+    mesh3d,
+    survey3d,
+    element_order=2,
+    geometric_factor_mode="auto",  # numerical for terrain, analytic when flat
+    linear_solver_backend="cudss",  # or "scipy"; "auto" selects an available GPU
+)
+```
+
+For large explicit sensitivities, `jacobian(..., batch_size=32,
+cell_batch_size=20000)` bounds temporary field memory. Assembly routing,
+active AB/MN electrode sets, numerical geometric factors, sparse plans, and
+fixed GPU right-hand sides are cached across inversion iterations.
+
+The initial 3D implementation supports flat-surface half-space models,
+four-node tetrahedral geometry, P1 or ten-node P2 basis functions, SciPy or
+NVIDIA cuDSS sparse factorization, analytic or terrain-aware numerical
+geometric factors, exact adjoint cell sensitivities, first-order face-neighbor
+regularization, and the existing single-time inversion API. Large-scale
+matrix-free time-lapse inversion remains on the 3D roadmap.
+
+`ERTForwardModeling` provides a small wrapper for mesh/data-like objects:
+
+```python
+from adtlert.forward import ERTForwardModeling
+
+modeling = ERTForwardModeling(mesh=mesh, data=scheme)
+log_rhoa, jac = modeling.forward_and_jacobian(log_resistivity, log_transform=True)
+```
+
+## Terrain Workflow
+
+```python
+import numpy as np
+
+from adtlert.workflows import (
+    build_terrain_forward_case,
+    discover_resistivity_slices,
+    parse_pftcl,
+    read_slope_x,
+    run_terrain_forward,
+    run_terrain_forward_series,
+    save_terrain_forward_dat,
+    save_terrain_forward_npz,
+)
+
+grid = parse_pftcl("parflow_models/sc2d_6.out.pftcl")
+slope_x = read_slope_x("parflow_models/sc2d_6.out.slope_x.pfb", y_index=2)
+rho_2d = np.load("resistivity_models_2d/resistivity2d_y2_t04536.npy")
+
+case = build_terrain_forward_case(rho_2d, grid, slope_x, y_index=2)
+rhoa = run_terrain_forward(case)
+save_terrain_forward_dat("synthetic_ert_terrain_vardz_t04536.dat", case, rhoa)
+save_terrain_forward_npz("synthetic_ert_terrain_vardz_t04536.npz", case, rhoa)
+
+pairs = discover_resistivity_slices("resistivity_models_2d", y_index=2)
+manifest, failures = run_terrain_forward_series(
+    pairs,
+    grid,
+    slope_x,
+    "result/timelapsedERT_forward",
+    y_index=2,
+)
+```
+
+## Inversion API
+
+```python
+import numpy as np
+
+from adtlert.inversion import ERTInversion, InversionConfig
+
+config = InversionConfig(
+    max_iterations=8,
+    data_std=0.05,
+    regularization=1.0e-2,
+    spatial_regularization="first_order",
+    model_bounds=(10.0, 20000.0),
+)
+
+initial_model = np.full(forward.mesh.cell_count, np.median(observed_rhoa))
+result = ERTInversion(
+    forward=forward,
+    observed_data=observed_rhoa,
+    config=config,
+).setup().run(initial_model)
+
+final_model = result.final_model
+predicted_rhoa = result.predicted_data
+coverage = result.coverage
+chi2_history = result.iteration_chi2
+```
+
+Windowed time-lapse inversion:
+
+```python
+from adtlert.inversion import WindowedTimeLapseERTInversion
+
+config = InversionConfig(
+    max_iterations=6,
+    data_std=np.log1p(relative_error_by_time),
+    regularization=50.0,
+    temporal_regularization=10.0,
+    temporal_regularization_mode="separate",
+    spatial_regularization="first_order",
+    model_bounds=(0.001, 1.0e4),
+    max_log_step=None,
+    line_search=True,
+)
+
+result = WindowedTimeLapseERTInversion(
+    forward=forward,
+    observed_data=observed_rhoa_by_time,
+    config=config,
+    window_size=3,
+    window_step=1,
+).setup().run(initial_model)
+
+final_models = result.final_models
+```
+
+## Validation
+
+```bash
+uv run pytest
+uv run python -m compileall adtlert
+uv build
+```

adtlert-0.1.0/README.md

@@ -0,0 +1,220 @@
+# AD-TLERT
+
+Differentiable 2.5D ERT and tetrahedral 3D DC forward tooling on Torch.
+
+The repository contains:
+
+- `adtlert/`: the core numerical implementation.
+- `example/single_time/`: ADTLERT/pyGIMLi forward examples and
+  ADTLERT/pyGIMLi/ResIPy single-time inversion examples.
+- `example/window_363/`: ADTLERT/pyGIMLi/ResIPy inversion examples for 365
+  time steps using 3-step sliding windows (363 windows).
+- `parflow_models/` and `resistivity_models_2d/`: input data used by the
+  examples.
+
+See [`example/README.md`](example/README.md) for commands and backend
+requirements.
+
+## Install
+
+Install the CPU/SciPy build from PyPI:
+
+```bash
+python -m pip install adtlert
+```
+
+CUDA 12 acceleration through NVIDIA cuDSS is an optional Linux extra:
+
+```bash
+python -m pip install "adtlert[cuda12]"
+```
+
+The CUDA driver must support CUDA 12, and only one CuPy CUDA variant may be
+installed in an environment. CPU-only installations do not install CuPy,
+cuDSS, or nvmath-python.
+
+For development from a checkout, use `uv`. The terrain examples read ParFlow
+PFB files and build Triangle inversion meshes:
+
+```bash
+uv sync --extra cuda12 --extra examples
+```
+
+## Core Forward API
+
+```python
+import torch
+
+from adtlert.forward import ERTForward2p5D
+
+forward = ERTForward2p5D.from_mesh_survey(mesh, survey)
+conductivity = torch.as_tensor(1.0 / resistivity, dtype=torch.float32)
+response = forward.solve(conductivity)
+
+rhoa = response.apparent_resistivity
+jacobian = forward.jacobian(conductivity)
+```
+
+For matrix-free differentiation, use the PyTorch autograd bridge. Its reverse
+pass calls `forward.vjp(...)`, while PyTorch forward AD calls
+`forward.jvp(...)`; no explicit Jacobian is materialized:
+
+```python
+from adtlert.forward import apparent_resistivity_autograd
+
+conductivity = conductivity.requires_grad_()
+rhoa = apparent_resistivity_autograd(conductivity, forward, currents=1.0)
+loss = data_misfit(rhoa, observed_rhoa)
+loss.backward()
+conductivity_gradient = conductivity.grad
+```
+
+True 3D DC forward modelling uses a tetrahedral mesh and three-coordinate
+electrodes. It follows pyGIMLi's 3D singularity-removal formulation, with an
+analytic half-space primary field and a mixed far-field boundary:
+
+```python
+from adtlert.forward import ERTForward3D
+from adtlert.mesh import Mesh3D
+from adtlert.survey import Survey
+
+mesh3d = Mesh3D.from_file("mesh3d.vtu")
+survey3d = Survey.from_arrays(electrode_xyz, abmn)
+forward3d = ERTForward3D.from_mesh_survey(mesh3d, survey3d)
+response3d, jacobian3d = forward3d.solve_with_jacobian(conductivity3d)
+```
+
+For topography, use quadratic tetrahedra and numerical geometric factors. The
+surface is inferred from upward-facing exterior triangles; pass
+`surface_face_mask=` to `Mesh3D.from_arrays` when boundary classification must
+be explicit:
+
+```python
+forward3d = ERTForward3D.from_mesh_survey(
+    mesh3d,
+    survey3d,
+    element_order=2,
+    geometric_factor_mode="auto",  # numerical for terrain, analytic when flat
+    linear_solver_backend="cudss",  # or "scipy"; "auto" selects an available GPU
+)
+```
+
+For large explicit sensitivities, `jacobian(..., batch_size=32,
+cell_batch_size=20000)` bounds temporary field memory. Assembly routing,
+active AB/MN electrode sets, numerical geometric factors, sparse plans, and
+fixed GPU right-hand sides are cached across inversion iterations.
+
+The initial 3D implementation supports flat-surface half-space models,
+four-node tetrahedral geometry, P1 or ten-node P2 basis functions, SciPy or
+NVIDIA cuDSS sparse factorization, analytic or terrain-aware numerical
+geometric factors, exact adjoint cell sensitivities, first-order face-neighbor
+regularization, and the existing single-time inversion API. Large-scale
+matrix-free time-lapse inversion remains on the 3D roadmap.
+
+`ERTForwardModeling` provides a small wrapper for mesh/data-like objects:
+
+```python
+from adtlert.forward import ERTForwardModeling
+
+modeling = ERTForwardModeling(mesh=mesh, data=scheme)
+log_rhoa, jac = modeling.forward_and_jacobian(log_resistivity, log_transform=True)
+```
+
+## Terrain Workflow
+
+```python
+import numpy as np
+
+from adtlert.workflows import (
+    build_terrain_forward_case,
+    discover_resistivity_slices,
+    parse_pftcl,
+    read_slope_x,
+    run_terrain_forward,
+    run_terrain_forward_series,
+    save_terrain_forward_dat,
+    save_terrain_forward_npz,
+)
+
+grid = parse_pftcl("parflow_models/sc2d_6.out.pftcl")
+slope_x = read_slope_x("parflow_models/sc2d_6.out.slope_x.pfb", y_index=2)
+rho_2d = np.load("resistivity_models_2d/resistivity2d_y2_t04536.npy")
+
+case = build_terrain_forward_case(rho_2d, grid, slope_x, y_index=2)
+rhoa = run_terrain_forward(case)
+save_terrain_forward_dat("synthetic_ert_terrain_vardz_t04536.dat", case, rhoa)
+save_terrain_forward_npz("synthetic_ert_terrain_vardz_t04536.npz", case, rhoa)
+
+pairs = discover_resistivity_slices("resistivity_models_2d", y_index=2)
+manifest, failures = run_terrain_forward_series(
+    pairs,
+    grid,
+    slope_x,
+    "result/timelapsedERT_forward",
+    y_index=2,
+)
+```
+
+## Inversion API
+
+```python
+import numpy as np
+
+from adtlert.inversion import ERTInversion, InversionConfig
+
+config = InversionConfig(
+    max_iterations=8,
+    data_std=0.05,
+    regularization=1.0e-2,
+    spatial_regularization="first_order",
+    model_bounds=(10.0, 20000.0),
+)
+
+initial_model = np.full(forward.mesh.cell_count, np.median(observed_rhoa))
+result = ERTInversion(
+    forward=forward,
+    observed_data=observed_rhoa,
+    config=config,
+).setup().run(initial_model)
+
+final_model = result.final_model
+predicted_rhoa = result.predicted_data
+coverage = result.coverage
+chi2_history = result.iteration_chi2
+```
+
+Windowed time-lapse inversion:
+
+```python
+from adtlert.inversion import WindowedTimeLapseERTInversion
+
+config = InversionConfig(
+    max_iterations=6,
+    data_std=np.log1p(relative_error_by_time),
+    regularization=50.0,
+    temporal_regularization=10.0,
+    temporal_regularization_mode="separate",
+    spatial_regularization="first_order",
+    model_bounds=(0.001, 1.0e4),
+    max_log_step=None,
+    line_search=True,
+)
+
+result = WindowedTimeLapseERTInversion(
+    forward=forward,
+    observed_data=observed_rhoa_by_time,
+    config=config,
+    window_size=3,
+    window_step=1,
+).setup().run(initial_model)
+
+final_models = result.final_models
+```
+
+## Validation
+
+```bash
+uv run pytest
+uv run python -m compileall adtlert
+uv build
+```

adtlert-0.1.0/adtlert/__init__.py

@@ -0,0 +1,43 @@
+"""Top-level package for differentiable time-lapse ERT on Torch."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from adtlert.fem import P1ElementData, build_p1_element_data, p1_shape_functions
+from adtlert.forward import (
+    ERT2p5DApparentResistivityFunction,
+    ERTForward2p5D,
+    ERTForwardModeling,
+    ForwardResponse,
+    apparent_resistivity_autograd,
+)
+from adtlert.inversion import (
+    ERTInversion,
+    InversionConfig,
+    TimeLapseERTInversion,
+    WindowedTimeLapseERTInversion,
+)
+from adtlert.mesh import Mesh
+from adtlert.survey import Survey
+
+try:
+    __version__ = version("adtlert")
+except PackageNotFoundError:  # pragma: no cover - source tree without installation
+    __version__ = "0+unknown"
+
+__all__ = [
+    "ERTForward2p5D",
+    "ERT2p5DApparentResistivityFunction",
+    "ERTForwardModeling",
+    "ERTInversion",
+    "ForwardResponse",
+    "InversionConfig",
+    "Mesh",
+    "P1ElementData",
+    "Survey",
+    "TimeLapseERTInversion",
+    "WindowedTimeLapseERTInversion",
+    "apparent_resistivity_autograd",
+    "build_p1_element_data",
+    "p1_shape_functions",
+    "__version__",
+]

adtlert-0.1.0/adtlert/fem/__init__.py

@@ -0,0 +1,72 @@
+"""Finite-element basis and quadrature utilities."""
+
+from adtlert.fem.assembly import (
+    COORouting,
+    assemble_global_bcoo,
+    assemble_helmholtz_operator,
+    assemble_local_mass,
+    assemble_local_mass_p2,
+    assemble_local_stiffness,
+    assemble_local_stiffness_p2,
+    build_coo_routing,
+    build_coo_routing_from_connectivity,
+)
+from adtlert.fem.boundary import (
+    BoundaryRouting,
+    assemble_boundary_bcoo,
+    assemble_local_boundary_mass,
+    assemble_local_boundary_mass_p2,
+    build_boundary_routing,
+    build_boundary_routing_from_connectivity,
+    robin_boundary_coefficients,
+)
+from adtlert.fem.p1 import (
+    P1ElementData,
+    build_p1_element_data,
+    p1_shape_functions,
+    reference_shape_gradients,
+    triangle_quadrature,
+)
+from adtlert.fem.p2 import P2ElementData, build_p2_element_data, p2_shape_functions, reference_shape_gradients_p2
+from adtlert.fem.tet_p1 import (
+    TetrahedronP1Data,
+    TetrahedronP2Data,
+    build_tetrahedron_p1_data,
+    build_tetrahedron_p2_data,
+    p2_tetrahedron_shape_values,
+    p2_triangle_mass_template,
+)
+
+__all__ = [
+    "BoundaryRouting",
+    "COORouting",
+    "assemble_boundary_bcoo",
+    "P1ElementData",
+    "assemble_global_bcoo",
+    "assemble_helmholtz_operator",
+    "assemble_local_boundary_mass",
+    "assemble_local_boundary_mass_p2",
+    "assemble_local_mass",
+    "assemble_local_mass_p2",
+    "assemble_local_stiffness",
+    "assemble_local_stiffness_p2",
+    "build_boundary_routing",
+    "build_boundary_routing_from_connectivity",
+    "build_p1_element_data",
+    "build_p2_element_data",
+    "build_coo_routing",
+    "build_coo_routing_from_connectivity",
+    "p1_shape_functions",
+    "p2_shape_functions",
+    "reference_shape_gradients",
+    "reference_shape_gradients_p2",
+    "robin_boundary_coefficients",
+    "triangle_quadrature",
+    "P2ElementData",
+    "TetrahedronP1Data",
+    "TetrahedronP2Data",
+    "build_tetrahedron_p1_data",
+    "build_tetrahedron_p2_data",
+    "p2_tetrahedron_shape_values",
+    "p2_triangle_mass_template",
+]