rsqsim_api.fault.patch

Attributes

`transformer_utm2nztm`
`transformer_nztm2wgs`
`transformer_wgs2nztm`
`anticlockwise90`

Classes

`RsqSimGenericPatch`	Base class representing a single fault patch in an RSQSim fault model.
`RsqSimTriangularPatch`	A single triangular fault patch for use in RSQSim fault models.
`OpenQuakeRectangularPatch`	A rectangular fault patch suitable for use with OpenQuake engine inputs.

Functions

`norm_3d`(a)	Calculate the Euclidean (2-norm) length of a 3-dimensional vector.
`cross_3d`(a, b)	Calculate the cross product of two 3-dimensional vectors.
`normalize_bearing`(bearing)	Wrap a bearing value into the half-open interval [0, 360).
`unit_vector`(vec1, vec2)	Compute the unit vector pointing from `vec1` to `vec2`.

Module Contents

rsqsim_api.fault.patch.transformer_utm2nztm[source]

rsqsim_api.fault.patch.transformer_nztm2wgs[source]

rsqsim_api.fault.patch.transformer_wgs2nztm[source]

rsqsim_api.fault.patch.anticlockwise90[source]

rsqsim_api.fault.patch.norm_3d(a)[source]

Calculate the Euclidean (2-norm) length of a 3-dimensional vector.

Parameters:: a (array-like of shape (3,)) – Input 3-component vector.
Returns:: Scalar Euclidean norm of a.
Return type:: float

Notes

Compiled with numba.njit for performance inside tight loops.

rsqsim_api.fault.patch.cross_3d(a, b)[source]

Calculate the cross product of two 3-dimensional vectors.

Parameters:

a (array-like of shape (3,)) – First input vector.
b (array-like of shape (3,)) – Second input vector.

Returns:

Vector perpendicular to both a and b, with magnitude |a| * |b| * sin(theta), following the right-hand rule.

Return type:

numpy.ndarray of shape (3,)

Notes

Compiled with numba.njit for performance inside tight loops.

rsqsim_api.fault.patch.normalize_bearing(bearing)[source]

Wrap a bearing value into the half-open interval [0, 360).

Parameters:: bearing (float | int) – Input bearing in degrees. May be any real number.
Returns:: Equivalent bearing constrained to [0, 360).
Return type:: float

rsqsim_api.fault.patch.unit_vector(vec1, vec2)[source]

Compute the unit vector pointing from vec1 to vec2.

Parameters:

vec1 (numpy.ndarray of shape (3,)) – Origin point (tail of the vector).
vec2 (numpy.ndarray of shape (3,)) – Destination point (head of the vector).

Returns:

Normalised direction vector from vec1 to vec2.

Return type:

numpy.ndarray of shape (3,)

Notes

Compiled with numba.njit for performance inside tight loops.

class rsqsim_api.fault.patch.RsqSimGenericPatch(segment, patch_number=0, dip_slip=None, strike_slip=None, rake=None, total_slip=None)[source]

Base class representing a single fault patch in an RSQSim fault model.

Stores patch identity, slip components, and the parent fault segment reference. Concrete subclasses add geometry (triangular, rectangular, etc.).

Parameters:

segment – Parent fault segment object that owns this patch.
patch_number (int, optional) – Zero-based integer index identifying the patch within its segment. Defaults to 0.
dip_slip (float, optional) – Dip-slip component of displacement in metres. Positive values indicate reverse/thrust motion.
strike_slip (float, optional) – Strike-slip component of displacement in metres. Positive values indicate right-lateral motion.
rake (float, optional) – Rake angle in degrees, measured from the along-strike direction following the Aki & Richards convention. Stored normalised to [0, 360).
total_slip (float, optional) – Total slip magnitude in metres (unused by the base class but accepted for interface consistency).

segment[source]: Reference to the parent fault segment.

patch_number[source]

Non-negative integer patch index.

Type:: int

dip_slip[source]

Dip-slip component in metres.

Type:: float or None

strike_slip[source]

Strike-slip component in metres.

