CLI interface#
The command-line interface can be used for certain specific tasks, such as
forward modelling and the computation of the gradient. The command is
emg3d
, consult the inbuilt help in your terminal to get started:
emg3d --help
The CLI is driven by command-line parameters and a configuration file. The
default configuration filename is emg3d.cfg
, but another name can be
provided as first positional argument to emg3d
. Note that arguments
provided in the command line overwrite the settings in the configuration file.
For an example see the CLI example in the gallery.
Format of the config file#
The shown values are examples. All values are commented out in this example; remove the comment signs to use them.
emg3d.cfg
:
# Files
# -----
# If the files are provided without ending the suffix `.h5` will be appended.
# The log has the same name as `output`, but with the suffix `.log`.
[files]
# path = . # Path (absolute or relative) to the data
# survey = survey.h5 # Also via `--survey`
# model = model.h5 # Also via `--model`
# output = emg3d_out.h5 # Also via `--output`
#
# # You can save the entire simulation with the `save` argument.
# save = my_sim.h5 # Also via `--save`
#
# # You can load an existing simulation with the `load` argument.
# # Note that if you provide a simulation it will ignore
# # - The survey and model under [files]
# # - Sections [simulation], [solver_opts], [gridding_opts], and [data]
# load = my_sim.h5 # Also via `--load`
# Simulation parameters
# ---------------------
# Input parameters for the `Simulation` class, except for `solver_opts`
# (defined in their own section), but including the parameter `min_offset`
# for `compute()`.
[simulation]
# max_workers = 4 # Also via `-n` or `--nproc`.
# gridding = single
# min_offset = 0.0 # off < min_off set to NaN; only if `--forward`.
# mean_noise = 0.0 # Mean of the noise; only if `--forward`.
# ntype = white_noise # Type of the noise; only if `--forward`.
# name = MyTestSimulation
# file_dir = None # For file-based comp; absolute or relative path.
# receiver_interpolation = cubic # Set it to <linear> for the gradient.
# Solver options
# --------------
# Input parameters for the solver.
# See https://emg3d.emsig.xyz/en/stable/api/emg3d.solver.solve.html
# for a list of all parameters. The only parameters that cannot be provided
# here are grid, model, sfield, efield, and return_info.
#
# Note that currently sslsolver, semicoarsening, and linerelaxation only
# accept True/False through the CLI.
[solver_opts]
# sslsolver = # bool
# semicoarsening = # bool
# linerelaxation = # bool
# cycle = # string
# tol = # float
# verb = # int
# maxit = # int
# nu_init = # int
# nu_pre = # int
# nu_coarse = # int
# nu_post = # int
# clevel = # int
# plain = # bool
# Gridding options
# ----------------
# Input parameters for the automatic gridding.
# See the description of `gridding_opts` and link therein in
# https://emg3d.emsig.xyz/en/stable/api/emg3d.simulations.Simulation.html
# for more details.
#
# List of lists: lists are comma-separated values, lists are separated by
# semi-colons.
#
# One of the limitation of the CLI is that `vector` has to be a string.
[gridding_opts]
# properties = # list, e.g.: 0.3, 1, 1e5
# center = # list, e.g.: 0, 0, 0
# cell_number = # list, e.g.: 8, 16, 32, 64, 128
# min_width_pps = # list, e.g.: 5, 3, 3
# expand = # list, e.g.: 0.3, 1e8
# domain = # list of lists, e.g.: -10000, 10000; None; None
# distance = # list of lists, e.g., None; None; -10000, 10000
# stretching = # list of lists, e.g.: None; None; 1.05, 1.5
# min_width_limits = # list of lists, e.g.: 10, 100; None; 50
# mapping = # string, e.g.: Resistivity
# vector = # string, e.g.: xy
# frequency = # float, e.g.: 1.0
# seasurface = # float, e.g.: 0.0
# max_buffer = # float, e.g.: 100000.0
# lambda_factor = # float, e.g.: 1.0
# verb = # int, e.g.: 0
# lambda_from_center = # bool, e.g.: False
# Data
# ----
# Select which sources, receivers, and frequencies of the survey are used. By
# default all data is used. These are comma-separated lists.
[data]
# sources = TxED-02, TxMD-08, TxEW-14
# receivers = RxEP-01, RxMP-10
# frequencies = f-1, f-3
# remove_empty = False # CLI uses False by default.