Io module (io.h)

Defines

PETGEM_SIM_FM

Simulation-type tags stamped into every PETGEM output product.

Written as the simulation_type root attribute by writeRunProvenance so a result file identifies which kernel produced it without inspecting its datasets. Forward modeling (fm.csem).

PETGEM_SIM_IM

Inverse modeling (im.csem).

Functions

PetscErrorCode readPetgemParams(const PetscMPIInt size, petgemParams *params)

Reads and validates CSEM CLI parameters from PETSc options.

Extracts the required runtime parameters (input/output paths) from the PETSc options database. The finite-element basis order -order is optional: when omitted, params->order is set to 0 so loadCsemInputs takes the order from the input bundle.

This function extracts required runtime parameters from the PETSc options database, including input/output paths and the finite-element basis order. All parameters are mandatory except -order, which can optionally override the value stored in the input bundle.

The -order option is mainly intended for debugging runs. If not provided, pg_Params->order is set to 0, meaning the value will be taken from the input bundle by loadCsemInputs.

Parameters:

  • size – [in] Number of MPI tasks.

  • pg_Params – [out] Struct receiving the parsed CSEM parameters.

  • size – [in] Number of MPI tasks.

  • pg_Params – [out] Struct containing parsed CSEM parameters.

Returns:

PetscErrorCode PETSC_SUCCESS on success, or a PETSc error code otherwise.

Returns:

PetscErrorCode PETSC_SUCCESS on success, or a PETSc error code otherwise.

PetscErrorCode loadCsemInputs(petgemParams *pg_params, DM *dm, Vec *conductivity, Vec *materialsID, CsemSourceSet *sources, Vec *receivers)

Loads all CSEM inputs from the unified PETGEM HDF5 bundle.

Opens pg_params->inputFile on PETSC_COMM_WORLD to load the DMPlex topology, sections, and the combined model-data vector (split into the per-cell conductivity and materials_id local Vecs). Opens the same file again on PETSC_COMM_SELF (each rank reads independently) to load:

  • /order single-element Vec, written into pg_params->order

  • /receivers Vec of 3·N_recv reals

  • /sources/frequency single-frequency scalar

  • /sources/position Vec of 3·N_src reals

  • /sources/current Vec of N_src reals

  • /sources/length Vec of N_src reals

  • /sources/dipAngle Vec of N_src reals

  • /sources/azimuthAngle Vec of N_src reals

Replaces the legacy importGrid + setupCsemSource + per-call receivers-file open path with a single open of the bundle produced by the Python preprocessor (utils/functions.py::writeBundle).

Loads all CSEM inputs from the unified PETGEM HDF5 bundle.

This routine reads the full simulation input file (mesh, model fields, sources, receivers, and auxiliary parameters) and reconstructs the runtime PETSc objects required by the solver.

Loading is split into two stages:

  • Phase 1 (parallel I/O): builds the DMPlex mesh, loads topology, distributes it across ranks, and reconstructs the combined per-cell model vector. This vector is then split into conductivity and material-ID fields using local sections.

  • Phase 2 (serial I/O on PETSC_COMM_SELF): reads scalar or small datasets such as /order, receivers, and source definitions.

The function enforces consistency between the bundled data layout and the internal DM structure, and applies CLI overrides when present (e.g., -order).

Parameters:

  • pg_Params – [inout] Parameters; inputFile is read, order is written from the bundle’s /order dataset.

  • odm – [out] Loaded DMPlex mesh.

  • conductivity_output – [out] Per-cell conductivity Vec.

  • materials_id_output – [out] Per-cell material-id Vec.

  • sources – [out] Forward transmitter set; pass NULL to skip (im.csem pulls multi-frequency sources via setupInversionSources instead).

  • receivers_output – [out] Serial Vec of 3·N_recv receiver reals; pass NULL to skip.

  • pg_Params – [inout] Runtime parameters (input file, order, etc.).

  • odm – [out] Output distributed mesh (DMPlex).

  • conductivity_output – [out] Cell-wise conductivity field.

  • materials_id_output – [out] Cell-wise material ID field.

  • sources – [out] Source set (optional, allocated if non-NULL).

  • receivers_output – [out] Receiver vector (optional, allocated if non-NULL).

Returns:

PetscErrorCode PETSC_SUCCESS on success, or a PETSc error code otherwise.

Returns:

