pycsamt 2.0.0

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.

✨ Highlights

• 📥 Data I/O & QC — EDI, Zonge AVG, Jones J, TDEM, and MARE2DEM files in one site model; frequency audits and noisy-station flagging.
• 📡 IoT-enabled field acquisition — station telemetry with edge QC (powerline harmonics, SNR, contact resistance, frequency coverage), clock-synchronisation audit, power monitoring, pluggable transports (file/HTTP built in; MQTT/serial/WebSocket optional), acquisition provenance, a field-network simulator, 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.
• 🧠 Inversion, classical & AI — Occam2D, ModEM, and MARE2DEM end to end, plus physics-informed neural networks (PINN 1-D/2-D/3-D) and hybrid deep-learning inverters.
• 🗺️ Interpretation & mapping — resistivity classification, pseudostratigraphic logs, station maps, pseudosections, and 3-D quick looks.
• 🤖 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+.

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."
)

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")

from pycsamt.ai.inversion import PINN2D

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

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")

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

The same engine drives all four — script it, automate it, or point and click.

📖 Citation

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

@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. Distributed under the LGPL-3.0 or later — see LICENSE.md.

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