Broadband User Guide v11.2.3 - Revision history

Fsilva: /* User Support */

2014-07-15T17:09:49Z

User Support

Patrices at 22:09, 8 May 2012

2012-05-08T22:09:03Z

Patrices at 22:05, 8 May 2012

2012-05-08T22:05:48Z

Patrices at 22:05, 8 May 2012

2012-05-08T22:05:06Z

Patrices at 22:02, 8 May 2012

2012-05-08T22:02:44Z

Show changes

Patrices at 21:55, 8 May 2012

2012-05-08T21:55:24Z

Show changes

Patrices at 21:38, 8 May 2012

2012-05-08T21:38:52Z

Patrices at 21:37, 8 May 2012

2012-05-08T21:37:18Z

Patrices at 21:36, 8 May 2012

2012-05-08T21:36:18Z

Patrices at 21:34, 8 May 2012

2012-05-08T21:34:37Z

@@ Line 784: / Line 784: @@
 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@scec.org software@intensity.usc.edu].
+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@scec.org software@scec.org].
 = Appendix A: Possible Module Permutations =

@@ Line 313: / Line 313: @@
 To perform a simulation, a user selects between different required and optional modules. Below we present a summary of the various modules.
-= Modules =
+== 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. A schematic of the available modules and their flow relationships is shown below:
-== Science Modules ==
+=== Science Modules ===
 All simulations must include a low-frequency, high-frequency, and site response science module. Simulations may include an optional rupture generation science module. Users may select between the following different implementations of each of these modules:
@@ Line 327: / Line 327: @@
 Site response:URS, UCSB, SDSU
-== Utility Modules ==
+=== Utility Modules ===
 A spectral response utility module is automatically run after the site response module. Additionally, users may select an optional goodness-of-fit utility module to run at the conclusion of the simulation. In the case of a user-defined event, users select a historical event or previously run simulation to use as the comparison for goodness-of-fit.
-= Platform Directory =
+== Platform Directory ==
 A broadband platform distribution is organized in a specific directory structure that separates the input data sets, the python scripts, the simulation configuration files, log files, and output data files.
@@ Line 343: / Line 343: @@
 Simulation output results will be written into the bbp_home/output
-= Validation Simulations =
+== Validation Simulations ==
 To run a validation simulation, go to the comps directory and run run_bbp_2G.py. The platform will ask you a series of questions. Answer 'y' to "Do you want to perform a validation run?"
@@ Line 364: / Line 364: @@
 In addition to the low-frequency modules which compute seismograms using 1D Green's Tensors, validation events can also be run using precomputed 3D seismograms to supply the low-frequency.
