The `domain` Class¶

The domain class holds information regarding the physical problem setup. This includes the problem dimension, rupture mode, if a problem is an elastic or plastic simulation, number of blocks and interfaces, grid spacing, finite difference method, and parallelization.

The user does not typically interact directly with domain objects, as all problems automatically contain one (and can only handle one) domain. All methods in domain contain interfaces through the problem object, and these wrapper functions should be the preferred method for altering a problem. Documentation is provided here for completeness.

class fdfault.domain¶

Class describing rupture problem domain

When initializing a domain, one is created with default attributes, including:

Variables:

ndim (int) – Number of spatial dimensions (2 or 3; default is 2)
mode (int) – Rupture mode (2 or 3, default is 2; only relevant for 2D problems)
mattype (str) – Simulation material type ('elastic' or 'plastic', default is 'elastic')
nx (tuple) – Number of grid points (tuple of 3 integers, default (1,1,1)). This cannot be modified as it is set automatically when modifying nx_block.
nblocks (tuple) – Number of blocks in each spatial dimension (tuple of 3 integers). Blocks must form a Cartesian grid.
nx_block (tuple) – Number of grid points for each block along each spatial dimension. Represented as a tuple of lists. Default is ([1], [1], [1]). Note that modifying nx_block automatically changes nx to match.
xm_block (tuple) – Grid location of minimum grid point in each block in each spatial dimension. This is also calculated automatically based on the values of nx_block, and cannot be modified directly. Represented as a tuple of lists, default is ([0], [0], [0]).
nifaces (int) – Number of interfaces (integer, default is zero). This is automatically set when nblocks is changed, and is not set by the user. Order is not important here, but when generating interfaces the code orders them by first creating all 'x' interfaces, then all 'y' interfaces, then all 'z' interfaces.
iftype (list) – List holding type of all interfaces (list of strings). Can be modified by changing interface type for a single interface. When a new interface is created it is by default a 'locked' interface.
sbporder (int) – Finite difference method order (integer 2-4, default 2).
nproc (tuple) – Number of processes in each dimension for parallelization. Represented as a tuple of integers (default (0,0,0)). A zero in a given dimension indicates that the number of processes in that direction will be set automatically. Thus, (0,0,0) indicates that the entire decomposition process will be automated, while (0,2,1) fixes the number of processes in the y and z directions (x will still be determined automatically). Note that specifying all three numbers requires that the product of all three numbers match the total number of processes selected when running the simulation.
cdiss (float) – Artificial dissipation coefficient (float, default 0.). A nonzero value will turn on artificial dissipation in the simulation. It is up to the user to select this value correctly.

__init__()¶

Create a new instance of a domain class

Initializes a new domain with a 2D mode 2 rupture containing a single elastic block. The block has the default material properties, one grid point in each direction, unit length in each direction, and the block is located at (0., 0., 0.) in space. The domain has a default finite difference order of 2 and no artificial dissipation. All defaults can be modified using the provided interfaces in the class.

Returns:	New `domain` instance with default properties
Return type:	domain

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 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_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 domain 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. Checks that all block corners match and all neighboring block edge grids conform.

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_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 loads. 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_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_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_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_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 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_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_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_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_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_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_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

An array with the wrong shape will result in an error.

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)

Providing arrays of the incorrect size will result in an error.

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_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_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_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_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

write_input(f, probname, directory, endian='=')¶

Writes domain information to input file

Method writes the current state of a domain 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).

Arguments include the input file f (file handle), problem name probname (string), output directory directory, and endianness of binary files ``endian. endian has a default value of = (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:

f (file) – file handle for text input file
probname (str) – problem name (used for any binary files)
directory (str) – Location where input file should be written
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 `domain` Class¶

The domain Class¶

The `domain` Class¶