rsqsim_api.fault.multifault

RSQSim multi-fault model container and related utilities.

Provides check_unique_vertices() for duplicate-vertex detection and RsqSimMultiFault for managing a collection of RsqSimSegment objects, including I/O from RSQSim/Bruce fault files, CFM tsurf directories, and various GIS export methods.

Classes

RsqSimMultiFault

Container for a collection of fault segments forming a complete fault model.

Functions

`check_unique_vertices`(vertex_array[, tolerance])	Check whether any vertices in a 3-D array are potential duplicates.
`read_bruce`([run_dir, fault_file, names_file])

Module Contents

rsqsim_api.fault.multifault.check_unique_vertices(vertex_array, tolerance=1)[source]

Check whether any vertices in a 3-D array are potential duplicates.

Sorts the vertex array and computes distances between adjacent rows in the sorted order; vertices closer than tolerance are flagged as potential duplicates.

Parameters:

vertex_array (numpy.ndarray of shape (n, 3)) – 3-D vertex coordinates.
tolerance (int or float, optional) – Distance threshold (m) below which vertices are reported as potential duplicates. Defaults to 1.

Returns:

num_closer (int) – Number of adjacent-sorted-vertex pairs closer than tolerance.
tolerance (float) – The tolerance value used.

class rsqsim_api.fault.multifault.RsqSimMultiFault(faults, crs=2193)[source]

Container for a collection of fault segments forming a complete fault model.

Aggregates RsqSimSegment objects, provides name-based lookup, boundary computation, and I/O methods for RSQSim/Bruce fault files, CFM tsurf directories, and various GIS export formats.

Parameters:

faults (list | tuple | set)
crs (int)

faults[source]

List of RsqSimSegment (or nested RsqSimMultiFault) objects.

Type:: list

patch_dic[source]

Mapping of global patch number to patch object.

Type:: dict

faults_with_patches[source]

Mapping of global patch number to the owning segment.

Type:: dict

property faults[source]

patch_dic[source]

faults_with_patches[source]

filter_faults_by_patch_numbers(patch_ls, fault_from_single_patch=False)[source]

Return the fault(s) associated with a given patch number or list of patch numbers.

Parameters:

patch_ls (int or array-like of int) – Patch number(s) to look up.
fault_from_single_patch (bool, optional) – If True and a single patch number is given, return the owning RsqSimSegment rather than the patch object. Defaults to False.

Returns:

The patch object, segment, or a new RsqSimMultiFault containing the relevant segments.

Return type:

RsqSimTriangularPatch or RsqSimSegment or RsqSimMultiFault

property names[source]

property name_dic[source]

get_names()[source]: Populate names and name_dic from the loaded faults.

property bounds[source]

property crs[source]

property v2_name_dic[source]

get_patch_areas()[source]

Return a flat array of patch areas for all faults.

Returns:: Patch areas in m².
Return type:: numpy.ndarray of shape (n_total_patches,)

make_v2_name_dic(path2cfm)[source]

Build a dictionary mapping Bruce-V2 fault names to CFM fault names.

Uses fuzzy string matching to find the closest name in the CFM fault model GIS file, with hardcoded overrides for ambiguous cases (Wairau, Hikurangi, Puysegur).

Parameters:: path2cfm (str) – Path to the CFM fault model GIS file (shapefile or GeoJSON) containing a "Name" column.
Returns:: Populates v2_name_dic.
Return type:: None
Raises:: AssertionError – If path2cfm does not exist.

classmethod read_fault_file(fault_file, verbose=False)[source]

Read in opensha xml file? TODO: decide whether this is necessary, and if so finish it :param fault_file: :param verbose: :return:

Parameters:

fault_file (str)
verbose (bool)

classmethod read_fault_file_keith(fault_file, verbose=False, crs=2193, read_slip_rate=True)[source]

Read an RSQSim fault file in Keith Richards-Dinger’s convention.

The file has 13 whitespace-separated columns: x1,y1,z1, x2,y2,z2, x3,y3,z3, rake, slip_rate, fault_num, fault_name.

Parameters:

fault_file (str) – Path to the RSQSim fault input file.
verbose (bool, optional) – If True, print per-fault progress and duplicate-vertex warnings. Defaults to False.
crs (int, optional) – EPSG code for the coordinate reference system. Defaults to 2193 (NZTM).
read_slip_rate (bool, optional) – If True (default), populate patch slip rates.

Return type:

RsqSimMultiFault

classmethod read_fault_file_bruce(main_fault_file, name_file, transform_from_utm=False, from_pickle=False, crs=2193, read_slip_rate=True)[source]

Read an RSQSim fault model in Bruce Shaw’s format.

