Two-stage Fault Connectivity Check

[lispandfound]

This PR adds a fallback check to the fault connectivity checker. This fallback check is designed to make it easier to construct faults with very small segments.

What Does the Fault Connectivity Check Do?

Faults are a series of connected planes. The planes should be connected along-strike and in a line, that is if plane_1 points to plane_2 and plane_2 points to plane_3 (along-strike), then the fault containing planes 1, 2, and 3 should be instantiated Fault([plane_1, plane_2, plane_3]). In a perfect world faults from all sources including the National Seismic Hazard Model, community fault model, and custom geometries would be specified like this. Unfortunately the world is far from perfect and instead faults are called with an arbitrary order of planes like Fault([plane_2, plane_1, plane_3]). So we must sort sort them ourselves.

How Does the Sorting Work?

The sorting works by building a graph with an edge between indices i and j of the input list if the rightmost top corner of plane_i is close to the leftmost top corner of plane_j. For the above fault with planes passed as a list [plane_2, plane_1, plane_3] the graph constructed would look like 1 --> 0 --> 2. The sorting is then a topological sort applied to this graph to get the sorted list of planes [plane_1, plane_2, plane_3]. Notably, we also check before this stage that the graph is a line. If the graph is not connected, or contains cycles, then that tells us the fault planes given do not make a fault consistent with the assumptions of the Fault class. We raise a ValueError in these cases.

What is the Problem?

There are three ways a fault can be invalid:

1. The fault planes are disconnected. This happens if the planes have inconsistent strikes (think two planes next to each other with strikes 180 degrees apart), or the planes are far apart.
2. The fault planes are connected, but the planes point into each other cyclically. Think a triangle of fault planes pointing into each other in a circle.
3. The fault planes have really short segments.

That last problem is artificial. The close to check we do when sorting the faults needs to have some leeway to admit faults that have rounded corners or other numerical imprecision. This in turn means that sometimes fault planes are erroneously believed to point into more than one plane downstream. For instance,

|    Plane 1   | 2 |    Plane 3   |

which might get the graph 1 -> [2, 3], 2 -> 3. We then throw a ValueError to reject this fault. A simple fix is adjusting the close to check to be more careful about which planes are considering pointing into each other, but then that causes more faults to be rejected of the first type. The NSHM is full of such faults with short segments unfortunately so the tension between type-1 and type-3 rejections is very painful.

The New Solution

Instead of relaxing the close to check for the upteenth time, I have made a modification to the line sorting algorithm. It now checks if the faults form a line, and if they don't it performs a transitive reduction and tries again. If it still fails the second time, an error is thrown. In the earlier example case, The graph starting 1 -> [2, 3], 2 -> 3 is reduced to 1 -> 2, 2 -> 3 and then the fault is then successfully constructed on the second pass. I don't believe this will introduce any errors where we accept invalid faults, but just in case I've added a warning so that the user knows to check the fault just in-case.

[Copilot]

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.