Overview

PETGEM provides two execution modes built on the same high-order vector finite element core: forward modeling of the 3D Controlled-Source Electromagnetic (CSEM) response, and inverse modeling (inversion) that recovers a subsurface conductivity model from observed data. Both modes share the same meshes, conductivity description, and preprocessing pipeline, and differ only in the kernel that consumes the prepared input.

Execution modes

PETGEM ships three binaries (built by make into build/):

  • fm.csem: the forward kernel (single-purpose).

  • im.csem: the inverse kernel (single-purpose).

  • petgem: a unified dispatcher that selects the mode from the command line:

    ./petgem modeling -options_file params.txt   # forward  (== fm.csem)
./petgem inverse  -options_file params.txt   # inverse  (== im.csem)

The single-purpose binaries and the matching petgem mode run identical code paths; use whichever fits your workflow.

Shared workflow

Regardless of mode, a PETGEM run follows the same high-level stages:

  1. Generate or import a tetrahedral mesh using Gmsh.

  2. Describe the subsurface conductivity model in a text table (sigmas.txt).

  3. Run utils/preprocess.py to assemble a single input bundle and a matching parameter file.

  4. Execute the appropriate kernel (fm.csem or im.csem).

  5. Post-process the results.

Stages 1-3 are common to both modes; the mode-specific details live in Forward modeling and Inverse modeling.

The input bundle

utils/preprocess.py is the centralized preprocessing entry point for both modes. It reads the mesh, conductivity table, receivers, and sources, and writes a single unified HDF5 bundle (-input_filename, default input.h5) together with a PETSc-style parameter file (-params_filename, default params.txt). The kernel reads everything case-specific from the bundle - the polynomial order (/nord), the model, the receivers, and (for inverse runs) the multi-frequency sources, observed data, noise level, and fixed-material list. The parameter file carries only solver and runtime knobs.

The mode is selected with -mode:

python3 utils/preprocess.py -mode forward ...   # forward bundle + params
python3 utils/preprocess.py -mode inverse ...   # inverse bundle + params

Conductivity model

The conductivity model is a whitespace text table passed via -sigma_file (relative to -case_dir). Each row is one material, indexed by 0-based material id (gmsh:physical - 1):

# sigma_x sigma_y sigma_z [fixed]
0.1 0.1 0.1 1     # held fixed during inversion (e.g. air, ocean)
1.0 1.0 1.0 0     # invertable
2.0 2.0 2.0       # 'fixed' column omitted -> defaults to 0

The optional fourth column (fixed) is only meaningful for inverse modeling: a non-zero entry marks the material as held fixed during inversion. Forward modeling ignores it.

Pre- and post-processing

PETGEM provides a suite of Python helpers (under utils/ and per-case scripts) for:

  • Mesh conversion into the bundle’s expected layout.

  • Conductivity model assembly from sigmas.txt.

  • Visualization of the model in VTK format (-output_vtk).

  • Comparison of responses against a reference (per-case postprocess.py).

Example cases ship under tests/cases/ (e.g. tests/cases/csem_model for forward modeling and tests/cases/inverse for inversion). These illustrate the construction of the bundle and parameter files for each mode.