View source for Broadband User Guide v13.9.0

'''Version 13.9.0'''

If you find errors in this document or sections to be unclear, please contact software@scec.org. If possible, please send a description of how to reproduce the problem. This will help SCEC developers more quickly identify and resolve the problem you have identified.

= Installing the Broadband Platform =
Installing the Broadband Platform involves obtaining a copy of the code and building the required executables. You can either download the platform from the Broadband web site ([http://www.scec.org/research/broadband http://www.scec.org/research/broadband]) or check the code out of SCEC's Subversion repository. Most users should download the platform.

== System Dependencies ==
The current version of the Broadband Platform is designed to run on standard 64-bit Linux machines. Testing has been performed on SCEC's development servers running Fedora Core 10 (kernel version 2.6.27.41-170.2.117.fc10.x86_64). In this guide we outline how to install the platform into your own account on a Linux computer using the simplest approach.

== Software Dependencies ==
The Broadband Platform has certain software dependencies.

Required:

*Python v2.6+ with
**Matplotlib 1.0.1
**Numpy 1.4.1
**Scipy 0.7.2
**Pyproj 1.8.9

*Intel compilers (64-bit) v12.0.4
*GNU compilers (gcc, gfortran) v4.5.1
*GNU Fortran 77 v3.4.6

== User Account Setup ==
For simplicity of installation, we recommend users use a bash shell for the Broadband Platform account. It is possible to get the platform running using other shell's, but we will focus on a bash shell installation. The user environment is a common source of problems since certain environment variables must be defined for the platform to work correctly.

To check your account, make sure you can run basic commands like ''ls'' and ''cd'' before proceeding.

== Downloading the Platform ==

Download the main Broadband distribution file from the Broadband website. Users should also download the Greens' Functions files for
the regions where simulations will be performed. Currently the platform supports the following regions:

* LABasin (this package is required to run the Unit and Acceptance tests)
* Mojave
* LomaPrieta (for Northern California)
* Western Japan
* Central Japan

Additionally, users can optionally download validation packages for the following recorded events:

* Northridge (requires the LABasin GF package)
* Loma Prieta (requires the Loma Prieta GF package)

After downloading the needed files to your local Linux system, users can calculate their checksums and compare them to the checksums on the
Broadband web site to verify that you have the correct files. If you type:

 $ which md5sum

You should get something like /usr/bin/md5sum. If you see the message 'no md5sum in...', contact your Linux system administrator and ask to have md5sum added to your path.

Once you can run the ''md5sum'' command, run:

 $ md5sum downloaded_file.tar.gz

where "downloaded_file.tar.gz" is the file downloaded from the Broadband website. Users should do this once for each of the downloaded files to make sure they have successfully downloaded the files.

If multiple users are planning to use the platform on the same system, you only need one copy of the data files per machine. Each user will still need his or her own copy of the code files.

Alternatively, if you would like access to the latest version of the platform and get frequent but less thoroughly tested improvements, you can check out the platform from SCEC's Subversion repository. Only advanced users should take this approach, outlined in detail in the [[#Advanced Users| Advanced Users section]].

== Broadband Platform Directory Structure Setup ==

After confirming that all downloaded files are good, it is time to set up the directory structure used by the Broadband Platform. Start by
creating a top-level directory for the Broadband Platform installation. In our example, we will use 'bbp' as this top-level directory. Assuming this directory will be installed in for the user "sarah":

 $ cd /home/sarah
 $ mkdir bbp
 $ cd bbp

Now, untar the main Broadband distribution file (assuming all downloaded files are located in /home/sarah/downloads):

 $ tar -xzvf /home/sarah/downloads/bbp-dist-13.9.0.tar.gz

This will create the "13.9.0" directory with the main distribution content. Now, create 2 more directories: one for the downloaded Greens' Functions and another for the optional Validation packages:

 $ mkdir bbp_gf
 $ mkdir bbp_val

Go into the bbp_gf directory and untar each of the downloaded GF packages:

 $ cd bbp_gf

For the LABasin package, the command would be:

 $ tar -xzvf /home/sarah/downloads/labasin-velocity-model-13.9.0.tar.gz

Please untar any other GF packages that you desire to install.

Now, we need to do the same thing for the validation packages. Switch to the bbp_val directory and install any validation packages that were
downloaded. For example, to install the Northridge validation package, users will need to:

 $ cd /home/sarah/bbp/bbp_val
 $ tar -xzvf /home/sarah/downloads/northridge-validation-13.9.0.tar.gz

We are almost ready now. Users will need to create another directory, which will contain all the simulations that will be generated by the
Broadband Platform. In this example, we will use "bbp_data", and will place it along with the other directories that we created above, using the commands:

 $ cd /home/sarah/bbp
 $ mkdir bbp_data

The last step before we can proceed is to set up environment variables indicating where each of the above directories are located so that the
Broadband Platform can find their locations. Using the example above, users will need to set up the following 6 environment variables:

If using BASH, add the following lines to your .bash_profile file:

 export BBP_DIR=/home/sarah/bbp/13.9.0
 export BBP_GF_DIR=/home/sarah/bbp/bbp_gf
 export BBP_VAL_DIR=/home/sarah/bbp/bbp_val
 export BBP_DATA_DIR=/home/sarah/bbp/bbp_data
 export PYTHONPATH=$BBP_DIR/comps:$PYTHONPATH
 export PATH=$BBP_DIR/comps:$BBP_DIR/utils/batch:$PATH

If using a C-shell, add the following to your .cshrc:

 setenv BBP_DIR /home/sarah/bbp/13.9.0
 setenv BBP_GF_DIR /home/sarah/bbp/bbp_gf
 setenv BBP_VAL_DIR /home/sarah/bbp/bbp_val
 setenv BBP_DATA_DIR /home/sarah/bbp/bbp_data
 setenv PYTHONPATH ${BBP_DIR}/comps:${PYTHONPATH}
 setenv PATH ${BBP_DIR}/comps:${BBP_DIR}/utils/batch:${PATH}

Note that users may need to log out and log in again in order for this change to take effect.

== Building the Platform ==

Once users have downloaded and untar'ed the code and supporting packages, the final step is to compile the Broadband Platform. In order to successfully compile the project, you'll need to make sure the required compilers directories are in your PATH variable. Broadband requires Intel 64-bit compilers, icc and ifort and GNU Compilers, gcc, g77 and f77 to compile the scientific code. Using the example provided in the section above, users will need to go to the 'src' directory and compile the code. Before trying to compile the code, users can use the following command to make sure the needed compilers are present in their path:

 $ which icc

If you get a message like "no icc in path" you will need to add the Intel compilers to your path. Once that is done, you can compile the code using the following commands:

 $ cd /home/sarah/bbp/13.9.0/src
 $ make clean
 $ make

This will take a few minutes, and once it is done, you are ready to start using the Broadband Platform!

== Broadband Platform Source Distribution Directory Structure ==

The platform consists of several top-level directories:

* 13.9.0 - Contains the source code, executables, scripts, and tests
* bbp_gf - Contrains the Green's Functions for the several regions supported by the Broadband Platform
* bbp_val - Contains the Validation Events that can be used with the Broadband Platform
* bbp_data - Contains the inputs, outputs, logs, and other temporary files generated by Broadband simulations. Please note that indata, logs, outdata, start, tmpdata, and xml sub-directories will be created when the Broadband Platform is first run, so they do not need to be created by the user.

The 13.9.0 directory has the following sub-directories:

* checksums - Tool to check the MD5 checksums for Bradband Green Functions and Validation files
* comps - Broadband modules required to run work-flows.
* examples - Support files required to run examples in user guide.
* mod_data - Data files used by the various simulation modules.
* patches - Patches to update the SCEC Broadband platform to the current version.
* plot - Scripts and data required to generate plots.
* ref_data - Reference inputs and results for unit and acceptance tests.
* src - Broadband science modules source code and supporting files.
* tests- Set of unit and acceptance tests.
* utils - Includes the batch utilities used for cluster operation

And the $BBP_DATA_DIR directory includes the following sub-directories:

* indata - Input data for simulations
* logs- Log files for simulations
* outdata - Output data from simulations
* start - Directory where user input files can be placed
* tmpdata - Temporary files generated during Broadband simulations
* xml - XML files with simulation parameters

In general, you will be interacting with the start directory for input files, comps to run the platform, tests to test the platform, and outdata to examine data products.

== Adding aliases ==

You may find it helpful to add aliases, so you can quickly and easily move to different broadband directories with a single command.  We recommend creating aliases for the comps, start, and outdata directories.

If you are using the Bash shell, you can create aliases by adding the following lines to ~/.bash_profile:

 alias comps='cd $BBP_DIR/comps'
 alias start='cd $BBP_DATA_DIR/start'
 alias outd='cd $BBP_DATA_DIR/outdata'

If you're using a C shell, edit your ~/.cshrc and add:

 alias comps cd ${BBP_DIR}/comps
 alias start cd ${BBP_DATA_DIR}/start
 alias outd cd ${BBP_DATA_DIR}/outdata

Log out and log back in.  You'll notice that now you can type the alias command as a shortcut to change directories:

 $ pwd
 /home/sarah
 $ comps
 $ pwd
 /home/sarah/bbp/13.9.0/comps

This can be a useful way to navigate around the broadband platform directories.

== Advanced Users ==
Alternatively, if you would like access to the latest version of the platform, to get frequent but less thoroughly tested improvements, you can check out the platform from SCEC's Subversion version control repository on intensity.usc.edu. Only advanced users should follow this approach. If you are unsure, you should download the code as outlined in [[#Downloading the Platform|Downloading the Platform]] and skip this section.

You may need to request access from the SCEC system administrator, John Yu ([mailto:johnyu@usc.edu johnyu@usc.edu]). Make sure you have subversion in your path before beginning.

Once you have access, you'll need to decide if you want a stable tagged version, or the latest version in the repository. For a stable version, open a terminal window on the system of your choice and type:

 $ svn checkout https://source.usc.edu/svn/broadband/tags/<stable version> <stable version>

For the latest version, type:

 $ svn checkout https://source.usc.edu/svn/broadband/trunk trunk

This will check out the project to your local machine. It contains the source code, tests, and some example files. You also need to obtain a copy of the Broadband Platform Green's Functions packages. They are too large to be stored in version control. You can get the .tar.gz files for the Green's Functions from the same download site you obtained this guide.

Periodically you should check for updates to the code. To do so, go to your trunk directory and type

 $ svn update

This will pull down any code updates that have been made in the repository. After you update, make the code again (detailed in [[Broadband_User_Guide#Building_the_Platform | Building the Platform]]) so that any code changes are captured in the executables.

= Running the Tests =

The Broadband Platform contains three kinds of tests. The checksum tests verify that the data files were copied correctly and you have all the files that are expected. Unit tests run each module using a set of input files, and compare the results against known outputs. They verify that each module has been built and is working correctly. Acceptance tests verify that the modules are working correctly together. They test the Platform end-to-end using different combinations with known inputs and compare the results. Each method (for both user-defined and validation events) are tested as checks against integration errors. Both unit and acceptance tests require the LABasin Greens' Functions package to be installed.

== Running Checksum Tests ==
To run the checksum tests, change to the checksums directory and run md5sum_check.py.

 $ cd checksums
 $ ./md5sum_check.py

It takes about 5 minutes to compute the checksums. If a checksum disagrees, that means that the contents of the datafile were not what was expected. Try reinstalling the data files and try again. If you continue to get a checksum error, contact support.

Once the checksums agree, move on to the unit tests.

== Running Unit Tests ==

In order to run the unit tests, users should go to the tests directory and type:

 $ cd /home/sarah/bbp/13.9.0/tests
 $ ./UnitTests.py

The tests should begin and will take approximately 30 minutes to run. At the end of each test, a "ok" should be printed if the test was
successful. At the end, the program will print the number of tests that passed and the number of tests that failed. If a test has failed, first check that you have built the executables.You can rerun just the specific test that failed (test_<module>.py). If the test is still failing, also verify that you have the ref_data directory, since it contains the input and reference files. If you're looking for more information about the failure, you can consult the Unit Tests log file in $BBP_DATA_DIR/logs/unit_test.log .  If you can't determine the reason for the failure, contact [mailto:software@intensity.usc.edu support].

Once the unit tests all pass, proceed to the acceptance tests. If there are any failure or errors while running the unit tests, consult the Troubleshooting section at the end of this user guide for know issues and their solutions.

== Running Acceptance Tests ==

Make sure the unit tests pass before moving on to the acceptance tests. To run the acceptance tests, users should:

$ cd /home/sarah/bbp/13.9.0/tests
$ ./AcceptTests.py

There will be one test for each method in the platform, for both the validation mode (historical events) and the scenario modes (hypotethical earthquakes). These tests will take somewhere between 2 and 3 hours to run, depending on how fast the computer is.

When they're complete, the console will either print "OK" or how many tests failed. Acceptance test failures indicate that the modules are not integrated correctly. Like with the unit tests, verify that you have the ref_data directory.  If a certain acceptance test fails, you can get more information by consulting the acceptance test logs in $BBP_DATA_DIR/logs/acceptance_tests_logs/<test that failed>.log .  If you can't determine the reason for the failure, contact [mailto:software@intensity.usc.edu support].

Since the acceptance tests can take a long time to run, you may wish to resume where you left off. This feature is supported automatically. If you do not wish to resume, delete the resume file in $BBP_DATA_DIR/logs/resume.txt. If there are any failure or errors while running the acceptance tests, consult the Troubleshooting section at the end of this user guide for known issues and their solutions.

= Performing Simulations =
The platform supports two kinds of simulations, validation events and user-defined events. Validation simulations are performed using a historical event, and are directly compared to observed seismograms using goodness-of-fit. User-defined events are run using a rupture description provided by the user which may not necessarily be a historical earthquake.

When you run a simulation, the platform assigns an ID to it. This ID can be used to track the simulation and locate the output data products.

To supply input files to the platform, put them in the start directory. This directory is located in the $BBP_DATA_DIR directory and it is created by the platform when it is first ran. Extensions are important - the platform recognizes station lists (.stl), SRF files (.srf), and simple source descriptions (.src). For example, when selecting a station file, the Broadband Platform will list all the .stl files in the start directory and will prompt the user to select one.

= Methods =

To perform a simulation, a user selects a method, including optional modules. Currently, the Broadband Platform supports the following methods:

* Graves & Pitarka (GP)
* SDSU
* UCSB
* Composite Source Model (CSM)
* EXSIM
* Irikura Recipe (under development)

== Modules ==
The Broadband Platform consists of a series of modules. There are two main types of modules, science modules and utility modules. Science modules are those for which the platform has multiple implementations, provided by different coding research groups. Utility modules only have 1 implementation and are used by all simulations. A schematic of the available modules and their flow relationships is shown below in the following sections.

== Science Modules ==

All simulations must include a module that creates synthetic seismograms. In some methods, there are separate low-frequency and high-frequency modules, while in other methods, these two steps are done by a single module. Rupture generation and site response are optional science modules. Users may select the following different implementations of each of these modules:

* Rupture generation: GP, UCSB
* Low-frequency: GP, UCSB, CSM, EXSIM
* High-frequency: GP, UCSB, SDSU, CSM, EXSIM
* Site response: GP, UCSB, SDSU

== Utility Modules ==

Two spectral response utility modules are automatically run after the seismogram synthesis is completed and the optional site response module. Additionally, users may select an optional goodness-of-fit (GoF) utility module to run at the conclusion of the simulation. The Broadband Platform currently supports both the GP and SDSU GoF modules and the users can select to run one, or both (or none) of these modules.

== Validation Simulations ==
To run a validation simulation, go to the comps directory and run run_bbp.py. The platform will ask you a series of questions. Answer 'y' to "Do you want to perform a validation run?"

 $ cd $BBP_DIR/comps
 $ ./run_bbp.py
 Welcome to the SCEC Broadband Platform.
 Please select the modules you want to run.
 Do you want to perform a validation run (y/n)? y
 Do you want to validate with:
 (1) Northridge
 (2) Loma Prieta
 ?
 ...

No input files are required by the user. However, you may wish to customize the validation simulation by selecting an alternate source description (src file) or a reduced station list to speed up the computations. You can put your own source description andor station list into the start directory (the format is described in [[#Station File List|section 5.3]]) or you can tell the platform where each file is located by using an absolute path. Note that any stations which do not have observed seismograms will not be included in the automatically generated goodness-of-fit comparison.

In addition to the low-frequency modules which compute seismograms using 1D Green's Tensors, certain methods allow validation events to be also run using precomputed seismograms to supply the low-frequency.

== User-defined Simulations ==
To run a user-defined simulation, two input files are required, a source description (src file) and a station list (stl file). For certain methods, the source description can either be in SRF format or a simple source description (the format is described in [[#Simple source description|section 5.1]]). Other methods will always require a simple source description (src file). To run a user-defined simulation, run run_bbp.py.

 $ cd $BBP_DIR/comps
 $ ./run_bbp.py
 Welcome to the SCEC Broadband Platform.
 Please select the modules you want to run.
 Do you want to perform a validation run (y/n)? n

User-defined events need to use one of the velocity models supported by the Broadband Platform. You should select the velocity model (region) that most closely match the area where the simulation will take place.

 Please select a velocity model (number or name are ok):

 (1) Mojave
 (2) LABasin
 (3) CentralJapan
 (4) LOMAP
 (5) WesternJapan
 ?
 ...

You may then choose the method you would like to run:

 Choose a Method to use in a Broadband forward simulation:
 (1) GP (Graves & Pitarka)
 (2) UCSB
 (3) SDSU
 (4) EXSIM
 (5) CSM
 (6) Irikura
 ?

== Logging ==
During the run, log files will be produced in logs/<simulation ID>/<simulation ID>.<module name>.log.  If the platform fails, this is a good place to look to determine the error. Additionally, any fatal errors will be recorded in fatal_error.log.

Metadata capturing all the executable calls is located in tmpdata/<simulation ID>/metadata.txt for careful tracing of exactly what was called.  Both the log files and metadata can be useful if troubleshooting an issue.

== Data Products ==
The platform produces a variety of data products. <nowiki>All data products are located in outdata/<simulation ID>. </nowiki> The ouput folder has a index-<simulation ID>.html file with a listing of all the data products in the output folder. You can open the index file on your browser window and then click through all data products. Image files can be displayed by clicking on the link to the file in the index.html page. The .bbp and .list files will be displayed as text files in the browser. On most Linux systems, you can show images using display:

 $ display <PNG file>

Make sure you have X11 forwarding enabled.

=== Station Map ===
To help visualize the stations in relationship to the fault, the platform produces a PNG file displaying station locations with red circles and the fault plane with a black line. You can find this file in outdata/<simulation ID>/station_map.png.

The Broadband Platform also produces a station_map.kml file that can be opened in Google Earth and will show the fault location and stations with their labels. This file is useful to identify the individual stations on the map.

=== Seismograms ===
When running the platform, you have the option to output velocity and acceleration seismograms, for each station.  Plots of these files can be found in outdata/<simulation ID>/<simulation ID>.<station>_<velocity or acceleration>_seis.png.

The raw seismogram data is available in outdata/<simulation ID>/<simulation ID>.<station>.vel.bbp (velocity) and outdata/<simulation ID>.<station>.acc.bbp (acceleration).  Its format is described in [[#BBP seismograms|section 5.4]].

To compare seismogram data, you can run comps/plotit.py with two seismograms. It will plot them both for comparison. From the comps directory, run:

 $> ./plotit.py <path to seismogram 1> <path to seismogram 2>

=== Response spectra ===
The respect code, run at the end of each simulation, calculates the response spectra for each station. The raw respect data is located at

 outdata/<simulation ID>/<simulation ID>.<station>.rsp

in the format described in [[#Response spectra|section 5.5]].

=== Goodness-of-fit ===
If you run goodness-of-fit, several additional data products are produced. Starting with version 11.7.0, two goodness-of-fit modules are available in Broadband.

* URS Goodness-of-fit:
The goodness-of-fit comparison is performed by comparing the response spectra of a set of calculated seismograms to seismograms from another simulation or observed seismograms. For each station involved in the comparison, a plot comparing the response spectra can be found at outdata/<simulation ID>/<comparison label>_<simulation ID>_<station>_rsp.png. A plot showing the seismograms on top and bottom can be found at outdata/<comparison label>_<simulation ID>_<station>_overlay.png. The goodness-of-fit plot can be found at gof-<comparison label>-<simulation ID>_r0-<cutoff distance>.png.

Note that at least 3 stations must be run for goodness-of-fit to be valid. If fewer than 3 stations are run, no goodness of fit calculation will be performed.

* SDSU Goodness-of-fit:
The SDSU goodness-of-fit module can compute several GoF measures. A detailed list of these GoF measure is listed here: [[Goodness_of_Fit#SDSU_GoF|SDSU MO-Gof]]. The goodness-of-fit comparison is performed by comparing the synthetic seismogram to the observed seismogram for each of the sites. For each GoF measure computed, a summary file labeled GOF_<measure>.list is generated with the GoF values for each of the sites. A weighted sum of GoF measures called site-fit is available in gof_summaray.txt file. If the simulation was run with three or more sites in the station list, GoF map plots will be available in the output directory as <simulation ID>_<Gof measure>_map.png. If PGA or PGV GoF values are computed a set of overlay plots showing the observed and synthetic seismograms on top and bottom will be available as outdata/gof_plots/<simulation ID>_<station>_match_<format>_overlay.png files.

=== Rupture files ===
When a user-defined event is simulated, the user has the option to run a rupture generator. This generator produces an SRF file, found in outdata/<simulation ID>/*.srf.  This file can be put in the start directory and used in future runs.  Additionally, the platform produces a plot of the cumulative slip on the fault surface, outdata/<simulation ID>/<SRF prefix>.png.

== Platform Modes ==
The platform can be run in multiple modes. The default is interactive mode, in which the user is prompted to answer a series of questions. Once all the information has been gathered, the run begins.

For a large number of runs, or if the user is repeating a specific run, this can be tedious. The platform provides two other ways to describe a run, with an option file or an XML description.

An option file provides responses to all the questions that the platform poses. The format is described in [[#Option File|section 5.6]], but it's basically a text file, 1 entry per line, with support for comments. It can be fed to the platform using the -o option.

The platform will also accept XML files containing a full description of a run. The schema for these files is given in [[#XML workflow description schema|section 5.7]]. These files are also produced by the platform after every simulation, and placed in xml/<simulation ID>.xml. So if you want to rerun a simulation, you can point the platform to the XML file from that simulation using the -x option. Note that a new simulation ID will be assigned to the run, so there is no risk of overwriting previous simulation results.

== Available Options ==
To get a list of the current available options, run run_bbp_2G.py with the -h flag.

 $> ./run_bbp_2G.py -h
 Usage: run_bbp_2G.py [options]
 Options:
  -h, --help show this help message and exit
  -x XML_FILE, --xml-file=XML_FILE
    Run using XML description of workflow
  -s SIM_ID, --simID=SIM_ID
    Force a simID
  -o OPTFILE, --option-file=OPTFILE
    File containing responses to interactive platform prompts
  -v, --version Broadband platform version
  -g, --generate-xml Generates the XML description but does not run the platform
  -l LOG_FILE, --log=LOG_FILE
    Store all output in a file
  -x: The platform will run a simulation from the XML description.
  -s: Force the platform to run with a given simID (a nonnegative integer)
  -o: Use an option file providing answers to the platform prompts
  -v: Prints the version of the platform and exits.
  -g: The platform will generate an XML description but not actually run the workflow. Useful if you want to create simulation descriptions and run them later.

== Cleanup ==
After a while, you may find that your indata, tmpdata, outdata, and logs directories are getting cluttered with files from past runs. If you wish to delete these old files, you can use the clean_directories.sh script in the etc directory.

 $> cd etc
 $> ./clean_directories <days>

Any simulation ID directories in the indata, tmpdata, outdata, and logs directories which were last accessed <days> days or longer ago will be deleted. If you have a few directories you want to keep, either copy them somewhere else, or copy them to a directory name that's not all digits and they won't be deleted.

= Examples =
Below are some examples that you can try using the sample files in the examples directory. Make sure all the tests pass before you try this.  You should be in the comps directory when you start these examples:

 $> cd comps

== Sample Validation Run ==
You don't need to move any files for this. Notice that 3D seismograms are a low-frequency option, since you're running a validation event.

 $> ./run_bbp_2G.py 
 Welcome to the SCEC Broadband Platform.
 Please select the modules you want to run.
 Do you want to perform a validation run (y/n)? y
 Do you want to validate with:
 Northridge (1)
 Loma Prieta (2)
 Landers (3)
 ?1
 Do you want to
 run all validation stations (1)
 select a station list (2)
 ?1
 Choose a source of low frequency seismograms:
 URS module (1)
 URS 3D seismograms (2)
 UCSB module (3)
 SDSU module (4)
 SDSU 3D seismograms (5)
 ?2
 Choose a high frequency module:
 URS (1)
 UCSB (2)
 SDSU (3)
 ?1
 Choose a site response module:
 URS (1)
 UCSB (2)
 SDSU (3)
 GATECH (4)
 ?1
 Do you want to plot velocity seismograms (y/n)? y
 Do you want to plot acceleration seismograms (y/n)? y
 Choose a Goodness of Fit (GOF) Module: 
 URS (1)
 SDSU (2)
 Both (3)
 ?3
 Do you want to calculate all MO-GOF metrics (y/n)? y

This simulation takes about 10 hours. Once it's complete, the platform will tell you:

 You can find results in <path to bbp_2g install>/outdata/<simulation ID> .

In that directory you will find:

*HTML Directory Listing(index.html)
*Velocity seismograms (<simulation ID>.<station>.bbp)
*Acceleration seismograms (<simulation ID>.<station>.acc.bbp)
*Plots of velocity seismograms (<simulation ID>.<station>_velocity_seis.png)
*Plots of acceleration seismograms (<simulation ID>.<station>_acceleration_seis.png)
*Response spectra files (<simulation ID>.<station>.rsp)
*Plots comparing simulated and observed seismograms (Northridge_<simulation ID>_<station>_overlay.png)
*Plots comparing simulated and observed response spectra (Northridge_<simulation ID>_<station>_rsp.png)
*Overall goodness-of-fit plots (gof-Northridge-<simulation ID>_r0-25.png)
*SDSU GoF file (GOF_<measure>.list and gof_summary.txt)
*SDSU GoF map plots (<simulation ID>_<Gof measure>_map.png)
*SDSU GoF overlay plots (gof_plots/<simulation ID>_<station>_match_<format>_overlay.png)

== Sample Validation run, custom stations ==
If the validation runs aren't performed with 3D low-frequency, it can take a long time, up to 10 minutes per station. Sometimes you might want to run with a reduced station list so the simulation will run faster.

Copy the files in example/valid_custom_stations into the start directory. Take a look at the format of the station file:

 $> more valid_test_stat.stl 
 #Required: lon, lat, station name, distance to fault plane, Vs30
 #Optional: low freq corner, high freq corner
 #Unused: station information
 #lon lat stationdist Vs30 LF corner HF corner station information
 -118.6417 34.5640 cast 20.47 450 0.120 23.0 CSMIP peer.berkeley.edu/nga
 -118.4180 34.0628 lacn 22.82 278 0.140 23.0 CSMIP peer.berkeley.edu/nga
 -118.8811 34.2886 moor 24.16 405 0.160 23.0 CSMIP peer.berkeley.edu/nga

Now, run the platform, using a station list:

 $> ./run_bbp_2G.py 
 Welcome to the SCEC Broadband Platform.
 Please select the modules you want to run.
 Do you want to perform a validation run (y/n)? y
 Do you want to validate with:
 Northridge (1)
 Loma Prieta (2)
 Landers (3)
 ?1
 Do you want to
 run all validation stations (1)
 select a station list (2)
 ?2

If you have multiple station list files in your start directory, you may see the following prompt asking you to select one. If you only have one, the platform will select it automatically.

 Found multiple BBP station list files in the start directory. Please select one:
 nr_one_stat.stl (1)
 valid_test_stat.stl (2)
 ?2
 Choose a source of low frequency seismograms:
 URS module (1)
 URS 3D seismograms (2)
 UCSB module (3)
 SDSU module (4)
 SDSU 3D seismograms (5)
 ?3
 Choose a high frequency module:
 URS (1)
 UCSB (2)
 SDSU (3)
 ?2
 Choose a site response module:
 URS (1)
 UCSB (2)
 SDSU (3)
 GATECH (4)
 ?2
 Do you want to plot velocity seismograms (y/n)? y
 Do you want to plot acceleration seismograms (y/n)? y
 Choose a Goodness of Fit (GOF) Module: 
 URS (1)
 SDSU (2)
 Both (3)
 ?3
 Do you want to calculate all MO-GOF metrics (y/n)? y

Again, when the run completes in about 15 minutes you can find results in the output directory. You'll notice far fewer files, as only 3 stations were run instead of 133. The goodness-of-fit plots won't look very good - more stations are really needed to get an accurate plot.

== Sample User-defined run with source description ==
Next let's try running a user-defined event. Copy examples/user_rup_gen/nr_one_stat.stl and examples/user_rup_gen/user_eq.src to the start directory. user_eq.src is a simple source description. Its format is outlined in [[#XML workflow description schema|section 5.1]]. Since this is a user-defined event, precomputed 3D seismograms aren't a valid option.

 $> ./run_bbp_2G.py 
 Welcome to the SCEC Broadband Platform.
 Please select the modules you want to run.
 Do you want to perform a validation run (y/n)? n
 Do you want to run a rupture generator (y/n)? y
 Rupture generators:
 URS (1)
 UCSB (2)
 ?1
 Using region: Southern California
 Choose a low frequency module:
 URS (1)
 UCSB (2)
 ?2
 Found multiple BBP station list files in the start directory. Please select one:
 nr_one_stat.stl (1)
 valid_test_stat.stl (2)
 ?1
 Choose a high frequency module:
 URS (1)
 UCSB (2)
 SDSU (3)
 ?2
 Choose a site response module:
 URS (1)
 UCSB (2)
 SDSU (3)
 GATECH *Not Available*
 ?1
 Do you want to plot velocity seismograms (y/n)? y
 Do you want to plot acceleration seismograms (y/n)? y
 Do you want to run goodness of fit (y/n)? n

Since this run only includes one station, it will run in about 5 minutes. In the output directory you'll notice there are no goodness-of-fit or files, since we didn't run goodness-of-fit. However, there is also a map file (station_map.png), showing the fault plane and the stations, and a plot of the rupture slip (user_eq.png). The SRF generated by the rupture generator is in user_eq.srf; this file could be used in future runs. The filenames of the rupture slip plot and SRF are taken from the rupture description filename.

== Sample User-defined run with SRF file and goodness-of-fit ==
Finally, try a run with an SRF file and run goodness-of-fit on the results. Copy in examples/user_no_rup_gen/ucsb_modSRF_0.srf and examples/user_no_rup_gen/nr_three_stat.stl

 $> ./run_bbp_2G.py 
 Welcome to the SCEC Broadband Platform.
 Please select the modules you want to run.
 Do you want to perform a validation run (y/n)? n
 Do you want to run a rupture generator (y/n)? n
 Using region: Southern California
 Choose a low frequency module:
 URS (1)
 UCSB (2)
 ?1
 Found multiple BBP station list files in the start directory. Please select one:
 nr_one_stat.stl (1)
 valid_test_stat.stl (2)
 nr_three_stat.stl (3)
 ?3
 Choose a high frequency module:
 URS (1)
 UCSB (2)
 SDSU (3)
 ?3
 Choose a site response module:
 URS (1)
 UCSB (2)
 SDSU (3)
 GATECH *Not Available*
 ?1
 Do you want to plot velocity seismograms (y/n)? y
 Do you want to plot acceleration seismograms (y/n)? y
 Do you want to run goodness of fit (y/n)? y
 What reference files would you like to compare to? Enter a simulation ID or a scenario name: Northridge
 Enter a label to use for the comparison seismograms: nr
 Choose a Goodness of Fit (GOF) Module: 
 URS (1)
 SDSU (2)
 Both (3)
 ?1

The reference files can either be a scenario event or a simulation ID previously run. The label is just for the figures when comparisons are plotted.

This run will take about 15 minutes, and the results can be found in the appropriate outdir. Again, the URS goodness of fit measures will look poor due to the few stations involved in the comparison. If you had fewer than 3 stations, no goodness-of-fit plots would be produced. However, response spectra comparison plots will still be generated.

= File Formats =
This section offers descriptions of various file formats in the broadband platform.

== Simple source description ==
This is the format for the simple source description. It is not whitespace sensitive. The filename must end in .src for the platform to identify it as a source description.

 MAGNITUDE = <magnitude>
 FAULT_LENGTH = <length of fault>
 DLEN = <DX, along length>
 FAULT_WIDTH = <down-dip fault width>
 DWID = <DY, along width>
 DEPTH_TO_TOP = <depth of fault below surface>
 STRIKE = <nowiki><strike></nowiki>
 RAKE = <rake>
 DIP = <dip>
 LAT_TOP_CENTER = <latitude of top center point in fault plane>
 LON_TOP_CENTER = <longitude of top center point in fault plane>
 HYPO_ALONG_STK = <along strike location of hypocenter (0.0 = middle)>
 HYPO_DOWN_DIP = <down dip location of hypocenter (0.0 = top)>
 DT = <nowiki><dt></nowiki>
 SEED = <random seed used in calculations>
 CORNER_FREQ = <corner frequency to use>

== SRF rupture description ==
Details of the Standard Rupture Format (SRF) are given in more detail in the accompanying document. The general fault surface is represented by a distribution of point sources, and it can support one or more planes. The platform produces SRFs as output from rupture generators, but a user can also supply an SRF file as input for user-defined simulations. SRF filenames must end with the suffix .srf for the platform to correctly identify them.

== Station File List ==
The user may specify a list of stations, matching the following format:

 #optional
 %comment
 # lines
 <nowiki><lon> <lat> <stat name> <distance to fault trace> <Vs30> <LF corner> <HF corner> <stat info></nowiki>
 ...

The station list filename needs to end in .stl for the platform to recognize it as a station list.

== BBP seismograms ==
All intermediate and output seismograms are produced in a 4-column text format, whether velocity or acceleration.

 # optional
 % comment
 # lines
 <nowiki><timestamp> <North/South> <East/West> <Up/Down></nowiki>
 ...

Time is in seconds and motion is in cm/s (velocity) or cm/s/s (acceleration) unless otherwise specified in the header. Velocity filenames end in .vel.bbp; accelerations in .acc.bbp.

== Response spectra ==
The response spectra file is in 4-column text format.

 # optional
 % comment
 # lines
 <nowiki><period (sec)> <North/South> <East/West> <Up/Down></nowiki>
 ...

The platform samples response spectra at 112 periods, 0.01-20 sec and outputs pseudo spectral acceleration in units of g.

== Option File ==
Option files contain responses to the prompts in the platform. You can use them with the -o option to run_bbp_2G.py. The responses have to match the prompts exactly. For example, if you craft an option file assuming there is only one station list in the start directory (and therefore the user isn't prompted to select one) but then it is run with multiple station lists in the start directory, this will cause the run to abort. Option files are recommended to perform a series of runs with different inputs or different modules. If you have a run you perform regularly, it's better practice to run the platform with the -g option and the option file to produce an XML description, which are more complete descriptions of the workflow.

 #optional comments
 %using either symbol
 n #comments
 y % can go
 1 # here
 ...

Use with:

 $> ./run_bbp_2G.py -o <option file>

== XML workflow description schema ==
Each time the platform is invoked, an XML file is produced describing the workflow, obeying the following schema:

 <nowiki><xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"></nowiki>
 <nowiki><xs:element name= "BBP_Run_Specification" minOccurs= "1" maxOccurs= "1"></nowiki>
   <nowiki><xs:attribute name="version" type = "xs:string" use = "required" /></nowiki>
   <nowiki><xs:complexType></nowiki>
     <nowiki><xs:sequence></nowiki>
       <nowiki><xs:element name= "Validation_Run" minOccurs= "0" maxOccurs = "1"></nowiki>
         <nowiki><xs:attribute name= "event" type= "xs:string" use= "required" /></nowiki>
         <nowiki><xs:attribute name= "input_station_file" type = "xs:string" /></nowiki>
         <nowiki><xs:attribute name= "subset" type = "xs:boolean" use = "required" /></nowiki>
       <nowiki></xs:element></nowiki>
       <nowiki><xs:element name= "BBP_Modules"></nowiki>
         <nowiki><xs:complexType></nowiki>
           <nowiki><xs:sequence></nowiki>
             <nowiki><xs:element name = "BBP_Module" maxOccurs = "unbounded" ></nowiki>
               <nowiki><xs:complexType></nowiki>
                 <nowiki><xs:sequence></nowiki>
                   <nowiki><xs:element name= "name" type="xs:string" /></nowiki>
                   <nowiki><xs:element name= "staged_files" ></nowiki>
                     <nowiki><xs:complexType></nowiki>
                       <nowiki><xs:sequence></nowiki>
                         <nowiki><xs:element name="file" type="xs:string" maxOccurs= "unbounded"/></nowiki>
                       <nowiki></xs:sequence></nowiki>
                     <nowiki></xs:complexType></nowiki>
                   <nowiki></xs:element></nowiki>
                   <nowiki><xs:element name= "arguments" ></nowiki>
                     <nowiki><xs:complexType></nowiki>
                       <nowiki><xs:sequence></nowiki>
                         <nowiki><xs:element name="argument" type="xs:string" maxOccurs="unbounded"></nowiki>
                           <nowiki><xs:attribute name= "type" type= "xs:string" user= "required" /></nowiki>
                         <nowiki></xs:element></nowiki>
                       <nowiki></xs:sequence></nowiki>
                     <nowiki></xs:complexType></nowiki>
                   <nowiki></xs:element></nowiki>
                 <nowiki></xs:sequence></nowiki>
               <nowiki></xs:complexType></nowiki>
             <nowiki></xs:element></nowiki>
           <nowiki></xs:sequence></nowiki>
         <nowiki></xs:complexType></nowiki>
       <nowiki></xs:element></nowiki>
     <nowiki></xs:sequence></nowiki>
   <nowiki></xs:complexType></nowiki>
 <nowiki></xs:element></nowiki>

These files are difficult to construct by hand, but can be generated using the -g flag when running run_bbp_2G.py.

= User Support =
If you run into bugs with the platform, you can open a trouble ticket at the [http://northridge.usc.edu/trac/broadband Broadband Trac site].

Check to see if there has already been a ticket opened for the bug. If you are unable to get the platform to run, you can get direct user support by emailing [mailto:software@intensity.usc.edu software@intensity.usc.edu].

= Appendix A: Troubleshooting =
If you experience trouble building the platform or successfully running test and simulations, try the following solutions.

=== Build Errors ===

The instruction for installing Broadband Platform are listed in Section 1: "Installing the Second-Generation Broadband Platform" of the User guide. If after following all steps listed in this section of the user guide the build fails, check if the failure is listed in this section and try the solution to fix the issue you are facing.

=== Unit/Acceptance Test Failures and Errors ===

Unit and Acceptance tests are provided to verify the Broadband platform and it's supporting modules built by the user are functioning as designed. Under certain circumstances, some of these test might fail or print a warning message. While some of these failure might indicate serious problems that will have to be addressed before the platform can used, it is acceptable to ignore some of the failures. This section lists some failures and their solutions.

== Related Entries ==
*[[CME Project]]
*[[SEISM Project]]
*[[Broadband Platform]]
*[http://scec.usc.edu/scecpedia/Main_Page SCECpedia wiki Home Page]