The friction Class

The friction class is the parent class of all frictional interfaces. Information on setting load perturbations is provided here, as this is common to all friction laws.

class fdfault.friction(ndim, index, direction, bm, bp)

Class representing a frictionless interface between blocks

This is the parent class of all other frictional interfaces. The friction class describes frictionless interfaces. While this interface type does not require any parameter specifications, it does calculate slip from traction and thus the interface tractions are relevant. Therefore, it allows for the user to specify interface tractions that are added to the stress changes calculated by the code. These tractions can be set either as “perturbations” (tractions following some pre-specified mathematical form), or “load files” where the tractions are set point-by-point and thus can be arbitrarily complex.

Frictionless interfaces have the following attributes:

Variables:

• ndim – Number of dimensions in problem (2 or 3)
• iftype – Type of interface (‘locked’ for all standard interfaces)
• index – index of interface (used for identification purposes only, order is irrelevant in simulation)
• bm – Indices of block in the “minus” direction (tuple of 3 integers)
• bp – Indices of block in the “plus” direction (tuple of 3 integers)
• direction – Normal direction in computational space (“x”, “y”, or “z”)
• nloads – Number of load perturbations (length of loads list)
• loads – List of load perturbations
• lf – Loadfile holding traction at each point

__init__(ndim, index, direction, bm, bp)

Initializes an instance of the friction class

Create a new friction given an index, direction, and block coordinates.

Parameters:

• ndim (int) – Number of spatial dimensions (must be 2 or 3)
• index (int) – Interface index, used for bookkeeping purposes, must be nonnegative
• direction (str) – String indicating normal direction of interface in computational space, must be 'x', 'y', or 'z', with 'z' only allowed for 3D problems)
• bm (tuple) – Coordinates of block in minus direction (tuple of length 3 of integers)
• bp (tuple) – Coordinates of block in plus direction (tuple of length 3 or integers, must differ from bm by 1 only along the given direction to ensure blocks are neighboring one another)

Returns:

New instance of friction class

Return type:

friction

add_load(newload)

Adds a load to list of load perturbations

Method adds the load provided to the list of load perturbations. If the newload parameter is not a load perturbation, this will result in an error.

Parameters:newload (fdfault.load) – New load to be added to the interface (must have type load) Returns:None

add_pert(newpert)

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).

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. Returns:None

delete_load(index=-1)

Deletes load at position index from the list of loads

Method deletes the load from the list of loads at position index. Default is most recently added load if an index is not provided. index must be a valid index into the list of loads.

Parameters:index (int) – Position within load list to remove (optional, default is -1) Returns:None

delete_loadfile()

Deletes the loadfile for the interface.

Returns:None

delete_paramfile()

Deletes friction parameter file for the interface

Removes the friction parameter file for the interface. The interface must be a frictional interface that can accept parameter files.

Returns:None

delete_pert(index=-1)

Deletes frictional parameter perturbation from interface

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

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

get_bm()

Returns block on negative side

Returns tuple of block indices on negative size

Returns:Block indices on negative side (tuple of integers) Return type:tuple

get_bp()

Returns block on positive side

Returns tuple of block indices on positive size

Returns:Block indices on positive side (tuple of integers) Return type:tuple

get_direction()

Returns interface orientation

Returns orientation (string indicating normal direction in computational space).

Returns:Interface orientation in computational space (‘x’, ‘y’, or ‘z’) Return type:str

get_index()

Returns index

Returns the numerical index corresponding to the interface in question. Note that this is just for bookkeeping purposes, the interfaces may be arranged in any order as long as no index is repeated. The code will automatically handle the indices, so this is typically not modified in any way.

Returns:Interface index Return type:int

get_load(index=None)

Returns load at position index

Returns a load from the list of load perturbations at position index. If no index is provided (or None is given), the method returns entire list. index must be a valid list index given the number of loads.

