fault_mesh.faults.leapfrog

Classes that implement the Leapfrog fault model. Inherit from GenericFault and GenericMultiFault.

Classes

LeapfrogMultiFault	Class to hold data for multiple faults, read in from shapefile (and hopefully also tsurfaces)
LeapfrogFault	Represents either a whole fault (for simple faults) or one segment. Behaviours is slightly

Module Contents

class fault_mesh.faults.leapfrog.LeapfrogMultiFault(fault_geodataframe, sort_sr=False, segment_distance_tolerance=100.0, smoothing_n=None, remove_colons=True, dip_choice='pref', trimming_gradient=1.0, epsg=None, dip_multiplier=1.0, strike_multiplier=0.5, check_optional_fields=True)

Bases: fault_mesh.faults.generic.GenericMultiFault

Class to hold data for multiple faults, read in from shapefile (and hopefully also tsurfaces)

Parameters:

• fault_geodataframe (geopandas.GeoDataFrame)

• sort_sr (bool)

• segment_distance_tolerance (float)

• smoothing_n (int)

• remove_colons (bool)

• dip_choice (str)

• trimming_gradient (float)

• epsg (int)

• dip_multiplier (float)

• strike_multiplier (float)

• check_optional_fields (bool)

find_connections(verbose=True)

Find all connections between faults in the fault list using networkx :param verbose: print out information about individual connections :return:

Parameters:

verbose (bool)

suggest_trace_extensions(out_file, fit_distance=5000.0, extend_distance=40000.0, proximity_threshold=1000.0, geojson_out_file=None)

Suggest trace extensions for faults that terminate against higher-priority faults.

Generates a CSV file with columns:

fault_name, end, extend_distance, fit_distance

The ‘end’ column is a compass direction (N, NE, E, SE, S, SW, W, NW) indicating which end of the fault trace to extend. Where both ends terminate, two rows are written.

The output file can be edited by the user and then read back with read_trace_extensions().

If geojson_out_file is provided, also writes a GeoJSON containing the suggested extended trace geometries (one feature per row of the CSV) so the suggestions can be inspected in GIS software before being applied.

Parameters:

• out_file (str)

• fit_distance (float)

• extend_distance (float)

• proximity_threshold (float)

• geojson_out_file (str)

read_trace_extensions(csv_file)

Read a trace-extensions CSV file.

Expected columns: fault_name, end, extend_distance, fit_distance. Fault names are validated against current curated fault names.

Parameters:

csv_file (str)

read_removed_trace_extensions(csv_file)

Drop trace extensions listed in a removals CSV.

Expected columns: fault_name, end. Written by review_trace_extensions.py as a separate list rather than by editing the curated extensions file, so the hand-made edited_trace_extensions.csv stays exactly as its author left it. Call between read_trace_extensions() and apply_trace_extensions().

Parameters:

csv_file (str)

apply_trace_extensions(resolution=1000.0)

Apply trace extensions previously loaded with read_trace_extensions().

For each row the relevant fault end is identified by compass direction and the trace is extended accordingly.

Parameters:

resolution (float)

check_surface_trace_extensions(mesh_dir, suffix='_cut.obj', flag_distance=2000.0, lateral_tolerance=500.0, top_depth=0.0, z_tolerance=1.0, out_file=None, geojson_out_file=None, verbose=True)

Compare the surface trace of each cut mesh against the original fault trace.

Trace extensions exist to grow a fault’s subsurface area so that it meets its neighbours and can be cut cleanly; they are not meant to survive at the surface. Where a cut mesh still reaches the surface beyond the end of the original (un-extended) trace, either the cut did not happen (fix with additional_cuts) or the extension was unnecessary (fix by removing it from the trace-extensions CSV).

Each cut mesh in mesh_dir is read back from disk, so this can be run on its own without re-cutting. For every fault the parts of the mesh’s surface trace lying further than lateral_tolerance from the original trace are reported, split by which end of the trace they run off; parts reaching more than flag_distance beyond it are flagged.

Parameters:

• mesh_dir (str) – directory holding the cut meshes

• suffix (str) – appended to the fault name to make each mesh filename

• flag_distance (float) – overhang (m) beyond which an end is flagged

• lateral_tolerance (float) – distance (m) from the original trace within which surface trace is considered coincident with it; allows for the smoothing and spline fitting done when meshing

• top_depth (float) – z value (m) of the top of the meshes

• z_tolerance (float) – tolerance (m) on top_depth

• out_file (str) – optional CSV to write the results to

• geojson_out_file (str) – optional GeoJSON of the extra trace geometry

• verbose (bool) – print a summary of the flagged faults

Returns:

DataFrame of results, worst overhang first

check_jagged_cuts(mesh_dir, suffix='_cut.obj', angle_threshold=20.0, min_kinked_segments=3, step_scales=(500.0, 1000.0), step_angle=30.0, min_reversals=3, top_depth=0.0, z_tolerance=1.0, out_file=None, geojson_out_file=None, verbose=True)

