### main

Source: https://seisflows.readthedocs.io/en/latest/_sources/autoapi/seisflows/examples/sfexample2d/index.rst.txt

Setup the example and then optionally run the actual seisflows workflow.

```APIDOC
## main()

### Description
Setup the example and then optionally run the actual seisflows workflow.

### Method
Python function call

### Parameters
None
```

--------------------------------

### Setup and Submit SPECFEM2D Example

Source: https://seisflows.readthedocs.io/en/latest/_sources/specfem2d_example.rst.txt

Sets up a SPECFEM2D example and submits it for execution. Use this to start a basic inversion workflow.

```bash
# Run command with open variable to set SPECFEM2D path
seisflows examples setup 1 -r ${PATH_TO_SPECFEM2D}
seisflows submit

# The following command is the same as above
seisflows examples run 1 --specfem2d_repo ${PATH_TO_SPECFEM2D}
```

--------------------------------

### Setup SPECFEM2D Example

Source: https://seisflows.readthedocs.io/en/latest/_sources/cluster_setup.rst.txt

Set up a 2D SPECFEM2D example on the cluster, generating a parameter file and working directory.

```bash
cd <path to working directory>  # empty directory
```

```bash
seisflows examples setup 2 -r <path to specfem2d repository>
```

--------------------------------

### Setup and Submit SPECFEM2D Example

Source: https://seisflows.readthedocs.io/en/latest/specfem2d_example.html

Use these commands to set up and submit a SPECFEM2D example. The `-r` flag points to an existing SPECFEM2D repository. If not provided, SeisFlows will download and compile SPECFEM2D.

```bash
seisflows examples setup 1 -r ${PATH_TO_SPECFEM2D}
seisflows submit
```

```bash
seisflows examples run 1 --specfem2d_repo ${PATH_TO_SPECFEM2D}
```

--------------------------------

### Run SeisFlows Example 1

Source: https://seisflows.readthedocs.io/en/latest/autoapi/seisflows/examples/ex1_homogeneous_halfspace/index.html

Execute Example 1 of SeisFlows from the command line. This command initiates the entire workflow, including SPECFEM2D setup and the inversion process.

```bash
seisflows examples run 1
```

--------------------------------

### Navigate Example Directory

Source: https://seisflows.readthedocs.io/en/latest/specfem2d_example.html

Change directory to the example and list its contents to understand the file structure.

```bash
cd ~/sfexamples/example_3
ls
```

```text
/home/bchow/Work/work/seisflows_example/example_3
logs        parameters.yaml  sflog.txt    specfem2d
output      scratch          sfstate.txt  specfem2d_workdir
```

--------------------------------

### Setup SPECFEM2D Working Directory

Source: https://seisflows.readthedocs.io/en/latest/_sources/2D_example_walkthrough.rst.txt

Creates a new SPECFEM2D working directory, copies essential binaries and the DATA directory from the Tape2007 example. This ensures the original repository is not modified and prepares the environment for running SPECFEM2D.

```bash
# Incase we've run this docs page before, delete the working directory before remaking
if os.path.exists(SPECFEM2D_WORKDIR):
    shutil.rmtree(SPECFEM2D_WORKDIR)

os.mkdir(SPECFEM2D_WORKDIR)
os.chdir(SPECFEM2D_WORKDIR)

# Copy the binary files incase we update the source code. These can also be symlinked.
shutil.copytree(SPECFEM2D_BIN_ORIGINAL, "bin")

# Copy the DATA/ directory because we will be making edits here frequently and it's useful to
# retain the original files for reference. We will be running one of the example problems: Tape2007
shutil.copytree(os.path.join(TAPE_2007_EXAMPLE, "DATA"), "DATA")

pwd
lS
```

--------------------------------

### Display Example 2 Help Message

Source: https://seisflows.readthedocs.io/en/latest/specfem2d_example.html

Run this command to see a help message dialogue detailing what Example 2 will do. This is useful for understanding the scope and parameters of the example before execution.

```bash
# Run the help message dialogue to see what Example 2 will do
seisflows examples 2

```

--------------------------------

### Display Help for seisflows setup

Source: https://seisflows.readthedocs.io/en/latest/command_line_tool.html

View the help message for the `seisflows setup` command to understand its options and usage.

```bash
seisflows setup -h
```

--------------------------------

### List Files in SPECFEM2D Example Directory

Source: https://seisflows.readthedocs.io/en/latest/_sources/specfem2d_example.rst.txt

Navigates to the SPECFEM2D example directory and lists its contents. This is typically done after setting up an example to inspect the generated files.

```bash
cd ~/sfexamples/example_2a
ls
```

--------------------------------

### setup()

Source: https://seisflows.readthedocs.io/en/latest/_sources/autoapi/seisflows/optimize/LBFGS/index.rst.txt

Set up the LBFGS optimization schema.

```APIDOC
## setup()

### Description
Set up the LBFGS optimization schema.
```

--------------------------------

### Run Example 2 with SPECFEM2D Path (SPECFEM2D)

Source: https://seisflows.readthedocs.io/en/latest/_sources/specfem2d_example.rst.txt

Executes Example 2, which involves a checkerboard inversion using Pyaflowa and L-BFGS. Requires specifying the path to your SPECFEM2D installation.

```bash
seisflows examples run 2 -r ${PATH_TO_SPECFEM2D}
```

--------------------------------

### Run SPECFEM2D Checkerboard Inversion Example

Source: https://seisflows.readthedocs.io/en/latest/specfem2d_example.html

Execute Example 2 of SPECFEM2D. Users must provide a path to their SPECFEM2D installation using the -r flag. This command initiates the inversion workflow.

```bash
seisflows examples run 2 -r ${PATH_TO_SPECFEM2D}

```

--------------------------------

### Display help for Example 3

Source: https://seisflows.readthedocs.io/en/latest/specfem2d_example.html

Shows the help dialogue for Example 3, detailing its purpose and steps.

```bash
# Run the help dialogue to see what occurs in Example 3
seisflows examples 3

```

