Analysis With Python

fdfault.analysis is a python module for analyzing dynamic rupture problems for use with the C++ code.

It contains classes corresponding to the two types of outputs from the code

The module contains the following classes:

  • fdfault.analysis.output – output unit for grid or fault data
  • fdfault.analysis.front – rupture front output for fault surfaces

The output units can hold a variety of different fields. See the documentation for the output units for more details.

The rupture front holds rupture time values for all points on the fault. This can be used to examine rupture speeds and determine the areas of the fault that slip.

Details on the data structures in each class can be found in the documentation.

The module also contains several functions for converting binary output files to text files for the SCEC Rupture Code Verification Group. It contains functions for on- and off-fault stations, and 2D and 3D problems, as well as rupture front times. See the details of each individual function. These are not imported by default when loading the analysis submodule

class fdfault.analysis.output(problem, name, datadir=None)

Class representing an output object

Output objects contain the following attributes:

Variables:
  • problem – Name of problem
  • name – Name of output unit
  • datadir – Directory where simulation data is held, if None (default) this is the current directory
  • field – Field that was saved to file
  • nt – Number of time steps
  • nx – Number of x grid points
  • ny – Number of y grid points
  • nz – Number of z grid points
  • endian – Byte-ordering of simulation data ('=' for native, '>' for big endian, '<' for little endian)
  • fielddata – Numpy array holding simulation data (also aliased using the field name itself)
load()

Load data from data file for output item

Method loads the data from file into the fielddata attribute, a Numpy array, and also creates an alias with the field attribute itself. If you have an existing instance of an output class whose simulation data has changed, load can be run more than once and will refresh the contents of the simulation output.

Method takes no inputs and has no outputs. Class is modified by running this method as the simulation data will be reloaded from file if it already exists.

Returns:None
class fdfault.analysis.front(problem, iface, datadir=None)

Class for rupture front objects

Object describing a rupture front, with the following attributes:

Variables:
  • problem – Name of problem
  • iface – Interface that was output
  • datadir – Directory where simulation data is held, if None (default) this is the current directory
  • nx – Number of x grid points (or number of y grid points if the target interface has an x normal)
  • ny – Number of y grid points (or number of z grid points if the target interface has an x or y normal)
  • endian – Byte-ordering of simulation data ('=' for native, '>' for big endian, '<' for little endian)
  • t – Numpy array holding rupture time data
load()

Load data from data file for rupture front

Method loads the data from file into the t attribute. If you have an existing instance of an front class whose simulation data has changed, load can be run more than once and will refresh the contents of the simulation output.

Method takes no inputs and has no outputs. Class is modified by running this method as the simulation data will be reloaded from file if it already exists.

Returns:None

The write_scec submodule

The write_scec module contains several functions useful for converting binary output from a simulation to the text file format used by the SCEC Rupture Code Verification group. Functions are written for on fault, off fault, and front data types, and there are versions for both 2D and 3D problems. The functions take several common optional arguments, including depthsign (indicates whether depth is positive or negative), author (the person who is submitting the results), version (the code version used to run the simulation), and grid_spacing (the resolution of the simulation, in the event you are submitting data for multiple grid spacings).

Each function writes a text file in the current directory following the file naming convention used by the server for the Code Verification group. More information on the file outputs are given in the documentation for each function.

fdfault.analysis.write_scec.write_off_fault(problem, station, depthsign=1.0, author='', version='', grid_spacing='')

Converts code output units for off-fault station from a 3D simulation into a formatted text file for SCEC website

This function converts off fault data from binary (written by the C++ code) to ASCII text for a 3D benchmark simulation. Required inputs are the problem name (string) and station (tuple of strings in the format (strike, across, depth)). Optional inputs include depthsign (1. by default, changes sign on depth coordinate if -1.), and author, verision, and grid spacing strings which will be inserted into the header of the output file.

The text file is written to {problem}_body{across}st{strike}dp{depth}.txt in the current directory.

Parameters:
  • problem (str) – Problem name to write to file
  • station (tuple) – Coordinates in 3D of output station (tuple of 3 strings)
  • depthsign (float) – Sign of depth output, must be 1. or -1. (optional, default is 1.)
  • author (str) – Person who ran the simulation (optional, default is "")
  • version (str) – Code version used in simulation (optional, default is "")
  • grid_spacing (str) – Grid spacing used in simulation (optional, default is "")
Returns:

None
fdfault.analysis.write_scec.write_off_fault_2d(problem, station, depthsign=1.0, author='', version='', grid_spacing='')

Converts code output units for off-fault station into a formatted text file for SCEC website