Flag cut meshes whose subsurface outline is jagged.

A clean cut leaves a smooth outline. A cut that has gone wrong leaves a rough one, and roughness comes in two forms that need measuring differently:

Kinks are single segments that differ in 3-D direction from both their neighbours by at least angle_threshold. This catches isolated spikes and the sliver segments a bad clip leaves behind. A fault with min_kinked_segments or more is flagged.

Steps are the staircases a cut leaves when it follows whole triangle edges instead of the true intersection. These are invisible to the kink test, because each tread and riser is several collinear segments: the turn inside a tread is zero, and the segment at a corner differs from only one of its neighbours. They are found instead by resampling the outline at each of step_scales and counting direction reversals – consecutive turns of at least step_angle that go opposite ways. The scale with the most reversals is reported, and min_reversals or more flags the fault.

Only the subsurface part of the outline is examined. The surface trace is dropped first, because a trace faithfully follows the mapped fault and is expected to bend sharply; use check_surface_trace_extensions() for that part of the outline.

Parameters:

• mesh_dir (str) – directory holding the cut meshes

• suffix (str) – appended to the fault name to make each mesh filename

• angle_threshold (float) – direction change (degrees) counting as a kink

• min_kinked_segments (int) – number of kinks needed to flag a fault

• step_scales (tuple) – chord lengths (m) at which to look for steps

• step_angle (float) – direction change (degrees) counting as a step turn

• min_reversals (int) – number of reversals needed to flag a fault

• top_depth (float) – z value (m) of the top of the meshes

• z_tolerance (float) – tolerance (m) on top_depth

• out_file (str) – optional CSV to write the results to

• geojson_out_file (str) – optional GeoJSON of the kinked and stepped parts

• verbose (bool) – print a summary of the flagged faults

Returns:

DataFrame of every mesh with a kink or a step, worst first

candidate_cutters(fault_name)

Every fault that could have cut fault_name: those ranked above it in the cutting hierarchy, plus any forced onto it by additional_cuts (which apply even where the named cutter ranks lower, or is absent from the hierarchy altogether).

Parameters:

fault_name (str)

attribute_jagged_cuts(jagged, uncut_mesh_dir, suffix='_depth_contours.obj', max_distance=1500.0, depth_surface=None, verify_cuts=True, actual_cuts=None, cut_threshold=0.7, min_cut_distance=10000.0, bottom_depth=-30000.0, out_file=None, geojson_out_file=None, verbose=True)

Work out which cut left each jagged fault’s outline serrated.

Takes the output of check_jagged_cuts() and, for every kinked segment, finds the nearest fault surface that was entitled to cut that fault (see candidate_cutters()). A kink sitting on a cutter’s surface was left by that cut. Kinks near neither, but close to the base depth surface, are attributed to it; the rest come back “unattributed” and are worth a look, since they point at something other than a cut – awkward contours, or a surface self-intersecting.

The uncut Stage 1 surfaces are used for the cutters, because those are the meshes the cutting loop starts from and they span the whole intersection even where the cutter was later trimmed itself.

Proximity alone will happily blame a fault that merely passes nearby, so each attribution is checked and reported in the cut_confirmed column. Pass actual_cuts – the record the cutting loop kept of what it really cut (see FaultMesh.cut_against) – and the column is exact. Without it, verify_cuts falls back to re-running the model’s own cut decision; that test is run without the higher-priority context that can veto a cut, which only makes it more willing to say yes, so a False still means the real run cannot have made that cut either.

Attributions that come back False are worth reading the other way round – the outline is following a surface that never cut it, which may be a cut that should have been made and was not.

Parameters:

• jagged (pandas.DataFrame) – DataFrame from check_jagged_cuts(), typically the flagged rows only

• uncut_mesh_dir (str) – directory of the uncut (Stage 1) surfaces

• suffix (str) – appended to the fault name to make each mesh filename

• max_distance (float) – how close (m) a kink must lie to a surface to be attributed to it

• depth_surface (pyvista.PolyData) – the base depth surface, if kinks should also be attributed to the depth trim

• verify_cuts (bool) – check each attribution when actual_cuts is not given

• actual_cuts – the cuts really made, as {fault_name: [cutter, …]} or the path to a two-column cuts_applied.csv; makes cut_confirmed exact and skips the re-test entirely

• cut_threshold (float) – threshold passed to decide_whether_to_cut

• min_cut_distance (float) – min_distance passed to decide_whether_to_cut

• bottom_depth (float) – bottom_depth passed to decide_whether_to_cut

• out_file (str) – optional CSV to write the results to

• geojson_out_file (str) – optional GeoJSON of the attributed segments

• verbose (bool) – print the attribution per fault

Returns:

DataFrame with a row per (jagged fault, cutter)

property additional_cuts

Set of (fault_name, fault_name) tuples for cuts that should always be made.

property excluded_cuts

Set of (fault_name, fault_name) tuples for cuts that should never be made.

read_additional_cuts(csv_file)

Read a two-column CSV listing pairs of faults that should always be cut.

Columns: fault_to_cut, cutting_fault Fault names are validated against current curated fault names.

Parameters:

csv_file (str)

read_excluded_cuts(csv_file)

Read a two-column CSV listing pairs of faults that should NOT be cut.

Columns: fault_to_cut, cutting_fault Fault names are validated against current curated fault names.

Parameters:

csv_file (str)

should_cut(fault_name, cutting_fault_name)

Check additional/excluded cut lists and return True/False/None.

Returns True if the pair is in additional_cuts, False if in excluded_cuts, or None if neither list applies (fall through to decide_whether_to_cut).

Parameters:

• fault_name (str)

• cutting_fault_name (str)

Return type:

bool

to_opensha_xml(exclude_subduction=True, buffer_width=5000.0, write_buffers=True, subduction_names=('hikurangi', 'puysegur'))

Write out XML in OpenSHA format :param exclude_subduction: Do not include subduction zones from CFM :return:

Parameters:

• exclude_subduction (bool)

• buffer_width (float)

• write_buffers (bool)

• subduction_names (tuple)

to_quads_mesh(sampled_dip=True, depth_multiplier=0.8, file_name=None)

Generate a mesh of quads from the fault traces. :param sampled_dip: If True, use the sampled dip value for the fault. :param depth_multiplier: Multiplier for the depth to control the spacing of the mesh. :return: Meshio mesh object.

Parameters:

• sampled_dip (bool)

• depth_multiplier (float)

• file_name (str)

combine_meshes_to_vtk(file_name=None, only_faults=None, include_connected_segments=True)

Merge each curated fault’s surface mesh into a single VTK file.

Each fault contributes its .mesh.mesh (a meshio Mesh on the attached FaultMesh). A fault_id cell array distinguishes faults in the merged output; the id → name mapping is stored as field data under fault_names. For ConnectedFaultSystem faults whose top-level mesh isn’t set, falls back to merging individual segment meshes when include_connected_segments is True.

Parameters:

• file_name (str) – Optional output path. Defaults to no save. .vtk extension is appended if missing.

• only_faults (List[str]) – Optional restricted list of fault names to include.

• include_connected_segments (bool) – If True, when a ConnectedFaultSystem has no combined mesh, merge in any meshes attached to its individual segments.

Returns:

The merged mesh.

Return type:

pv.PolyData (or UnstructuredGrid)

class fault_mesh.faults.leapfrog.LeapfrogFault(parent_multifault=None, smoothing=5, trimming_gradient=1.0, segment_distance_tolerance=100.0)

Bases: fault_mesh.faults.generic.GenericFault

Represents either a whole fault (for simple faults) or one segment. Behaviours is slightly

Parameters:

• parent_multifault (LeapfrogMultiFault)

• smoothing (int)

• trimming_gradient (float)

• segment_distance_tolerance (float)

property is_segment

Records whether instance is a segment of a larger multi-segment fault like the Alpine Fault. :return:

property smoothing

n value to use in Chaikin’s corner-cutting algorithm. :return:

property trimming_gradient

Factor that controls how much the ends of segment contours of a multi-segment fault are shortened to allow :return:

property parent

Return LeapfrogMultiFault instance that this fault is part of. :return:

property sampled_dip

Dip value sampled from the fault trace. Used for calculating dip in depth contours. :return:

generate_sampled_dip(from_parent=True)

Generate a sampled dip value from the min and max dip :param from_parent: If True, use the parent multi-fault’s sampled dip value. :return:

property down_dip_vector_sampled

Calculated from dip and dip direction

depth_contour(depth, smoothing=True, km=False, sr_and_rake=False, dummy_segment_length=100.0)

Generate contour of fault surface at depth below surface :param depth: In metres, upwards is positive :param smoothing: N for use with Chaikin’s corner cutting :param km: If True, divide depth by 1000 :return: LineString or MultiLineString representing contour

Parameters:

• depth (float)

• smoothing (bool)

• sr_and_rake (bool)

• dummy_segment_length (float)

property nztm_trace_coords

Return the coordinates of the nztm trace as a numpy array. :return: numpy array of coordinates

extend_footprint(end_i, other_end, other_segment, deepest_contour_depth=30000.0, search_line_length=150000.0, buffer_size=5000.0, fall_back_distance=40.3)

Parameters:

• end_i (shapely.geometry.Point) – End to extend

• other_end (shapely.geometry.Point) – Other end of segment

• other_segment (LeapfrogFault) – Other

• deepest_contour_depth (float)

• search_line_length (float)

• buffer_size (float)

• fall_back_distance (float)

Returns:

to_quads(sampled=True, depth_multiplier=0.8)

Extract quads and vertices for writing using meshio. :param sampled: If True, use the sampled dip vector. :param depth_multiplier: Multiplier for the depth to scale the bottom trace. :return: vertices and quads as numpy arrays.

Parameters:

• sampled (bool)

• depth_multiplier (float)

Return type:

dict