Parameters:index (int or None) – Index within load list (optional, default is None to return full list) Returns:load or list

get_loadfile()

Returns loadfile for interface

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

Returns:Current loadfile for the interface (if the interface does not have a loadfile, returns None) Return type:loadfile or None

get_nloads()

Returns number of load perturbations on the interface

Method returns the number of load perturbations presently in the list of loads.

Returns:Number of load perturbations Return type:int

get_nperts()

Returns number of friction parameter perturbations on interface

Method returns the number of parameter perturbations for the list

Returns:Number of parameter perturbations Return type:int

get_paramfile()

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

Returns:paramfile

get_pert(index=None)

Returns perturbation at position index

Method returns a perturbation from the 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: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_type()

Returns string of interface type

Returns the type of the given interface (“locked”, “frictionless”, “slipweak”, or “stz”)

Returns:Interface type Return type:str

set_index(index)

Sets interface index

Changes value of interface index. New index must be a nonnegative integer

Parameters:index (int) – New value of index (nonnegative integer) Returns:None

set_loadfile(newloadfile)

Sets loadfile for 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:newloadfile (loadfile) – New loadfile to be used for the given interface Returns:None

set_paramfile(newparamfile)

Sets paramfile for the interface

Method sets the file holding frictional parameters for the 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: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

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

Writes interface details to input file

This routine is called for every interface when writing problem data to file. It writes the appropriate section for the interface in the input file. It also writes any necessary binary files holding interface loads, parameters, or state variables.

Parameters:

• f (file) – File handle for input file
• probname (str) – problem name (used for naming binary files)
• directory (str) – Directory for output
• endian (str) – Byte ordering for binary files ('<' little endian, '>' big endian, '=' native, default is native)

Returns:

None

class fdfault.load(perttype='constant', t0=0.0, x0=0.0, dx=0.0, y0=0.0, dy=0.0, sn=0.0, s2=0.0, s3=0.0)

Class representing load perturbations to frictional interfaces

The load class represents interface traction perturbations that can be expressed in a simple functional form. The load class holds information on the shape of the perturbation and the three traction components to be applied to the interface.

Perturbations have the following attributes:

Variables:

• perttype – String describing perturbation shape. See available types below.
• t0 – Perturbation onset time (linear ramp function that attains its maximum at t0; t0 = 0. means perturbation is on at all times)
• x0 – Perturbation location along first spatial dimension (see below for details)
• dx – Perturbation scale along first spatial dimension (see below for details)
• y0 – Perturbation location along second spatial dimension (see below for details)
• dy – Perturbation scale along second spatial dimension (see below for details)
• sn – Normal traction perturbation
• s2 – In-plane shear traction perturbation
• s3 – Out of plane shear traction perturbation

By default, all time, shape, and load parameters are set to zero.

There are several available types of perturbations:

• 'constant' – A spatially uniform perturbation. All spatial information is ignored
• 'boxcar' – Perturbation is constant within a rectangle centered at (x0, y0) with a half width of (dx, dy) in each spatial dimension
• 'ellipse' – Perturbation is constant within an ellipse centered at (x0, y0) with half axis lengths of (x0, y0)
• 'gaussian' – Perturbation follows a Gaussian function centered at (x0, y0) with standard deviations (dx, dy) in each spatial dimension
• 'linear' – Perturbation is a linear function with intercept x0 and slope 1/dx in the first spatial dimension and intercept y0 and slope 1/dy in the second spatial dimension. If either dx or dy is zero, the linear function is constant in that particular spatial dimension (i.e. set dy = 0. if you want to have a function that is only linear in the first spatial dimension)

The shape variables are only interpreted literally for rectangular blocks. If the block is not rectangular, then the shape variables are interpreted as if the block on the negative side were rectangular with the dimensions that are provided when setting up the problem. For example, if you run a problem with a dipping fault that has a trapezoidally shaped block on the minus side of the fault, then x0 and dx would be measured in terms of depth rather than distance along the interface, since the “rectangular” version of the block would have depth along the fault dimension.