PetscErrorCode PETSC_SUCCESS on success, or a PETSc error code otherwise.

PetscErrorCode buildOutputPath(const petgemParams *params, const char *suffix, char *out, size_t outSize)

Builds the canonical output path {output_dir}/{output_filename}{suffix}.

The single place both kernels compose an output path, so fm.csem and im.csem name their products identically. A trailing ‘/’ on the output directory is optional (inserted when absent).

See io.h. Single implementation shared by the forward responses writer (computeFields), the inversion results writer (writeInversionResults) and the VTU snapshot writer, so all three name their products identically.

Parameters:

  • params – [in] Parameters carrying outputDirectory and outputFilename.

  • suffix – [in] Extension or stem suffix, e.g. “.h5” (may be empty).

  • out – [out] Buffer receiving the composed path.

  • outSize – [in] Size of out in bytes.

  • params – [in] Parameters carrying outputDirectory and outputFilename.

  • suffix – [in] Extension or stem suffix, e.g. “.h5” (may be empty).

  • out – [out] Buffer receiving the composed path.

  • outSize – [in] Size of out in bytes.

Returns:

PetscErrorCode PETSC_SUCCESS on success, or a PETSc error code otherwise.

Returns:

PetscErrorCode PETSC_SUCCESS on success, or a PETSc error code otherwise.

PetscErrorCode writeRunProvenance(PetscViewer viewer, const petgemParams *params, const char *simulationType)

Writes the common root provenance attributes of an output file.

Shared by both kernels so every PETGEM product carries the same traceability block, with identical attribute names and casing:

petgem_version, simulation_type, input_filename, order, ksp_type, pc_type, mpi_tasks, date

The caller adds its own product-specific attributes afterwards (fm.csem: num_sources, frequency; im.csem: num_frequencies, lambda, error_level, num_iterations, convergence_reason).

The solver keys are read back from the PETSc options database so the file records the configuration the run actually used; they read “default” when the option was not set.

See io.h. Both kernels call this so every PETGEM product carries the same traceability block under identical attribute names; each kernel then adds only its product-specific attributes.

Parameters:

  • viewer – [in] Open HDF5 viewer positioned at the file root.

  • params – [in] Shared base parameters (input path, order, tasks).

  • simulationType – [in] PETGEM_SIM_FM or PETGEM_SIM_IM.

  • viewer – [in] Open HDF5 viewer positioned at the file root.

  • params – [in] Shared base parameters (input path, order, tasks).

  • simulationType – [in] PETGEM_SIM_FM or PETGEM_SIM_IM.

Returns:

PetscErrorCode PETSC_SUCCESS on success, or a PETSc error code otherwise.

Returns:

PetscErrorCode PETSC_SUCCESS on success, or a PETSc error code otherwise.

struct petgemParams
#include <io.h>

Parsed user-input parameters consumed by the PETGEM kernels.

Public Members

char inputFile[PETSC_MAX_PATH_LEN]

Unified PETGEM input bundle (HDF5) - contains mesh topology, sections, per-cell conductivity + materials_id, receivers (under /receivers), and single-frequency forward sources (under /sources/…). Produced by runPreprocessing() on the Python side. Consumed by loadCsemInputs().

char outputDirectory[PETSC_MAX_PATH_LEN]

Output directory path.

char outputFilename[PETSC_MAX_PATH_LEN]

Output filename stem for responses.

PetscInt order

Finite-element basis order (0 = take from bundle).

PetscMPIInt numMPITasks

Number of MPI tasks in the run.

PetscBool quiet

Suppress per-call assembly headers (“Assembly RHS:”, “Vector size”, “Initiated”, “Finished”, “Assembly K + M(sigma)”, etc.) emitted by src/assembly.c. Default PETSC_FALSE preserves current fm.csem output; the inversion kernel sets this to PETSC_TRUE to silence repeated per-frequency / per-iteration headers in the L-BFGS loop.

PetscBool mms

Method-of-Manufactured-Solutions verification mode (forward kernel only). When PETSC_TRUE, runForward dispatches to runMMSVerification (src/mms.c), which runs the complete MMS verification (Galerkin solve + L2 projection + optional diagnostics) and exits, skipping the normal receiver pipeline. Enabled with -mms; default PETSC_FALSE. See include/mms.h and paper/tests_mms/. im.csem ignores it.