Skip to content

Draft: fault block fields and kinematics fixes - #409

Merged
lachlangrose merged 20 commits into
Loop3D:masterfrom
lachlangrose:kiridashi/block-fields
Nov 17, 2026
Merged

lachlangrose merged 20 commits into
Loop3D:masterfrom
lachlangrose:kiridashi/block-fields

Conversation

@lachlangrose

Copy link
Copy Markdown
Member

Moved from lachlangrose#5.

Summary

Draft changes for review on the fork. Nothing here is proposed to Loop3D yet. The base is master of this fork, synced with upstream at f501197c.

One commit per item, so each can be taken alone.

Fault block fields (new, provisional API)

  • Evaluate a geological feature in one fault block, with no interpolation across the fault: evaluate_feature_block_value and evaluate_feature_block_gradient.
  • Fault frame value and gradient, tip functions, and restoration of points in a block.
  • A fault block can be passed to region checks (abutment, unconformity).
  • Across its fault, a block continues its own displacement profile smoothly (C2): a cubic profile by its own cubic, any other profile by its value, slope and curvature at the fault, blended to a constant away from the fault. The mirror image, which has a kink for a profile with a slope at the fault, stays only as a module setting for comparison.

Bug fixes that change model results

  • A point is restored through a displaced fault once, not twice. Changes models where a fault displaces a feature and is itself displaced by a younger fault that also displaces that feature. Models without displaced faults do not change. Listed in COMPAT.md for the release notes.
  • An unconformity truncates the faults that are older than it. A fault is younger when it displaces the series of the unconformity or a series above an earlier unconformity; every other fault is older and takes the region. Onlap unconformities are unchanged. The changed behaviours are listed in COMPAT.md.
  • The CG solver uses the model tol; before, scipy stopped at its own rtol of 1e-5.

Solver tolerance in model length units (new, off by default)

  • position_tolerance on GeologicalModel, the create_and_add_* methods and DiscreteInterpolator.solve_system: the solver stops when the estimated position error of the isosurfaces is below a length in model units. It is an estimate, not a guarantee; in the measurements it was conservative.
  • Measured reason: with rtol 1e-5 the largest isosurface position error was 59 m and 147 m on the Claudius example and 207 m on a 10 km faulted model.

Other

  • apply_to_points honours reverse=True.
  • get_feature_relations: a public accessor for the relations between features.
  • The tip of a displacement profile can be declared (tip_ends); a cubic profile is clamped beyond its limit.
  • Cell indexes are found in one vectorised step (about 20 % less fixed cost per call).

Open questions

  • Default of position_tolerance: None (this draft) or 1e-4 of the largest side of the model? Build time at 1e-4 was 1.04 to 2.6 times a build with rtol 1e-5.
  • tol used as the CG atol is not scale free (a 10 km model stops early; the same model in a unit box does not). Drop it, or scale it?
  • "Older" is read from the faults list of the cover series: a fault left out of that list for another reason is now truncated.
  • Should onlap unconformities truncate faults as well?
  • Commit type of the unconformity change: fix (this draft) or a breaking change?
  • Blend distances of the block continuation (exact to 0.25, constant from 0.5, in fault-frame units).

Test plan

  • pytest tests: 2877 passed, 36 skipped, 0 failed (102 new tests); master gives 2775 passed.
  • packages/loop_interpolation/tests: 641 passed (26 new), 47 skipped, 2 xfailed.
  • packages/loop_common/tests: 421 passed.
  • No existing test changed.

The counts are from the local branch, which also holds documentation-only commits that are left out of this copy; the code is the same.

🤖 Generated with Claude Code

https://claude.ai/code/session_01XADRvLtMSHY4aXcrL452oh