Type:: float or None

rake[source]

Rake angle in degrees, normalised to [0, 360).

Type:: float or None

segment[source]

property patch_number[source]: Non-negative integer index identifying this patch within its segment.

property dip_slip[source]

Dip-slip displacement component in metres.

Setting this value also recomputes the rake if the strike-slip component is already defined.

property strike_slip[source]

Strike-slip displacement component in metres.

Setting this value also recomputes the rake if the dip-slip component is already defined.

property rake[source]

Rake angle in degrees, normalised to the interval [0, 360).

Setting this value calls normalize_bearing() automatically.

property vertices[source]

Array of patch corner vertices in NZTM coordinates (metres).

Returns None until populated by a subclass setter.

property total_slip[source]

Euclidean magnitude of the slip vector in metres.

Computed from strike_slip and dip_slip; treats None components as zero.

set_slip_rake(total_slip, rake)[source]

Decompose a total slip magnitude and rake into strike-slip and dip-slip.

Sets strike_slip, dip_slip, and rake on the patch directly without triggering the cross-update logic in the individual property setters.

Parameters:

total_slip (float) – Total slip magnitude in metres.
rake (float) – Rake angle in degrees (stored normalised to [0, 360)).

static calculate_rake(strike_slip, dip_slip)[source]

Compute rake from strike-slip and dip-slip components.

Parameters:

strike_slip (float) – Strike-slip displacement component in metres.
dip_slip (float) – Dip-slip displacement component in metres.

Returns:

Rake angle in degrees, normalised to [0, 360) via normalize_bearing().

Return type:

float

class rsqsim_api.fault.patch.RsqSimTriangularPatch(segment, vertices, patch_number=0, dip_slip=None, strike_slip=None, patch_data=None, rake=None, total_slip=None)[source]

Bases: RsqSimGenericPatch

A single triangular fault patch for use in RSQSim fault models.

Stores the three corner vertices and derives geometric quantities (normal vector, down-dip vector, along-strike vector, dip, centre, area) either from supplied patch_data or by computing them from the vertices.

Parameters:

segment – Parent fault segment object that owns this patch.
vertices (list or numpy.ndarray or tuple) – Array-like of shape (3, 3) giving the (x, y, z) coordinates of the triangle corners in NZTM (metres). If more than three rows are supplied only the first three are used.
patch_number (int, optional) – Zero-based integer index identifying the patch. Defaults to 0.
dip_slip (float, optional) – Dip-slip component of displacement in metres.
strike_slip (float, optional) – Strike-slip component of displacement in metres.
patch_data (list or numpy.ndarray or tuple, optional) – Pre-computed geometry sequence of the form [normal_vector, down_dip_vector, dip, along_strike_vector, centre, area]. When provided the geometric calculations are skipped.
rake (float, optional) – Rake angle in degrees.
total_slip (float, optional) – Total slip magnitude in metres. When provided, set_slip_rake is called using this value and the current rake.

segment[source]: Reference to the parent fault segment.

patch_number[source]

Non-negative integer patch index.

Type:: int

vertices[source]

Triangle corner coordinates in NZTM (metres).

Type:: numpy.ndarray of shape (3, 3)

normal_vector[source]

Unit normal vector of the patch pointing upward.

Type:: numpy.ndarray of shape (3,)

down_dip_vector[source]

Vector pointing in the steepest down-dip direction.

Type:: numpy.ndarray of shape (3,)

along_strike_vector[source]

Vector pointing along strike.

Type:: numpy.ndarray of shape (3,)

dip[source]

Dip angle in degrees, measured from horizontal.

Type:: float

centre[source]

Centroid of the triangle in NZTM (metres).

Type:: numpy.ndarray of shape (3,)

area[source]

Area of the triangular patch in square metres.

Type:: float

vertices[source]

Array of patch corner vertices in NZTM coordinates (metres).

Returns None until populated by a subclass setter.

property vertices_lonlat[source]

Triangle corner coordinates transformed to WGS84 longitude/latitude.

