Parameter File
The parameter file is the central control object for a SeisFlows workflow. Here we take a look at the anatomy of a parameter file. Parameter files in SeisFlows are formatted in the YAML format (YAML Ain’t Markup Language).
Template
Each workflow starts with the module-only template parameter file which
defines the core modules of the package. Your choices for each of these
modules will determine which paths and parameters are included in the
full parameter file. Running seisflows setup
from the command line
will create the template file.
seisflows setup -h
usage: seisflows setup [-h] [-f]
In the specified working directory, copy template parameter file containing
only module choices, and symlink source code for both the base and super
repositories for easy edit access. If a parameter file matching the provided
name exists in the working directory, a prompt will appear asking the user if
they want to overwrite.
optional arguments:
-h, --help show this help message and exit
-f, --force automatically overwrites existing parameter file
seisflows setup
creating parameter file: parameters.yaml
cat parameters.yaml
# //////////////////////////////////////////////////////////////////////////////
#
# SeisFlows YAML Parameter File
#
# //////////////////////////////////////////////////////////////////////////////
#
# Modules correspond to the structure of the source code, and determine
# SeisFlows' behavior at runtime. Each module requires its own sub-parameters.
#
# .. rubric::
# - To determine available options for modules listed below, run:
# > seisflows print modules
# - To auto-fill with docstrings and default values (recommended), run:
# > seisflows configure
# - To set values as NoneType, use: null
# - To set values as infinity, use: inf
#
# MODULES
# ///////
# workflow (str): The types and order of functions for running SeisFlows
# system (str): Computer architecture of the system being used
# solver (str): External numerical solver to use for waveform simulations
# preprocess (str): Preprocessing schema for waveform data
# optimize (str): Optimization algorithm for the inverse problem
# ==============================================================================
workflow: forward
system: workstation
solver: specfem2d
preprocess: default
optimize: gradient
How do I choose modules?
As seen above, each of the modules comes with a default value which represents the base class* for this module.
For an explanation of base classes and Python inheritance, see the inheritance page
These default values are likely not suitable for all, e.g., if you want
to run an inversion and not a forward workflow, or use SPECFEM3D not
SPECFEM2D. To see all available module options, use the
seisflows print modules
command.
seisflows print modules
SEISFLOWS MODULES
/////////////////
'-': module, '*': class
- workflow
* forward
* inversion
* migration
- system
* chinook
* cluster
* frontera
* lsf
* maui
* slurm
* workstation
- solver
* specfem
* specfem2d
* specfem3d
* specfem3d_globe
- preprocess
* default
* pyaflowa
- optimize
* LBFGS
* NLCG
* gradient
How do I change modules?
Feel free to use any text editor, or use the seisflows par
command
to make changes directly from the command line. For example, say we want
to use SPECFEM3D as our solver module.
This is also covered in the command line tool page
# Changes the current parameter to the given value
seisflows par solver specfem3d
solver: specfem2d -> specfem3d
# Prints out the current parameter value
seisflows par solver
solver: specfem3d
How do I create a full parameter file?
The module-only parameter file serves as as a template for dynamically
generating the full parameter file. Since each module requires it’s own
unique set of parameters and paths, each parameter file will look
different. We use the seisflows configure
command to complete the
file.
seisflows configure -h
usage: seisflows configure [-h] [-a]
SeisFlows parameter files will vary depending on chosen modules and their
respective required parameters. This function will dynamically traverse the
source code and generate a template parameter file based on module choices.
The resulting file incldues docstrings and type hints for each parameter.
Optional parameters will be set with default values and required parameters
and paths will be marked appropriately. Required parameters must be set before
a workflow can be submitted.
optional arguments:
-h, --help show this help message and exit
-a, --absolute_paths Set default paths relative to cwd
seisflows configure
Below we will take a look at the parameter file we just created
Anatomy of a parameter file
Each of SeisFlows’ modules will define its own section in the parameter file, separated by a header of comments representing the docstring. Within each header, parameter names, types and descriptions are listed. At the bottom of the parameter file, there is a section defining paths required by SeisFlows. Section headers will look something:
# =============================================================================
# MODULE
# ------
# Module description
#
# Parameters
# ----------
# :type parameter: type
# :param paramter: description
# ...
# =============================================================================
parameter: value
head -80 parameters.yaml
# ////////////////////////////////////////////////////////////////////////////// # # SeisFlows YAML Parameter File # # ////////////////////////////////////////////////////////////////////////////// # # Modules correspond to the structure of the source code, and determine # SeisFlows' behavior at runtime. Each module requires its own sub-parameters. # # .. rubric:: # - To determine available options for modules listed below, run: # > seisflows print modules # - To auto-fill with docstrings and default values (recommended), run: # > seisflows configure # - To set values as NoneType, use: null # - To set values as infinity, use: inf # # MODULES # /////// # workflow (str): The types and order of functions for running SeisFlows # system (str): Computer architecture of the system being used # solver (str): External numerical solver to use for waveform simulations # preprocess (str): Preprocessing schema for waveform data # optimize (str): Optimization algorithm for the inverse problem # ============================================================================== workflow: forward system: workstation solver: specfem3d preprocess: default optimize: gradient # ============================================================================= # # Forward Workflow # ---------------- # Run forward solver in parallel and (optionally) calculate # data-synthetic misfit and adjoint sources. # # Parameters # ---------- # :type modules: list of module # :param modules: instantiated SeisFlows modules which should have been # generated by the function seisflows.config.import_seisflows with a # parameter file generated by seisflows.configure # :type data_case: str # :param data_case: How to address 'data' in the workflow, available options: # 'data': real data will be provided by the user in # path_data/{source_name} in the same format that the solver will # produce synthetics (controlled by solver.format) OR # synthetic': 'data' will be generated as synthetic seismograms using # a target model provided in path_model_true. If None, workflow will # not attempt to generate data. # :type export_traces: bool # :param export_traces: export all waveforms that are generated by the # external solver to path_output. If False, solver traces stored in # scratch may be discarded at any time in the workflow # :type export_residuals: bool # :param export_residuals: export all residuals (data-synthetic misfit) that # are generated by the external solver to path_output. If False, # residuals stored in scratch may be discarded at any time in the workflow # # # ============================================================================= data_case: data export_traces: False export_residuals: False # ============================================================================= # # Workstation System # ------------------ # Runs tasks in serial on a local machine. # # Parameters # ---------- # :type ntask: int # :param ntask: number of individual tasks/events to run during workflow. # Must be <= the number of source files in path_specfem_data # :type nproc: int # :param nproc: number of processors to use for each simulation # :type log_level: str # :param log_level: logger level to pass to logging module.
tail parameters.yaml
path_model_true: null
path_state_file: /Users/Chow/Repositories/seisflows/docs/notebooks/sfstate.txt
path_data: null
path_par_file: /Users/Chow/Repositories/seisflows/docs/notebooks/parameters.yaml
path_log_files: /Users/Chow/Repositories/seisflows/docs/notebooks/logs
path_output_log: /Users/Chow/Repositories/seisflows/docs/notebooks/sflog.txt
path_specfem_bin: null
path_specfem_data: null
path_solver: /Users/Chow/Repositories/seisflows/docs/notebooks/scratch/solver
path_preconditioner: null
How do I know how parameters need to be set?
Most SeisFlows parameters come with reasonable default values. The
docstrings headers will also list the expected type and available
options (if any). You may also run the seisflows check
command which
verifies that parameters are set correctly.
seisflows check
================================================================================ PARAMETER ERRROR //////////////// path_specfem_bin must exist and must point to directory containing SPECFEM executables ================================================================================
rm parameters.yaml # to delete the created file from this working directory