This function converts off fault data from binary (written by the C++ code) to ASCII text for a 3D benchmark simulation. Required inputs are the problem name (string) and station (tuple of strings in the format (strike, across, depth)). Optional inputs include depthsign (1. by default, changes sign on depth coordinate if -1.), and author, verision, and grid spacing strings which will be inserted into the header of the output file.

The text file is written to {problem}_body{across}st{strike}dp{depth}.txt in the current directory.

Parameters:
  • problem (str) – Problem name to write to file
  • station (tuple) – Coordinates in 2D of output station (tuple of 3 strings, but strike should be '0')
  • depthsign (float) – Sign of depth output, must be 1. or -1. (optional, default is 1.)
  • author (str) – Person who ran the simulation (optional, default is "")
  • version (str) – Code version used in simulation (optional, default is "")
  • grid_spacing (str) – Grid spacing used in simulation (optional, default is "")
Returns:

None
fdfault.analysis.write_scec.write_on_fault(problem, station, depthsign=1.0, normal=True, author='', version='', grid_spacing='')

Converts code output units for on-fault station into a formatted text file for SCEC website

This function converts on fault data from binary (written by the C++ code) to ASCII text for a 3D benchmark simulation. Required inputs are the problem name (string) and station (tuple of strings in the format (strike, depth)). Optional inputs include depthsign (1. by default, changes sign on depth coordinate if -1.), and author, verision, and grid spacing strings which will be inserted into the header of the output file.

The text file is written to {problem}_faultst{strike}dp{depth}.txt in the current directory.

Parameters:
  • problem (str) – Problem name to write to file
  • station (tuple) – Coordinates of output station (tuple of 2 strings for strike and depth coordinates)
  • depthsign (float) – Sign of depth output, must be 1. or -1. (optional, default is 1.)
  • author (str) – Person who ran the simulation (optional, default is "")
  • version (str) – Code version used in simulation (optional, default is "")
  • grid_spacing (str) – Grid spacing used in simulation (optional, default is "")
Returns:

None
fdfault.analysis.write_scec.write_on_fault_2d(problem, station, depthsign=1.0, normal=True, author='', version='', grid_spacing='')

Converts code output units for on-fault station into a formatted text file for SCEC website

This function converts on fault data from binary (written by the C++ code) to ASCII text for a 2D benchmark simulation. Required inputs are the problem name (string) and station (tuple of strings in the format (strike, depth), with values chosen appropriately for a 2D simulation). Optional inputs include depthsign (1. by default, changes sign on depth coordinate if -1.), and author, verision, and grid spacing strings which will be inserted into the header of the output file.

The text file is written to {problem}_faultst{strike}dp{depth}.txt in the current directory.

Parameters:
  • problem (str) – Problem name to write to file
  • station (tuple) – Coordinates of output station (tuple of 2 strings for strike and depth coordinates)
  • depthsign (float) – Sign of depth output, must be 1. or -1. (optional, default is 1.)
  • author (str) – Person who ran the simulation (optional, default is "")
  • version (str) – Code version used in simulation (optional, default is "")
  • grid_spacing (str) – Grid spacing used in simulation (optional, default is "")
Returns:

None
fdfault.analysis.write_scec.write_front(problem, iface=0, depthsign=1.0, author='', version='', grid_spacing='')

Converts code output units for rupture front times into a formatted text file for SCEC website

This function converts rupture time data from binary (written by the C++ code) to ASCII text for a 3D benchmark simulation. Required inputs are the problem name (string). Optional inputs include the interface to write to file (default is 0), depthsign (1. by default, changes sign on depth coordinate if -1.), and author, verision, and grid spacing strings which will be inserted into the header of the output file.

The text file is written to {problem}_cplot.txt in the current directory.

Parameters:
  • problem (str) – Problem name to write to file
  • iface – Interface to be written to file (default is 0)
  • depthsign (float) – Sign of depth output, must be 1. or -1. (optional, default is 1.)
  • author (str) – Person who ran the simulation (optional, default is "")
  • version (str) – Code version used in simulation (optional, default is "")
  • grid_spacing (str) – Grid spacing used in simulation (optional, default is "")
Returns:

None

Example

An example of how to use the included classes for analysis is included in the file python_example.py, included in the python directory.

# example using output class in python

# required arguments are problem name and output unit name
# data directory is optional, if no argument provided assumes it is the current working directory

from __future__ import print_function
import numpy as np
import matplotlib.pyplot as plt
from fdfault.analysis import output

vybody = output('testprob', 'vybody')

# load data structure containing information

vybody.load()

# field arrays are indexed by (t,x,y,z), with any singleton dimensions removed
# print statement prints basic information

print(vybody)

# can also access fields directly

print(vybody.vy)

# plot velocity

plt.figure()
plt.pcolor(vybody.x, vybody.y, vybody.vy[0,:,:])
plt.colorbar()
plt.show()