The output Class

The output class contains information on saving simulation data to file.

Each problem contains a list of “output units,” each of which saves a particular set of data points from the simulation to file. An output unit is given a name, selects a field from the simulation, and picks grid and time points to output. The corresponding spatial grid and time information is automatically output for each item.

Output items fall into two main groups: fields that are defined in the volume (particle velocities, stress components, and plastic strain/strain rate). These are defined for every grid point in the simulation, and so there are no restrictions on the range that the spatial points can take other than them being within the domain and the min/max values are self-consistent.

Other fields such as slip, slip rate, interface tractions, and state variables, are only defined on a particular interface between blocks. These output units require more careful specification of their limits, as the points chosen must lie on an interface. The Python and C++ code check the validity of these limits (the Python code only checks that the points make up a 2D slice, while the C++ code ensures that the 2D slice lies on an interface in the simulation).

The grid point limits can be used to specify a single point, 1D, 2D, or 3D selection of the domain for output by setting the min/max values to be identical or different.

Output can only be done for specific grid points within the computational domain. However, a helper function find_nearest_point can be used for a given problem to find the nearest grid point to a spatial location for complex domains.

Acceptable field names for volume output:

• 'vx' - x particle velocity
• 'vy' - y particle velocity
• 'vz' - z particle velocity
• 'sxx' - xx stress component
• 'sxy' - xy stress component
• 'sxz' - xz stress component
• 'syy' - yy stress component
• 'syz' - yz stress component
• 'szz' - zz stress component
• 'gammap' - scalar plastic strain
• 'lambda' - scalar plastic strain rate