Returns:: Columns are (longitude, latitude, depth) for each of the three corners, in degrees (WGS84) and metres depth.
Return type:: numpy.ndarray of shape (3, 3)

property centre_lonlat[source]

Patch centroid transformed to WGS84 longitude/latitude.

Returns:: (longitude, latitude, depth) of the patch centroid, in degrees (WGS84) and metres depth.
Return type:: numpy.ndarray of shape (3,)

static calculate_normal_vector(vertices)[source]

Compute the upward-pointing unit normal vector of a triangular patch.

Uses the cross product of two edge vectors. If the raw cross product points downward its sign is flipped so that the normal always has a positive z-component.

Parameters:: vertices (numpy.ndarray of shape (3, 3)) – Triangle corner coordinates (x, y, z) in any consistent Cartesian coordinate system.
Returns:: Unit normal vector with non-negative z-component.
Return type:: numpy.ndarray of shape (3,)

Notes

Compiled with numba.njit for performance.

property normal_vector[source]: Upward-pointing unit normal vector of the triangular patch.

property down_dip_vector[source]: Vector pointing in the steepest down-dip direction of the patch.

static calculate_down_dip_vector(normal_vector)[source]

Derive the down-dip vector from a patch normal vector.

The down-dip direction is the steepest descent direction on the fault plane. For a vertical patch (zero z-component in the normal) it defaults to straight down (0, 0, -1).

Parameters:: normal_vector (numpy.ndarray of shape (3,)) – Upward-pointing unit normal of the fault patch.
Returns:: Down-dip vector whose z-component is -xy_mag and whose horizontal components are scaled by |dz| / xy_mag.
Return type:: numpy.ndarray of shape (3,)

Notes

Compiled with numba.njit for performance.

property dip[source]

Dip angle of the patch in degrees, measured from horizontal.

Returns 90 for vertical patches and numpy.nan if the down-dip vector contains NaN values.

static calculate_dip(down_dip_vector)[source]

Calculate the dip angle in degrees from a down-dip vector.

Parameters:: down_dip_vector (numpy.ndarray of shape (3,)) – Down-dip direction vector (need not be a unit vector).
Returns:: Dip angle in degrees measured from horizontal. Returns numpy.nan if down_dip_vector[-1] is NaN, or 90.0 when the horizontal component magnitude is less than 1e-10 (effectively vertical patch).
Return type:: float

Notes

Compiled with numba.njit for performance.

property along_strike_vector[source]: Vector pointing along the strike direction of the patch.

property strike[source]

Strike bearing of the patch in degrees, normalised to [0, 360).

Derived from the along-strike vector using the standard geographic convention (clockwise from north). Recomputes normal, down-dip, and along-strike vectors if any are None.

static calculate_along_strike_vector(normal_vector, down_dip_vector)[source]

Compute the along-strike vector as the cross product of the normal and down-dip vectors.

Parameters:

normal_vector (numpy.ndarray of shape (3,)) – Upward-pointing unit normal of the fault patch.
down_dip_vector (numpy.ndarray of shape (3,)) – Down-dip direction vector of the fault patch.

Returns:

Along-strike vector (normal cross down-dip, right-hand rule).

Return type:

numpy.ndarray of shape (3,)

Notes

Compiled with numba.njit for performance.

property centre[source]: Centroid of the triangular patch in NZTM coordinates (metres).

static calculate_centre(vertices)[source]

Calculate the centroid of a triangular patch.

Parameters:: vertices (numpy.ndarray of shape (3, 3)) – Triangle corner coordinates (x, y, z) in NZTM (metres).
Returns:: Mean of the three corner coordinates, i.e. the centroid.
Return type:: numpy.ndarray of shape (3,)

Notes

numpy.mean is not supported by Numba’s njit compiler, so the centroid is computed as sum / len directly. Compiled with numba.njit for performance.

property area[source]: Area of the triangular patch in square metres.

static calculate_area(vertices)[source]

Calculate the area of a triangular patch from its three vertices.

