Frequently asked questions#
Find the right answer, then keep moving
Search by symptom, command, file format, or workflow. Answers lead to the detailed guide when you need more than the short version.
Choose your shortest path
Getting started
What is the quickest way to verify that pyCSAMT works?Popular
Install pyCSAMT in a clean environment, confirm the import, and run the bundled first-survey workflow. This separates installation problems from problems in your own field data.
Next: follow the quickstart or review installation options.
Should I use Python, the CLI, desktop app, or web app?Choose
Use Python for reproducible research and custom pipelines; the CLI for automation and batch jobs; the desktop app for interactive local work; and the web app for a browser-based workflow. They expose the same project concepts, so you can start visually and move to code later.
Compare: interfaces at a glance and the CLI overview.
Why does an optional feature fail after the base package installs?Setup
Some plotting, geospatial, AI, and application features use optional dependencies. Read the error for the missing package or extra, install only the feature set you need, then restart the Python process so imports are refreshed.
Next: see installation and optional dependencies.
Do I need Numba or joblib installed?Optional
No. The perf extra (python -m pip install "pycsamt[perf]") adds optional Numba/joblib acceleration for pycsamt.models.occam1d, batch survey agents, and pipeline execution. Everything that can use them degrades gracefully to a slower pure-Python/NumPy path when they are absent -- perf is a convenience, never a hard requirement, and it is not part of the full extra.
Details: the optional feature groups table.
Why does a table-returning function give me an APIFrame instead of a plain pandas DataFrame?Key concept
Most dataframe-returning functions accept an api keyword that defaults to api=None, which resolves through the package-wide PYCSAMT_API_VIEW switch -- and that switch defaults to "pycsamt", not "pandas". A bare call is therefore already wrapped into an APIFrame (or APIResult for multi-table workflows) unless you pass api=False for the raw DataFrame, or disable wrapping globally with configure_api_view(backend=False).
Next: read API views for the full behaviour, including custom wrappers.
Direct AI inversion versus inversion agents
What is the difference between pycsamt.ai inversion and an inversion agent?Key concept
pycsamt.ai.inversion is the scientific model API: you construct inverter classes, datasets, networks, losses, training loops, checkpoints, and predictions directly. pycsamt.agents is the workflow layer around those classes. An inversion agent can load survey files, build features, train or load the underlying inverter, predict, calculate selected diagnostics, save figures, preserve warnings, and return a standard AgentResult.
Compare: AI inversion agents and the agent decision guide.
When should I call pycsamt.ai directly?Research control
Use the direct API when you need control of array contracts, architecture, geological priors, forward operators, loss terms, optimizer, data splits, batching, callbacks, calibration, checkpointing, or an experimental training loop. It is also the better layer for developing and testing a new method because the scientific choices remain explicit instead of being hidden behind a workflow contract.
Start: review the AI inversion guide and data contracts.
When is an inversion agent the better interface?Workflow
Use an agent when its documented input contract matches your task and you want a repeatable end-to-end step with standard status, warnings, error hints, timing, diagnostics, figures, and output paths. Agents are especially useful in coordinated QC-to-inversion pipelines, application interfaces, batch surveys, and reviewed production runs. They reduce orchestration code; they do not remove the need to record configuration or inspect the science.
What does Inv2DAgent do, and when should I use it?U-Net 2-D
Inv2DAgent wraps EMInverter2D in a profile workflow. It consumes the complete station-frequency panel and predicts a depth-by-station section with a U-Net-style model, so it can learn lateral continuity instead of treating every station independently. Use it when the stations form a defensible profile and the synthetic training distribution represents the expected 2-D structures. Its learned smoothness and quick data-space diagnostic are not equivalent to a classical 2-D EM roughness objective or full forward solve.
Review: Inv2DAgent assumptions and example.
What does Inv3DAgent do, and is it a full 3-D inversion?Know the scope
Inv3DAgent wraps GCNInverter3D. It builds or accepts a graph from station coordinates so neighbouring stations exchange information, predicts layered resistivity at each graph node, and can estimate Monte Carlo dropout spread. It is a spatial graph-based AI inversion, not the same numerical problem as a full 3-D Maxwell inversion such as ModEM. Use it for rapid spatial prediction only after reviewing coordinates, graph edges, training coverage, uncertainty, and a physics-based baseline.
Do inversion agents require an LLM or make the scientific decision for me?Human review
No. The numerical workflow can be deterministic without an LLM; a configured language model may add narrative interpretation or help orchestrate a request, but it does not validate the inversion. An agent status of success only means the software workflow completed. Review warnings, input QC, training provenance, out-of-distribution checks, response residuals, uncertainty, dimensionality assumptions, and independent geological evidence before accepting the result.
Validate: scientific validation and AgentResult semantics.
Will direct AI inversion and an agent always produce the same model?Reproducibility
Only when both paths use the same survey ordering, frequency grid, features, scaling, architecture, weights or training data, random seeds, hyperparameters, checkpoint, inference mode, and post-processing. Agents may apply documented defaults and preprocessing that differ from a custom notebook. For a fair comparison, export the agent configuration and inverter object metadata, then reproduce the same inputs through the direct API.
Trace: see the common execution contract.
Solvers, compilation, and binaries
Do ModEM, Occam2D, and MARE2DEM come with pyCSAMT?Important
pyCSAMT provides builders, native-file readers and writers, runners, and result loaders, but it does not ship pre-compiled executables. Occam2D and ModEM are external Fortran programs whose source is vendored for supported builds; MARE2DEM source is downloaded separately under its own licence. You can prepare and validate inputs without running a solver.
Start: read compiling external solvers and the model-integration lifecycle.
How do I compile ModEM 2-D or 3-D?Fortran
Use pycsamt build modem2d --auto-install for Mod2DMT or pycsamt build modem3d --auto-install for Mod3DMT. The build needs gfortran, make, and LAPACK/BLAS. On Windows, pyCSAMT can create an isolated conda toolchain; Linux and macOS use their normal package managers. MPI and Intel builds are opt-in and require those compilers to be installed already.
Commands and platform notes: ModEM compilation.
How do I compile Occam2D?Fortran
Run pycsamt build occam2d --auto-install -y. The build script selects a modern gfortran instead of the legacy f90 name in the original Makefile and places the resulting Occam2D or Occam2D.exe in the vendored source directory. Use --clean when compiler changes or stale objects make a rebuild necessary.
Details: Occam2D compilation and the runner workflow.
Why is compiling MARE2DEM different?MPI + MKL
MARE2DEM source is not vendored and its build requires the Intel MPI Fortran/C toolchain plus MKL/ScaLAPACK. Use pycsamt build mare2dem to inspect status, then pycsamt build mare2dem --auto-install -y only after Intel oneAPI is installed and sourced. Native Windows builds are unsupported; use Linux, macOS, WSL2, or an HPC system.
Prepare: MARE2DEM prerequisites and source management.
How does pyCSAMT find and run a compiled binary?Popular
Prefer an explicit executable path in the engine configuration: OccamRunner(binary_path=...), ModEmConfig(binary_2d=..., binary_3d=...), or Mare2DEMConfig(binary=...). The runner launches the program as a subprocess inside the native run directory, captures logs, and leaves native outputs for the result loader. Some runners also search the run directory, system PATH, and pyCSAMT build locations, but an explicit path records better provenance.
Configure: configuration and executable I/O.
The binary was compiled, but pyCSAMT cannot run it. What should I verify?Checklist
Confirm the exact path and executable permission, run the binary directly once, and check architecture plus runtime libraries. On Windows keep the copied MinGW DLLs beside the executable; for MPI verify mpirun, process count, and environment initialization. Also confirm that required native input filenames are present in the working directory. A successful compile does not prove that the runtime environment or model inputs are valid.
Diagnose: use the checks in the compilation guide.
How should I choose between Occam2D, ModEM, and MARE2DEM?Decision
Choose Occam2D for a smooth MT/AMT/CSAMT profile where 2-D geology and strike assumptions are defensible. Choose ModEM for native 2-D or 3-D MT workflows, especially area surveys and covariance-controlled 3-D models. Choose MARE2DEM for 2.5-D finite-element MT/CSEM problems requiring adaptive triangular meshes, detailed topography, transmitter geometry, or an established MPI workflow.
Compare: the backend decision matrix.
Maxwell forward datasets and Python solvers
When should I generate a 2-D Maxwell forward dataset?2-D
Use a 2-D dataset when lateral structure along a profile matters and a layered 1-D response is no longer adequate. Build a Grid2D, run MT2DForward for TE and TM responses, and vary anomaly geometry, resistivity, station positions, frequencies, and noise with controlled seeds. This is appropriate for method tests, survey design, and training data whose assumptions are explicitly 2-D.
Build: 2-D solver datasets and the MT2D solver.
What is the difference between a pseudo-3-D dataset and an MT3DForward dataset?Know the physics
generate_dataset_3d creates multi-station spatial datasets from local 1-D MT responses. MT3DForward uses a 3-D resistivity grid and, in its quasi-3-D mode, solves orthogonal 2-D slices to approximate tensor responses. Neither should be labelled a validated production full-3-D Maxwell result. Use ModEM or another full-3-D engine when full 3-D coupling is part of the scientific claim.
Understand: pseudo-3-D datasets and quasi-3-D limitations.
When should I use MT2DForward versus MT3DForward?Decision
Use MT2DForward for profile-scale TE/TM physics, lateral anomaly experiments, and comparison with a 2-D inversion. Use MT3DForward for rapid volume sensitivity studies, station-grid survey design, or synthetic AI catalogues where its quasi-3-D approximation is acceptable. Move to a production external solver when off-profile current flow and full 3-D coupling must be resolved quantitatively.
Compare: solvers and grids.
What must I save with a 2-D or 3-D synthetic dataset?Reproducibility
Save the resistivity model or generator parameters, grid including padding and air cells, station geometry, frequency axis, components and array layout, solver and version, boundary settings, random seeds, noise model, units, and train/validation/test split rules. Validate finite values and shapes and plot selected responses before training. A feature matrix without its physics and geometry metadata is not a reusable Maxwell dataset.
Audit: dataset quality checks.
When should I use SimPEG?Python native
Use SimPEG when you need a Python-native research workflow with explicit meshes, mappings, regularization, optimization, sensitivities, and the ability to customize or differentiate the inverse problem. It is a strong choice for experimentation and integration with scientific Python. Expect to manage optional dependency versions and to validate the chosen electromagnetic simulation against a trusted reference.
Decide: compare Python and native backends.
When should I use pyGIMLi?Python ecosystem
Use pyGIMLi when your workflow benefits from its modelling and inversion framework, especially 1-D or stitched-profile experiments, TDEM support, mesh tools, or integration with other geophysical methods already handled in that ecosystem. Like SimPEG, it is an optional backend: confirm that the installed version supports the method and dimensionality you intend to report.
Decide: the backend matrix.
Should I begin with SimPEG, pyGIMLi, or a compiled Fortran solver?Rule of thumb
Begin with pyCSAMT's built-in backend for a smoke test. Choose SimPEG or pyGIMLi when Python-level control and extensibility matter most. Choose Occam2D, ModEM, or MARE2DEM when a validated native workflow, established file format, HPC execution, or direct comparison with an existing project matters most. Solver choice does not replace dimensionality analysis, error modelling, or independent validation.
Data and quality control
Which survey file formats can pyCSAMT read?Reference
pyCSAMT supports the common electromagnetic survey formats documented in the data-format matrix, including EDI, Zonge AVG, Jones J, TDEM, and modelling formats. Check the matrix before converting data: keeping the native format usually preserves more metadata.
My EDI files load, but stations appear in the wrong order. What should I check?Pro tip
Do not assume filenames define survey order. Verify station identifiers, coordinates, profile geometry, and units; then use the site ordering tools. Plot the station map before processing because a plausible-looking pseudosection can still hide a geometry error.
Diagnose: site and station tools.
What quality checks should I run before correction or inversion?Popular
Check station geometry, frequency overlap, missing components, apparent-resistivity and phase continuity, error estimates, outliers, and repeatability. Save the unmodified import and record every exclusion: correction should address a diagnosed problem, not make a curve merely look smooth.
Workflow: load and audit data, then use the processing catalogue.
I have raw Stratagem/Zonge hardware field data, not EDI -- is there a complete worked example?Tutorial
Yes. A full tutorial covers a real field survey from raw Stratagem hardware output through StratagemRawReader, injecting surveyed coordinates with CoordinateInjector, static-shift correction, frequency filtering, noise removal, QC export, and an Occam2D inversion using the vendored, compilable solver. It also shows cross-checking the correction against an independent tool and against pyCSAMT's own log-frequency smoothing.
Does pyCSAMT read modern EMTF-XML files, or only classic EDI?New
Both, through the same boundary. Site/Sites now wrap either format via a lazy dual backend: whichever representation was not natively supplied is materialized from the other on first access and cached, so every existing EDI-only accessor (z, tipper, rho, phase) keeps working unchanged. ensure_sites normalizes a single .xml file, an EMTF object, or a directory mixing *.edi and *.xml files into the same Sites container -- no separate function to learn, and nothing downstream needs to know which format a station arrived in.
Read: loading EMTF-XML the same way and the full Site/Sites XML reference.
Airborne EM (ZTEM, AFMAG, MobileMT)
Does pyCSAMT support airborne EM surveys like ZTEM, AFMAG, or MobileMT?New
Yes. pycsamt.airborne is a technology-neutral data model built directly on EMTF documents -- flight lines, datasets, a technology/format registry, and structural QC -- with no EDI bridge and no impedance requirement, since a genuine airborne measurement rarely has one. Three technology subpackages (pycsamt.airborne.afmag, .ztem, .mobilemt) map each system's decoded response onto that shared model.
Start: the airborne EM guide, beginning with the data-model overview.
How do I read a directory of airborne EMTF-XML files?Tool
pycsamt.airborne.site.ensure_asites is the airborne counterpart of ensure_sites: point it at a directory of EMTF-XML files and it returns an AirborneSites collection with each station's technology auto-detected from its document, ready for the same kind of selection, mapping, and export operations ground Sites already support.
See it read real sample surveys: the airborne site view.
Why is an airborne station's z always None?Not a bug
ZTEM, AFMAG, and MobileMT have no electric-field channel, so there is no impedance to build. An AirborneSite deliberately never fabricates one -- check has_component("tipper") or "admittance" instead of assuming z will populate. ZTEM/AFMAG carry a tipper or interstation tensor; MobileMT carries a ground-electric-to-airborne-magnetic admittance tensor, a genuinely different physical quantity from either.
Understand the four response shapes: one container, four response families.
Processing and interpretation
How do I choose a correction method?Decision
Start from the observed failure mode and survey physics. Diagnose dimensionality, strike, static shift, cultural noise, and frequency-local outliers separately. Apply the least invasive method that targets the evidence, compare before and after, and retain parameters in a reproducible pipeline.
Compare: the EM tools catalogue and scientific background.
Should I smooth noisy curves before inversion?Caution
Not automatically. First distinguish isolated outliers, coherent cultural noise, static shift, and genuine geological structure. Over-smoothing can remove useful signal and produce unjustified confidence. Preserve raw data, document exclusions, and propagate realistic error floors into inversion.
Learn: diagnostics and corrections.
Which pyCSAMT tool actually performs frequency-domain smoothing, and how do I judge whether it helped?Tool
pycsamt.emtools.remove_noise.smooth_logfreq applies a triangular or box kernel along the log-frequency axis. Judge it by comparing the smoothed curve against both the unmodified import and, where available, an independent processing of the same stations -- agreement between two different corrections is a better signal than a curve that merely looks less noisy.
See it applied: the static shift and smoothing section of the Stratagem tutorial.
How do I know whether an interpretation is defensible?Expert
A defensible interpretation connects data quality, assumptions, model sensitivity, uncertainty, and independent geological evidence. Compare alternative processing choices and models; report what is resolved and what is inferred. A low misfit alone does not make a model unique.
Next: use the interpretation guide.
Inversion and modelling
Which inversion backend should I choose?Choose
Choose from the survey dimensionality, data type, compute environment, licensing constraints, and the outputs you must defend—not from the solver name alone. Begin with the simplest model compatible with the data, then increase complexity only when diagnostics justify it.
Compare: solver integrations and the inversion workflow.
Why can pyCSAMT prepare an inversion but not run it?External tool
Input preparation and result inspection are built into pyCSAMT, while some numerical engines are separate executables. Confirm that the selected engine is installed, licensed where required, and discoverable on your system. The prepared files remain useful even when the executable is unavailable.
Next: check backend setup.
When should I use AI inversion?Advanced
Use AI methods when training coverage, validation design, uncertainty reporting, and deployment constraints are explicit. Always benchmark against a classical method and test domain shift. For a new survey or limited training data, a classical baseline is usually the more interpretable starting point.
Evaluate: AI inversion guidance.
Do I need an external Occam1D binary for 1-D inversion?New
No, not unless you want one. pycsamt.models.occam1d is a native, pure Python/NumPy 1-D Occam smooth-model engine -- forward model, analytic Jacobian, roughness regularization, and the nonlinear Occam loop are all implemented directly, with no compiled dependency. Occam1DRunner remains available for driving an external Occam1D-compatible executable instead, if you already have one and prefer it.
Walk through it: configuration, single-station, and batch inversion.
Applications and troubleshooting
Can I move a project between the desktop, web, and Python interfaces?Workflow
Yes, when you preserve the project inputs, configuration, and exported outputs rather than relying only on interface state. Treat the project folder as the handoff boundary and record version information when reproducibility matters.
See: application guides.
What information should I include when reporting a problem?Best practice
Include the pyCSAMT and Python versions, operating system, interface used, exact command or minimal code, complete traceback, expected and actual behaviour, and a small anonymised input when possible. Remove credentials and confidential coordinates before sharing.
Report: search existing issues before opening a new one.
The answer is not here—where should I look next?Help
Use the global documentation search for the exact exception, class, command, or file suffix. Then check the relevant application troubleshooting page and existing issue reports. If it is reproducible and still unresolved, open an issue with the diagnostic bundle described above.
Continue: application help, API reference, or issue tracker.
No matching question yet
Try fewer words or search the complete documentation.