```text
No existing SPECFEM2D repo given, default to: /home/bchow/Work/work/seisflows_example/example_2/specfem2d

                                    @@@@@@@@@@
                               .@@@@    .%&(
                            @@@@   @@@@   &@@@@@@ ,%@
                         @@@@   @@@,  /@@              @
                        @@@   @@@@   @@@              @
                      @@@@   @@@@   @@@                @  @
                      @@@   @@@@   ,@@@                @ @
                     @@@@   @@@@    @@@@              @@ @ @
                     @@@@   @@@@@    @@@@@          @@@ @@ @
                     @@@@    @@@@@     @@@@@@@@@@@@@@  @@  @
                      @@@@    @@@@@@        @@@&     @@@  @
                      @@@@@     @@@@@@@@         %@@@@#  @@
                        @@@@#      @@@@@@@@@@@@@@@@@   @@
                         &@@@@@          @@@@(       @@&
                            @@@@@@@             /@@@@
                                @@@@@@@@@@@@@@@@@
                                    @@@@@@@@@@


================================================================================
                              SEISFLOWS EXAMPLE 3
                              ///////////////////
This is a [SPECFEM2D] [WORKSTATION] example, which will run forward simulations
to generate synthetic seismograms through a homogeneous halfspace starting
model. This example uses no preprocessing or optimization modules. [10 events,
25 stations] The tasks involved include:

1. (optional) Download, configure, compile SPECFEM2D
2. [Setup] a SPECFEM2D working directory
3. [Setup] starting model from 'Tape2007' example
4. [Setup] a SeisFlows working directory
5. [Run] the forward simulation workflow
================================================================================

```

--------------------------------

### Execute SPECFEM2D Example 3 with Path

Source: https://seisflows.readthedocs.io/en/latest/_sources/specfem2d_example.rst.txt

Run SPECFEM2D Example 3, specifying the path to your SPECFEM2D installation using an environment variable. This command initiates the forward simulation workflow.

```bash
# Run command with open variable to set SPECFEM2D path
seisflows examples run 3 -r ${PATH_TO_SPECFEM2D}
```

--------------------------------

### Run SeisFlows Examples

Source: https://seisflows.readthedocs.io/en/latest/autoapi/seisflows/seisflows/index.html

Use the 'examples' command to list or run SeisFlows example problems. Specify 'run' and a choice to execute a specific example.

```bash
seisflows examples
seisflows examples run 1
```

--------------------------------

### Print Specfem2D Example Help

Source: https://seisflows.readthedocs.io/en/latest/_sources/specfem2d_example.rst.txt

Use this command to print the help dialogue for a specific Specfem2D example. This is useful for understanding the parameters and options available for running the example.

```bash
seisflows examples 1  # print example help dialogue
```

--------------------------------

### List SPECFEM2D Example Files

Source: https://seisflows.readthedocs.io/en/latest/_sources/specfem2d_example.rst.txt

Navigate to the example directory and list its contents to see generated files such as logs, parameters, and output directories.

```bash
cd ~/sfexamples/example_2
ls
```

--------------------------------

### Navigate to Example Directory

Source: https://seisflows.readthedocs.io/en/latest/_sources/specfem2d_example.rst.txt

Changes the current directory to the SPECFEM2D example's working directory. Use this to inspect output files.

```bash
cd ~/sfexamples/example_1
ls
```

--------------------------------

### setup()

Source: https://seisflows.readthedocs.io/en/latest/_sources/autoapi/seisflows/preprocess/default/index.rst.txt

Sets up the data preprocessing machinery.

```APIDOC
## setup()

### Description
Initializes and configures the data preprocessing components.

### Method
`setup()`
```

--------------------------------

### View Example 2 Help Message (SPECFEM2D)

Source: https://seisflows.readthedocs.io/en/latest/_sources/specfem2d_example.rst.txt

Displays the help message for Example 2, outlining its configuration and workflow. This is useful for understanding the example before running it.

```bash
seisflows examples 2
```

--------------------------------

### Setup Seisflows Workflow

Source: https://seisflows.readthedocs.io/en/latest/_sources/autoapi/seisflows/seisflows/index.rst.txt

Runs check() and setup() functions for a parameter file and modules, ensuring parameters are acceptable and performing setup procedures like directory creation and file management.

```bash
seisflows setup(**kwargs)
```

--------------------------------

### setup()

Source: https://seisflows.readthedocs.io/en/latest/autoapi/seisflows/workflow/inversion/index.html

Initializes the inversion workflow by assigning modules and setting up sub-modules, synthetic data, and database files.

```APIDOC
## setup()

Assigns modules as attributes of the workflow. I.e., self.solver to access the solver module (or workflow.solver from outside class)
Lays groundwork for inversion by running setup() functions for the involved sub-modules, generating True model synthetic data if necessary, and generating the pre-requisite database files.
```

--------------------------------

### Print Example Help Dialogue

Source: https://seisflows.readthedocs.io/en/latest/specfem2d_example.html

Prints the help dialogue for SeisFlows example 1. This command is used to understand the parameters and options available for the example.

```bash
seisflows examples 1  # print example help dialogue

```

--------------------------------

### View SPECFEM2D Example Help

Source: https://seisflows.readthedocs.io/en/latest/_sources/specfem2d_example.rst.txt

Displays the help message for running SPECFEM2D examples, including descriptions of optional arguments like --event_id. Use this to understand available parameters for example runs.

```bash
# Run the help message to view the description of the optional arguemnt --event_id
seisflows examples -h
```

--------------------------------

### List available files in example directory

Source: https://seisflows.readthedocs.io/en/latest/specfem2d_example.html

Use the `ls` command to view the contents of the example directory. This helps in identifying generated files and directories.

```bash
cd ~/sfexamples/example_2
ls

```

```text
/home/bchow/Work/work/seisflows_example/example_2
logs        parameters.yaml  sflog.txt    specfem2d
output      scratch          sfstate.txt  specfem2d_workdir

```

