Getting Started
================

Learn how to run an example, understand its outputs, and manipulate SeisFlows
for your own research problems.

Running an example problem
~~~~~~~~~~~~~~~~~~~~~~~~~~~

SeisFlows can be run on your laptop alongside
`SPECFEM2D <https://geodynamics.org/cig/software/specfem2d/>`__. There are a
number of `2D example problems <specfem2D_example.html>`__ including toy
simulation and inversion problems.

The following code block executes Example Problem 1, a synthetic homogeneous
halfspace inversion. This example:

- automatically downloads and compiles SPECFEM2D,
- sets up starting and target homogeneous halfspace models,
- runs a 1 iteration inversion.

.. code:: bash

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

Interested in what's happening under the hood? See the
`example walkthrough <2D_example_walkthrough.html>`__ for a step-by-step
explanation of problem setup and execution.

Understanding SeisFlows
~~~~~~~~~~~~~~~~~~~~~~~

A User's interaction with SeisFlows will have the same structure, whether they're
running a 2D laptop problem, or a 3D HPC problem. The following Docs pages can
help you understand the key components of SeisFlows,

* `Command line tool <command_line_tool.html>`__: Learn to operate SeisFlows
  from the terminal
* `Working directory <working_directory.html>`__: Understand the structure of
  generated by a SeisFlows workflow
* `Parameter file <parameter_file.html>`__: Figure out how to decipher
  the SeisFlows YAML parameter file
* `Setting up on a cluster <cluster_start_here.html>`__: Follow along on
  setting up SeisFlows on your HPC system
* `Background <background.html>`__: Learn about how the SeisFlows source code
  is structured
* `Extend the package <extending.html>`__: Become a SeisFlows contributor
* `API <autoapi/index.html>`__: Source code reference manual



Training Material
~~~~~~~~~~~~~~~~~

- **New to SPECFEM?** We hosted a 3-day virtual workshop for new users of
  SPECFEM in October, 2022. You can
  `view all the recordings and workshop material here
  <https://sites.google.com/alaska.edu/carltape/home/research/
  specfem2022?authuser=0>`__.

- `adjDocs <https://github.com/adjtomo/adjdocs>`__ houses training material
  related to SeisFlows, the adjTomo software suite, and SPECFEM. Have a look
  there for any related training or presentation material.


Running tests
~~~~~~~~~~~~~

SeisFlows has some unit/integration tests that ensure the capabilities of
the package are working as intended. Tests should be run before and after any
edits to the source code are made. To run the tests, from the top level
`seisflows` directory:

.. code:: bash

    cd seisflows/tests
    pytest

If developing SeisFlows, please ensure that you run these tests before and after
any changes are made to ensure that your changes do not break intended package
functionality.