seisflows.workflow.forward
The simplest simulation workflow you can run is a large number of forward simulations to generate synthetics from a velocity model. Therefore the Forward class represents the BASE workflow. All other workflows will build off of the scaffolding defined by the Forward class.
Module Contents
Classes
Forward Workflow |
- class seisflows.workflow.forward.Forward(modules=None, data_case='data', stop_after=None, export_traces=False, export_residuals=False, workdir=os.getcwd(), path_output=None, path_data=None, path_state_file=None, path_model_init=None, path_model_true=None, path_eval_grad=None, **kwargs)
Forward Workflow
Defines foundational structure for Workflow module. When used standalone is in charge of running forward solver in parallel and (optionally) calculating 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 stop_after
str
- param stop_after
optional name of task in task list (use seisflows print tasks to get task list for given workflow) to stop workflow after, allowing user to prematurely stop a workflow to explore intermediate results or debug.
- 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
Paths
- type workdir
str
- param workdir
working directory in which to perform a SeisFlows workflow. SeisFlows internal directory structure will be created here. Default cwd
- type path_output
str
- param path_output
path to directory used for permanent storage on disk. Results and exported scratch files are saved here.
- type path_data
str
- param path_data
path to any externally stored data required by the solver
- type path_state_file
str
- param path_state_file
path to a text file used to track the current status of a workflow (i.e., what functions have already been completed), used for checkpointing and resuming workflows
- type path_model_init
str
- param path_model_init
path to the starting model used to calculate the initial misfit. Must match the expected solver_io format.
- type path_model_true
str
- param path_model_true
path to a target model if `case`==’synthetic’ and a set of synthetic ‘observations’ are required for workflow.
- type path_eval_grad
str
- param path_eval_grad
scratch path to store files for gradient evaluation, including models, kernels, gradient and residuals.
- property task_list
USER-DEFINED TASK LIST. This property defines a list of class methods that take NO INPUT and have NO RETURN STATEMENTS. This defines your linear workflow, i.e., these tasks are to be run in order from start to finish to complete a workflow.
This excludes ‘check’ (which is run during ‘import_seisflows’) and ‘setup’ which should be run separately
Note
For workflows that require an iterative approach (e.g. inversion), this task list will be looped over, so ensure that any setup and teardown tasks (run once per workflow, not once per iteration) are not included.
- Return type
list
- Returns
list of methods to call in order during a workflow
- check()
Check that workflow has required modules. Run their respective checks
- setup()
Assigns modules as attributes of the workflow. I.e., self.solver to access the solver module (or workflow.solver from outside class)
Makes required path structure for the workflow, runs setup functions for all the required modules of this workflow.
- checkpoint()
Saves active SeisFlows working state to disk as a text files such that the workflow can be resumed following a crash, pause or termination of workflow.
- run()
Call the Task List in order to ‘run’ the workflow. Contains logic for to keep track of completed tasks and avoids re-running tasks that have previously been completed (e.g., if you are restarting your workflow)
- evaluate_initial_misfit()
Evaluate the initial model misfit. This requires setting up ‘data’ before generating synthetics, which is either copied from user-supplied directory or running forward simulations with a target model. Forward simulations are then run and prepocessing compares data-synthetic misfit
Note
This is run altogether on system to save on queue time waits, because we are potentially running two simulations back to back.
- prepare_data_for_solver(**kwargs)
Determines how to provide data to each of the solvers. Either by copying data in from a user-provided path, or generating synthetic ‘data’ using a target model.
Note
Must be run by system.run() so that solvers are assigned individual task ids and working directories
- run_forward_simulations(path_model, **kwargs)
Performs forward simulation for a single given event.
Note
if PAR.PREPROCESS == None, will not perform misfit quantification
Note
Must be run by system.run() so that solvers are assigned individual task ids/ working directories.
- evaluate_objective_function(save_residuals=False, **kwargs)
Uses the preprocess module to evaluate the misfit/objective function given synthetics generated during forward simulations
Note
Must be run by system.run() so that solvers are assigned individual task ids/ working directories.