--------------------------------

### Specfem2D Workstation Example 1: Homogenous Halfspace Inversion

Source: https://seisflows.readthedocs.io/en/latest/specfem2d_example.html

This example runs a synthetic inversion with 1 event and 1 station over 1 iteration. It assesses the misfit between two homogenous halfspace models with slightly different velocities. The process includes optional SPECFEM2D compilation, setup of working directories, model preparation, and running the inversion workflow.

```bash
No existing SPECFEM2D repo given, default to: /home/bchow/REPOSITORIES/seisflows/docs/notebooks/specfem2d

                                    @@@@@@@@@@
                               .@@@@    .%&(
                            @@@@   @@@@   &@@@@@@ ,%@
                         @@@@   @@@,  /@@              @
                        @@@   @@@@   @@@              @
                      @@@@   @@@@   @@@                @  @
                      @@@   @@@@   ,@@@                @ @
                     @@@@   @@@@    @@@@              @@ @ @
                     @@@@   @@@@@    @@@@@          @@@ @@ @
                     @@@@    @@@@@     @@@@@@@@@@@@@@  @@  @
                      @@@@    @@@@@@        @@@&     @@@  @
                      @@@@@     @@@@@@@@         %@@@@#  @@
                        @@@@#      @@@@@@@@@@@@@@@@@   @@
                         &@@@@@          @@@@(       @@&
                            @@@@@@@             /@@@@
                                @@@@@@@@@@@@@@@@@
                                    @@@@@@@@@@


================================================================================
                              SEISFLOWS EXAMPLE 1
                              ///////////////////
This is a [SPECFEM2D] [WORKSTATION] example, which will run an inversion to
assess misfit between two homogeneous halfspace models with slightly different
velocities. [1 events, 1 station, 1 iterations]. The tasks involved include:

1. (optional) Download, configure, compile SPECFEM2D
2. [Setup] a SPECFEM2D working directory
3. [Setup] starting model from 'Tape2007' example
4. [Setup] target model w/ perturbed starting model
5. [Setup] a SeisFlows working directory
6. [Run] the inversion workflow
================================================================================

```

--------------------------------

### Run SeisFlows Example from Command Line

Source: https://seisflows.readthedocs.io/en/latest/_sources/containers.rst.txt

Executes a SeisFlows-Pyatoa-Specfem2D example from the command line. It sets a working directory, mounts it into the container, and runs the example, saving outputs to the local filesystem.

```bash
WORKDIR=/Users/Chow/Work/scratch  # choose your own directory here
cd ${WORKDIR}
docker run \
    --workdir $(pwd) \
    --mount type=bind,source=$(pwd),target=$(pwd),
    ghcr.io/seisscoped/adjtomo:nightly \
    seisflows examples run 2
```

--------------------------------

### Navigate to Example Directory

Source: https://seisflows.readthedocs.io/en/latest/_sources/command_line_tool.rst.txt

Changes the current directory to an example problem directory (`~/sfexamples/example_2`) to prepare for plotting operations.

```bash
# a directory where we have run an example problem
cd ~/sfexamples/example_2
ls
```

--------------------------------

### Navigate and List Example 3 Files

Source: https://seisflows.readthedocs.io/en/latest/_sources/specfem2d_example.rst.txt

Change directory to the SeisFlows example directory and list its contents to inspect the generated files. This is useful for understanding the output structure.

```bash
cd ~/sfexamples/example_3
ls
```

--------------------------------

### Run SeisFlows Example with Custom Parameters

Source: https://seisflows.readthedocs.io/en/latest/specfem2d_example.html

An example command to run a SeisFlows example with a specified number of stations, tasks (events), and iterations. Useful for testing or scaling inversions.

```bash
# An example call for running Example 1 with variable number of stations, events and iterations
seisflows examples run 1 --nsta 10 --ntask 5 --niter 2
```

--------------------------------

### seisflows.setup

Source: https://seisflows.readthedocs.io/en/latest/_sources/autoapi/seisflows/seisflows/index.rst.txt

Runs check() and setup() functions for a given parameter file and SeisFlows modules, ensuring parameter acceptability and performing setup procedures like directory creation.

```APIDOC
## seisflows.setup

### Description
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.

### Parameters
- **kwargs** - Additional keyword arguments.
```

--------------------------------

### run_sf_example

Source: https://seisflows.readthedocs.io/en/latest/_sources/autoapi/seisflows/examples/sfexample2d/index.rst.txt

Use subprocess to run the SeisFlows example we just set up.

```APIDOC
## run_sf_example()

### Description
Use subprocess to run the SeisFlows example we just set up.

### Method
Python function call

### Parameters
None
```

--------------------------------

### SeisFlows Inversion Workflow Log (Text)

Source: https://seisflows.readthedocs.io/en/latest/2D_example_walkthrough.html

Example log output from a SeisFlows inversion, showing setup, iteration, and line search progress.