Reads a two-file layout: a main CSV fault file and a companion names file. Handles the case where multiple fault segments share the same name by appending a numeric suffix.

Parameters:

main_fault_file (str) – Path to the main fault geometry file (space-separated, 13 columns: x1–z3, rake, slip_rate, fault_num, name). Can also be a pickled DataFrame if from_pickle is True.
name_file (str) – Path to the text file listing fault names (one per line, in the same order as fault numbers).
transform_from_utm (bool, optional) – If True, transform vertex coordinates from UTM zone 59S to NZTM. Defaults to False.
from_pickle (bool, optional) – If True, read the main file as a pickled DataFrame. Defaults to False.
crs (int, optional) – EPSG code. Defaults to 2193 (NZTM).
read_slip_rate (bool, optional) – If True (default), populate patch slip rates.

Return type:

RsqSimMultiFault

pickle_model(file)[source]

Serialise all patch data to a pickled pandas DataFrame.

Parameters:: file (str) – Output pickle file path.

classmethod read_cfm_directory(directory=None, files=None, shapefile=None)[source]

Parameters:

directory (str)
files (str | list | tuple)

plot_faults_2d(fault_list=None, show=False, write=None)[source]

Plot selected fault segments in map view coloured by slip rate.

Parameters:

fault_list (iterable of str or None, optional) – Names of faults to plot. Defaults to all faults.
show (bool, optional) – If True, call fig.show(). Defaults to False.
write (str or None, optional) – Output file path for saving the figure.

plot_fault_traces(fault_list=None, ax=None, edgecolor='r', linewidth=0.1, clip_bounds=None, linestyle='-', facecolor='0.8')[source]

Plot fault surface traces on a map axes.

Parameters:

fault_list (iterable of str or None, optional) – Names of faults to plot. Defaults to all faults.
ax (matplotlib.axes.Axes or None, optional) – Axes to draw onto. A new figure is created if None.
edgecolor (str, optional) – Trace edge colour. Defaults to "r".
linewidth (int or float, optional) – Line width. Defaults to 0.1.
clip_bounds (list or None, optional) – [x1, y1, x2, y2] bounding box for the coastline.
linestyle (str, optional) – Line style. Defaults to "-".
facecolor (str, optional) – Not currently used. Defaults to "0.8".

Return type:

matplotlib.axes.Axes

write_fault_traces_to_gis(fault_list=None, prefix='./bruce_faults', crs='EPSG:2193')[source]

Write fault surface traces to shapefiles.

Parameters:

fault_list (iterable of str or None, optional) – Names of faults to export. Defaults to all faults.
prefix (str, optional) – Output file prefix. Two shapefiles are written: {prefix}.shp and {prefix}_traces.shp. Defaults to "./bruce_faults".
crs (str, optional) – CRS string for the output shapefile. Defaults to "EPSG:2193".

write_fault_outlines_to_gis(fault_list=None, prefix='./bruce_faults', crs='EPSG:2193')[source]

Write fault patch-outline polygons to a shapefile.

Parameters:

fault_list (iterable of str or None, optional) – Names of faults to export. Defaults to all faults.
prefix (str, optional) – Output file prefix; produces {prefix}_outlines.shp. Defaults to "./bruce_faults".
crs (str, optional) – CRS string. Defaults to "EPSG:2193".

plot_slip_distribution_2d()[source]

slip_rate_array(include_zeros=True, min_slip_rate=None, nztm_to_lonlat=False, mm_per_year=True)[source]

Build a flat array of triangle vertex coordinates plus slip rate and rake.

Parameters:

include_zeros (bool, optional) – If True (default) and min_slip_rate is set, include below-threshold patches with slip and rake set to zero.
min_slip_rate (float or None, optional) – Minimum slip rate (mm/yr if mm_per_year is True) for inclusion. Defaults to None (include all).
nztm_to_lonlat (bool, optional) – If True, output vertex coordinates in WGS84 (longitude, latitude). Defaults to False.
mm_per_year (bool, optional) – If True (default), convert slip rates from m/s to mm/yr.

Returns:

Columns: [x1,y1,z1, x2,y2,z2, x3,y3,z3, slip_rate, rake].

Return type:

numpy.ndarray of shape (n_patches, 11)

slip_rate_to_mesh(include_zeros=True, min_slip_rate=None, nztm_to_lonlat=False, mm_per_year=True)[source]

Build a meshio.Mesh containing slip rate and rake as cell data.

Parameters:

include_zeros (bool, optional) – Include below-threshold patches as zeros. Defaults to True.
min_slip_rate (float or None, optional) – Minimum slip rate threshold. Defaults to None.
nztm_to_lonlat (bool, optional) – Output in WGS84. Defaults to False.
mm_per_year (bool, optional) – Convert to mm/yr. Defaults to True.