If you are in doubt regarding how a perturbation will be interpreted for a particular geometry, it is usually less ambiguous to use a file to set values, as they explicitly set the value at each grid point. However, for some simple forms, perturbations can be more convenient as they use less memory and do not require loading information in parallel from external files.

The different traction components may not correspond to unique coordinate directions for the interface. The code handles complex boundary conditions by rotating the fields into a coordinate system defined by three mutually orthogonal unit vectors. The normal direction is defined to always point into the “positive” block and is uniquely defined by the boundary geometry. The two tangential components are defined as follows for each different type of interface:

• Depending on the orientation of the interface in the computational space, a different convention is used to set the first tangent vector. For 'x' or 'y' oriented interfaces, the \({z}\) component of the first tangent vector is set to zero. This is done to ensure that for 2D problems, the second tangent vector points in the \({z}\)-direction. For 'z' oriented interfaces, the \({y}\) component of the first tangent vector is set to zero.
• With one component of the first tangent vector defined, the other two components can be uniquely determined to make the tangent vector orthogonal up to a sign. The sign is chosen such that the tangent vector points in the direction where the grid points are increasing.
• The second tangent vector is defined by taking the right-handed cross product of the normal and first tangent vectors, except for 'y' interfaces, where the left-handed cross product is used. This is done to ensure that for 2D problems, the vertical component always points in the \({+z}\)-direction.

The consequence of this is that the letter used to designate the desired component is only valid for rectangular geometries. For non-rectangular geometries, the components will be rotated into the coordinate system described above. For interfaces in the “x” direction (i.e. connecting blocks whose indices only differ in the \({x}\)-direction), the \({y}\) component of output units will be along the first tangent vector, and the \({z}\) component will be along the second tangent vector. Similarly, for “y” interfaces the \({x}\) component is set by the first tangent vector and the \({z}\) component is determined by the second tangent vector, and for “z” interfaces the first tangent vector is in the \({x}\)-direction and the second tangent vector corresponds to the \({y}\)-direction.

__init__(perttype='constant', t0=0.0, x0=0.0, dx=0.0, y0=0.0, dy=0.0, sn=0.0, s2=0.0, s3=0.0)

Initialize a new instance of an interface load perturbation

Method creates a new instance of a load perturbation. It calls the superclass routine to initialize the spatial and temporal details of the perturbation, and creates the variables holding the interface traction details. Default values are provided for all arguments (all zeros, with a perttype of 'constant').

Parameters:

• perttype (str) – Perturbation type (string, default is 'constant')
• t0 (float) – Linear ramp time scale (default 0.)
• x0 (float) – Perturbation location along first interface dimension (default 0.)
• dx (float) – Perturbation scale along first interface dimension (default 0.)
• y0 (float) – Perturbation location along second interface dimension (default 0.)
• dy (float) – Perturbation scale along second interface dimension (default 0.)
• sn (float) – Interface normal traction perturbation (negative in compression, default 0.)
• s2 (float) – Interface horizontal shear traction perturbation (default 0.)
• s3 (float) – Interface vertical shear traction perturbation (default 0.)

Returns:

New instance of perturbation

Return type:

fdfault.load

get_dx()

Returns perturbation scale along first interface coordinate

Returns:Scale of perturbation along first interface coordinate Return type:float

get_dy()

Returns perturbation scale along second interface coordinate

Returns:Scale of perturbation along second interface coordinate Return type:float

get_s2()

Returns in plane shear stress perturbation

Returns:In plane stress perturbation Return type:float

get_s3()

Returns out of plane shear stress perturbation

Returns:Out of plane shear stress perturbation Return type:float

get_sn()

Returns normal stress perturbation

Returns:Normal stress perturbation Return type:float

get_t0()

Returns onset time

Returns:Perturbation onset time Return type:float