```text
2022-08-16 14:41:12 (D) | setting iteration==1 from state file
2022-08-16 14:41:12 (I) |
================================================================================
                         SETTING UP INVERSION WORKFLOW
================================================================================
2022-08-16 14:41:18 (D) | running setup for module 'system.Workstation'
2022-08-16 14:41:21 (D) | copying par/log file to: /home/bchow/Work/scratch/logs/sflog_003.txt
2022-08-16 14:41:21 (D) | copying par/log file to: /home/bchow/Work/scratch/logs/parameters_003.yaml
2022-08-16 14:41:21 (D) | running setup for module 'solver.Specfem2D'
2022-08-16 14:41:21 (I) | initializing 3 solver directories
2022-08-16 14:41:22 (D) | running setup for module 'preprocess.Default'
2022-08-16 14:41:24 (D) | running setup for module 'optimize.Gradient'
2022-08-16 14:41:26 (I) | re-loading optimization module from checkpoint
2022-08-16 14:41:28 (I) | re-loading optimization module from checkpoint
2022-08-16 14:41:28 (I) |
////////////////////////////////////////////////////////////////////////////////
                              RUNNING ITERATION 01
////////////////////////////////////////////////////////////////////////////////
2022-08-16 14:41:28 (I) |
================================================================================
                           RUNNING INVERSION WORKFLOW
================================================================================
2022-08-16 14:41:28 (I) | 'evaluate_initial_misfit' has already been run, skipping
2022-08-16 14:41:28 (I) | 'run_adjoint_simulations' has already been run, skipping
2022-08-16 14:41:28 (I) | 'postprocess_event_kernels' has already been run, skipping
2022-08-16 14:41:28 (I) | 'evaluate_gradient_from_kernels' has already been run, skipping
2022-08-16 14:41:28 (I) | initializing 'bracket'ing line search
2022-08-16 14:41:28 (I) | enforcing max step length safeguard
2022-08-16 14:41:28 (D) | step length(s) = 0.00E+00
2022-08-16 14:41:28 (D) | misfit val(s)  = 1.28E-03
2022-08-16 14:41:28 (I) | try: first evaluation, attempt guess step length, alpha=9.08E+11
2022-08-16 14:41:28 (I) | try: applying initial step length safegaurd as alpha has exceeded maximum step length, alpha_new=1.44E+10
2022-08-16 14:41:28 (D) | overwriting initial step length, alpha_new=2.32E+09
2022-08-16 14:41:28 (I) | trial model 'm_try' parameters:
2022-08-16 14:41:28 (I) | 5800.00 <= vp <= 5800.00
2022-08-16 14:41:28 (I) | 3244.51 <= vs <= 3790.00
2022-08-16 14:41:29 (I) |
LINE SEARCH STEP COUNT 01
--------------------------------------------------------------------------------
2022-08-16 14:41:29 (I) | evaluating objective function for source 001
2022-08-16 14:41:29 (D) | running forward simulation with 'Specfem2D'
2022-08-16 14:41:33 (D) | quantifying misfit with 'Default'
2022-08-16 14:41:33 (I) | evaluating objective function for source 002
2022-08-16 14:41:33 (D) | running forward simulation with 'Specfem2D'
2022-08-16 14:41:36 (D) | quantifying misfit with 'Default'
2022-08-16 14:41:36 (I) | evaluating objective function for source 003

```

--------------------------------

### Run Example 1 with Custom Parameters (SPECFEM2D)

Source: https://seisflows.readthedocs.io/en/latest/_sources/specfem2d_example.rst.txt

Runs Example 1 with a specified number of stations, tasks, and iterations. Useful for scaling tests or specific workflow configurations.

```bash
seisflows examples run 1 --nsta 10 --ntask 5 --niter 2
```

--------------------------------

### List Files in Example Working Directory

Source: https://seisflows.readthedocs.io/en/latest/_sources/specfem2d_example.rst.txt

Lists the files and directories within the SPECFEM2D example's working directory. Shows logs, parameters, and solver files.

```bash
/home/bchow/Work/work/seisflows_example/example_1
logs	parameters.yaml  sflog.txt    specfem2d
output	scratch		sfstate.txt  specfem2d_workdir
```

--------------------------------

### Run SPECFEM2D Example 3

Source: https://seisflows.readthedocs.io/en/latest/_sources/specfem2d_example.rst.txt

Execute the help dialogue for Example 3 to understand its functionality. This command initiates the process of running a SPECFEM2D forward simulation.

```bash
# Run the help dialogue to see what occurs in Example 3
seisflows examples 3
```

--------------------------------

### seisflows examples

Source: https://seisflows.readthedocs.io/en/latest/_sources/autoapi/seisflows/seisflows/index.rst.txt

List or run SeisFlows example problems. Users can list available examples or run a specific one by providing its identifier.

```APIDOC
## seisflows examples

### Description
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
#### Path Parameters
- **method** (bool) - Optional - if True, run an example of choice `choice`
- **choice** (str) - Optional - The choice of example, must match the given tag or file name that is assigned to it
```

--------------------------------

### Run Example 3 forward simulations

Source: https://seisflows.readthedocs.io/en/latest/specfem2d_example.html

Executes the forward simulation workflow for Example 3, requiring the SPECFEM2D path to be set.

```bash
# Run command with open variable to set SPECFEM2D path
seisflows examples run 3 -r ${PATH_TO_SPECFEM2D}

```

--------------------------------

### Example SeisFlows State File Content

Source: https://seisflows.readthedocs.io/en/latest/_sources/working_directory.rst.txt

This is an example of the sfstate.txt file, showing completed tasks and the current iteration for an inversion workflow.

```text
# SeisFlows State File
# Tue Aug 16 14:33:17 2022
# Acceptable states: 'completed', 'failed'
# =======================================
evaluate_initial_misfit: completed
run_adjoint_simulations: completed
postprocess_event_kernels: completed
evaluate_gradient_from_kernels: completed
initialize_line_search: completed
perform_line_search: completed
iteration: 1
```

--------------------------------

### Run Example Problem 1

Source: https://seisflows.readthedocs.io/en/latest/getting_started.html

Executes Example Problem 1, a synthetic homogeneous halfspace inversion. This includes downloading and compiling SPECFEM2D, setting up models, and running a single iteration inversion.

```bash
cd <PATH_TO_WORKING_DIRECTORY>  # choose an empty working directory
seisflows examples run 1

```

--------------------------------

### Run SPECFEM2D Example with Custom Parameters

Source: https://seisflows.readthedocs.io/en/latest/_sources/specfem2d_example.rst.txt

This command runs a specific SPECFEM2D example (example 2) with custom parameters. It allows setting the SPECFEM2D repository path, choosing a specific event ID, and limiting the number of iterations.

```bash
seisflows examples run 2 -r ${PATH_TO_SPECFEM2D} --event_id 7 --niter 1
```

--------------------------------

### Run SPECFEM2D Example with MPI

Source: https://seisflows.readthedocs.io/en/latest/specfem2d_example.html

