The stz Class

The main class used for creating STZ interfaces is the stz class. This also includes setting the STZ parameters through perturbations and files, as well as setting the initial state variable.

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

Class representing a Shear Transformation Zone (STZ) Theory Frictional Interface

STZ Frictional Interfaces are an interface with a state variable, in this case an effective temperature. The interface also requires setting the interface tractions and parameter values in addition to the initial value of the state variable. All of these can be set using some combination of perturbations and files. Parameters include:

• Reference velocity \({V_0}\) , v0
• Reference activation barrier \({f_0}\), f0
• Frictional direct effect \({a}\), a
• Frictional yield coefficient \({\mu_y}\), muy
• Effective temperature specific heat \({c_0}\), c0
• Effective temperature relaxation rate \({R}\), R
• Effective temperature relaxation barrier \({\beta}\), beta
• Effective temperature activation barrier \({\chi_w}\), chiw
• Reference velocity for effective temperature activation \({V_1}\), v1

STZ Frictional 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
• nperts – Number of parameter perturbations (length of perts list)
• perts – List of parameter perturbations (each must be stzparam)
• pf – Paramfile holding traction at each point
• state – Initial value of state variable
• sf – Statefile holding heterogeneous initial state variable values

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

Initializes an instance of the stz class

Create a new stz 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 stz class

Return type:

stz

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 must have type stzparam).

Parameters:newpert (stzparam) – New perturbation to be added 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

delete_statefile()

Deletes statefile for the interface

Delete the statefile for the interface. Will set the statefile attribute for the interface to None.

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 for this interface Return type: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_state()

Returns initial state variable value for interface

Returns:Initial state variable Return type:float

get_statefile()

Returns state file of interface

If interface does not have a statefile returns None

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

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 type stzparam. Errors can also result if the shape of the paramfile does not match with the interface.

Parameters:newparamfile (stzparamfile) – New frictional parameter file Returns:None

set_state(newstate)

Sets initial state variable for interface

Set the initial value for the state variable. state is the new state variable (must be a float or some other valid number).

Parameters:state (float) – New value of state variable Returns:None

set_statefile(newstatefile)

Sets state file for interface

Set the statefile for the interface.``newstatefile``must have type statefile. Errors can also result if the shape of the statefile does not match with the interface.

Parameters:newstatefile (statefile) – New statefile for the 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.stzparam(perttype='constant', t0=0.0, x0=0.0, dx=0.0, y0=0.0, dy=0.0, v0=0.0, f0=0.0, a=0.0, muy=0.0, c0=0.0, R=0.0, beta=0.0, chiw=0.0, v1=0.0)

Class representing STZ Theory parameter perturbations to frictional interfaces

The stzparam class represents STZ Theory parameter perturbations that can be expressed in a simple functional form. The stzparam class holds information on the shape of the perturbation and the nine parameter values for 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)
• v0 – Reference slip rate perturbation
• f0 – Friction activation barrier perturbation
• a – Frictional direct effect perturbation
• muy – Yielding friction coefficient perturbation
• c0 – Effective temperature specific heat perturbation
• R – Effective temperature relaxation rate perturbation
• beta – Effective temperature relaxation barrier perturbation
• chiw – Effective temperature activation barrier perturbation
• v1 – Effective temperature reference slip rate perturbation

By default, all time, shape, and friction 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.

__init__(perttype='constant', t0=0.0, x0=0.0, dx=0.0, y0=0.0, dy=0.0, v0=0.0, f0=0.0, a=0.0, muy=0.0, c0=0.0, R=0.0, beta=0.0, chiw=0.0, v1=0.0)

Initialize a new instance of an STZ parameter perturbation

Method creates a new instance of a STZ parameter perturbation. It calls the superclass routine to initialize the spatial and temporal details of the perturbation, and creates the variables holding the parameter values specific to the STZ law. 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.)
• v0 (float) – Reference slip rate perturbation (default 0.)
• f0 (float) – Friction activation barrier perturbation (default 0.)
• a (float) – Frictional direct effect perturbation (default 0.)
• muy (float) – Yielding friction coefficient perturbation (default 0.)
• c0 (float) – Effective temperature specific heat perturbation (default 0.)
• R (float) – Effective temperature relaxation rate perturbation (default 0.)
• beta (float) – Effective temperature relaxation barrier perturbation (default 0.)
• chiw (float) – Effective temperature activation barrier perturbation (default 0.)
• v1 (float) – Effective temperature reference slip rate perturbation (default 0.)

