seisflows.seisflows

A command line tool for using and manipulating SeisFlows. The main entry point to the SeisFlows package, this command line tool facilitates interface with the underlying SeisFlows package.

$ seisflows -h # runs the help command to investigate package features

Note

To add new functions to the seisflows command line tool, you must: - Write a new function within the SeisFlows class - Add a new subparser with optional arguments to sfparser() - Add subparser to subparser dict at the end of sfparser() In-function import statements are used to reduce call-time for simpler fx’s

Module Contents

Classes

SeisFlows

The main entry point to the SeisFlows package, to be interacted with

Functions

sfparser()	An command-line argument parser which allows for intuitive exploration of
return_modules()	Search for the names of available modules in SeisFlows name space.
main()	Main entry point into the SeisFlows package is via the SeisFlows class

seisflows.seisflows.sfparser()

An command-line argument parser which allows for intuitive exploration of the available functions.

Gets User defined arguments or assign defaults. Makes use of subparsers to get individual help statements for each of the main functions.

$ seisflows {main arg} {optional sub arg}

Return type

argparse.ArgumentParser()

Returns

User defined or default arguments

class seisflows.seisflows.SeisFlows(workdir=None, parameter_file=None)

The main entry point to the SeisFlows package, to be interacted with through the command line. This class is responsible for:

1. setting up or re-creating a SeisFlows working enviornment,

2. (re-)submitting workflows to the system,

3. inspecting, manipulating or viewing a live working environment via

   command line arguments.

$ seisflows -h

Note

Almost every modules requires loading of other modules, i.e. to run any checks we must load the entire SeisFlows environment, which is slow but provides the most flexibility when accessing internal information

property _public_methods

Return a list of all public methods within this class.

Warning

Only methods that can be called via the command line should be public, all other methods and attributes should be private.

__call__(command=None, **kwargs)

When called, SeisFlows will execute one of its internal functions

Parameters

• command (str) – If not None, allows controlling this class from inside a Python environment. If sub-commands are required, these are inserted using the kwargs. Usually not required unless writing tests or scripting SF in Python

• return_self (bool) – if True, do not execute a command, which init usually does, but return the SeisFlows class itself. This is used just for testing purposes

Returns

setup(force=False, **kwargs)

Initiate a SeisFlows working directory from scratch by establishing a template parameter file.

Note

Future working directory setup functions can be placed here

Parameters

force (bool) – flag to force parameter file overwriting

configure(absolute_paths=False, **kwargs)

Dynamically generate the parameter file by writing out docstrings and default values for each of the SeisFlows module parameters. This function writes files manually, consistent with the .yaml format.

Note

This function relies on docstrings being formatted the same way throughout the package. Note the trailing ‘***’ character at the end of the docstring. This is required for configure to know where one docstring ends and another beings. The formatting looks like:

some description

type a

int

param a

parameter a

type path_a

str

param path_a

path for a

***

Parameters

absolute_paths (bool) – if True, expand pathnames to absolute paths, else if False, use path names relative to the working directory. Defaults to False, uses relative paths.

swap(module, classname, **kwargs)

Swap the parameters of an existing parameter file with a new module. Useful for changing out parameters without having to re-make a parameter file from scratch. e.g., to swap systems from a workstation to a cluster

TODO figure out how to match paths too

$ seisflows swap system slurm

check(**kwargs)

Run check() functions for a given parameter file and each of the SeisFlows modules, ensuring that parameters are acceptable for the given set of user-defined parameters

init(**kwargs)

Run check() + setup() functions for a given parameter file and each of the SeisFlows modules, ensuring that parameters are acceptable for the given set of user-defined parameters and running setup procedure which may create directories and perform some file management.

submit(**kwargs)

Main SeisFlows execution command. Submit the SeisFlows workflow to the chosen system, and execute seisflows.workflow.main(). Will create the working directory and any required paths and ensure that all required paths exist.

clean(force=False, **kwargs)

Clean the SeisFlows working directory except for the parameter file.

Parameters

force (bool) – ignore the warning check that precedes the clean() function, useful if you don’t want any input messages popping up

restart(force=False, **kwargs)

Restart simply means clean the workding dir and submit a new workflow.

debug(**kwargs)

Initiate an IPython debugging environment to explore the currently active SeisFlows environment. Reloads the system modules in an interactive environment allowing exploration of the package space. Does not allow stepping through of code (not a breakpoint).

sempar(parameter, value=None, skip_print=False, par_file='Par_file', **kwargs)

check or set parameters in the SPECFEM parameter file. By default assumes the SPECFEM parameter file is called ‘Par_file’ But this can be overwritten by using the ‘-p’ flag.

usage

seisflows sempar [parameter] [value]

to check the parameter ‘nproc’ from the command line:

seisflows sempar nstep

to set the parameter ‘model’ to ‘GLL’:

seisflows sempar model GLL

to check the values of a velocity model (SPECFEM2D)

seisflows sempar velocity_model

to edit the values of a velocity model (SPECFEM2D)

seisflows sempar velocity_model “1 1 2600.d0 5800.d0 3500.0d0 0 0 10.d0 10.d0 0 0 0 0 0 0”

OR for a two-layered model

seisflows sempar velocity_model “1 1 2600.d0 5800.d0 3500.0d0 0 0 10.d0 10.d0 0 0 0 0 0 0 + 1 1 2600.d0 5800.d0 3500.0d0 0 0 10.d0 10.d0 0 0 0 0 0 0”

