Tutorial

The PETGEM tutorial contains a collection of programs which demonstrate various aspects of the PETGEM work-flow. Each such example has the following structure:

  1. Introduction. What the program does, including the mathematical model.
  2. The commented program. An extensively documented of the source code.
  3. Results. The output of the program, with comments and interpretation.

The programs are in the examples/ directory of local PETGEM folder. This tutorial focuses on the distributed-memory PETGEM version. Please refer to the Download section for details about the shared-memory version.

Basic notions

The start point of using PETGEM to solve a CSEM forward modelling is through its definition in a parameters file description, also referred to as input file. In such file, the modelling is described using several keywords that allow one to define physical parameters, mesh format, solvers, parallel specifications, and so on. See Parameters file description in Manual section for a full explanation of those keywords.

The syntax of the input file is very simple yet powerful. For a general CSEM forward modelling, the PETGEM work-flow can be summarize as follows:

  1. The kernel (kernel.py) reads an input file.
  2. Following the contents of the input file, a problem instance is created.
  3. The problem sets up its domain, sub-domains, source, solver. This stage include the data structures computation related with the edges in the mesh.
  4. Parallel assemblig of \(Ax=b\). See CSEM problem and Edge finite element formulation sections for a detail mathematical background of this equation system.
  5. The solution is obtained in parallel by calling ksp() PETSc object.
  6. Interpolation & post-processing parallel stage.
  7. Finally the solution can be stored by calling save_solution() function. Current version support binary files, HDF5 and VTK format.

Pre-processing

The petgem_preprocessing.m Matlab script provides functions to change input file formats into a representation that is more suitable for PETGEM. It transforms the mesh files into a PETSc binary format, which allow parallel computations in a simple way. This step is hence mandatory for any modelling. This script is included in utils/Preprocessing/petgem_preprocessing.m of the PETGEM source tree.

From a Matlab terminal, petgem_preprocessing.m is invoked has follows:

$ petgem_preprocessing('mesh_file', 'mesh_format', sigma_domain_per_subdomain, 'receivers_file')

See Utilities section for more details about petgem_preprocessing.m.

Running a simulation

This section introduces the basics of running PETGEM on the command line. The $ represents the command prompt of the terminal. The following commands should be run in the top-level directory of the PETGEM source tree.

PETGEM kernel is invoked as follows:

$ mpirun -n <# of MPI processes> python3 kernel.py -options_file path/petsc.opts path/input_file.py

where petsc.opts is the PETSc options file and input_file.py is the PETGEM parameters file, which describes the modelling to be solved in terms PETGEM can understand.

Parameters file template

By definition, any model should include: physical parameters, a mesh file, source and receivers files, computational issues (solver type, domain decomposition) and an output file format.

In sake of simplicity and in order to avoid a specific parser, the PETGEM parameters file is defined as a Pyhton dictionary. As consequence, the dictionary name and his key names MUST NOT BE changed.

A template of this file is included in examples/params_file_template.py of the PETGEM source tree. A glance of this file is the following:

 modelling = {
  # -------------------------------
  # ----------- General -----------
  # -------------------------------

  # -------------------------------
  # ----- Pyshical parameters -----
  # -------------------------------
  # Source
  # Source frequency. Type: float
  # Optional: NO
  'freq': 1.0,

  # Source position(x, y, z). Type: float
  # Optional: NO
  'src_pos': [1750.0, 1750.0, -975.0],

  # Source orientation. Type: int
  # 1 = X-directed source
  # 2 = Y-directed source
  # 3 = Z-directed source
  # Optional: NO
  'src_direc': 1,

  # Source current. Type: float
  # Optional: NO
  'src_current': 1.0,

  # Source length. Type: float
  # Optional: NO
  'src_length': 1.0,

  # Conductivity model. Type: str
  # Optional: NO
  'sigma_file': 'examples/WHAM/elemsSigma.dat',

  # Background conductivity. Type: float
  # Optional: NO
  'sigma_background': 3.33,

  # -------------------------------
  # ------- Mesh information ------
  # -------------------------------
  # Mesh files

  # Nodes spatial coordinates. Type: str
  # Optional: NO
  'nodes_file': 'examples/WHAM/nodes.dat',

  # Elements-nodes connectivity. Type: str
  # Optional: NO
  'elemsN_file': 'examples/WHAM/elemsN.dat',

  # Elements-edges connectivity. Type: str
  # Optional: NO
  'elemsE_file': 'examples/WHAM/elemsE.dat',

  # Edges-nodes connectivity. Type: str
  # Optional: NO
  'edgesN_file': 'examples/WHAM/edgesN.dat',

  # nnz for matrix allocation (PETSc)
  'nnz_file': 'examples/WHAM/nnz.dat',

  # Boundary-edges. Type: str
  # Optional: NO
  'bEdges_file': 'examples/WHAM/bEdges.dat',

  # -------------------------------
  # ------------ Solver -----------
  # -------------------------------
  # Solver options must be set in
  # petsc_solver.opts file

  # -------------------------------
  # ------------ Output -----------
  # -------------------------------
  # Name of the file that contains the receivers position. Type: str
  # Optional: NO
  'receivers_file': 'examples/WHAM/receivers.dat',
}

In section Parameters file description is included a deep explanation about this file is included.

Visualization of results

Once a solution of CSEM forward modelling has been obtained, it should be post-processed by using a visualization program. PETGEM does not do the visualization by itself, but it generates output files (binary format) with the final results which can be exported to other format by using the Post-processing PETGEM scripts. It also gives timing values in order to evaluate the performance. It requires task Paraview.