Returns:

New instance of slip weakening parameter perturbation

Return type:

stzparam

get_R()

Returns effective temperature relaxation rate perturbation

Returns:Effective temperature relaxation rate perturbation Return type:float

get_a()

Returns frictional direct effect perturbation

Returns:frictional direct effect perturbation Return type:float

get_beta()

Returns effective temperature relaxation activation barrier perturbation

Returns:Effective temperature relaxation activation barrier perturbation Return type:float

get_c0()

Returns effective temperature specific heat perturbation

Returns:Effective temperature specific heat perturbation Return type:float

get_chiw()

Returns effective temperature activation barrier perturbation

Returns:Effective temperature activation barrier perturbation Return type:float

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_f0()

Returns activation barrier perturbation

Returns:activation barrier perturbation Return type:float

get_muy()

Returns yielding friction coefficient perturbation

Returns:yielding friction coefficient 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_v0()

Returns reference slip rate perturbation

Returns:reference slip rate perturbation Return type:float

get_v1()

Returns effective temperature reference slip rate perturbation

Returns:Effective temperature reference slip rate perturbation Return type:float

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_R(R)

Sets effective temperature relaxation rate perturbation

Parameters:R (float) – Value of effective temperature relaxation perturbation Returns:None

set_a(a)

Sets frictional direct effect perturbation

Parameters:a (float) – Value of frictional direct effect perturbation Returns:None

set_beta(beta)

Sets effective temperature relaxation activation barrier perturbation

Parameters:beta (float) – Value effective temperature relaxation activation barrier perturbation Returns:None

set_c0(c0)

Sets effective temperature specific heat perturbation

Parameters:c0 (float) – Value of effective temperature specific heat perturbation Returns:None

set_chiw(chiw)

Sets effective temperature activation barrier perturbation

Parameters:chiw (float) – Value of effective temperature activation barrier perturbation Returns:None

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_f0(f0)

Sets activation barrier perturbation

Parameters:f0 (float) – Value of activation barrier perturbation Returns:None

set_muy(muy)

Sets yielding friction coefficient perturbation

Parameters:muy (float) – Value yielding friction coefficient 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_v0(v0)

Sets reference slip rate perturbation

Parameters:v0 (float) – Value of reference slip rate perturbation Returns:None

set_v1(v1)

Sets effective temperature reference slip rate perturbation

Parameters:v1 (float) – Value of effective temperature reference slip rate perturbation 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.stzparamfile(n1, n2, v0, f0, a, muy, c0, R, beta, chiw, v1)

The stzparamfile class is a class for loading heterogeneous friction parameter values from file. It is only used for STZ interfaces.

All stzparamfile instances 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
• v0 – Array holding reference slip rate perturbation (numpy array with shape (n1,n2))
• f0 – Array holding friction activation barrier perturbation (numpy array with shape (n1,n2))
• a – Array holding frictional direct effect perturbation (numpy array with shape (n1,n2))
• muy – Array holding yielding friction coefficient perturbation (numpy array with shape (n1,n2))
• c0 – Array holding effective temperature specific heat perturbation (numpy array with shape (n1,n2))
• R – Array holding effective temperature relaxation rate perturbation (numpy array with shape (n1,n2))
• beta – Array holding effective temperature relaxation activation barrier perturbation (numpy array with shape (n1,n2))
• chiw – Array holding effective temperature activation barrier perturbation (numpy array with shape (n1,n2))
• v1 – Array holding effective temperature reference slip rate perturbation (numpy array with shape (n1,n2))

stzparamfile will also define nine numpy array with shape (n1,n2) holding the various friction parameters (reference slip rate, friction activation barrier, frictional direct effect, yielding friction coefficient, effective temperature specific heat, effective temperature relaxation rate, effective temperature relaxation activation barrier, effective temperature activation barrier, and effective temperature reference slip rate. STZ parameter 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}.

When writing stzparamfile 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, v0, f0, a, muy, c0, R, beta, chiw, v1)