get_type()

Returns perturbation type

Returns:Perturbation type Return type:str

get_x0()

Returns perturbation location in first interface coordinate

Returns:Location of perturbation along first interface coordinate Return type:float

get_y0()

Returns perturbation location in second interface coordinate

Returns:Location of perturbation along second interface coordinate Return type:float

set_dx(dx)

Sets first coordinate of perturbation scale

Changes value of perturbation scale for first coordinate direction. New value must be nonnegative.

Parameters:dx (float) – New value of perturbation scale along second coordinate Returns:None

set_dy(dy)

Sets second coordinate of perturbation scale

Changes value of perturbation scale for second coordinate direction. New value must be nonnegative.

Parameters:dy (float) – New value of perturbation scale along second coordinate Returns:None

set_s2(s2)

Sets in-plane shear stress perturbation

Parameters:s2 (float) – New value of in plane shear stress perturbation Returns:None

set_s3(s3)

Sets out of plane shear stress perturbation

Parameters:s3 (float) – New value of out of plane shear stress perturbation Returns:None

set_sn(sn)

Sets normal stress perturbation

Parameters:sn (float) – New value of normal stress perturbation Returns:None

set_t0(t0)

Sets onset time

Changes value of onset time. New value must be nonnegative.

Parameters:t0 (float) – New value of onset time Returns:None

set_type(perttype)

Sets perturbation type

Resets the perturbation type to perttype. Note that the new type must be among the valid perturbation types.

Parameters:perttype (str) – New value for perttype, must be a valid perturbation type Returns:None

set_x0(x0)

Sets first coordinate of perturbation location

Parameters:x0 (float) – New value of perturbation location along first coordinate Returns:None

set_y0(y0)

Sets second coordinate of perturbation location

Parameters:x0 (float) – New value of perturbation location along second coordinate Returns:None

write_input(f)

Writes perturbation to input file

Method writes perturbation to input file (input file provided as input)

Parameters:f (file) – Output file to which the perturbation will be written Returns:none

class fdfault.loadfile(n1, n2, sn, s2, s3)

The loadfile class is a class for loading interface tractions to simulation from file. It includes arrays for normal and two components of shear tractions to be applied at the specific boundary.

All loadfile members contain the following internal parameters:

Variables:

• n1 – Number of grid points along first coordinate direction
• n2 – Number of grid points along the second coordinate direction
• sn – Normal stress perturbation (must be an (n1,n2) shaped numpy array)
• s2 – In plane shear stress perturbation (must be an (n1,n2) shaped numpy array)
• s3 – Out of plane shear stress perturbation (must be an (n1,n2) shaped numpy array)

loadfile instances hold three numpy arrays with shape (n1,n2) for the normal and two shear tractions actin on the interface. Load files do not include any information about the shape of the boundary, and it is up to the user to ensure that that the parameter values correspond to the coordinates of the interface. However, because parameter files explicitly assign a value to each grid point, there is less ambiguity regarding the final values when compared to perturbations. Depending on the orientation of the interface, the two coordinate directions will have different orientations in space. The first coordinate direction is the \({x}\) direction for \({y}\) and \({z}\) interfaces (for \({x}\) interfaces, the first index is in the \({y}\) direction), and the second coordinate is in the \({z}\) direction except for \({z}\) interfaces, where \({y}\) is the second index}.

The different traction components may not correspond to unique coordinate directions for the interface. The code handles complex boundary conditions by rotating the fields into a coordinate system defined by three mutually orthogonal unit vectors. The normal direction is defined to always point into the “positive” block and is uniquely defined by the boundary geometry. The two tangential components are defined as follows for each different type of interface:

• Depending on the orientation of the interface in the computational space, a different convention is used to set the first tangent vector. For 'x' or 'y' oriented interfaces, the \({z}\) component of the first tangent vector is set to zero. This is done to ensure that for 2D problems, the second tangent vector points in the \({z}\)-direction. For 'z' oriented interfaces, the \({y}\) component of the first tangent vector is set to zero.
• With one component of the first tangent vector defined, the other two components can be uniquely determined to make the tangent vector orthogonal up to a sign. The sign is chosen such that the tangent vector points in the direction where the grid points are increasing.
• The second tangent vector is defined by taking the right-handed cross product of the normal and first tangent vectors, except for 'y' interfaces, where the left-handed cross product is used. This is done to ensure that for 2D problems, the vertical component always points in the \({+z}\)-direction.

The consequence of this is that the letter used to designate the desired component is only valid for rectangular geometries. For non-rectangular geometries, the components will be rotated into the coordinate system described above. For interfaces in the “x” direction (i.e. connecting blocks whose indices only differ in the \({x}\)-direction), the \({y}\) component of output units will be along the first tangent vector, and the \({z}\) component will be along the second tangent vector. Similarly, for “y” interfaces the \({x}\) component is set by the first tangent vector and the \({z}\) component is determined by the second tangent vector, and for “z” interfaces the first tangent vector is in the \({x}\)-direction and the second tangent vector corresponds to the \({y}\)-direction.

When writing loadfile instances to disk, the code uses numpy to write information to disk in binary format. Byte-ordering can be specified, and should correspond to the byte-ordering on the system where the simulation will be run (default is native).

__init__(n1, n2, sn, s2, s3)

Initialize a new instance of a loadfile object

Create a new instance of a loadfile, which is a class describing interface boundary traction perturbations in a file. Required information is the number of grid points for the interface and one array for each of the three interface traction component perturbations. All the array shapes must be (n1, n2) or the code will raise an error.

Parameters:

• n1 (int) – Number of grid points along first coordinate direction
• n2 (int) – Number of grid points along the second coordinate direction
• sn (ndarray) – Interface normal traction perturbation array (negative in compression)
• s2 (ndarray) – Interface horizontal shear traction perturbation array
• s3 (ndarray) – Interface vertical shear traction perturbation array

Returns:

New loadfile instance

Return type:

loadfile

get_n1()

Returns number of grid points in 1st coordinate direction

Returns:Number of grid points in 1st coordinate direction (\({x}\), except for \({x}\) interfaces, where \({y}\) is the first coordinate direction) Return type:int

get_n2()

Returns number of grid points in 2nd coordinate direction

Returns:Number of grid points in 2nd coordinate direction (\({z}\), except for \({z}\) interfaces, where \({y}\) is the second coordinate direction) Return type:int

get_s2(index=None)

Returns in plane shear stress at given indices

Returns in plane shear stress perturbation at the indices given by index. If no indices are provided, the method returns the entire array.

Parameters:index (float, tuple, or None) – Index into s2 array (optional, if not provided returns entire array) Returns:In plane shear stress perturbation (either ndarray or float, depending on value of index) Return type:ndarray or float

get_s3(index=None)

Returns out of plane shear stress at given indices

Returns out of plane shear stress perturbation at the indices given by index. If no indices are provided, the method returns the entire array.

Parameters:index (float, tuple, or None) – Index into s3 array (optional, if not provided returns entire array) Returns:Out of plane shear stress perturbation (either ndarray or float, depending on value of index) Return type:ndarray or float

get_sn(index=None)

Returns normal stress at given indices

Returns normal stress perturbation at the indices given by index. If no indices are provided, the method returns the entire array.

Parameters:index (float, tuple, or None) – Index into sn array (optional, if not provided returns entire array) Returns:Normal stress perturbation (either ndarray or float, depending on value of index) Return type:ndarray or float

write(filename, endian='=')

Write perturbation data to file

Parameters:

• filename (str) – Name of binary file to be written
• endian (str) – Byte-ordering for output. Options inclue '=' for native, '<' for little endian, and '>' for big endian. Optional, default is native

Returns:

None