Uses the cross-product formula: area = 0.5 * |a x b|, where a and b are two edge vectors meeting at the same vertex.

Parameters:: vertices (numpy.ndarray of shape (3, 3)) – Triangle corner coordinates (x, y, z) in NZTM (metres).
Returns:: Area of the triangle in square metres.
Return type:: float

Notes

Compiled with numba.njit for performance.

slip3d_to_ss_ds(x1_slip, x2_slip, x3_slip)[source]

Decompose a 3-D slip vector into strike-slip and dip-slip components.

Projects the supplied Cartesian slip vector onto the along-strike and (negated) down-dip directions of this patch.

Parameters:

x1_slip (float | int) – Slip component in the x1 (easting) direction in metres.
x2_slip (float | int) – Slip component in the x2 (northing) direction in metres.
x3_slip (float | int) – Slip component in the x3 (vertical) direction in metres.

Returns:

ds (float) – Dip-slip component in metres (projection onto the up-dip direction).
ss (float) – Strike-slip component in metres (projection onto the along-strike direction).

horizontal_sv_to_ds_ss(slipvec, magnitude=1)[source]

Convert a horizontal slip-vector azimuth to dip-slip and strike-slip components.

Parameters:

slipvec – Azimuth of the slip vector measured clockwise from north, in degrees.
magnitude (float | int) – Desired total magnitude of the output slip components. Results are normalised to this value. Defaults to 1.

Returns:

strike_perp (float) – Strike-perpendicular (dip-slip proxy) component, normalised to magnitude.
strike_par (float) – Strike-parallel (strike-slip proxy) component, normalised to magnitude.
rake (float) – Rake angle in degrees derived from arctan2(strike_perp, strike_par).

Notes

The angle between the patch strike and the input azimuth is used to project the horizontal slip direction onto the fault-plane axes, accounting for the patch dip when resolving the strike-perpendicular component.

slip_vec_3d()[source]

Compute the 3-D slip vector for this patch.

Combines the strike-slip and dip-slip components with their respective direction vectors to produce the full 3-D displacement vector in NZTM Cartesian coordinates (metres).

Returns:: 3-D slip vector in NZTM (metres).
Return type:: numpy.ndarray of shape (3,)

rake_from_stress_tensor(sigma1)[source]

Set the rake to align with the shear stress resolved onto the patch.

Resolves the principal stress vector sigma1 onto the fault plane, extracts the shear-stress component, and sets the patch rake to the angle between that shear stress and the along-strike direction. Assumes sigma2 = sigma3 = 0.

Parameters:: sigma1 (numpy.ndarray of shape (3,)) – Maximum principal stress vector (direction and relative magnitude).
Raises:: AssertionError – If sigma1 does not have exactly 3 elements, or if either along_strike_vector or normal_vector is None.

Notes

Only the direction of sigma1 influences the resulting rake; sigma2 and sigma3 are not accounted for.

property vertical_slip[source]

Vertical component of the dip-slip displacement in metres.

Computed as dip_slip * cos(dip), where dip is in degrees. Positive when the hanging wall moves upward relative to the footwall (reverse/thrust sense).

as_polygon()[source]

Return the triangular patch as a Shapely Polygon.

Returns:: Polygon whose exterior ring is defined by the three patch vertices.
Return type:: shapely.geometry.Polygon

class rsqsim_api.fault.patch.OpenQuakeRectangularPatch(segment, patch_number=0, dip_slip=None, strike_slip=None, rake=None)[source]

Bases: RsqSimGenericPatch

A rectangular fault patch suitable for use with OpenQuake engine inputs.

Stores the four corner points of a planar rectangular fault surface and derives geometric direction vectors from them. Provides a class method to construct a patch from a Shapely Polygon and an export method for writing OpenQuake-compatible XML.

Parameters:

segment – Parent fault segment object that owns this patch.
patch_number (int, optional) – Zero-based integer index identifying the patch. Defaults to 0.
dip_slip (float, optional) – Dip-slip component of displacement in metres.
strike_slip (float, optional) – Strike-slip component of displacement in metres.
rake (float, optional) – Rake angle in degrees.

