6. Inversion

Inversion turns processed electromagnetic observations into a resistivity model. In pyCSAMT this guide is the decision point between three related but different paths: the backend-neutral pycsamt.inversion API for built-in and adapter workflows, the classical engine integrations in pycsamt.models for Occam2D, ModEM, and MARE2DEM native projects, and the learned workflows in pycsamt.ai, documented separately as AI inversion.

Forward modelling is not an inversion path. It predicts responses from a known model and is documented in Forward Modelling; it is often used to design, test, or validate inversion choices. The common Python interface itself lives at Inversion API.

• 6.1. Overview
  • 6.1.1. Before Any Inversion
  • 6.1.2. Backend-Neutral Workflow
  • 6.1.3. Minimal MT 1-D
  • 6.1.4. Minimal TDEM 1-D
  • 6.1.5. Profile Inversion
  • 6.1.6. Exports And Review
  • 6.1.7. Hydrogeophysical Handoff
  • 6.1.8. Next Steps
• 6.2. Classical model integrations
  • 6.2.1. Overview
    • 6.2.1.1. At a glance
    • 6.2.1.2. Shared workflow
    • 6.2.1.3. What the inversion is minimizing
    • 6.2.1.4. Model integrations versus the common inversion API
    • 6.2.1.5. Engine assumptions in plain terms
    • 6.2.1.6. Run-directory principles
    • 6.2.1.7. Minimum review evidence
    • 6.2.1.8. Related reading
  • 6.2.2. Choosing A Model Backend
    • 6.2.2.1. Two Different Choices
    • 6.2.2.2. Quick Recommendation
    • 6.2.2.3. Backend Matrix
    • 6.2.2.4. Decision Axis 1: Dimensionality
    • 6.2.2.5. Decision Axis 2: Data Type
    • 6.2.2.6. Decision Axis 3: Operational Control
    • 6.2.2.7. Typical File Responsibility
    • 6.2.2.8. External Executables
    • 6.2.2.9. Workflow Map
    • 6.2.2.10. Connection To InversionConfig
    • 6.2.2.11. Direct Model Integration Example
    • 6.2.2.12. Risk Checklist
    • 6.2.2.13. Common Mistakes
    • 6.2.2.14. Recommended Path By Deliverable
    • 6.2.2.15. Next Steps
  • 6.2.3. Configuration And File I/O
    • 6.2.3.1. The Three-Layer Record
    • 6.2.3.2. Configuration Template Formats
    • 6.2.3.3. Strict Loading
    • 6.2.3.4. Backend-Neutral Versus Native Configuration
    • 6.2.3.5. Native Files By Engine
    • 6.2.3.6. Recommended Directory Layouts
    • 6.2.3.7. Builder, Runner, Loader Contract
    • 6.2.3.8. Validation Before A Run
    • 6.2.3.9. Provenance To Keep With Every Run
    • 6.2.3.10. Archiving Results
    • 6.2.3.11. Common Mistakes
    • 6.2.3.12. Pre-Run Checklist
    • 6.2.3.13. Post-Run Checklist
    • 6.2.3.14. Next Steps
  • 6.2.4. Compiling the External Solvers
    • 6.2.4.1. Quick Start
    • 6.2.4.2. Auto-Install Behavior
    • 6.2.4.3. ModEM
    • 6.2.4.4. Occam2D
    • 6.2.4.5. MARE2DEM
    • 6.2.4.6. Self-Contained Windows Binaries
    • 6.2.4.7. Troubleshooting
    • 6.2.4.8. Related Reading
  • 6.2.5. Occam2D
    • 6.2.5.1. When To Use Occam2D
    • 6.2.5.2. Package Map
    • 6.2.5.3. Configuration
    • 6.2.5.4. Native Files
    • 6.2.5.5. Build Input Files
    • 6.2.5.6. Data Rows And Type Codes
    • 6.2.5.7. Mesh And Model Review
    • 6.2.5.8. Run Occam2D
    • 6.2.5.9. Backend-Neutral Occam2D Runs
    • 6.2.5.10. Load Results
    • 6.2.5.11. Response And Misfit Diagnostics
    • 6.2.5.12. Log And Convergence
    • 6.2.5.13. Plotting And QC
    • 6.2.5.14. Recommended Run Layout
    • 6.2.5.15. Pre-Run Checklist
    • 6.2.5.16. Post-Run Checklist
    • 6.2.5.17. Common Mistakes
    • 6.2.5.18. Next Steps
  • 6.2.6. Occam1D inversion
    • 6.2.6.1. When To Use Occam1D
    • 6.2.6.2. Package Map
    • 6.2.6.3. Configuration
    • 6.2.6.4. Build Input Files
    • 6.2.6.5. Running The Inversion
    • 6.2.6.6. Batch inversion
    • 6.2.6.7. Text and image products
    • 6.2.6.8. Common Mistakes
    • 6.2.6.9. Next Steps
  • 6.2.7. ModEM
    • 6.2.7.1. When To Use ModEM
    • 6.2.7.2. Dimensionality
    • 6.2.7.3. Package Map
    • 6.2.7.4. Configuration
    • 6.2.7.5. Native Files
    • 6.2.7.6. Data Files And Components
    • 6.2.7.7. Build A 3-D Input Set
    • 6.2.7.8. Build A 2-D Input Set
    • 6.2.7.9. Build From Existing Data
    • 6.2.7.10. Models
    • 6.2.7.11. Covariance
    • 6.2.7.12. Control Files
    • 6.2.7.13. Run ModEM
    • 6.2.7.14. Load Results
    • 6.2.7.15. Log Diagnostics
    • 6.2.7.16. Plotting
    • 6.2.7.17. A Vertical Section Through The 3-D Model
    • 6.2.7.18. Conversion And Utility Tools
    • 6.2.7.19. Backend-Neutral Workflows
    • 6.2.7.20. Recommended Run Layout
    • 6.2.7.21. Pre-Run Checklist
    • 6.2.7.22. Post-Run Checklist
    • 6.2.7.23. Common Mistakes
    • 6.2.7.24. Next Steps
  • 6.2.8. MARE2DEM
    • 6.2.8.1. When To Use MARE2DEM
    • 6.2.8.2. Package Map
    • 6.2.8.3. Configuration
    • 6.2.8.4. Source And Binary Management
    • 6.2.8.5. Binary Resolution
    • 6.2.8.6. Native Files
    • 6.2.8.7. Build A Run Directory
    • 6.2.8.8. Create MT Data
    • 6.2.8.9. Create CSEM Data
    • 6.2.8.10. Merge And Noise Utilities
    • 6.2.8.11. Geometry And Topography
    • 6.2.8.12. Grid And Mesh Utilities
    • 6.2.8.13. Run MARE2DEM
    • 6.2.8.14. Inspect Results
    • 6.2.8.15. Plotting And QC
    • 6.2.8.16. Model Comparison
    • 6.2.8.17. Recommended Run Layout
    • 6.2.8.18. Pre-Run Checklist
    • 6.2.8.19. Post-Run Checklist
    • 6.2.8.20. Common Mistakes
    • 6.2.8.21. Next Steps
  • 6.2.9. PCSF — Common Subsurface Format
    • 6.2.9.1. Four geometry kinds
    • 6.2.9.2. PCSF on disk
    • 6.2.9.3. Converting an Occam2D result
    • 6.2.9.4. Converting a ModEM 3-D result
    • 6.2.9.5. Converting a MARE2DEM result
    • 6.2.9.6. Stacking lines into a fence
    • 6.2.9.7. Topography
    • 6.2.9.8. A terrain-draped Occam2D section
    • 6.2.9.9. One point cloud, every geometry kind
    • 6.2.9.10. Consumers
    • 6.2.9.11. Associating observed boreholes
    • 6.2.9.12. PCSM: the browsable ASCII projection
    • 6.2.9.13. Versioning and conformance