Execute the SPECFEM2D example using MPI. The `--with_mpi` flag enables MPI, and `--nproc` specifies the number of processors. This example runs with 4 cores.

```bash
seisflows examples run 1 -r ${PATH_TO_SPECFEM2D} --with_mpi --nproc 4
```

--------------------------------

### Setup SeisFlows working directory

Source: https://seisflows.readthedocs.io/en/latest/_sources/2D_example_walkthrough.rst.txt

The 'seisflows setup -f' command initializes the SeisFlows working directory and creates the 'parameters.yaml' file. The '-f' flag ensures any existing 'parameters.yaml' is overwritten. Use 'os.chdir(WORKDIR)' to navigate to the correct directory first.

```bash
# The command 'setup' creates the 'parameters.yaml' file that controls all of SeisFlows
# the '-f' flag removes any exist 'parameters.yaml' file that might be in the directory
os.chdir(WORKDIR)
seisflows setup -f
ls
```

--------------------------------

### Run SeisFlows Example Problem 1

Source: https://seisflows.readthedocs.io/en/latest/_sources/getting_started.rst.txt

Executes a synthetic homogeneous halfspace inversion. This example automatically downloads and compiles SPECFEM2D, sets up models, and runs a single iteration inversion. Ensure you are in an empty working directory before running.

```bash
cd <PATH_TO_WORKING_DIRECTORY>  # choose an empty working directory
seisflows examples run 1
```

--------------------------------

### SPECFEM2D Example Command with Custom Parameters

Source: https://seisflows.readthedocs.io/en/latest/specfem2d_example.html

This command runs Example 2 with a specified SPECFEM2D path, selects event ID 7, and limits the run to 1 iteration. This is useful for replicating specific published results or testing configurations.

```bash
# Run command with open variable to set SPECFEM2D path. Choose event_id==7 and only run 1 iteration
seisflows examples run 2 -r ${PATH_TO_SPECFEM2D} --event_id 7 --niter 1

```

--------------------------------

### Example Source File Directory Structure

Source: https://seisflows.readthedocs.io/en/latest/_sources/noise_inversion.rst.txt

Demonstrates the expected directory structure for source files within the DATA directory.

```bash
     specfem_workdir/
     └── DATA/
         ├── Par_file
         ├── FORCESOLUTION_AA_A000
         ├── FORCESOLUTION_AA_A001
         ├── FORCESOLUTION_BB_B000
         └── ...
```

--------------------------------

### Run SeisFlows Example 3

Source: https://seisflows.readthedocs.io/en/latest/autoapi/seisflows/examples/ex3_fwd_solver/index.html

Command-line instruction to execute the third SeisFlows example, which involves forward simulations and misfit quantification.

```bash
seisflows examples run 3
```

--------------------------------

### Setup SeisFlows with Overwrite Flag

Source: https://seisflows.readthedocs.io/en/latest/command_line_tool.html

Initialize the SeisFlows parameter file using `seisflows setup`. The '-f' flag ensures that any existing parameter file is automatically overwritten.

```bash
# The '-f' flag (overwrite) will overwrite any existing parameter file
seisflows setup -f
```

--------------------------------

### setup()

Source: https://seisflows.readthedocs.io/en/latest/autoapi/seisflows/solver/specfem/index.html

Prepares solver scratch directories for an impending workflow. Sets up directory structure expected by SPECFEM and copies or generates seismic data to be inverted or migrated. Exports INIT/STARTING and TRUE/TARGET models to disk.

```APIDOC
## setup()

### Description
Prepares solver scratch directories for an impending workflow. Sets up directory structure expected by SPECFEM and copies or generates seismic data to be inverted or migrated. Exports INIT/STARTING and TRUE/TARGET models to disk (output/ dir.).

### Method
N/A (Function call)

### Endpoint
N/A
```

--------------------------------

### Example Parameter File Paths

Source: https://seisflows.readthedocs.io/en/latest/_sources/parameter_file.rst.txt

Illustrates typical file paths used within the SeisFlows configuration.

```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
```

--------------------------------

### Run Tape2007 Example and Verify Output

Source: https://seisflows.readthedocs.io/en/latest/_sources/2D_example_walkthrough.rst.txt

Executes the Tape2007 example script to confirm SPECFEM2D is functioning correctly. It checks for the existence of an output image file and displays the last lines of the output log.

```bash
# Run the Tape2007 example to make sure SPECFEM2D is working as expected
os.chdir(TAPE_2007_EXAMPLE)
./run_this_example.sh > output_log.txt

assert(os.path.exists("OUTPUT_FILES/forward_image000004800.jpg")),
    (f"Example did not run, the remainder of this docs page will likely not work."
     f"Please check the following directory: {TAPE_2007_EXAMPLE}")

tail output_log.txt
```

--------------------------------

### Run SeisFlows Example within JupyterHub Terminal

Source: https://seisflows.readthedocs.io/en/latest/_sources/containers.rst.txt

Commands to be executed inside the JupyterHub terminal after starting the container. It creates a directory, navigates into it, and runs a SeisFlows example.

```bash
# From inside the JupyterHub terminal
mkdir sf_sem2d_example
cd sf_sem2d_example
seisflows examples run 2
```

--------------------------------

### Example STATIONS file structure

Source: https://seisflows.readthedocs.io/en/latest/_sources/noise_inversion.rst.txt

Illustrates the expected format for the STATIONS file.

```text
  A000 AA 2.43610e+05 2.78904e+05 0.0 0.0
  A001 AA 3.38981e+05 1.77849e+05 0.0 0.0
  B000 BB 1.64438e+05 2.94733e+05 0.0 0.0
```

--------------------------------

### Setup SeisFlows for Noise Inversion

Source: https://seisflows.readthedocs.io/en/latest/noise_inversion.html

Initializes the SeisFlows environment for the noise inversion workflow and configures the system.

```bash
seisflows par workflow noise_inversion
seisflows configure

```

--------------------------------

### Example sfstate.txt Structure