Acceptable field names for interface output (coordinates must form a 2D (1D for 2D problems) slice through the domain along a single interface between two blocks. Note that if your slice extends through multiple interfaces, only one will be saved due to how parallel I/O is handled in the code.

• 'U' - scalar slip (line integral of slip velocity)
• 'Ux' - x slip component (signed)
• 'Uy' - y slip component (signed)
• 'Uz' - z slip component (signed)
• 'V' - scalar slip velocity (vector magnitude of components)
• 'Vx' - x slip velocity component (signed)
• 'Vy' - y slip velocity component (signed)
• 'Vz' - z slip velocity component (signed)
• 'Sn' - Interface normal traction (negative in compression)
• 'S' - scalar interface shear traction (vector magnitude)
• 'Sx' - x shear traction component (signed)
• 'Sy' - y shear traction component (signed)
• 'Sz' - z shear traction component (signed)

The different interface components do not truly correspond to the corresponding coordinate directions. 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. If you desire the components in a different coordinate system, you can convert them from the output data. Note that this also means that you can only specify certain components for interface output, depending on the direction of the interface.

class fdfault.output(name, field, tm=0, tp=0, ts=1, xm=0, xp=0, xs=1, ym=0, yp=0, ys=1, zm=0, zp=0, zs=1)

Class representing a simulation dataset to be written to file.

Attributes include a name (used for setting the file name of the resulting files), output field, and grid point information. Initializing an output unit requires specifying a name and field, the grid point information is optional.

Variables:

• name – Name used in files for saving data
• field – Field to be saved to file (see list of acceptable values above)
• tm – Minimum time index to be written to file (inclusive)
• tp – Maximum time index to be written to file (inclusive)
• ts – Stride for time output (will skip over appropriate number of time steps so that every ts time steps are saved between tm and tp)
• xm – Minimum x index to be written to file (inclusive)
• xp – Maximum x index to be written to file (inclusive)
• xs – Stride for x output (will skip over appropriate number of x grid points so that one per every xs points are saved between xm and xp)
• ym – Minimum y index to be written to file (inclusive)
• yp – Maximum y index to be written to file (inclusive)
• ys – Stride for y output (will skip over appropriate number of y grid points so that one per every ys points are saved between ym and yp)
• zm – Minimum z index to be written to file (inclusive)
• zp – Maximum z index to be written to file (inclusive)
• zs – Stride for z output (will skip over appropriate number of z grid points so that one per every zs points are saved between zm and zp)

__init__(name, field, tm=0, tp=0, ts=1, xm=0, xp=0, xs=1, ym=0, yp=0, ys=1, zm=0, zp=0, zs=1)

Initialize a new ouput unit

Creates a new output unit. Required arguments are the name and field to be saved. Specifying additional parameters gives the user control over what data is saved. Time and three spatial dimensions can be set with a triplet of integers representing minus, plius, and stride values. Minus sets the first index that is saved, plus sets the last, and stride controls how frequently the data is saves (stride of 1 means every value is saved, 2 means every other point is saved, etc.). Specifying values out of bounds such as minus > plus or any number less than zero will result in an error. If values that are outside the simulation range are given, the code will give a warning but not an error.

All triplets have default values of minus = 0, plus = 0, and stride = 1, and are optional.

Parameters:

• name (str) – Name used in files for saving data
• field (str) – Field to be saved to file (see list of acceptable values above)
• tm (int) – Minimum time index to be written to file (inclusive)
• tp (int) – Maximum time index to be written to file (inclusive)
• ts (int) – Stride for time output (will skip over appropriate number of time steps so that every ts time steps are saved between tm and tp)
• xm (int) – Minimum x index to be written to file (inclusive)
• xp (int) – Maximum x index to be written to file (inclusive)
• xs (int) – Stride for x output (will skip over appropriate number of x grid points so that one per every xs points are saved between xm and xp)
• ym (int) – Minimum y index to be written to file (inclusive)
• yp (int) – Maximum y index to be written to file (inclusive)
• ys (int) – Stride for y output (will skip over appropriate number of y grid points so that one per every ys points are saved between ym and yp)
• zm (int) – Minimum z index to be written to file (inclusive)
• zp (int) – Maximum z index to be written to file (inclusive)
• zs (int) – Stride for z output (will skip over appropriate number of z grid points so that one per every zs points are saved between zm and zp)

Returns:

New instance of output unit

Return type:

output

get_field()

Returns output field

Returns:Output field Return type:str

get_name()

Returns output unit name

Returns:Output unit name Return type:str

get_time_indices()

Returns all index info for time output as (tm, tp, ts)

Returns:Set of time step info indices (tm, tp, ts) Return type:tuple

get_tm()

Returns minimum time step for output

Returns:minimum time step index Return type:int

get_tp()

Returns maximum time step for output

Returns:maximum time step index Return type:int

get_ts()

Returns time stride for output

Returns:time stride Return type:int

get_x_indices()

Returns all index info for x output as (xm, xp, xs)

Returns:all x grid point information (xm, xp, xs) Return type:tuple

get_xm()

Returns minimum x grid point for output

Returns:minimum x grid point Return type:int

get_xp()

Returns maximum x grid point for output

Returns:maximum x grid point Return type:int

get_xs()

Returns x stride for output

Returns:x stride Return type:int

get_y_indices()

Returns all index info for y output as (ym, yp, ys)

Returns:Index information for the y direction (ym, yp, ys) Return type:tuple

get_ym()

Returns minimum y grid point for output

Returns:minimum y grid point Return type:int

get_yp()

Returns maximum y grid point for output

Returns:maximum y grid index Return type:int

get_ys()

Returns y stride for output

Returns:y stride for data output Return type:int

get_z_indices()

Returns all index info for z output as (zm, zp, zs)

Returns:z output information (zm, zp, zs) Return type:tuple

get_zm()

Returns minimum z grid point for output

Returns:minimum z grid point Return type:int

get_zp()

Returns maximum z grid point for output

Returns:maximum z grid point Return type:int

get_zs()

Returns z stride for output

Returns:z stride Return type:int

set_field(field)

Sets output file (must be a valid block or interface field)

Parameters:field (str) – New output field (must match option above) Returns:None

set_name(name)

Set output unit name (if not a string, the code will produce an error)

Parameters:name (str) – New name for output unit Returns:None

set_time_indices(tm, tp, ts)

Sets all time indices

Method sets all three values of tm, tp, and ts

Parameters:

• tm (int) – New value of minimum time index
• tp (int) – New value of maximum time index
• ts (int) – New value of time stride

Returns:

None

set_tm(tm)

Sets minimum time index for output

New minimum must be nonnegative and less than tp

Parameters:tm (int) – New value of minimum time step Returns:None

set_tp(tp)

Sets maximum time index for output

New value of maximum time must be nonnegative and not less than tm

Parameters:tp (int) – New value of minimum time index Returns:None

set_ts(ts)

Sets t stride for output

Stride must be a positive integer.

Parameters:ts (int) – New value of time stride Returns:None

set_x_indices(xm, xp, xs)

Sets all x indices

Method sets all three values of xm, xp, and xs

Parameters:

• xm (int) – New value of minimum x index
• xp (int) – New value of maximum x index
• xs (int) – New value of x stride

Returns:

None

set_xm(xm)

Sets minimum x index for output

New minimum must be nonnegative and less than xp

Parameters:xm (int) – New value of minimum x grid point Returns:None

set_xp(xp)

Sets maximum x index for output

New value of maximum x index must be nonnegative and not less than xm

Parameters:xp (int) – New value of maximum x index Returns:None

set_xs(xs)

Sets x stride for output

Stride must be a positive integer.

Parameters:xs (int) – New value of x stride Returns:None

set_y_indices(ym, yp, ys)

Sets all y indices

Method sets all three values of ym, yp, and ys

Parameters:

• ym (int) – New value of minimum y index
• yp (int) – New value of maximum y index
• ys (int) – New value of y stride

Returns:

None

set_ym(ym)

Sets minimum y index for output

New minimum must be nonnegative and less than yp

Parameters:ym (int) – New value of minimum y grid point Returns:None

set_yp(yp)

Sets maximum y index for output

New value of maximum y index must be nonnegative and not less than ym

Parameters:yp (int) – New value of maximum y index Returns:None

set_ys(ys)

Sets y stride for output

Stride must be a positive integer.

Parameters:ys (int) – New value of y stride Returns:None

set_z_indices(zm, zp, zs)

Sets all z indices

Method sets all three values of zm, zp, and zs

Parameters:

• zm (int) – New value of minimum z index
• zp (int) – New value of maximum z index
• zs (int) – New value of z stride

Returns:

None

set_zm(zm)

Sets minimum z index for output

New minimum must be nonnegative and less than zp

Parameters:zm (int) – New value of minimum z grid point Returns:None

set_zp(zp)

Sets maximum z index for output

New value of maximum z index must be nonnegative and not less than zm

Parameters:zp (int) – New value of maximum z index Returns:None

set_zs(zs)

Sets z stride for output

Stride must be a positive integer.

Parameters:zs (int) – New value of z stride Returns:None

write_input(f)

Writes output unit to file

Method writes the information for the output unit to file. The information is inserted into a list of output units that are formatted for input into the C++ code.

Parameters:f (file) – file handle for output file Returns:None