• 6.3. AI inversion
  • 6.3.1. AI inversion concepts
    • 6.3.1.1. Where AI inversion fits
    • 6.3.1.2. Why EM inversion remains difficult
    • 6.3.1.3. Three AI inversion families
    • 6.3.1.4. Choosing 1-D, 2-D, or 3-D
    • 6.3.1.5. Depth support is not the model depth
    • 6.3.1.6. Model parameterization
    • 6.3.1.7. Data representation
    • 6.3.1.8. The feature contract
    • 6.3.1.9. Training distribution as prior
    • 6.3.1.10. Simulation-to-field domain gap
    • 6.3.1.11. Supervised learning objective
    • 6.3.1.12. Physics-informed objective
    • 6.3.1.13. Architectures encode assumptions
    • 6.3.1.14. Training, validation, and test separation
    • 6.3.1.15. Evaluation hierarchy
    • 6.3.1.16. Uncertainty concepts
    • 6.3.1.17. Configuration objects
    • 6.3.1.18. The Sites bridge
    • 6.3.1.19. Agents and automation
    • 6.3.1.20. Pretrained checkpoints
    • 6.3.1.21. Reproducibility and provenance
    • 6.3.1.22. Scientific acceptance framework
    • 6.3.1.23. Common conceptual mistakes
    • 6.3.1.24. Next steps
    • 6.3.1.25. Documentation figures
  • 6.3.2. Architecture roadmap
    • 6.3.2.1. Package map
    • 6.3.2.2. The 3-D Maxwell equation and the production-backend choice
    • 6.3.2.3. What is verified today
    • 6.3.2.4. Wired into the agents
    • 6.3.2.5. Milestone status
    • 6.3.2.6. Next steps
  • 6.3.3. Canonical data contracts
    • 6.3.3.1. Building a survey
    • 6.3.3.2. The 3-D Maxwell dataset contract
    • 6.3.3.3. Invalid data are never invented
    • 6.3.3.4. Convention is part of the data
    • 6.3.3.5. Selecting, subsetting, and merging
    • 6.3.3.6. Fitting a normalizer once, reusing it everywhere
    • 6.3.3.7. Splitting realizations without leaking
    • 6.3.3.8. Recording what actually produced a dataset
    • 6.3.3.9. Accounting for every station, not just the aggregate
  • 6.3.4. Correlated geological priors
    • 6.3.4.1. What a Gaussian correlation length means
    • 6.3.4.2. Verify correlation statistically
    • 6.3.4.3. Build stratigraphy before adding bodies
    • 6.3.4.4. Compose lenses with explicit overlap rules
    • 6.3.4.5. Topography is a mask, not a vertical stretch
    • 6.3.4.6. Carry the same composition into 3-D
    • 6.3.4.7. Connecting a rich prior to 3-D Maxwell training
    • 6.3.4.8. Persist identity and audit the ensemble
  • 6.3.5. Domain-gap and noise simulation
    • 6.3.5.1. Two families of corruption
    • 6.3.5.2. Composing one reproducible pass
    • 6.3.5.3. Fitting corruption from a real survey
    • 6.3.5.4. Comparing simulated and field distributions
    • 6.3.5.5. Accounting for every station, not just corruption
  • 6.3.6. Solver-neutral Maxwell contracts
    • 6.3.6.1. The problem and result contracts
    • 6.3.6.2. A validated execution path, not just an interface
    • 6.3.6.3. Meshes built from geology, not by hand
    • 6.3.6.4. Proven against physics, not asserted
    • 6.3.6.5. What the solved 3-D backends guarantee
    • 6.3.6.6. Backends found by capability, not by import
    • 6.3.6.7. Caching and batch generation
  • 6.3.7. 2-D Maxwell training-data generation
    • 6.3.7.1. Configuring one coherent dataset
    • 6.3.7.2. From complex impedance to network channels
    • 6.3.7.3. Two impedance modes, and why one needed more care than the other
    • 6.3.7.4. Fail fast before an impractical mesh
    • 6.3.7.5. Handing this to noise, or to training
  • 6.3.8. 3-D Maxwell training-data generation
    • 6.3.8.1. Configuring a 3-D dataset
    • 6.3.8.2. A padded mesh, not a uniform one
    • 6.3.8.3. Frequency-aware core resolution
    • 6.3.8.4. Fail fast before an impractical mesh
    • 6.3.8.5. From impedance tensor to network channels
    • 6.3.8.6. Handing this to noise, agents, or training
  • 6.3.9. Loss functions for scientific inversion
    • 6.3.9.1. Weighting a residual by what it means
    • 6.3.9.2. Penalizing structure, not just misfit
    • 6.3.9.3. Anchoring what the training data cannot see
    • 6.3.9.4. Closing the loop back through the forward solver
    • 6.3.9.5. Making declared uncertainty answerable to evidence
    • 6.3.9.6. Assemble an auditable staged score
    • 6.3.9.7. Wiring the spatial terms into a trainable network
    • 6.3.9.8. Choose and validate the objective deliberately
  • 6.3.10. Recovery, residual, and OOD diagnostics
    • 6.3.10.1. Scoring recovery when the truth is known
    • 6.3.10.2. Breaking a response residual down by where it comes from
    • 6.3.10.3. Checking whether declared uncertainty deserves trust
    • 6.3.10.4. Flagging predictions the training distribution never covered
    • 6.3.10.5. Reading the four diagnostics together
    • 6.3.10.6. Turning diagnostics into an acceptance decision
    • 6.3.10.7. What actually reaches an agent’s result today
  • 6.3.11. Reproducible experiment configuration
    • 6.3.11.1. Deriving stable, order-independent seeds
    • 6.3.11.2. Pinning a dataset by hash, not by path
    • 6.3.11.3. Fixing acceptance criteria before looking at results
    • 6.3.11.4. The complete configuration
    • 6.3.11.5. One frozen protocol still needs repeated runs
    • 6.3.11.6. What the configuration does not prove
  • 6.3.12. AI inversion data preparation
    • 6.3.12.1. Data preparation workflow
    • 6.3.12.2. 1. Start from the decision and parameterization
    • 6.3.12.3. 2. Load field data canonically
    • 6.3.12.4. 3. Use observation containers before features
    • 6.3.12.5. 4. Freeze the 1-D feature contract
    • 6.3.12.6. 5. Build a 2-D field panel
    • 6.3.12.7. 6. Prepare coordinates for graph inversion
    • 6.3.12.8. 7. Design synthetic earth models
    • 6.3.12.9. 8. Generate a 1-D synthetic dataset
    • 6.3.12.10. 9. Understand ForwardDataset
    • 6.3.12.11. 10. Generate pseudo-3-D graph data
    • 6.3.12.12. 11. Prepare 2-D training profiles
    • 6.3.12.13. 12. Prepare 3-D training profiles
    • 6.3.12.14. 13. Add realistic observation effects
    • 6.3.12.15. 14. Audit synthetic arrays
    • 6.3.12.16. 15. Split without leakage
    • 6.3.12.17. 16. Fit preprocessing on training only
    • 6.3.12.18. 17. Compare field and synthetic domains
    • 6.3.12.19. 18. Store datasets with provenance
    • 6.3.12.20. Complete 1-D preparation example
    • 6.3.12.21. Review checklist
    • 6.3.12.22. Common mistakes
    • 6.3.12.23. Next steps
  • 6.3.13. AI model selection
    • 6.3.13.1. Selection workflow
    • 6.3.13.2. 1. Define the selection objective
    • 6.3.13.3. 2. Decide dimension before architecture
    • 6.3.13.4. 3. Compare model families
    • 6.3.13.5. 4. Choose the 1-D architecture
    • 6.3.13.6. 5. Choose layer count and target complexity
    • 6.3.13.7. 6. Select solver and feature content
    • 6.3.13.8. 7. Select the 2-D U-Net configuration
    • 6.3.13.9. 8. Select graph architecture and adjacency
    • 6.3.13.10. 9. Decide whether joint inversion is justified
    • 6.3.13.11. 10. Decide between supervised, PINN, and hybrid
    • 6.3.13.12. 11. Decide whether an ensemble is required
    • 6.3.13.13. 12. Establish baselines
    • 6.3.13.14. 13. Define a fair comparison protocol
    • 6.3.13.15. 14. Compare multiple metric families
    • 6.3.13.16. 15. Consider persistence and deployment
    • 6.3.13.17. 16. Use InversionConfig for 1-D candidates
    • 6.3.13.18. 17. Record the selection decision
    • 6.3.13.19. Complete selection example
    • 6.3.13.20. Selection checklist
    • 6.3.13.21. Common mistakes
    • 6.3.13.22. Next steps
  • 6.3.14. Training AI inversion models
    • 6.3.14.1. What fit means in pyCSAMT
    • 6.3.14.2. Before starting a run
    • 6.3.14.3. Splits, leakage, and normalization
    • 6.3.14.4. Configuration-first 1-D training
    • 6.3.14.5. Direct 1-D fitting
    • 6.3.14.6. Understanding the training arguments
    • 6.3.14.7. Augmentation is a scientific nuisance model
    • 6.3.14.8. Monitor more than one loss
    • 6.3.14.9. Training a 2-D U-Net
    • 6.3.14.10. Training a graph model
    • 6.3.14.11. Joint and ensemble training
    • 6.3.14.12. PINN and hybrid optimization
    • 6.3.14.13. Reproducible experiment design
    • 6.3.14.14. Failure diagnosis
    • 6.3.14.15. Training completion checklist
  • 6.3.15. AI inversion inference
    • 6.3.15.1. Inference workflow
    • 6.3.15.2. 1. Define the inference unit
    • 6.3.15.3. 2. Assemble the approved model package
    • 6.3.15.4. 3. Verify integrity and compatibility
    • 6.3.15.5. 4. Load a 1-D checkpoint
    • 6.3.15.6. 5. Prepare 1-D field features
    • 6.3.15.7. 6. Replay preprocessing exactly
    • 6.3.15.8. 7. Gate out-of-domain inputs
    • 6.3.15.9. 8. Run 1-D prediction
    • 6.3.15.10. 9. Run 2-D profile prediction
    • 6.3.15.11. 10. Run graph 3-D prediction
    • 6.3.15.12. 11. Predict graph uncertainty
    • 6.3.15.13. 12. Ensemble inference
    • 6.3.15.14. 13. PINN and hybrid inference
    • 6.3.15.15. 14. Decode outputs safely
    • 6.3.15.16. 15. Reconstruct forward responses
    • 6.3.15.17. 16. Apply acceptance rules
    • 6.3.15.18. 17. Batch and resource behavior
    • 6.3.15.19. 18. Export an inference record
    • 6.3.15.20. Complete 1-D inference example
    • 6.3.15.21. Review checklist
    • 6.3.15.22. Common mistakes
    • 6.3.15.23. Next steps
  • 6.3.16. AI inversion validation
    • 6.3.16.1. Validation is a claim with a scope
    • 6.3.16.2. The evaluation partitions
    • 6.3.16.3. Freeze the artifact before testing
    • 6.3.16.4. Parameter-space evaluation
    • 6.3.16.5. Model geometry and boundary recovery
    • 6.3.16.6. Response-space validation
    • 6.3.16.7. Baselines and ablations
    • 6.3.16.8. Robustness and stress testing
    • 6.3.16.9. Uncertainty validation
    • 6.3.16.10. Field-data validation
    • 6.3.16.11. Validation by inversion family
    • 6.3.16.12. Failure analysis
    • 6.3.16.13. Worked rejection decision
    • 6.3.16.14. Acceptance criteria
    • 6.3.16.15. Statistical reporting
    • 6.3.16.16. Minimum validation record
    • 6.3.16.17. Validation checklist
  • 6.3.17. AI inversion uncertainty
    • 6.3.17.1. What uncertainty should answer
    • 6.3.17.2. Sources of uncertainty
    • 6.3.17.3. Calibration and sharpness must be read together
    • 6.3.17.4. Deep ensembles
    • 6.3.17.5. Calibration data are a separate resource
    • 6.3.17.6. Conformal prediction intervals
    • 6.3.17.7. Coverage diagnostics
    • 6.3.17.8. Calibrated posterior samples
    • 6.3.17.9. From parameter uncertainty to model uncertainty
    • 6.3.17.10. Forward-response uncertainty
    • 6.3.17.11. Sensitivity and perturbation tests
    • 6.3.17.12. Out-of-distribution checks
    • 6.3.17.13. Uncertainty for 2-D, graph, joint, and hybrid models
    • 6.3.17.14. Persistence and reproducibility
    • 6.3.17.15. Reporting uncertainty responsibly
    • 6.3.17.16. Common mistakes
    • 6.3.17.17. Decision checklist
  • 6.3.18. Hybrid AI and physics inversion
    • 6.3.18.1. Before you run it
    • 6.3.18.2. The two-stage objective
    • 6.3.18.3. 1-D hybrid inversion
    • 6.3.18.4. 2-D hybrid refinement
    • 6.3.18.5. 3-D and graph hybrid workflows
    • 6.3.18.6. Agent-assisted hybrid runs
    • 6.3.18.7. Convergence and stopping
    • 6.3.18.8. Sensitivity design
    • 6.3.18.9. What to compare
    • 6.3.18.10. Reporting requirements
    • 6.3.18.11. Common failure modes
    • 6.3.18.12. Next steps
  • 6.3.19. Physics-informed 2-D inversion
    • 6.3.19.1. When to use this workflow
    • 6.3.19.2. Workflow
    • 6.3.19.3. 1. Understand the model parameterization
    • 6.3.19.4. 2. Understand the loss function
    • 6.3.19.5. 3. Prepare and order profile data
    • 6.3.19.6. 4. Select polarization mode
    • 6.3.19.7. 5. Choose the common frequency grid
    • 6.3.19.8. 6. Choose layer count and depth
    • 6.3.19.9. 7. Select regularization weights
    • 6.3.19.10. 8. Select optimizer controls
    • 6.3.19.11. 9. Run a baseline inversion
    • 6.3.19.12. 10. Extract resistivity and thickness
    • 6.3.19.13. 11. Review convergence
    • 6.3.19.14. 12. Review residuals
    • 6.3.19.15. 13. Plot the section correctly
    • 6.3.19.16. 14. Run TE/TM and regularization scenarios
    • 6.3.19.17. 15. Compare with 1-D and classical 2-D results
    • 6.3.19.18. 16. Use the PINN agent for orchestration
    • 6.3.19.19. 17. Consider hybrid 2-D refinement
    • 6.3.19.20. 18. Assess uncertainty
    • 6.3.19.21. 19. Preserve a run record
    • 6.3.19.22. Complete example
    • 6.3.19.23. Review checklist
    • 6.3.19.24. Common mistakes
    • 6.3.19.25. Next steps
  • 6.3.20. AI inversion agents
    • 6.3.20.1. Agent map
    • 6.3.20.2. Common execution contract
    • 6.3.20.3. AgentResult
    • 6.3.20.4. Prepare data before running an agent
    • 6.3.20.5. Deep-learning backend
    • 6.3.20.6. Read every inversion as a contract
    • 6.3.20.7. AIInversionAgent: 1-D workflow
    • 6.3.20.8. Inv2DAgent: profile workflow
    • 6.3.20.9. Inv3DAgent: spatial graph workflow
    • 6.3.20.10. EnsembleAgent: uncertainty-aware 1-D workflow
    • 6.3.20.11. PINNInversionAgent
    • 6.3.20.12. ModelZooAgent
    • 6.3.20.13. Checkpoint and output policy
    • 6.3.20.14. Optional LLM interpretation
    • 6.3.20.15. Failure handling
    • 6.3.20.16. Choosing the right interface
    • 6.3.20.17. Review checklist
    • 6.3.20.18. Common mistakes
    • 6.3.20.19. Next steps
  • 6.3.21. AI inversion reporting
    • 6.3.21.1. Reporting objectives
    • 6.3.21.2. Recommended reporting workflow
    • 6.3.21.3. 1. Define report status and audience
    • 6.3.21.4. 2. Use linked identifiers
    • 6.3.21.5. 3. Recommended package structure
    • 6.3.21.6. 4. Write a dataset card
    • 6.3.21.7. 5. Write a model card
    • 6.3.21.8. 6. Report model selection
    • 6.3.21.9. 7. Report training behavior
    • 6.3.21.10. 8. Report test metrics in context
    • 6.3.21.11. 9. Report field-domain status
    • 6.3.21.12. 10. Report predictions with an output schema
    • 6.3.21.13. 11. Report response reconstruction
    • 6.3.21.14. 12. Report uncertainty and calibration
    • 6.3.21.15. 13. Report classical and independent validation
    • 6.3.21.16. 14. Report figures responsibly
    • 6.3.21.17. 15. Use ReportAgent carefully
    • 6.3.21.18. 16. Handle optional LLM narrative
    • 6.3.21.19. 17. Write the narrative report
    • 6.3.21.20. 18. Build a machine-readable manifest
    • 6.3.21.21. 19. Validate the report package
    • 6.3.21.22. 20. Review and approval roles
    • 6.3.21.23. 21. Monitor deployed models
    • 6.3.21.24. Complete reporting skeleton
    • 6.3.21.25. Release checklist
    • 6.3.21.26. Common reporting mistakes
    • 6.3.21.27. Next steps