Source: https://seisflows.readthedocs.io/en/latest/working_directory.html

An example of the sfstate.txt file format, showing workflow functions and their completion status. 'completed' indicates successful execution, while 'failed' would require re-running the task. The 'iteration' field is specific to inversion workflows.

```text
# SeisFlows State File
# Tue Aug 16 14:33:17 2022
# Acceptable states: 'completed', 'failed'
# =======================================
evaluate_initial_misfit: completed
run_adjoint_simulations: completed
postprocess_event_kernels: completed
evaluate_gradient_from_kernels: completed
initialize_line_search: completed
perform_line_search: completed
iteration: 1

```

--------------------------------

### Workflow Check and Setup

Source: https://seisflows.readthedocs.io/en/latest/_sources/autoapi/seisflows/workflow/forward/index.rst.txt

Methods to check for required modules and set up the workflow environment.

```APIDOC
## check()

### Description
Check that workflow has required modules. Run their respective checks

### Method
check
```

```APIDOC
## setup()

### Description
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.

### Method
setup
```

--------------------------------

### Specfem3D Check and Setup

Source: https://seisflows.readthedocs.io/en/latest/autoapi/seisflows/solver/specfem3d/index.html

Provides methods for performing SPECFEM3D-Cartesian specific checks and setting up initial/target models for visualization.

```python
check()
setup()
```

--------------------------------

### seisflows.tests.test_preprocess.test_pyaflowa_setup

Source: https://seisflows.readthedocs.io/en/latest/autoapi/seisflows/tests/test_preprocess/index.html

Tests the setup procedure for SeisFlows, internalizing workflow information.

```APIDOC
## Function: test_pyaflowa_setup(tmpdir)

### Description
Tests the setup procedure for SeisFlows, which internalizes workflow information crucial for subsequent tasks.

### Parameters
* **tmpdir** (string) - A temporary directory for setup operations.

### Returns
(Not specified in source)
```

--------------------------------

### setup()

Source: https://seisflows.readthedocs.io/en/latest/autoapi/seisflows/system/workstation/index.html

Prepares the Seisflows directory structure for a new workflow, creating necessary directories and log files without overwriting existing configurations.

```APIDOC
## setup()

### Description
Create the SeisFlows directory structure in preparation for a SeisFlows workflow. Ensure that if any config information is left over from a previous workflow, that these files are not overwritten by the new workflow. Should be called by submit().

Note: This function is expected to create dirs: SCRATCH, SYSTEM, OUTPUT and the following log files: output, error
Note: Logger is configured here as all workflows, independent of system, will be calling setup().

### Method
N/A (Function Call)

### Parameters
None

### Returns
- tuple of str: (path to output log, path to error log)
```

--------------------------------

### SeisFlows Workflow Execution Log

Source: https://seisflows.readthedocs.io/en/latest/2D_example_walkthrough.html

A log output from a SeisFlows inversion workflow, detailing the setup process, iteration start, and the execution of adjoint simulations for kernel generation. It shows module setup, file copying, and solver initialization.

```text
2022-08-16 14:36:42 (D) | setting iteration==1 from state file
2022-08-16 14:36:42 (I) |
================================================================================
                         SETTING UP INVERSION WORKFLOW
================================================================================
2022-08-16 14:36:48 (D) | running setup for module 'system.Workstation'
2022-08-16 14:36:51 (D) | copying par/log file to: /home/bchow/Work/scratch/logs/sflog_002.txt
2022-08-16 14:36:51 (D) | copying par/log file to: /home/bchow/Work/scratch/logs/parameters_002.yaml
2022-08-16 14:36:51 (D) | running setup for module 'solver.Specfem2D'
2022-08-16 14:36:51 (I) | initializing 3 solver directories
2022-08-16 14:36:51 (D) | running setup for module 'preprocess.Default'
2022-08-16 14:36:52 (D) | running setup for module 'optimize.Gradient'
2022-08-16 14:36:53 (I) | re-loading optimization module from checkpoint
2022-08-16 14:36:54 (I) | re-loading optimization module from checkpoint
2022-08-16 14:36:54 (I) |
////////////////////////////////////////////////////////////////////////////////
                              RUNNING ITERATION 01
////////////////////////////////////////////////////////////////////////////////
2022-08-16 14:36:54 (I) |
================================================================================
                           RUNNING INVERSION WORKFLOW
================================================================================
2022-08-16 14:36:54 (I) | 'evaluate_initial_misfit' has already been run, skipping
2022-08-16 14:36:54 (I) |
////////////////////////////////////////////////////////////////////////////////
                EVALUATING EVENT KERNELS W/ ADJOINT SIMULATIONS
////////////////////////////////////////////////////////////////////////////////
2022-08-16 14:36:54 (I) | running SPECFEM executable bin/xspecfem2D, log to 'adj_solver.log'
2022-08-16 14:37:05 (D) | renaming output event kernels: 'alpha' -> 'vp'
2022-08-16 14:37:05 (D) | renaming output event kernels: 'beta' -> 'vs'
2022-08-16 14:37:05 (I) | running SPECFEM executable bin/xspecfem2D, log to 'adj_solver.log'
2022-08-16 14:37:16 (D) | renaming output event kernels: 'alpha' -> 'vp'
2022-08-16 14:37:16 (D) | renaming output event kernels: 'beta' -> 'vs'
2022-08-16 14:37:18 (I) | running SPECFEM executable bin/xspecfem2D, log to 'adj_solver.log'
2022-08-16 14:37:29 (D) | renaming output event kernels: 'alpha' -> 'vp'
2022-08-16 14:37:29 (D) | renaming output event kernels: 'beta' -> 'vs'
2022-08-16 14:37:30 (I) |
////////////////////////////////////////////////////////////////////////////////
                      GENERATING/PROCESSING MISFIT KERNEL
////////////////////////////////////////////////////////////////////////////////
2022-08-16 14:37:30 (I) | combining event kernels into single misfit kernel
2022-08-16 14:37:31 (I) | scaling gradient to absolute model perturbations
2022-08-16 14:37:32 (I) | stop workflow at stop_after: evaluate_gradient_from_kernels

```