-= User-defined Simulations =
+== User-defined Simulations ==
 To run a user-defined simulation, two input files are required, a rupture description and a station list. The rupture description can either be in SRF format or a simplified source description (the format is described in [[#Simple source description|section 5.1]]). To run a user-defined simulation, run run_bbp_2G.py.
@@ Line 388: / Line 388: @@
 The user-defined events must be within one of the regions supported by the platform - Southern California, Northern California, or the Mojave. The platform will automatically select a region based on the event hypocenter. If the event falls outside of these regions, you'll get an error.
-= Logging =
+== 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 =
+== Data Products ==
 The platform produces a variety of data products. <nowiki>All data products are located in outdata/<simulation ID>. </nowiki>On most Linux systems, you can show images using display:
@@ Line 400: / Line 400: @@
 Make sure you have X11 forwarding enabled.
-== Station map ==
+=== 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, on an image of California.  You can find this file in outdata/<simulation ID>/station_map.png.
-== Seismograms ==
+=== 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.
@@ Line 412: / Line 412: @@
   $> plotit.py <path to seismogram 1> <path to seismogram 2>
-== Response spectra ==
+=== 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
@@ Line 421: / Line 421: @@
 in the format described in [[#Response spectra|section 5.5]].
-== Goodness-of-fit ==
+=== Goodness-of-fit ===
 If you run goodness-of-fit, several additional data products are produced. 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.
-== Rupture 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.

@@ Line 784: / Line 784: @@
 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].
+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@scec.org software@intensity.usc.edu].
 = Appendix A: Possible Module Permutations =

@@ Line 316: / Line 316: @@
 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. A schematic of the available modules and their flow relationships is shown below:
-= Science Modules =
+== Science Modules ==
 All simulations must include a low-frequency, high-frequency, and site response science module. Simulations may include an optional rupture generation science module. Users may select between the following different implementations of each of these modules:
@@ Line 327: / Line 327: @@
 Site response:URS, UCSB, SDSU
-= Utility Modules =
+== Utility Modules ==
 A spectral response utility module is automatically run after the site response module. Additionally, users may select an optional goodness-of-fit utility module to run at the conclusion of the simulation. In the case of a user-defined event, users select a historical event or previously run simulation to use as the comparison for goodness-of-fit.

@@ Line 470: / Line 470: @@
   $> cd comps
-== Sample Validation Run ==
+=== 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.
@@ Line 524: / Line 524: @@
 *Overall goodness-of-fit plots (gof-Northridge-<simulation ID>_r0-25.png)
-== Sample Validation run, custom stations ==
+=== 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.
@@ Line 585: / Line 585: @@
 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 ==
+=== 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.
@@ Line 622: / Line 622: @@
 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 ==
+=== 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
@@ Line 663: / Line 663: @@
 This section offers descriptions of various file formats in the broadband platform.
-== Simple source description ==
+=== 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.
@@ Line 683: / Line 683: @@
   CORNER_FREQ = <corner frequency to use>
-== SRF rupture description ==
+=== 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 ==
+=== Station File List ===
 The user may specify a list of stations, matching the following format:
@@ Line 697: / Line 697: @@
 The station list filename needs to end in .stl for the platform to recognize it as a station list.
-== BBP seismograms ==
+=== BBP seismograms ===
 All intermediate and output seismograms are produced in a 4-column text format, whether velocity or acceleration.
@@ Line 708: / Line 708: @@
 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 ==
+=== Response spectra ===
 The response spectra file is in 4-column text format.
@@ Line 719: / Line 719: @@
 The platform samples response spectra at 112 periods, 0.01-20 sec and outputs pseudo spectral acceleration in units of g.
-== Option File ==
+=== 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.
@@ Line 733: / Line 733: @@
   $> run_bbp_2G.py -o <option file>
-== XML workflow description schema ==
+=== XML workflow description schema ===
 Each time the platform is invoked, an XML file is produced describing the workflow, obeying the following schema:

@@ Line 1,652: / Line 1,652: @@
 == Appendix C: Technical Notes ==
-== Running Individual Acceptance Tests ==
+=== Running Individual Acceptance Tests ===
 The acceptance test script ./tests/AcceptTest.py attempts to run all of the defined tests when executed. However, sometimes it is useful to run an acceptance test in isolation for troubleshooting purposes:
@@ Line 1,664: / Line 1,664: @@
 Since you are running the test outside of AcceptTest.py, you will not see a PASS/FAIL message once the simulation completes. However, you can review the contents of the ./outdata/<SIMID> directory to verify that the correct seismograms and response spectra tables were produced.
-== Manaully Setting Random Number Generator Seed Values ==
+=== Manaully Setting Random Number Generator Seed Values ===
 Several of the platform codebases employ random number generators to produce SRFs and seismograms. These random number generators are generally seeded with an initial value (typically an integer) which are hard-coded in the platform. Advanced users may desire to change these seed values.

@@ Line 660: / Line 660: @@
 This run will take about 15 minutes, and the results can be found in the appropriate outdir. Again, the 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 =
+== File Formats ==
 This section offers descriptions of various file formats in the broadband platform.
@@ Line 781: / Line 781: @@
 These files are difficult to construct by hand, but can be generated using the -g flag when running run_bbp_2G.py.
-= User Support =
+== 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: Possible Module Permutations =
+== Appendix A: Possible Module Permutations ==
 === Validation Events ===
@@ Line 1,454: / Line 1,454: @@
 |}
-= Appendix B: Troubleshooting =
+== Appendix B: Troubleshooting ==
 If you experience trouble building the platform or successfully running test and simulations, try the following solutions.
@@ Line 1,650: / Line 1,650: @@
 '''Solution:''' The stochastic nature of the high frequency simulations is considered, and a constant random seed as input for our tests. This is the same constant random seed used to generate the reference results included in the release. This ensures that the time-series generated with unit tests agree with reference results. However, the high frequency codes are more sensitive to changes in compilers and machines due to the algorithm, so small differences that cause the test to fail are generally acceptable. The user is however encouraged to plot the two time-series and visually inspect them to verify they look similar. We are trying to come up with a better comparison for these tests.
-= Appendix C: Technical Notes =
+== Appendix C: Technical Notes ==
 == Running Individual Acceptance Tests ==

@@ Line 463: / Line 463: @@
 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 =
+== 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: