The `problem` Class¶

The main class used for creating problems is the problem class. problem holds all relevant variables and classes needed to specify a simulation, and provides interfaces to automatically create the necessary classes when modifying the simulation. The class also contains methods for searching the grids that will be generated in a simulation in order to find specific points where output is desired. After the simulation is set up, it also has a method to write all information to file when complete.

class fdfault.problem(name)¶

Class describing a dynamic rupture problem.

This is the main class used in the python module. The problem class holds all relevant information for setting up the simulation, and any modifications to a problem should be done with the included interfaces.

To create a problem, a problem name (string) is required to initialize an instance of problem

>>> import fdfault
>>> p = fdfault.problem('myproblem')

This will initialize a problem with the default attributes. This includes the following:

Variables:

name (str) – Problem name (string, must be provided when initializing)
datadir (str) – Data directory where output will be saved (default is ‘data/’)
nt (int) – Number of time steps (default is 0)
dt (float) – Time step size (default is 0.)
ttot (float) – Total simulation time (default is 0.)
cfl (float) – Courant ratio (dt * wave speed / dx, must be less than 1., default 0.)
ninfo (int) – Frequency at which information is printed to the terminal during a simulation (default 10)
rkorder (int) – Order of accuracy of time integration (default is 1)
d (domain) – Initializing a problem also creates a new domain, which can be modified using the methods below.
outputlist (list) – Initializing a problem creates an empty output list. To create output items, add them to the list using the appropriate method.
frt (front) – A new problem contains a front with output turned off. To turn on front output, use the appropriate method.

The four variables related to the time step provide several ways to set the time step. You can set the time step using any pair of the variables except the time step and the Courant ratio. If you provide more than two, the code defaults to the total time and either the time step or the Courant ratio if the time step is not provided.

Use the methods described below to modify the simulation. When the problem is fully set-up, you can write the result to file

>>> p.write_output()

This will create the file myproblem.in in the current directory as well as any necessary binary files.

__init__(name)¶

Creates a new instance of the problem class

Initializes a new instance of the problem class. Requires a problem name (string), other parameters are set to the following defaults:

datadir = 'data/' (path is relative to the main code directory)

nt, dt, ttot, and cfl are set to zero. You must specify two of these to set the time step, except the time step and the Courant ratio

ninfo = 10

rkorder = 1

An empty output list is initialized

front output is False

A domain is created with a single block with 1 grid point in each direction, default material properties, and a 2nd order finite difference method. All boundary conditions are set to 'none'

All properties can be modified using the provided interfaces through the problem class.

Parameters:	name (str) – Name for new problem
Returns:	New problem instance
Return type:	problem

add_load(newload, index=None)¶

Adds load to interface

Add a load perturbation to the interface with the given index. If no index is provided, the load will be added to all interfaces. If the index is an integer, the load will be added to the interface with that index. Finally, the index can be an interable (list or tuple) of integers, and the load will be added to all interfaces in the iterable. Indices that are out of bounds or indicate an interface that is not frictional will raise an error. Default value is None (all interfaces).

newload must be a load perturbation (i.e. have type ~fdfault.load), or the code will raise an error. newload will be appended to the load list

Parameters:	newload (load) – Load to be added index (int or tuple or list or None) – Interface to which the load should be added. Can be a single integer, iterable of integers, or `None` to add to all interfaces (default is `None`)
Returns:	None

add_output(item)¶

Adds output item to output list

Add new output item item to output list. item must have type output or the code will raise an error. The item will be added to the end of the list (order is not important for output lists)

Parameters:	item (output) – New output item
Returns:	None

add_pert(newpert, index=None)¶

Add new friction parameter perturbation to an interface

Method adds a frictional parameter perturbation to an interface. newpert must be a parameter perturbation of the correct kind for the given interface type (i.e. if the interface is of type slipweak, then newpert must have type swparam).

index indicates the index of the interface to which the perturbation will be added. index can be a single integer index, an iterable containing multiple indices, or None to add to all interfaces (default behavior is None). Out of bounds values will raise an error.

Parameters:	newpert (pert (more precisely, one of the derived classes of friction parameter perturbations)) – New perturbation to be added. Must have a type that matches the interface(s) in question. index (int or list or tuple or None) – Index of interface to which the perturbation will be added (single index or iterable of indices, or `None` for all interfaces, optional)
Returns:	None

check()¶

Checks problem for errors

No inputs, no return value, and the problem will not be modified.

This is run automatically when calling write_input. You may also run it manually to see if the problem contains self-consistent input values.