Note

For multi-layered models, the delimiter ” + ” is important, you must have the whitespace on either side else the function won’t recognize these are separate layers.

Parameters

• parameter (str) – parameter to check in parameter file. case insensitive

• value (str) – value to set for parameter. if none, will simply print out the current parameter value. to set as nonetype, set to ‘null’ SPECFEM2D: if set to ‘velocity_model’ allows the user to set and edit the velocity model defined in the SPECMFE2D Par_file. Not a very smart capability, likely easier to do this manually.

• par_file (str) – name of the SPECFEM parameter file, defaults: Par_file

• skip_print (bool) – skip the print statement which is typically sent to stdout after changing parameters.

par(parameter, value=None, skip_print=False, **kwargs)

Check or set parameters in the seisflows parameter file.

USAGE

seisflows par [parameter] [value]

to check the parameter ‘NPROC’ from the command line:

seisflows par nproc

to set the parameter ‘BEGIN’ to 2:

seisflows par begin 2

to change the scratch path to the current working directory, don’t print to stdout:

seisflows par scratch ./ -p

Parameters

• parameter (str) – parameter to check in parameter file. case insensitive

• value (str) – value to set for parameter. if None, will simply print out the current parameter value. to set as nonetype, set to ‘null’

• skip_print (bool) – skip the print statement which is typically sent to stdout after changing parameters.

examples(method=None, choice=None, **kwargs)

List or run a SeisFlows example problems

USAGE

seisflows examples [run] [choice]

To list available examples:

seisflows examples

To run a specific example (this is the same as ‘python example.py’)

seisflows examples run 1

Parameters

• method (bool) – if True, run an example of choice choice

• choice (str) – The choice of example, must match the given tag or file name that is assigned to it

static _print_examples()

Simply print a list of available examples which match the format ex_?*.py

print(choice=None, **kwargs)

Print information relating to an active SeisFlows environment. Type ‘seisflows check –help’ for a detailed help message.

Parameters

choice (str) – underlying sub-function to choose

plotst(fids, data_format='ASCII', savefig=None, **kwargs)

Simple stream/waveform plotter to visualize synthetic waveforms created by the solver. Uses ObsPy under the hood to generate a large stream and then plots all waveforms together.

Note

Very simple function to look at waveforms. If you want more sophisticated plotting tools, look at Python packages Pyatoa or PySEP

Parameters

• fids (list) – list of file ID’s to plot

• data_format (str) – data format used to determine how to read data files

• savefig (str or None) – full path and filename to save the output figure. If NoneType, will not save the figure

plot2d(name=None, parameter=None, cmap=None, savefig=None, **kwargs)

Plot model, gradient or kernels in the PATH.OUTPUT

Parameters

• name (str) – Name of directory in the output/ directory

• parameter (str) – Name of parameter to plot from name, e.g., ‘vs’, ‘vp’ etc.

• cmap (str) – optional colormap parameter to be passed to Pyplot

• savefig (str) – optional name and path of filename to save figure to disk

reset(choice=None, **kwargs)

Mid-level function to wrap lower level reset functions

TODO re-write ‘_reset_line_search’

_inspect_class_that_defined_method(name, func, **kwargs)

Given a function name and generalized module (e.g. solver), inspect which of the subclasses actually defined the function. Makes it easier to debug/edit source code as the user can quickly determine where in the source code they need to look to find the corresponding function.

https://stackoverflow.com/questions/961048/get-class-that-defined-method

Parameters

• name (str) – SeisFlows module name

• func (str) – Corresponding method/function name for the given module

_inspect_module_hierarchy(name=None, **kwargs)

Determine the order of class hierarchy for a given SeisFlows module.

https://stackoverflow.com/questions/1401661/

list-all-base-classes-in-a-hierarchy-of-given-class

$ seisflows print inherit

Parameters

name (str) – choice of module, if None, will print hierarchies for all modules.

_print_modules(package=None, **kwargs)

Print out available modules in the SeisFlows name space for all available packages and modules.

$ seisflows print module

Parameters

• name (str) – specify an specific module name to list

• package (str) – specify an indivdual package to search

_print_tasks(**kwargs)

Simply print out the seisflows.workflow.main() flow variable which describes what order workflow functions will be run. Useful for filling out the RESUME_FROM and STOP_AFTER parameters.

$ seisflows print flow

_print_inheritance(name=None, func=None, **kwargs)

Inspect inheritance hierarchy of classes, methods defined by SeisFlows. Useful when developing or debugging, facilitates identification of the package top-level.

USAGE

seisflows inspect [name] [method]

To view overall hierarchy for all names in the SeisFlows namespace

seisflows inspect

To check the inheritance hierarchy of the ‘workflow’ module

seisflows inspect workflow

To check which class defined a given method, e.g. the ‘eval_func’ method attributed to the solver module

seisflows inspect solver eval_func

seisflows.seisflows.return_modules()

Search for the names of available modules in SeisFlows name space. This simple function checks for files with a ‘.py’ extension inside each of the sub-directories, ignoring private files like __init__.py.

Return type

dict of dict of lists

Returns

a dict with keys matching names and values as dicts for each package. nested list contains all the avaialble modules

seisflows.seisflows.main()

Main entry point into the SeisFlows package is via the SeisFlows class