--------------------------------

### TestFlow Workflow Setup

Source: https://seisflows.readthedocs.io/en/latest/autoapi/seisflows/workflow/test_flow/index.html

Initializes the TestFlow workflow, setting up the working directory and output paths. It can optionally accept a list of modules to test.

```python
TestFlow(_modules=None, _workdir=os.getcwd(), _path_output=None, _**kwargs_)
```

--------------------------------

### setup()

Source: https://seisflows.readthedocs.io/en/latest/_sources/autoapi/seisflows/system/singularity/index.rst.txt

Copies 'submit' and 'run' .py scripts from the repository into the working directory. This allows users to run these scripts directly, enabling container execution without native environment commands.

```APIDOC
## setup()

### Description
Copies 'submit' and 'run' .py scripts from the repository into the working directory so that the User can run these scripts directly. This is a manual step in order to allow Users to run with a container without using native environment commands (e.g., sbatch) from inside a container.

### Method
```python
setup()
```
```

--------------------------------

### List Files and Count Lines in Parameter File

Source: https://seisflows.readthedocs.io/en/latest/command_line_tool.html

After setup, list the files in the directory and count the number of lines in the generated `parameters.yaml` file.

```bash
ls
wc -l parameters.yaml  # List the number of lines in the file
```

--------------------------------

### Basic Inheritance Example

Source: https://seisflows.readthedocs.io/en/latest/background.html

This snippet shows a simple class 'Super' that inherits all attributes from a 'Base' class without adding new functionality. It's a starting point for demonstrating inheritance.

```python
class Super(Base):
    """
    This Superclass will now inherit all of the attributes of the Baseclass.
    It does nothing new.
    """
    pass
```

```python
module = Super(example_integer=6, example_float=3.)
module.check()
print(module.manipulate())
```

```text
9.0
```

--------------------------------

### List Working Directory Contents

Source: https://seisflows.readthedocs.io/en/latest/specfem2d_example.html

This command lists the contents of the example's working directory, showing key subdirectories and files.

```bash
/home/bchow/Work/work/seisflows_example/example_1
logs        parameters.yaml  sflog.txt    specfem2d
output      scratch          sfstate.txt  specfem2d_workdir

```

--------------------------------

### Execute Submit Workflow Script

Source: https://seisflows.readthedocs.io/en/latest/_sources/autoapi/seisflows/system/runscripts/submit_workflow/index.rst.txt

Example of how to run the submit script from the command line with specified working directory and parameters file.

```bash
python submit -w ./ -p parameters.yaml
```

```bash
sbatch submit -w ./ -p parameters.yaml
```

--------------------------------

### L-BFGS Setup Method

Source: https://seisflows.readthedocs.io/en/latest/autoapi/seisflows/optimize/LBFGS/index.html

Initializes the LBFGS optimization schema. This method is called at the beginning of the optimization process.

```python
def setup(self):
    """Set up the LBFGS optimization schema"""
    super().setup()
```

--------------------------------

### Set up SPECFEM Working Directory

Source: https://seisflows.readthedocs.io/en/latest/running_on_chinook.html

Creates a clean working directory for SPECFEM, links executables, copies example data, and creates an output directory.

```bash
mkdir -p $CENTER/work/specfem3d_workdir  # clean working directory
cd $CENTER/work/specfem3d_workdir
ln -s $CENTER/REPOS/specfem3d/bin .
cp -r $CENTER/REPOS/specfem3d/EXAMPLES/homogeneous_halfspace/DATA .
cp -r $CENTER/REPOS/specfem3d/EXAMPLES/homogeneous_halfspace/meshfem3D_files ./DATA
mkdir OUTPUT_FILES
```

--------------------------------

### Example 3 completion message

Source: https://seisflows.readthedocs.io/en/latest/specfem2d_example.html

Confirms successful completion of the Example 3 workflow.

```text
================================================================================
EXAMPLE COMPLETED SUCCESFULLY
================================================================================

```

--------------------------------

### Setup SeisFlows Parameter File

Source: https://seisflows.readthedocs.io/en/latest/_sources/parameter_file.rst.txt

Initializes a template parameter file in the working directory. Use the --force flag to overwrite existing files.

```bash
seisflows setup -h
```

```bash
seisflows setup
```

--------------------------------

### Install Development Version of Seisflows

Source: https://seisflows.readthedocs.io/en/latest/_sources/CHANGELOG.md.txt

Use this command to install the development version of Seisflows, including development dependencies.

```bash
pip install -e .[dev]  # to install dev branches 
```

--------------------------------

### Setup TestFlow Workflow

Source: https://seisflows.readthedocs.io/en/latest/cluster_setup.html

Prepare a working directory and generate a template parameter file for the TestFlow workflow. This is the initial step before configuring system-specific parameters.

```bash
cd <path to working directory>  # empty directory on System

# Generate a template parameter file
seisflows setup -f

```

--------------------------------

### Successful Example Completion Log

Source: https://seisflows.readthedocs.io/en/latest/_sources/specfem2d_example.rst.txt

This log message indicates that the SPECFEM2D example, including forward simulations, has completed successfully.

```bash
================================================================================
EXAMPLE COMPLETED SUCCESFULLY
================================================================================
```

--------------------------------

### SPECFEM2D Example Completion Log

Source: https://seisflows.readthedocs.io/en/latest/_sources/specfem2d_example.rst.txt

Indicates a successfully completed SPECFEM2D example run. Look for these messages at the end of the log file.

```bash
CLEANING WORKDIR FOR NEXT ITERATION
--------------------------------------------------------------------------------
2022-08-29 15:51:05 (I) | thrifty inversion encountering first iteration, defaulting to standard inversion workflow
2022-08-29 15:51:06 (I) |
////////////////////////////////////////////////////////////////////////////////
                                 COMPLETE ITERATION 01                              
////////////////////////////////////////////////////////////////////////////////
2022-08-29 15:51:06 (I) | setting current iteration to: 2

================================================================================
EXAMPLE COMPLETED SUCCESFULLY
================================================================================
```