In addition to checking values relevant to the problem class, check is run for all relevant classes contained in a rupture problem. This includes domain (which will also run check on itself, as well as any included output units (which are individually checked against the total number of spatial grid points and time steps in the simulation). However, it will only print a warning and the input file will still be written if any of these situations fail (this is mostly to alert the user, as the C++ code will simply adjust the relevant indices to fall within the values in the simulation).

Returns:	None

delete_block_surf(coords, loc)¶

Removes boundary surface for a particular block edge

Removes the bounding surface of a particular block edge. The block is selected by using coords, which is a tuple or list of 3 integers indicated block coordinates. Within that block, location is determined by loc which is an integer that indexes into a list. Locations correspond to the following: 0 = left, 1 = right, 2 = front, 3 = back, 4 = bottom, 5 = top. Note that the location must be 0 <= loc < 2*ndim

If coords or loc is out of bounds, the code will also signal an error.

Parameters:	coords (tuple or list) – Coordaintes of desired block (tuple or list of 3 integers) loc (int) – Location of desired boundary to be removed (0 = left, 1 = right, 2 = front, 3 = back, 4 = bottom, 5 = top). For 2D problems, `loc` must be between 0 and 3.
Returns:	None

delete_load(niface, index=-1)¶

Deletes load from index niface at position index from the list of loads

Deletes loads from a frictional interface. niface is an index refering to the desired interface. Out of bounds values or interfaces that are not frictional will result in an error.

index indicates the position in the load list that should be deleted. Default for index is -1 (most recently added).

Parameters:	niface (int) – Interface from which the load should be removed. `niface` must refer to a frictional interface index (int) – Index within the load perturbation that should be removed (default is last)
Returns:	None

delete_loadfile(niface)¶

Deletes loadfile for given interface

Deletes the loadfile for the specified interface. niface is the index of the interface from which to delete the loadfile, and values that are not valid indices, or indices that refer to non-frictional interfaces will result in an error.

Parameters:	niface (int) – Index of interface for loadfile removal
Returns:	None

delete_output(index=-1)¶

Delete output item

Deletes the output item at the given location index within the output list. If no index is provided, it pops the most recently added item.

Parameters:	index (int) – Index of output item to remove
Returns:	None

delete_paramfile(niface)¶

Deletes friction parameter file for given interface

Removes the friction parameter file for the interface with index niface. The interface in question must be a frictional interface that can accept parameter files.

Parameters:	niface (int) – Index of interface that will have its paramfile removed
Returns:	None

delete_pert(niface, index=-1)¶

Deletes frictional parameter perturbation from interface

niface is an integer indicating the index of the desired interface. If out of bounds, will give an error.

index is an integer that indicates the position within the list of perturbations. Default is most recently added (-1).

Parameters:	niface (int) – Index of interface from which to remove the parameter perturbation index (int) – Index within perturbation list of the given interface to remove. Default is last item (-1, or most recently added)
Returns:	None

delete_statefile(niface)¶

Deletes statefile for given interface

Delete the statefile for a given interface. niface must be a valid index that refers to an interface with a state variable. Will set the statefile attribute for the interface to None.

Parameters:	niface (int) – Index of interface that will have its statefile removed
Returns:	None

find_nearest_point(point, known=None, knownloc=None)¶

Finds the coordinate indices closest to a desired set of grid values

Method takes a set of grid values (tuple or list of 2 or 3 floats) and finds the indices of the grid point closest to that location (in terms of Euclidean distance). The method returns a set of coordinates (tuple of length 3 of integers) of point that is closest to the input point.

The method also allows you to search along a given interface. To do this, you must pass known = 'x' (or 'y' or 'z' depending on the normal direction of the interface) and the known index in knownloc (integer value, which does not necessarily need to be on an interface – it just fixes that coordinate when performing the search)

The location is found using an iterative binary search algorithm. The search begins along the x direction using binary search until the distance to the desired point’s x coordinate is minimized. The search then proceeds in the y and z directions. The algorithm then searches again in the x direction, y direction, and z direction, until the coordinates do not change over an entire iteration. This iteration procedure needs to take place because the coordinate directions are not independent. The algorithm is usually fairly efficient and finds coordinates fairly quickly.

Parameters:	point (tuple or list) – Desired spatial location (tuple or list of floats) known (str or None) – Spatial direction to fix during search (optional, string) knownloc (int or None) – Fixed coordinate value along `known` direction (optional, integer)
Returns:	Closest spatial coordinate (tuple of 3 integers)
Return type:	tuple

get_block_lx(coords)¶

Returns physical size of a block with a given set of coordinates. Note that this assumes the block is rectangular. It can be overridden by setting the edge of a block to be a curve (2D) or surface (3D), so this is not always the definitive size of a block.

Parameters:	coords (tuple or list) – Coordinates of desired block (tuple or list of three integers)
Returns:	Dimensions of desired block (tuple of three floats)
Return type:	tuple

get_block_surf(coords, loc)¶

Returns block boundary surface for a block edge

Returns the surface assigned to a specific block along a specific edge. The block is chosen using coords which is a tuple or list of 3 positive integers that corresponds to the coordinates of the block. Within that block, loc determines the edge that is returned (integer, corresponding to an index). Location indices correspond to the following: 0 = left, 1 = right, 2 = front, 3 = back, 4 = bottom, 5 = top Note that the location must be 0 <= loc < 2*ndim (for 2D problems, loc cannot be 5 or 6).

Returns either a curve (2D problems) or surface (3D problems) or None

If coords or loc indices are out of bounds, the code will raise an error.

Parameters:	coords (tuple or list) – Coordaintes of desired block (tuple or list of 3 integers) loc (int) – Location of desired boundary (0 = left, 1 = right, 2 = front, 3 = back, 4 = bottom, 5 = top). For 2D problems, `loc` must be between 0 and 3.
Returns:	curve or surface corresponding to the selected block and location. If the desired edge does not have a bounding surface, returns None.
Return type:	curve or surface or None

get_block_xm(coords)¶

Returns starting index (zero-indexed) of each block (list of three lists of integers)

Parameters:	coords (tuple or list) – Coordinates of desired block (tuple or list of three integers)
Returns:	list of three lists (each list is a list of integers)
Return type:	list

get_bm(index)¶

Returns block in minus direction of interface index. Returns a tuple of 3 integers indicating block coordinates of target block

Parameters:	index (int) – index of desired interface (zero-indexed)
Returns:	tuple

get_bounds(coords, loc=None)¶

Returns boundary types of a particular block

If loc (int) is provided, the method returns a specific location (str). Otherwise it returns a list of all boundaries, which will have length 4 for 2D problems and length 6 for 3D problems. loc serves effectively as an index into the list, and the indices correspond to the following: 0 = left, 1 = right, 2 = front, 3 = back, 4 = bottom, 5 = top. Note that the location must be 0 <= loc < 2*ndim

Parameters:	coords (tuple) – Block coordinate location (list or tuple of three integers) loc (int or None) – Location of boundary that is desired (optional). If `loc` is not provided, returns a list
Returns:	Boundary type (if `loc` provided, returns a string of the boundary type for the desired location, of not returns a list of strings indicating all boundary types)
Return type:	str or list

get_bp(index)¶

Returns block in plus direction of interface index. Returns a tuple of 3 integers indicating block coordinates of target block

Parameters:	index (int) – index of desired interface (zero-indexed)
Returns:	tuple

get_cdiss()¶

Returns artificial dissipation coefficient

Returns:	Artificial dissipation coefficient
Return type:	float

get_cfl()¶

Returns Courant ratio (dt * wave speed / grid spacing)

Returns:	Courant ratio
Return type:	float

get_datadir()¶

Returns data directory (data directory can be a relative or absolute path)

Returns:	Data directory
Return type:	str

get_direction(index)¶

Returns direction (formally, normal direction in computational space) of interface with given index Returns a string ‘x’, ‘y’, or ‘z’, which is the normal direction for a simulation with rectangular blocks

Parameters:	index (int) – index of desired interface (zero-indexed)
Returns:	str

get_dt()¶

Returns time step size

Returns:	Time step size
Return type:	float

get_front_field()¶

Returns front field

Returns:	Rupture front field (string, “U” denotes slip and “V” denotes slip velocity)
Return type:	str

get_front_output()¶

Returns status of front output (boolean)

Returns:	Status of front output
Return type:	bool

get_front_value()¶

Returns front threshold value. Front output is the earliest time at which the given field exceeds this value

Returns:	Threshold value for rupture front output
Return type:	float

get_het_material()¶

Returns heterogeneous material properties for simulation

Returns a numpy array with shape (3, nx, ny, nz). First index indicates parameter value (0 = density, 1 = Lame parameter, 2 = Shear modulus). The other three indicate grid coordinates. If no heterogeneous material parameters are specified, returns None

Returns:	ndarray

get_het_stress()¶

Returns heterogeneous stress initial values.

Returns a numpy array with shape (ns, nx, ny, nz). First index indicates stress component. The following three indices indicate grid coordinates.If no array is currently specified, returns None.

For 2D mode 3 problems, indices for ns are (0 = sxz, 1 = syz)

For elastic 2D mode 2 problems, indices for ns are (0 = sxx, 1 = sxy, 2 = syy). For plastic 2D mode 2 problems, indices for ns are (0 = sxx, 1 = sxy, 2 = syy, 3 = szz).

For 3D problems, indices for ns are (0 = sxx, 1 = sxy, 2 = sxz, 3 = syy, 4 = syz, 5 = szz)

Returns:	ndarray

get_iftype(index=None)¶

Returns interface type of given index, if none provided returns full list

Parameters:	index (int) – (optional) index of desired interface (zero-indexed). If not given or if `None` is given the entire list of interface types is returned
Returns:	str or list

get_load(niface, index=None)¶

Returns load for index niface at position index. If no index provided, returns entire list of perturbations

Parameters:	niface (int) – index of desire interface (zero-indexed) index (int) – (optional) index of perturbation. If not provided or None, then returns entire list
Returns:	load or list

get_loadfile(niface)¶

Returns loadfile for interface with index niface

Loadfile sets any surface tractions set for the particular interface in question. Note that these tractions are added to any any set by the constant initial stress tensor, initial heterogeneous stress, or interface traction perturbations

Parameters:	niface – index of desired interface (zero-indexed)
Returns:	Current loadfile for the interface (if the interface does not have a loadfile, returns None)
Return type:	loadfile or None

get_material(coords)¶

Returns material properties for a given block

Returns the material class associated with block with coordinates coords. coords must be a tuple or list of valid block indices

Parameters:	coords (tuple or list) – Coordinates of the target block (tuple or list of 3 nonnegative integers)
Returns:	Material class with properties for this block
Return type:	material

get_mattype()¶

Returns material type (‘elastic’ or ‘plasitc’)

Returns:	Material type
Return type:	str

get_mode()¶

Returns rupture mode (2 or 3), only valid for 2D problems (stored at domain level)

Returns:	Rupture mode
Return type:	int

get_name()¶

Returns problem name

Returns:	Problem name
Return type:	str

get_nblocks()¶

Returns number of blocks points in (nx, ny, nz) format

Returns:	Number of blocks (tuple of three integers)
Return type:	tuple

get_nblocks_tot()¶

Returns total number of blocks

Returns:	Total number of blocks
Return type:	int

get_ndim()¶

Returns Number of spatial dimensions

Returns:	Number of spatial dimensions
Return type:	int

get_nifaces()¶

Returns number of interfaces

Returns:	Number of interfaces
Return type:	int

get_ninfo()¶

Returns frequency at which information is written to the terminal during a simulation

Returns:	Frequency of terminal output
Return type:	int

get_nloads(index)¶

Returns number of loads on interface with given index

Parameters:	index – index of desire interface (zero-indexed)
Returns:	int

get_nperts(index)¶

Returns number of frictional parameter perturbations (integer) on given interface with given index

Parameters:	index (int) – index of desired interface (zero-indexed)
Returns:	int

get_nproc()¶

Returns number of processes (in x, y, z directions).

0 means MPI will do the domain decomposition in that direction automatically

Returns:	Number of processes in each spatial dimension (x, y, z) (tuple of three integers)
Return type:	tuple

get_nt()¶

Returns number of time steps

Returns:	Number of time steps
Return type:	int

get_nx()¶

Returns number of grid points in (nx, ny, nz) format

Returns:	Number of grid points (tuple of three integers)
Return type:	tuple

get_nx_block()¶

Returns number of grid points in each block along each spatial dimension

Returns:	Number of grid points in each block (list of three lists)
Return type:	list

get_output(index=None)¶

Returns output item at given index (if none give, returns entire list)

Parameters:	index (int) – (optional) index of desired output unit. If not given or if `None` is given the entire list of output units is returned
Returns:	output item or list of output items
Return type:	output or list

get_paramfile(niface)¶

Returns paramfile (holds arrays of heterogeneous friction parameters) for interface with index niface. Can return a subtype of paramfile corresponding to any of the specific friction law types.

Parameters:	niface (int) – index of desired interface (zero-indexed)
Returns:	paramfile

get_pert(niface, index=None)¶

Returns perturbation for index niface at position index

Method returns a perturbation from a particular interface. niface must be a valid integer index referring to an interface. index is the index into the perturbation list for the particular index. If index is not provided or is None, the method returns the entire list.

Parameters:	niface (int) – Index referring to an interface. (Must be a valid integer index.) index (int or None) – Index into the perturbation list for the index in question (optional, if not provided or `None`, then returns entire list)
Returns:	pert or list

get_rkorder()¶

Returns order of accuracy of time integration

Returns:	Order of accuracy of time integration
Return type:	int

get_sbporder()¶

Returns order of accuracy of finite difference method (stored at domain level)

Returns:	Order of accuracy of finite difference method
Return type:	int

get_state(niface)¶

Returns initial state variable value for interface with index niface

Parameters:	niface – index of desired interface (zero-indexed)
Returns:	Initial state variable
Return type:	float

get_statefile(niface)¶

Returns state file of given interface

If interface does not have a statefile returns None

Parameters:	niface – index of desired interface (zero-indexed)
Returns:	statefile or None

get_stress()¶

Returns uniform intial stress values

Note that 2D simulations do not use all stress components. Mode 2 elastic simulations only use sxx, sxy, and syy, and mode 3 elastic simulations use sxz, and syz (though the normal stresses sxx and syy can be set to constant values that are applied to any frictional failure criteria). Mode 2 plastic simulations use szz, and mode 3 plastic simulations use all three normal stress components in evaluating the yield criterion.

Returns:	Initial stress tensor (list of floats). Format is `[sxx, sxy, sxz, syy, syz, szz]`
Return type:	list

get_ttot()¶

Returns total simulation time ttot

Returns:	Total simulation time
Return type:	float

get_x(coord)¶

Returns grid value for given spatial index

For a given problem set up, returns the location of a particular set of coordinate indices. Note that since blocks are set up by setting values only on the edges, coordinates on the interior are not specified a priori and instead determined using transfinite interpolation to generate a regular grid on the block interiors. Calling get_x generates the interior grid to find the coordinates of the desired point.

Within each call to get_x, the grid is generated on the fly only for the relevant block where the desired point is located. It is not stored. This helps reduce memory requirements for large 3D problems (since the Python module does not run in parallel), but is slower. Because the computational grid is regular, though, it can be done in a single step in closed form.

Returns a numpy array of length 3 holding the spatial location (x, y, z).

Parameters:	coord (tuple or list) – Spatial coordinate where grid values are desired (tuple or list of 3 integers)
Returns:	(x, y, z) coordinates of spatial location
Return type:	ndarray

set_block_lx(coords, lx)¶

Sets block with coordinates coords to have dimension lx

coords is a tuple of nonnegative integers that indicates the coordinates of the desired block (0-indexed, must be less than the number of blocks in that particular direction or the code will raise an error). lx is a tuple of two (2D) or three (3D) positive floats indicating the block length in each spatial dimension. Note that this assumes each block is rectangular. When a single block is modified, the code automatically adjusts the lower left corner of all simulation blocks to be consistent with this change.

This can be overridden by setting a block edge to be a curve (2D) or surface (3D). However, traction and friction parameter perturbations still make use of these block lengths when altering interface tractions or friction parameters. More information on how this works is provided in the pert documentation.

Finally, note that neighboring blocks must have conforming grids. When writing simulation data to file, the code checks that all interfacial grids match, and raises an error if it disagrees. So while the set_block_lx method may not complain about an error like this, you will not be able to save the simulation to a file with such an error.

Parameters:	coords (tuple or list) – Coordinates (tuple or list of 3 nonnegative integers) lx (tuple or list) – New dimensions of desired block (tuple or list of 2 or 3 positive floats)
Returns:	None

set_block_surf(coords, loc, surf)¶

Sets boundary surface for a particular block edge

Changes the bounding surface of a particular block edge. The block is selected by using coords, which is a tuple or list of 3 integers indicated block coordinates. Within that block, location is determined by loc which is an integer that indexes into a list. Locations correspond to the following: 0 = left, 1 = right, 2 = front, 3 = back, 4 = bottom, 5 = top. Note that the location must be 0 <= loc < 2*ndim

For 2D problems, surf must be a curve. For 3D problems, surf must be a surface. Other choices will raise an error. If coords or loc is out of bounds, the code will also signal an error.

Parameters:	coords (tuple or list) – Coordaintes of desired block (tuple or list of 3 integers) loc (int) – Location of desired boundary (0 = left, 1 = right, 2 = front, 3 = back, 4 = bottom, 5 = top). For 2D problems, `loc` must be between 0 and 3. surf (curve or surface) – curve or surface corresponding to the selected block and location
Returns:	None

set_bounds(coords, bounds, loc=None)¶

Sets boundary types of a particular block.

Changes the type of boundary conditions on a block. Acceptable values are ‘absorbing’ (incoming wave amplitude set to zero), ‘free’ (no traction on boundary), ‘rigid’ (no displacement of boundary), or ‘none’ (boundary conditions set by imposing interface conditions).

The block to be modified is determined by coords, which is a tuple or list of 3 integers that match the coordinates of a block.

There are two ways to use set_bounds:

Set loc to be None (default) and provide a list of strings specifying boundary type for bounds. The length of bounds is 4 for a 2D simulation and 6 for 3D.
Set loc to be an integer denoting location and give bounds as a single string. The possible locations correspond to the following: 0 = left, 1 = right, 2 = front, 3 = back, 4 = bottom, 5 = top. 4 and 5 are only applicable to 3D simulations (0 <= loc < 2*ndim).

Parameters:	coords (tuple or list) – Location of block to be modifies (tuple or list of 3 integers) bounds (str or list) – New boundary condition type (string or list of strings) loc (int or None) – If provided, only change one type of boundary condition rather than all (optional, loc serves as an index into the list if used)
Returns:	None

set_cdiss(cdiss)¶

Sets artificial dissipation coefficient

New artificial dissipation coefficient must be nonnegative. If it is set to zero, the code will not use artificial dissipation in the simulation.

There is not a hard and fast rule for setting the coefficient, so some degree of trial and error may be necessary. Values around 0.1 have worked well in the past, but that may not be true for all meshes.

Parameters:	cdiss (float) – New artificial dissipation coefficient
Returns:	None

set_cfl(cfl)¶

Sets CFL ratio The CFL ratio must be between 0. and 1. If the provided value is not a float, it will be converted into a float

The four variables related to the time step provide several ways to set the time step. You can set the time step using any pair of the variables except the time step and the Courant ratio. If you provide more than two, the code defaults to the total time and either the time step or the Courant ratio if the time step is not provided.

Parameters:	cfl (float) – New value for the CFL ratio
Returns:	None

set_datadir(datadir)¶

Sets problem data directory to new value Method checks if datadir is a string and ends in ‘/’, but does not check that it is a valid path

Parameters:	name (str) – New problem data directory (must be a string)
Returns:	None

set_domain_xm(xm)¶

Sets lower left corner of domain to spatial coordinate xm

Moves the lower left corner of the simulation. This does not affect block lengths, only the minimum spatial location of the entire comain in each cartesian direction. Individual block locations are calculated automatically from this and the length information for each block. Thus, you cannot set the location of each block directly, just the overall value of the domain and then all other blocks are positioned based on the length of other blocks.

If the simulation is 2D and a nonzero value for the z-coordinate is provided, the z position of all blocks will be automatically set to zero.

Note that the location of any block can be overridden by setting the edges to be surfaces. The corners must still match one another (this is checked when writing the simulation data to file), and neighboring blocks must have conforming grids at the edges.

Parameters:	xm (tuple or list) – New lower left coordinate of simulation domain (tuple of 2 or 3 floats)
Returns:	None

set_dt(dt)¶

Sets time step New time step cannot be negative (will trigger an error) If time step is not a float, it is converted to a float

The four variables related to the time step provide several ways to set the time step. You can set the time step using any pair of the variables except the time step and the Courant ratio. If you provide more than two, the code defaults to the total time and either the time step or the Courant ratio if the time step is not provided.

Parameters:	dt (float) – New time step
Returns:	None

set_front_field(field)¶

Sets rupture front field

Sets new value of rupture front field field. field must be a string (slip ('U') or slip velocity ('V')). Other choices will raise an error.

Parameters:	field (str) – New rupture front field
Returns:	None

set_front_output(output)¶

Sets front output to be on or off

Sets rupture front output to be the specified value (boolean). Will raise an error if the provided value cannot be converted into a boolean.

Parameters:	output (bool) – New value of output
Returns:	None

set_front_value(value)¶

Sets front threshold value

Changes value of rupture front threshold. The rupture time is the earliest time at which the chosen field exceeds this value. value is the new value (must be a positive number).

Parameters:	value (float) – New values of the threshold for rupture front times.
Returns:	None

set_het_material(mat)¶

Sets heterogeneous material properties for simulation

New heterogeneous material properties must be a numpy array with shape (3, nx, ny, nz). First index indicates parameter value (0 = density, 1 = Lame parameter, 2 = Shear modulus). The other three indicate grid coordinates

Parameters:	mat (ndarray) – New material properties array (numpy array with shape `(3, nx, ny, nz)`)
Returns:	None

set_het_stress(s)¶

Sets heterogeneous stress initial values

Sets initial heterogeneous stress. New stress must be a numpy array with shape (ns, nx, ny, nz). First index indicates stress component. The following three indices indicate grid coordinates.

For 2D mode 3 problems, indices for ns are (0 = sxz, 1 = syz)

For elastic 2D mode 2 problems, indices for ns are (0 = sxx, 1 = sxy, 2 = syy). For plastic 2D mode 2 problems, indices for ns are (0 = sxx, 1 = sxy, 2 = syy, 3 = szz).

For 3D problems, indices for ns are (0 = sxx, 1 = sxy, 2 = sxz, 3 = syy, 4 = syz, 5 = szz)

Parameters:	s (ndarray) – New heterogeneous stress array (numpy array with shape `(3, nx, ny, nz)`
Returns:	None

set_iftype(index, iftype)¶

Sets type of interface with a given index

Changes type of a particular interface. index is the index of the interface to be modified and iftype is a string denoting the interface type. Valid values for iftype are 'locked', 'frictionless', 'slipweak', and 'stz'. Any other values will result in an error, as will an interface index that is out of bounds.

Parameters:	index (int) – Index (nonnegative integer) of interface to be modified iftype (str) – New interface type (see valid values above)
Returns:	None

set_loadfile(niface, newloadfile)¶

Sets loadfile for interface with index niface

niface indicates the index of the interface that will be modified, and must be a frictional interface. newloadfile is the new loadfile (must have type loadfile). If the index is bad or the loadfile type is not correct, the code will raise an error. Errors can also result if the shape of the loadfile does not match with the interface.

Parameters:	niface – index of desired interface (zero-indexed) newloadfile (loadfile) – New loadfile to be used for the given interface
Returns:	None

set_material(newmaterial, coords=None)¶

Sets block material properties for the block with indices given by coords

If coords is not provided, all blocks are changed to have the given material properties. newmaterial must have a type material and coords must be a tuple or list of three integers that match the coordinates of a block.

If set_material changes all blocks in the simulation, it also changes the material type for the whole simulation (equivalent to calling set_mattype). If set_material acts only on a single block, the new material type of that block must match the one set in the fields type (i.e. the return value of get_mattype).

Parameters:	newmaterial (material) – New material properties coords (tuple or list) – Coordinates of block to be changed (optional, omitting changes all blocks). `coords` must be a tuple or list of three integers that match the coordinates of a block.
Returns:	None

set_mattype(mattype)¶

Sets field and block material type (‘elastic’ or ‘plastic’)

Sets the material type for the simulation. Options are ‘elastic’ for an elastic simulation and ‘plastic’ for a plastic simulation. Anything else besides these options will cause the code to raise an error.

Once the simulation type is altered, all blocks material types are changed as well. This is necessary to ensure that the right set of parameters are written to file. Note that all blocks must therefore have the same material type, though you can ensure that a given block always behaves elastically by setting an appropriate value for the yield criterion.

Parameters:	mattype (str) – New material type (‘elastic’ or ‘plastic’)
Returns:	None

set_mode(mode)¶

Sets rupture mode

Rupture mode is only valid for 2D problems, and is either 2 or 3 (other values will cause an error, and non-integer values will be converted to integers). For 3D problems, entering a different value of the rupture mode will alter the rupture mode cosmetically but will have no effect on the simulation.

Parameters:	mode (int) – New value of rupture mode
Returns:	None

set_name(name)¶

Sets problem name

Parameters:	name (str) – New problem name (must be a string)
Returns:	None

set_nblocks(nblocks)¶

Sets number of blocks

set_nblocks alters the number of blocks in the simulation. The method adds or deletes blocks from the list of blocks as needed. Depending on how the number of blocks is changed, new blocks may only have a single grid point, or if added in a direction where the number of blocks is already established the number of grid points may be copied from the existing simulation. If in doubt, use get_nx_block to check the number of grid points and use set_nx_block to modify if necessary.

Parameters:	nblocks (tuple) – New number of blocks (tuple of 3 positive integers)
Returns:	None

set_ndim(ndim)¶

Sets number of dimensions

The new number of spatial dimensions must be an integer, either 2 or 3. If a different value is given, the code will raise an error. If a non-integer value is given that is acceptable, the code will convert it to an integer.

Note: Converting a 3D problem into a 2D problem will automatically collapse the number of grid points and the number of blocks in the $z$ direction to be 1. Any modifications to these quantities that were done previously will be lost.

Parameters:	ndim (int) – New value for ndim (must be 2 or 3)
Returns:	None

set_ninfo(ninfo)¶

Sets frequency of information output

The simulation will write out information to the terminal after each ninfo time steps. ninfo must be a positive integer (if less than zero, will trigger an error). ninfo is converted into an integer.

Parameters:	ninfo (int) – New value of ninfo
Returns:	None

set_nproc(nproc)¶

Sets number of processes in domain decomposition manually

New number of processes nproc must be a tuple/list of nonnegative integers. If the problem is 2D, the number of processes in the z direction will automatically be set to 1. Any number can be set to zero, in which case MPI will set the number of processes in that direction automatically. If all three numbers are nonzero, then it is up to the user to ensure that the total number of processors ($nx imes ny imes nz$) is the same as the total number when running the executable.

Parameters:	nproc (tuple) – New number of processes (must be a tuple of positive integers)
Returns:	None

set_nt(nt)¶

Sets number of time steps New number of time steps cannot be negative (will trigger an error) If number of time steps is not an integer, it is converted to an integer

The four variables related to the time step provide several ways to set the time step. You can set the time step using any pair of the variables except the time step and the Courant ratio. If you provide more than two, the code defaults to the total time and either the time step or the Courant ratio if the time step is not provided.

Parameters:	nt (int) – New number of time steps
Returns:	None

set_nx_block(nx_block)¶

Set number of grid points in each block as a list of lists.

Input must be a list or tuple of length 3, with each item a list of integers representing the number of grid points for each block along the respective dimension. If the list lengths do not match the number of blocks, the code will raise an error. The blocks must form a regular cartesian grid with conforming edges, so all blocks along a single spatial dimension must have the same number of grid points along that spatial dimension.

For example, if nblocks = (3,2,1), then nblock[0] has length 3, nblock[1] has length 2, and nblock[2] has length 1. All blocks that are at position 0 in the x-direction will have nblock[0][0] grid points in the x-direction, all blocks at position 1 in the x-direction will have nblock[0][1] grid points in the x-direction, etc.

Parameters:	nx_block (list) – New number of grid points (list of 3 lists of positive integers)
Returns:	None

set_paramfile(niface, newparamfile)¶

Sets paramfile for given interface

Method sets the file holding frictional parameters for an interface. Interface to be modified is set by niface, which must be a valid index for an interface.

newparamfile must be a parameter perturbation file of the correct type for the given interface type (i.e. if the interface is of type slipweak, then newpert must have type swparamfile). Errors can also result if the shape of the paramfile does not match with the interface.

Parameters:	niface (int) – index of desired interface (zero-indexed) newparamfile (paramfile (actual type must be the appropriate subclass for the friction law of the particular interface and have the right shape)) – New frictional parameter file (type depends on interface in question)
Returns:	None

set_rkorder(rkorder)¶

Sets order of low storage RK method (integer 1-4).

Value is converted to an integer, and error will be signaled if a different value is given outside of this range.

Parameters:	rkorder (int) – New value of order of accuracy of integration
Returns:	None

set_sbporder(sbporder)¶

Sets finite difference order

Finite difference method order must be an integer 2-4. A value outside of this range will result in an error. If a non-integer value is given that is acceptable, it will be converted to an integer and there will be no error message.

Parameters:	sbporder (int) – New value of finite difference method order (integer 2-4)
Returns:	None

set_state(niface, state)¶

Sets initial state variable for interface

Set the initial value for the state variable for a given interface. niface is the index of the interface to be set (must be a valid integer index). The interface must have a state variable associated with it, or an error will occur. state is the new state variable (must be a float or some other valid number).

Parameters:	niface (int) – Index of interface to modify. Must be an interface with a state variable state (float) – New value of state variable
Returns:	None

set_statefile(niface, newstatefile)¶

Sets state file for interface

Set the statefile for the indicated interface. niface must be a valid index to an interface, out of bounds values will lead to an error. newstatefile``must have type ``statefile and the interface must support a state variable. Errors can also result if the shape of the statefile does not match with the interface.

Parameters:	niface (int) – Index of interface to be modified newstatefile (statefile) – New statefile for the interface in question.
Returns:	None

set_stress(s)¶

Sets uniform intial stress

Changes initial uniform stress tensor. New stress tensor must be a list of six floats.

Note that 2D simulations do not use all stress components. Mode 2 elastic simulations only use sxx, sxy, and syy, and mode 3 elastic simulations use sxz, and syz (though the normal stresses sxx and syy can be set to constant values that are applied to any frictional failure criteria). Mode 2 plastic simulations use szz, and mode 3 plastic simulations use all three normal stress components in evaluating the yield criterion.

Params s:	New stress tensor (list of 6 floats). Format is `[sxx, sxy, sxz, syy, syz, szz]`
Returns:	None

set_ttot(ttot)¶

Sets total simulation time Total time cannot be negative (will trigger an error) If total time is not a float, it is converted to a float

The four variables related to the time step provide several ways to set the time step. You can set the time step using any pair of the variables except the time step and the Courant ratio. If you provide more than two, the code defaults to the total time and either the time step or the Courant ratio if the time step is not provided.

Parameters:	ttot (float) – New value for total time
Returns:	None

write_input(filename=None, directory=None, endian='=')¶

Writes problem to input file

Method writes the current state of a problem to an input file, also writing any binary data to file (i.e. block boundary curves, heterogeneous stress tensors, heterogeneous material properties, heterogeneous interface tractions, heterogeneous state variables, or heterogeneous friction parameters).

All input arguments are optional. Possible arguments include filename (string, default is problem name) which will set the input file name (the code adds on .in to the provided filename), directory (string holding the path to the location where the file will be written, default is current directory), and endian to set byte-ordering for writing binary files (default is = (native), other options inlcude < (little) and > (big)).

When write_input is called, the code calls check, which verifies the validity of the simulation and alerts the user to any problems. check examines if block surface edges match, if neighboring blocks have matching grids, and other things that cannot be checked when modifying the simulation. The same checks are run in the C++ code when initializing a problem, so a problem that runs into trouble when calling check is likely to have similar difficulties when running the simulation.

Parameters:

filename (str) – name of file (default is problem name); code will add .in to this
directory (str) – Location where input file should be written (default current directory)
endian – Byte-ordering for files. Should match byte ordering of the system where the simulation will be run (it helps to run the Python script directly with native byte ordering enabled). Default is native (=), other options include < for little endian and > for big endian.

Returns:

None

Previous topic

Next topic

This Page

The `problem` Class¶

The problem Class¶

The `problem` Class¶