<jupyter_start><jupyter_text>Parameter FileThe parameter file is the central control object for a SeisFlows3 workflow. Here we take a look at the anatomy of a parameter file. Parameter files in SeisFlows3 are formatted in the [YAML format (YAML Ain't Markup Language)](https://pyyaml.org/wiki/PyYAMLDocumentation). TemplateEach workflow starts with the module-only template parameter file which defines the core modules which make up the package. Running `seisflows setup` from the command line will create this file.<jupyter_code>! seisflows setup
! cat parameters.yaml<jupyter_output># //////////////////////////////////////////////////////////////////////////////
#
#                        SeisFlows3 YAML Parameter File
#
# //////////////////////////////////////////////////////////////////////////////
#
# Modules correspond to the structure of the source code, and determine
# SeisFlows3' 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 method for running SeisFlows3; equivalent to main()
# SOLVER (str):      External numerical solver to use for waveform simulations
# SYSTEM (str):      Computer architecture of th[...]<jupyter_text>How do I choose my modules?As seen above, each of the modules comes with a default value. But you may want to run a migration, not an inversion. Or run with SPECFEM3D not 2D. As stated in the comments at the top of the file, the `seisflows print modules` command lists out all available options. Don't see an option that works for you? Learn to extend the SeisFlows3 package here: **!!! docs page link here !!!**<jupyter_code>! seisflows print modules<jupyter_output>SEISFLOWS3 MODULES                               
                               //////////////////                               
'+': package, '-': module, '*': class

+ SYSTEM
    - seisflows3
        * base
        * cluster
        * lsf
        * slurm
        * workstation
    - seisflows3-super
        * chinook
        * maui
+ PREPROCESS
    - seisflows3
        * base
        * pyatoa
    - seisflows3-super
        * pyatoa_nz
+ SOLVER
    - seisflows3
        * base
        * specfem2d
        * specfem3d
        * specfem3d_globe
    - seisflows3-super
        * specfem3d_maui
+ POSTPROCESS
    - seisflows3
        * base
    - seisflows3-super
+ OPTIMIZE
    - seisflows3
        * LBFGS
        * NLCG
        * base
    - seisflows3-super
+ WORKFLOW
    - seisflows3
        * base
        * inversion
        * migration
        * test
    - seisflows3-super
        * thrifty_inversion
        * t[...]<jupyter_text>How do I change modules?Feel free to use any old text editor to edit the YAML file, or you can use the `seisflows par` command to make changes directly from the command line. For example, say we want to use SPECFEM3D<jupyter_code># Changes the current parameter to the given value
! seisflows par solver specfem3d
# Prints out the current parameter value
! seisflows par solver<jupyter_output>SOLVER: specfem3d<jupyter_text>How do I get to a full parameter file?The module-only parameter file serves as as a template for dynamically generating a full parameter file. Since each module requires it's own unique set of parameters and paths, each parameter file will look different. We can use the `seisflows configure` command to complete our parmater file, based on the chosen modules.<jupyter_code>! seisflows configure<jupyter_output>filling parameters.yaml w/ default values<jupyter_text>Anatomy of the parameter fileAs we will see below, the parameter file has now been generated. Each module will define its own section, separated by a header of comments. 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 the workflow. Section headers will look something:<jupyter_code># =============================================================================
#                                    MODULE
#                                    //////                                    
# PARAMETER_NAME (type):
#   Description
# ...
# =============================================================================
PARAMETER_NAME: parameter_value
! head -80 parameters.yaml
! tail --lines=54 parameters.yaml<jupyter_output># =============================================================================
#                                     PATHS                                    
#                                     /////                                    
# SCRATCH:
#   scratch path to hold temporary data during workflow
# OUTPUT:
#   directory to save workflow outputs to disk
# SYSTEM:
#   scratch path to hold any system related data
# LOCAL:
#   path to local data to be used during workflow
# LOGFILE:
#   the main output log file where all processes will track their status
# SOLVER:
#   scratch path to hold solver working directories
# SPECFEM_BIN:
#   path to the SPECFEM binary executables
# SPECFEM_DATA:
#   path to the SPECFEM DATA/ directory containing the 'Par_file', 'STATIONS'
#   file and 'CMTSOLUTION' files
# DATA:
#   path to data available to workflow
# MASK:
#   Directory to mask files for gradient masking
# OPTIMIZE:
#   scratch path to store data related to nonl[...]<jupyter_text>How do I know what parameters need to be set?> **NOTE**: Required parameters that can not be set to default values will be listed as `!!! REQUIRED PARAMETER !!!`We can check the required paths and parameters manually by scrolling through the parameter file, or we can use the `seisflows par --required` command to list them out all at once.<jupyter_code>! seisflows par --required<jupyter_output>!!! REQUIRED PARAMETER !!!
==========================
	MATERIALS
	DENSITY
	ATTENUATION
	NT
	DT
	FORMAT
	CASE
	END
!!! REQUIRED PATH !!!
=====================
	SPECFEM_BIN
	SPECFEM_DATA
	MODEL_INIT<jupyter_text>Checking parameter validityYou might be asking, how do I know if my parameters are set correctly? SeisFlows3 modules feature check() functions which dictate correct parameter values. You can run `seisflows init` to run these check() functions. Because we have required parameters still left unset in our parameter file, we expect the `seisflows init` function to throw an error.<jupyter_code>! seisflows init<jupyter_output>================================================================================
                           PARAMETER FILE READ ERROR                            
                           /////////////////////////                            
Please check that your parameter file is properly formatted in the YAML format.
If you have just run 'seisflows configure', you may have some required
parameters that will need to be filled out before you can proceed. The error
message is:

could not determine a constructor for the tag 'tag:yaml.org,2002:!'
  in "parameters.yaml", line 147, column 12
================================================================================<jupyter_text>Let's set some random variables for the required parameters with the `seisflows par` command and try again.<jupyter_code>! seisflows par materials elastic
! seisflows par density constant
! seisflows par attenuation False
! seisflows par nt 100
! seisflows par dt .05
! seisflows par format ascii
! seisflows par case data
! seisflows par end 1
! seisflows par specfem_bin ./
! seisflows par specfem_data ./
! seisflows par model_init ./
! seisflows init<jupyter_output>instantiating SeisFlows3 working state in directory: output<jupyter_text>Of course we knew that the above parameters were acceptable. But what if we input an unacceptable parameter into the  parameter file and try again?<jupyter_code>! rm -r output/
! seisflows par materials visibily_incorrect_value
! seisflows init<jupyter_output>MATERIALS: elastic -> visibily_incorrect_value
================================================================================
                               MODULE CHECK ERROR                               
                               //////////////////                               
seisflows.config module check failed with:

solver: MATERIALS must be in ['ELASTIC', 'ACOUSTIC', 'ISOTROPIC', 'ANISOTROPIC']
================================================================================<jupyter_text>And voila, the module check has thrown an error, and told us (the User) how to properly set the value of the materials parameter. Hopefully a combination of thorough explanations in the parameter file section headers, and error catching with `seisflows init` makes crafting your own parameter file a smooth process.<jupyter_code>! head -155 parameters.yaml | tail --lines=38
! rm parameters.yaml  # to delete the created file from this working directory<jupyter_output><empty_output>
{'fraction_non_alphanumeric': 0.14160239931448157, 'fraction_numerical': 0.005784061696658098, 'mean_word_length': 2.631660832360949, 'pattern_counts': {'":': 0, '<': 32, '<?xml version=': 0, '>': 36, 'https://': 1, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 9, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'chain_length': '10', 'dir': 'jupyter-structured-clean-dedup', 'id': '639956', 'license': 'BSD-2-Clause', 'n_tokens_mistral': 2544, 'n_tokens_neox': 2383, 'n_words': 968, 'path': 'seisflows3/docs/notebooks/parameter_file.ipynb', 'repo_name': 'bch0w/seisflows3', 'size': '9336'}