Scientific Python for electromagnetic geophysics — processing, inversion, AI agents, and apps.

---

pyCSAMT v2 is a full-lifecycle toolkit for controlled-source and natural-source electromagnetic (EM) geophysics — CSAMT, AMT, MT, and TDEM. One coherent, scikit-learn-inspired API takes a survey from raw field files through quality control, corrections, and inversion to interpreted, publication-ready results.

Documentation · Getting started · User guide · Examples · API reference

✨ Highlights

• 📥 Data I/O & QC — EDI, Zonge AVG, Jones J (BIRRP), TDEM, MARE2DEM, and airborne EMTF-XML (ZTEM, AFMAG, MobileMT) in one site model; frequency audits and noisy-station flagging.
• 📡 IoT-enabled field acquisition — station telemetry with edge QC (powerline harmonics, SNR, contact resistance), clock-synchronisation audit, power monitoring, pluggable transports, acquisition provenance, and dashboards — feeding directly into the processing pipeline.
• 🎚️ Processing & corrections — a catalogue of 25 methods in six categories: notch filtering, static-shift removal, tensor rotation, phase-tensor analysis, and more.
• 🧱 Forward modelling — synthetic layered-earth and 2-D models, forward responses, realistic noise, and datasets for survey design or training.
• 🧠 AI-assisted processing & inversion — learned denoising, gap-filling, anomaly detection, and uncertainty tools; classical Occam2D/ModEM/MARE2DEM plus physics-informed (PINN) and hybrid deep-learning inverters.
• 🗺️ Interpretation & mapping — resistivity classification, pseudostratigraphic logs, an interactive 3-D MapView (PCSF format, boreholes, geology overlays), and publication-ready pseudosections.
• 🤖 Pipelines, agents & apps — reproducible YAML/JSON/Python workflows, LLM-driven agents (Anthropic, OpenAI, Gemini), a web dashboard, and a desktop GUI.

🚀 Installation

pip install pycsamt           # core, minimal dependencies
pip install "pycsamt[full]"   # + ML backends, apps, geospatial, docs

Requires Python 3.9+.

🖥️ Desktop app

Prefer point-and-click? Download the ready-made desktop suite (Profile, Map, QC, Correction, Forward, Inversion, Interpretation, Airborne EM, AI agents):

Platform	Download	Install
Windows 10/11 (64-bit)	pycsamt-desktop-setup.exe	Run the installer. SmartScreen warns on unsigned builds: More info → Run anyway.
Linux (x86-64)	pycsamt-desktop-linux-x86_64.sh	chmod +x pycsamt-desktop-linux-x86_64.sh && ./pycsamt-desktop-linux-x86_64.sh (no root needed)

Every install starts a 30-day full-feature trial. Checksums, older versions and details are on the releases page and in the desktop installation guide.

Optional extras & source install

Extra	Installs
torch	PyTorch backend for PINN / hybrid inverters
tensorflow	TensorFlow / Keras backend
geo	pyproj, xarray, contextily for maps and reprojection
agents	Anthropic, OpenAI/DeepSeek, and Gemini SDKs for AI agents
app	Desktop GUI (PySide6) + Dash web dashboard
docs	Sphinx, PyData theme, numpydoc
full	All of the above (prefers the PyTorch backend)

Track the active development branch:

git clone https://github.com/earthai-tech/pycsamt.git
cd pycsamt && git checkout v2
pip install -e ".[full]"

⚡ Quick start

Chain named processing steps into a repeatable pipeline — the result carries per-step outputs, a log, and an exportable manifest:

from pycsamt.pipeline import Pipeline, Step

pipe = Pipeline([
    ("notch",        Step("NR001", mains_hz=50)),
    ("band",         Step("FREQ001")),
    ("static_shift", Step("SS001")),
    ("rotate",       Step("TZ001")),
])
result = pipe.run(sites, outdir="outputs/run01/")
print(result.summary())

Or hand the whole job to an AI agent in plain language:

from pycsamt.agents import AgentMaster

master = AgentMaster(provider="anthropic")
report = master.run(
    "Load data/edi/, flag stations with RMS > 2, build an Occam2D input "
    "for profile L22, launch inversion, and produce a PDF report."
)

More examples — inversion results, PINN, IoT, CLI

Load a MARE2DEM run directory and plot responses or the resistivity section:

from pycsamt.models.mare2dem import InversionResult, PlotResponse, PlotModel

result = InversionResult("runs/demo_mt/")
PlotResponse(result).plot(max_rx=6, savefig="response.pdf")
PlotModel(result).plot(cmap="turbo_r", savefig="section.pdf")

Physics-informed inversion from site data and a forward operator:

from pycsamt.ai.inversion import PINN2D

inv = PINN2D(n_layers=64, epochs=3000, backend="torch")
model = inv.fit(sites, frequencies=freqs)
model.plot_section()

Ingest IoT field telemetry, quality-control it at the edge, and hand it straight to processing — with a reproducible provenance manifest:

from pycsamt.iot import FieldSession, simulate_iot_network, plot_field_dashboard

# real edge telemetry, or a simulated network for demos/tests
packets = simulate_iot_network(n_stations=24, profiles=["L1", "L3"])
session = FieldSession("SSL2026")
session.add_packets(packets)

session.assess()                                 # stream QC -> MonitoringStatus
session.to_pipeline_input()                      # hand-off for processing
session.export_manifest("field_manifest.json")   # reproducible provenance
plot_field_dashboard(session, output_path="dashboard.png")

The full workflow is also scriptable from the terminal:

pycsamt survey set data/edi/
pycsamt invert build data/edi/ --solver occam2d --workdir runs/occam2d/
pycsamt pipe run --config pipeline.yaml --survey data/edi/ --out outputs/run01/

🖥️ Interfaces

Python API	CLI	Web dashboard	Desktop GUI
import pycsamt	pycsamt --help	pycsamt-web	pycsamt-desktop

The same engine drives all four — script it, automate it, or point and click. The desktop GUI also ships as a standalone installer — see Desktop app.

📖 Citation

If pyCSAMT contributes to published research, please cite Kouadio et al. (2022), J. Applied Geophysics.

BibTeX

@article{Kouadio2022,
  author  = {Kouadio, K. L. and Liu, R. and Mi, B. and Liu, C.},
  title   = {pyCSAMT: An alternative Python toolbox for groundwater exploration
             using controlled-source audio-frequency magnetotelluric},
  journal = {Journal of Applied Geophysics},
  year    = {2022},
  doi     = {10.1016/j.jappgeo.2022.104647}
}

@article{Kouadio2023,
  author  = {Kouadio, K. L. and Liu, R. and Malory, A. O. and Liu, W. and Liu, C.},
  title   = {A novel approach for water reservoir mapping using
             controlled-source audio-frequency magnetotelluric in Xingning area,
             Hunan Province, China},
  journal = {Geophysical Prospecting},
  year    = {2023},
  doi     = {10.1111/1365-2478.13385}
}

🤝 Contributing & license

Bug reports and feature requests are welcome on the issue tracker; see the developer guide before opening a pull request. Participation is governed by our Code of Conduct. Distributed under the LGPL-3.0 or later — see LICENSE.md.

---

Developed by earthai-tech  —  Lead developer: Laurent Kouadio 🌐