Initialize a new instance of a stzparamfile object

Create a new instance of a stzparamfile, which is a class describing STZ parameter perturbations in a file. Required information is the number of grid points for the interface and one array for each of the nine parameter 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
• v0 (ndarray) – Reference slip rate perturbation array
• f0 (ndarray) – Friction activation barrier perturbation array
• a (ndarray) – Frictional direct effect perturbation array
• muy (ndarray) – Yielding friction coefficient perturbation array
• c0 (ndarray) – Effective temperature specific heat perturbation array
• R (ndarray) – Effective temperature relaxation rate perturbation array
• beta (ndarray) – Effective temperature relaxation barrier perturbation array
• chiw (ndarray) – Effective temperature activation barrier perturbation array
• v1 (ndarray) – Effective temperature reference slip rate perturbation array

Returns:

New swparamfile instance

Return type:

swparamfile

get_R(index=None)

Returns effective temperature relaxation rate at given indices

Returns effective temperature relaxation rate 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 effective temperature relaxation rate array (optional, if not provided returns entire array) Returns:Effective temperature relaxation rate perturbation (either ndarray or float, depending on value of index) Return type:ndarray or float

get_a(index=None)

Returns frictional direct effect at given indices

Returns frictional direct effect 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 frictional direct effect array (optional, if not provided returns entire array) Returns:Frictional direct effect perturbation (either ndarray or float, depending on value of index) Return type:ndarray or float

get_beta(index=None)

Returns effective temperature relaxation activation barrier at given indices

Returns effective temperature relaxation activation barrier 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 effective temperature relaxation activation barrier array (optional, if not provided returns entire array) Returns:Effective temperature relaxation activation barrier perturbation (either ndarray or float, depending on value of index) Return type:ndarray or float

get_c0(index=None)

Returns effective temperature specific heat at given indices

Returns effective temperature specific heat 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 effective temperature specific heat array (optional, if not provided returns entire array) Returns:Effective temperature specific heat perturbation (either ndarray or float, depending on value of index) Return type:ndarray or float

get_chiw(index=None)

Returns effective temperature activation barrier at given indices

Returns effective temperature activation barrier 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 effective temperature activation barrier array (optional, if not provided returns entire array) Returns:Effective temperature activation barrier perturbation (either ndarray or float, depending on value of index) Return type:ndarray or float

get_f0(index=None)

Returns friction activation barrier at given indices

Returns friction activation barrier 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 friction activation barrier array (optional, if not provided returns entire array) Returns:Friction activation barrier perturbation (either ndarray or float, depending on value of index) Return type:ndarray or float

get_muy(index=None)

Returns yielding friction coefficient at given indices

Returns yielding friction coefficient 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 yielding friction coefficient array (optional, if not provided returns entire array) Returns:Yielding friction coefficient perturbation (either ndarray or float, depending on value of index) Return type:ndarray or float

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_v0(index=None)

Returns reference slip rate at given indices

Returns reference slip rate 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 reference slip rate array (optional, if not provided returns entire array) Returns:Reference slip rate perturbation (either ndarray or float, depending on value of index) Return type:ndarray or float

get_v1(index=None)

Returns effective temperature reference slip rate at given indices

Returns effective temperature reference slip rate 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 effective temperature reference slip rate array (optional, if not provided returns entire array) Returns:Effective temperature reference slip rate 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

class fdfault.statefile(n1, n2, state)

The statefile class is a class for loading heterogeneous initial state variable values from file. It is only used for friction laws that require an additional state variable in addition to the slip/slip rate to specify frictional strength

All statefile instances 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
• state – Array holding state variable perturbation (numpy array with shape (n1,n2))

statefile will also define a numpy array with shape (n1,n2) holding the state variable. State 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}.

When writing statefile 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, state)

Initialize a new instance of a statefile object

Create a new instance of a statefile, which is a class describing interface state variable value perturbations in a file. Required information is the number of grid points for the interface and one array for the state variable. The array shape 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) – State variable perturbation array

Returns:

New statefile instance

Return type:

statefile

get_state(index=None)

Returns state variable at given indices

Returns state variable 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 state variable array (optional, if not provided returns entire array) Returns:State variable 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