lachlangrose and others added 20 commits November 16, 2026 10:03
Add the private module utils/_fault_block with the helpers that check a
fault block (fault name to +1, -1 or 0) and put a fault frame value on
one side of the fault. The sign regions evaluate their feature in the
block, and a block that fixes the side of the region's fault also fixes
the side outside the support of that fault.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XADRvLtMSHY4aXcrL452oh
GeologicalFeature.evaluate_value and evaluate_gradient take an optional
keyword block. The block goes to the regions and to the faults of the
feature, so each fault it names restores the points as if they were on
the given side. The gradient does not refine its tetrahedra across a
fault that the block names, because the block field has no jump there.
Without a block the calls are the same as before.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XADRvLtMSHY4aXcrL452oh
FaultSegment.apply_to_points, evaluate_value and evaluate_displacement
take an optional keyword block. If the block names the fault, the frame
coordinate gx is put on that side (side * max(|gx|, 1e-9)) wherever the
fault is evaluated, so the displacement is that of the given wall,
extended smoothly over the whole support; 0 leaves the points in place.
The frame is evaluated in the same block, so a fault that younger faults
displace follows the block of those faults.

New provisional methods:
- evaluate_frame_value / evaluate_frame_gradient: one frame coordinate
  without the fault regions, optionally in a block of the younger faults.
- evaluate_tip_value / evaluate_tip_gradient: min(1 - |g|) over the frame
  coordinates whose displacement profile is zero at |g| = 1; inf for a
  fault without a tip.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XADRvLtMSHY4aXcrL452oh
Provisional GeologicalModel methods that evaluate a feature, by name, in
one fault block. The block must name faults of the model. The regions of
the feature itself are ignored by default, so the result is the smooth
extension of the block over the whole support.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XADRvLtMSHY4aXcrL452oh
Planar constant-slip fault (analytic offset between the blocks, equality
inside each block, smooth gradient, no state, threads), finite fault
(equal fields beyond the tip, displacement to zero at the tip, tip
gradient), an abutting fault (absent in the footwall block of its host)
and a displaced fault (block frames match the undisplaced fault).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XADRvLtMSHY4aXcrL452oh
The block-field tests and the kinematics tests share them.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XADRvLtMSHY4aXcrL452oh
The sign of reverse was applied to the displacement before the
integration loop, and the loop recomputed the displacement without it,
so reverse=True restored the points instead of moving them forward.
The loop now applies the sign at every step. No caller inside
LoopStructural passes reverse=True, so no model built by LoopStructural
changes; external forward modelling (for example the fault benchmark's
forward()) now moves points forward.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XADRvLtMSHY4aXcrL452oh
A feature keeps its faults youngest first. When a younger fault displaces
an older fault, the frame of the older fault is built in the space
restored by the younger fault, and its frame features list the younger
fault among their own faults. Evaluating the feature restored the point
through the younger fault, then the older fault evaluated its frame at
that point and restored it through the younger fault a second time.
The builder restored the data the same way, so the model was consistent
with itself but its kinematics were wrong: the side and the slip of the
older fault were read at a point moved twice by the younger fault.

The faults of a list are now applied by one helper, restore_through,
which tells each fault which faults the points have already been
restored through; the fault evaluates its frame (value and slip
gradient) without those faults. The new keyword restored_through on
FaultSegment.apply_to_points / apply_to_vectors and on
GeologicalFeature.evaluate_value / evaluate_gradient carries it; no
state changes. Without the keyword every call is as before.

THIS CHANGES THE RESULTS OF EXISTING MODELS: every model where a fault
displaces a feature and is itself displaced by a younger fault that also
displaces that feature (the series data and the evaluation both change).
Models without displaced faults do not change. LambdaGeologicalFeature
and AnalyticalFeature keep their own fault loops and are not changed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XADRvLtMSHY4aXcrL452oh
A fault-like object with only apply_to_points(points) (as in
test_support_expansion_contains_restored_points) failed because the
helper always passed reverse=. It now passes reverse, block and
restored_through only when they are needed, as the old loops did.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XADRvLtMSHY4aXcrL452oh
Provisional GeologicalModel.get_feature_relations() returns the
relations of a model as a plain dictionary: the event order (features in
the order they were added), for each fault the faults that displace it,
the faults it abuts with the side and the unconformities that truncate
it, for each other feature the faults that displace it (restore order)
and its truncations, and for each unconformity its series, value and
what it truncates. It reads the builders, so it is the same before and
after update(); it changes nothing. Logic in
FeatureRelationshipManager.relations.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XADRvLtMSHY4aXcrL452oh
FaultDisplacement.tip_ends gives, for gy (1) and gz (2), the ends where
the profile is exactly zero, from a new tip_ends attribute of the
profiles (FaultProfileFunction subclasses and smooth_peak). A profile
that does not declare it is still tested numerically.
FaultSegment.evaluate_tip_value reads it instead of testing profiles.