segment[source]: Reference to the parent fault segment.

patch_number[source]

Non-negative integer patch index.

Type:: int

top_left[source]

Top-left corner in NZTM (metres); populated after construction.

Type:: numpy.ndarray of shape (3,) or None

top_right[source]

Top-right corner in NZTM (metres); populated after construction.

Type:: numpy.ndarray of shape (3,) or None

bottom_left[source]

Bottom-left corner in NZTM (metres); populated after construction.

Type:: numpy.ndarray of shape (3,) or None

bottom_right[source]

Bottom-right corner in NZTM (metres); populated after construction.

Type:: numpy.ndarray of shape (3,) or None

property top_left[source]: Top-left corner of the rectangular patch in NZTM (metres).

property top_right[source]: Top-right corner of the rectangular patch in NZTM (metres).

property bottom_left[source]: Bottom-left corner of the rectangular patch in NZTM (metres).

property bottom_right[source]: Bottom-right corner of the rectangular patch in NZTM (metres).

property along_strike_vector[source]: Unit vector pointing along strike, from top-left to top-right corner.

property top_centre[source]: Midpoint of the top edge of the rectangular patch in NZTM (metres).

property bottom_centre[source]: Midpoint of the bottom edge of the rectangular patch in NZTM (metres).

property down_dip_vector[source]: Unit vector pointing down-dip, from top-centre to bottom-centre.

classmethod from_polygon(polygon, segment=None, patch_number=0, dip_slip=None, strike_slip=None, rake=None, wgs_to_nztm=False)[source]

Construct an OpenQuakeRectangularPatch from a Shapely Polygon.

Parses the four corners of a rectangular fault-surface polygon, identifies which corners belong to the top and bottom edges based on depth (z-coordinate), and assigns them as top-left, top-right, bottom-left, and bottom-right using the along-strike direction to determine left/right orientation.

Parameters:

polygon (shapely.geometry.Polygon) – Closed polygon with exactly 5 exterior coordinates (4 unique corners plus the closing repeat of the first). Each coordinate must have three values (x, y, z); z is depth in metres using a negative-downward convention.
segment – Parent fault segment object. Defaults to None.
patch_number (int, optional) – Zero-based patch index. Defaults to 0.
dip_slip (float, optional) – Dip-slip displacement in metres.
strike_slip (float, optional) – Strike-slip displacement in metres.
rake (float, optional) – Rake angle in degrees.
wgs_to_nztm (bool, optional) – If True, the polygon coordinates are assumed to be in WGS84 (longitude, latitude, depth) and are reprojected to NZTM before assigning corners. Defaults to False.

Returns:

New patch instance with all four corner coordinates set.

Return type:

OpenQuakeRectangularPatch

Raises:

AssertionError – If the polygon exterior does not have exactly 5 coordinate rows (i.e. 4 unique corners).

Notes

For vertical patches (where a top corner shares its horizontal position with a bottom corner) the down-dip vector is set to [0, 0, -1] and the along-strike vector is computed directly from the top edge. For non-vertical patches an across-strike vector is projected horizontally and rotated 90 degrees anti-clockwise using the module-level anticlockwise90 matrix to determine the along-strike direction, which in turn determines the left/right assignment of corner pairs.

to_oq_xml()[source]

Serialise the patch as an OpenQuake planarSurface XML element.

Converts the four corner coordinates from NZTM (metres) to WGS84 longitude/latitude and depth in kilometres, then builds an xml.etree.ElementTree.Element with child elements for each corner.

Returns:: <planarSurface> element containing four child elements named topLeft, topRight, bottomLeft, and bottomRight, each carrying depth (km, 4 d.p.), lat (degrees, 4 d.p.), and lon (degrees, 4 d.p.) attributes.
Return type:: xml.etree.ElementTree.Element

Notes

Depth is stored as a positive value in kilometres following the OpenQuake NRML convention, converted from the negative-downward metres used internally via depth_km = -1e-3 * z.