Repository navigation
Draft: fault block fields and kinematics fixes - #409
Merged
lachlangrose merged 20 commits intoNov 17, 2026
Merged
Conversation
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
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
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
marked this pull request as ready for review
November 17, 2026 23:45
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Moved from lachlangrose#5.
Summary
Draft changes for review on the fork. Nothing here is proposed to Loop3D yet. The base is
masterof this fork, synced with upstream atf501197c.One commit per item, so each can be taken alone.
Fault block fields (new, provisional API)
evaluate_feature_block_valueandevaluate_feature_block_gradient.Bug fixes that change model results
COMPAT.mdfor the release notes.COMPAT.md.tol; before, scipy stopped at its own rtol of 1e-5.Solver tolerance in model length units (new, off by default)
position_toleranceonGeologicalModel, thecreate_and_add_*methods andDiscreteInterpolator.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.Other
apply_to_pointshonoursreverse=True.get_feature_relations: a public accessor for the relations between features.tip_ends); a cubic profile is clamped beyond its limit.Open questions
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.tolused as the CGatolis not scale free (a 10 km model stops early; the same model in a unit box does not). Drop it, or scale it?faultslist of the cover series: a fault left out of that list for another reason is now truncated.fix(this draft) or a breaking change?Test plan
pytest tests: 2877 passed, 36 skipped, 0 failed (102 new tests);mastergives 2775 passed.packages/loop_interpolation/tests: 641 passed (26 new), 47 skipped, 2 xfailed.packages/loop_common/tests: 421 passed.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