CubicFunction now clamps to the value of a value constraint that sits
exactly at its limit. The least squares fit left about 1.5e-14 where
the constraint asks for 0, so the BaseFault / BaseFault3D displacement
was 1.5e-14 * scale * displacement, not 0, beyond |gx| = 1. THIS CHANGES
THE RESULTS OF EXISTING MODELS WITH BaseFault OR BaseFault3D PROFILES,
by at most about 1e-14 of the displacement, at |gx| >= 1.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XADRvLtMSHY4aXcrL452oh
… (LS-F1)

scipy's cg stops at max(rtol*|b|, atol). solve_with_cg and
solve_with_cg_normal_equations set atol=tol and left rtol unset, so
scipy's default rtol=1e-5 decided the stop and the tol of a
LoopStructural model (1e-10 of the box) had no effect; the library's own
DEFAULT_CG_RTOL (1e-8) was used only without a tol. Both now go through
_set_cg_tolerances: atol=tol if no atol is given, rtol=DEFAULT_CG_RTOL
if no rtol is given. A caller's own atol is no longer replaced by tol.

THIS CHANGES THE RESULTS OF EXISTING MODELS solved with cg: the solve
runs to rtol 1e-8. Measured on the fault benchmark cases: the field
moves by up to 1.4e-3 (planar_fault, in a data-free corner) and 3.2e-4
(fault_tip), the build takes 15 % to 70 % longer, and the values no
longer depend on where scipy stopped (they agree with rtol 1e-12 to
the printed digits).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XADRvLtMSHY4aXcrL452oh
position_to_cell_index read origin, step_vector and nsteps_cells (each a
computed property) once per axis and floored each axis separately. It
is called several times per interpolator evaluation, so for small
batches its fixed cost dominated. It now reads the geometry once and
works on all axes at once; inside() keeps its overridable behaviour.
Same results (loop_common tests unchanged, 421 passed). Measured on a
1-point block evaluation of the planar_fault benchmark: 0.70 ms to
0.55 ms per call.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XADRvLtMSHY4aXcrL452oh
…(LS-F1)

position_tolerance says how far the isosurfaces of a cg-solved field may
be from the isosurfaces of the fully converged field, as a length in the
units of the model (the support is moved and rotated but not scaled, so
1.0 is 1 m in a model in metres). It is a keyword of
DiscreteInterpolator.solve_system, an attribute of GeologicalModel
(default None) and a keyword of the create_and_add_* methods. None keeps
the present stop on the residual; tol is not removed.

The stop is an estimate, not a guarantee. cg_to_position_tolerance runs
the iteration of scipy's cg (the same operations, so the same iterates)
and, every 10 iterations once the residual has dropped by 1e-6, takes
the size of the error from |r| / theta (theta: the smallest Ritz value of
the Lanczos matrix of the cg steps, which bounds the 2-norm of the error
once it has converged) and its distribution over the unknowns from the
change of the solution over the last 50 iterations (the delay estimate
of Strakos and Tichy). The interpolator turns that into a length with
the median gradient norm at the support nodes.

Measured on five models (faulted 1 unit and 10 km, Claudius FDI and PLI,
Laurent2016), for tolerances of 1e-3 to 1e-5 of the box: the largest
position error at a node is 6e-5 to 0.19 times the tolerance. A fixed
rtol gives position errors that differ by 1e5 between solves, and a stop
on the change alone is up to 1000 times over the tolerance on systems
where cg stagnates. At 1e-4 of the box the build takes 1.04 to 2.6 times
the build with scipy's rtol 1e-5.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XADRvLtMSHY4aXcrL452oh
…it (LS-D2)