Return type:

meshio.Mesh

slip_rate_to_vtk(vtk_file, include_zeros=True, min_slip_rate=None, nztm_to_lonlat=False, mm_per_year=True)[source]

Write slip rate and rake data to a VTK file.

Parameters:

vtk_file (str) – Output VTK file path.
include_zeros (bool, optional) – Include below-threshold patches. Defaults to True.
min_slip_rate (float or None, optional) – Minimum slip rate threshold. Defaults to None.
nztm_to_lonlat (bool, optional) – Output in WGS84. Defaults to False.
mm_per_year (bool, optional) – Convert to mm/yr. Defaults to True.

write_rsqsim_input_file(output_file, mm_yr=True)[source]

Write all faults to a single RSQSim fault input file.

Parameters:

output_file (str) – Output file path.
mm_yr (bool, optional) – If True (default), treat stored slip rates as mm/yr and convert to m/s for the output.

write_b_value_file(a_value, default_a_b, difference_dict, output_file)[source]

Write per-patch b-values to a text file for use with RSQSim.

Parameters:

a_value (float) – Global a-value parameter (0–1).
default_a_b (float) – Default a − b value (negative float).
difference_dict (dict) – Mapping of fault name to (a − b) value override.
output_file (str) – Output text file path.

tile_quads(tile_size=5000.0, interpolation_distance=1000.0, manual_tiles=None, output_file=None)[source]

Discretize all faults into rectangular tiles.

Calls discretize_rectangular_tiles() on each fault. Manual tile arrays can override individual faults.

Parameters:

tile_size (float, optional) – Target tile dimension (m). Defaults to 5000.
interpolation_distance (float, optional) – Down-dip interpolation spacing (m). Defaults to 1000.
manual_tiles (dict or None, optional) – Mapping of fault name to pre-computed tile array (loaded from a .npy file). Defaults to None.
output_file (str or None, optional) – If given, pickle the resulting dict to this file.

Returns:

Mapping of fault name to tile array (shape (n_tiles, 4, 3)).

Return type:

dict

search_name(search_string)[source]

Search fault names using a wildcard pattern.

Parameters:: search_string (str) – Wildcard pattern (case-insensitive) to match against fault names.
Returns:: Fault names that match the pattern.
Return type:: list of str

find_closest_patches(x, y)[source]

Find the patches closest to given 2-D coordinates.

Parameters:

x (float) – Easting (NZTM) in metres.
y (float) – Northing (NZTM) in metres.

Returns:

Patch numbers of the patches in the closest fault whose vertices include the nearest vertex.

Return type:

list of int

find_closest_patches_3d(x, y, z)[source]

Find the patches closest to given 3-D coordinates.

Parameters:

x (float) – Easting (NZTM) in metres.
y (float) – Northing (NZTM) in metres.
z (float) – Depth (negative metres below sea level).

Returns:

Patch numbers of the patches in the closest fault whose vertices include the nearest vertex.

Return type:

list of int

property traces[source]

get_traces()[source]: Build and cache a GeoDataFrame of all fault surface traces.

property outlines[source]

get_outlines()[source]: Build and cache a GeoDataFrame of all fault patch-outline polygons.

merge_segments(matching_string, name_dict=None, fault_name=None)[source]

Merge multiple fault segments matching a name pattern into one segment.

Parameters:

matching_string (str) – Wildcard pattern used to identify segments to merge. Without name_dict, matches names like "{matching_string}?" or "{matching_string}??".
name_dict (dict or None, optional) – Mapping of internal segment name to an alternative name for pattern matching.
fault_name (str or None, optional) – Name for the merged segment.

Returns:

New segment containing all patches from the matched segments, with merged surface trace.

Return type:

RsqSimSegment

get_subduction_patch_numbers(subduction_faults=('hikkerm', 'puysegur'))[source]

Return patch numbers for all subduction-zone fault segments.

Parameters:: subduction_faults (tuple of str, optional) – Substrings used to identify subduction faults by name. Defaults to ("hikkerm", "puysegur").
Return type:: numpy.ndarray of int

get_crustal_patch_numbers(subduction_faults=('hikkerm', 'puysegur'))[source]

Return patch numbers for all crustal (non-subduction) fault segments.

Parameters:: subduction_faults (tuple of str, optional) – Substrings identifying subduction faults to exclude. Defaults to ("hikkerm", "puysegur").
Return type:: numpy.ndarray of int

rsqsim_api.fault.multifault.read_bruce(run_dir='/home/UOCNT/arh128/PycharmProjects/rnc2/data/shaw2021/rundir4627', fault_file='bruce_faults.in', names_file='bruce_names.in')[source]

Parameters:

run_dir (str)
fault_file (str)
names_file (str)