--------------------------------

### Adjoint Source File Content Example

Source: https://seisflows.readthedocs.io/en/latest/2D_example_walkthrough.html

Example content of an adjoint source file, showing two columns of numerical data.

```text
-48.0000000         0.0000000
-47.9400000         0.0000000
-47.8800000         0.0000000
-47.8200000         0.0000000
-47.7600000         0.0000000
-47.7000000         0.0000000
-47.6400000         0.0000000
-47.5800000         0.0000000
-47.5200000         0.0000000
-47.4600000         0.0000000
```

--------------------------------

### Singularity Setup Method

Source: https://seisflows.readthedocs.io/en/latest/autoapi/seisflows/system/singularity/index.html

Copies 'submit' and 'run' Python scripts into the working directory. This manual step allows users to execute these scripts directly, facilitating containerized workflows without relying on native environment commands like 'sbatch' from within the container.

```python
def setup():
    """
    Copies ‘submit’ and ‘run’ .py scripts from the repository into the working directory so that the User can run these scripts directly. This is a manual step in order to allow Users to run with a container without using native environment commands (e.g., sbatch) from inside a container.
    """
    pass
```

--------------------------------

### Setup SeisFlows Working Directory

Source: https://seisflows.readthedocs.io/en/latest/_sources/command_line_tool.rst.txt

Initialize a SeisFlows working directory by copying a template parameter file. Use the '-f' flag to force overwrite if a parameter file already exists.

```bash
cd ~/Scratch
rm *
l s
```

```bash
seisflows setup -h
```

```bash
# The '-f' flag (overwrite) will overwrite any existing parameter file
seisflows setup -f
```

--------------------------------

### Run SPECFEM2D Example with MPI

Source: https://seisflows.readthedocs.io/en/latest/_sources/specfem2d_example.rst.txt

Executes a SPECFEM2D example using MPI for parallel processing. Specify the number of processors with --nproc.

```bash
# Run Solver tasks with MPI on 4 cores
seisflows examples run 1 -r ${PATH_TO_SPECFEM2D} --with_mpi --nproc 4
```

--------------------------------

### Setup TestFlow Workflow

Source: https://seisflows.readthedocs.io/en/latest/_sources/cluster_setup.rst.txt

Prepare a working directory and configure SeisFlows for TestFlow, which verifies interaction with the workload manager by submitting small test jobs.

```bash
cd <path to working directory>  # empty directory on System
```

```bash
seisflows setup -f
```

```bash
seisflows par workflow test_flow
```

```bash
seisflows par system <name of your system>
```

```bash
seisflows par solver null
```

```bash
seisflows par preprocess null
```

```bash
seisflows par optimize null
```

```bash
seisflows configure
```

--------------------------------

### Parameter Error Example

Source: https://seisflows.readthedocs.io/en/latest/parameter_file.html

This is an example of a parameter error message that might be displayed. It indicates that `path_specfem_bin` must exist and point to the SPECFEM executables directory.

```text
================================================================================
                                PARAMETER ERRROR
                                ////////////////
path_specfem_bin must exist and must point to directory containing SPECFEM
executables
================================================================================

```

--------------------------------

### Install SeisFlows with Conda

Source: https://seisflows.readthedocs.io/en/latest/_sources/index.rst.txt

Installs SeisFlows and its dependencies into a new Conda environment. It is recommended to use a Conda environment to avoid conflicts with your root environment.

```bash
git clone https://github.com/adjtomo/seisflows.git
cd seisflows
conda env create -f environment.yml
conda activate seisflows
```

--------------------------------

### Run SPECFEM2D Example with Custom MPI Executable

Source: https://seisflows.readthedocs.io/en/latest/_sources/specfem2d_example.rst.txt

Runs a SPECFEM2D example with MPI, specifying a custom MPI executable. Useful if your system does not use 'mpirun'.

```bash
seisflows examples run 1 -r ${PATH_TO_SPECFEM2D} --with_mpi --nproc 4 --mpiexec srun
```

--------------------------------

### _setup_quantify_misfit()

Source: https://seisflows.readthedocs.io/en/latest/autoapi/seisflows/preprocess/pyaflowa/index.html

Gather a list of filenames of matching waveform IDs that can be run through the misfit quantification step, and generate empty adjoint sources so that Solver knows which components are zero’d out.

```APIDOC
## _setup_quantify_misfit(_source_name_ , _save_adjsrcs =None_, _components =None_)

### Description
Gather a list of filenames of matching waveform IDs that can be run through the misfit quantification step, and generate empty adjoint sources so that Solver knows which components are zero’d out.

### Method
Not applicable (function call)

### Parameters
#### Path Parameters
* **source_name** (str) - the name of the source to process
* **components** (list) - optional list of components to ignore preprocessing traces that do not have matching components. The adjoint sources for these components will be 0. E.g., [‘Z’, ‘N’]. If None, all available components will be considered.

### Return type
list of tuples

### Returns
[(observed filename, synthetic filename)]. tuples will contain filenames for matching stations + component for obs and syn
```

--------------------------------

### List Initial Model Files

Source: https://seisflows.readthedocs.io/en/latest/_sources/working_directory.rst.txt

Lists the files present in the 'output/MODEL_INIT' directory, which contains the initial model files.

```bash
ls output/MODEL_INIT
```

--------------------------------

### Parameter File Module Section Example

Source: https://seisflows.readthedocs.io/en/latest/_sources/parameter_file.rst.txt

This is an example of how a module section is structured within a SeisFlows parameter file. It includes a header with module description, parameter definitions, and a section for paths.

```bash
# =============================================================================
# MODULE
# ------
# Module description 
#
# Parameters
# ----------
# :type parameter: type
# :param paramter: description
# ...
# =============================================================================
parameter: value
```