add_unconformity skipped faults: a fault that was already in the model
kept its frame and its surface above the unconformity and moved points
there. Only a fault created after the call took the region. Now every
fault that is older than the unconformity takes its region, so the frame
and the surface exist only below the unconformity and the fault moves no
point above it. The features that the fault displaces are marked to be
built again.

Which faults are older: a new feature is displaced by every fault that
the model has at that moment, unless its faults argument gives another
list. A fault is younger if it displaces the series of the unconformity,
or a series above an earlier unconformity; it is not changed. Every
other fault is older: a fault added after the series (before or after
the call), and a fault added before it that the faults argument of the
series leaves out.

A fault created after several unconformities takes the region of each
of them, not only of the last one.

The unconformity region of a fault that a younger fault displaces is
read at the point restored once through the younger fault (keyword
restored_through on UnconformityFeature.evaluate and __call__); it was
read at the point restored twice.

Onlap unconformities are not changed: no fault takes their region.

THIS CHANGES THE RESULTS OF EXISTING MODELS (listed in COMPAT.md): where
a fault is left out of the faults list of the series of an unconformity
or is added between that series and the call; where a fault follows two
or more unconformities; where a truncated fault is displaced by a
younger fault. Models without an unconformity, faults that displace the
series of the unconformity and onlap unconformities give bit-equal
results.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XADRvLtMSHY4aXcrL452oh
…LS-E1)

Owner decision D3: the fix of the double restoration (54371120,
bb7ef627) goes in with no flag and is listed as a bug fix.

CHANGELOG.md is written by release-please from the commit subjects. The
two commits have the type fix, so the release gets a "Bug Fixes" entry
"fault: restore a point through a displaced fault once (LS-E1)". The
changelog does not take the commit body, so the text of the release
notes is the new row in the behaviour table of COMPAT.md: what was
wrong, which models change (a fault displaces a feature and is itself
displaced by a younger fault that also displaces that feature), and that
models without displaced faults do not change.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XADRvLtMSHY4aXcrL452oh
… fault (LS-A2)

Owner decision D1: the extension of a block across its fault is not the
mirror image. A block field is evaluated on both sides of the fault; on
the other side the displacement was the profile at side * |gx|. That is
an even extension: it has a kink where the profile has a slope at the
fault, so the faulted field had a sharp change of gradient there.

The displacement on the other side is now the smooth continuation of
the profile of the block's side across gx = 0
(_fault_function.block_displacement):

* Ones, Zeros: the constant.
* CubicFunction (BaseFault, BaseFault3D, user cubics): its own cubic at
  the signed coordinate, without its limits. Smooth to all orders.
* any other gx profile, and a fault function that is not a
  FaultDisplacement: the second-order expansion at the fault, with
  one-sided finite differences of fourth order (step 1e-3 in gx). C2.

Up to 0.25 in gx from the fault the continuation is exact; it is blended
(C2) to a constant at 0.5, so it cannot grow without limit. The gy and
gz profiles are not changed. On the block's own side every value is bit
equal. evaluate_feature_block_gradient uses the same displacement.

The side of a point for regions and abutting faults still uses
side * |gx| (force_side). The mirror image stays as
_fault_block.BLOCK_EXTENSION = "mirror", a module setting to compare
with data made with it (the fault benchmark study).

Constant-slip blocks do not change. For the library cubics the block
field on the other side changes by 4 |gx|^3 times the displacement
scale: measured up to 2.3e-4 within one cell of 1/48 and 4.4e-2 far from
the fault (BaseFault3D, displacement 0.2, minor axis 0.5).

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XADRvLtMSHY4aXcrL452oh
…uncation of older faults

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XADRvLtMSHY4aXcrL452oh
@lachlangrose
lachlangrose marked this pull request as ready for review November 17, 2026 23:45
@lachlangrose
lachlangrose merged commit 593953b into Loop3D:master Nov 17, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant