loop-interpolation 0.0.1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (39) hide show
  1. loop_interpolation/__init__.py +152 -0
  2. loop_interpolation/_builders.py +149 -0
  3. loop_interpolation/_constant_norm.py +232 -0
  4. loop_interpolation/_diagnostics.py +102 -0
  5. loop_interpolation/_discrete_fold_interpolator.py +242 -0
  6. loop_interpolation/_discrete_interpolator.py +1405 -0
  7. loop_interpolation/_fd_fold_interpolator.py +237 -0
  8. loop_interpolation/_finite_difference_interpolator.py +1348 -0
  9. loop_interpolation/_fold_event.py +185 -0
  10. loop_interpolation/_fold_norm_alignment.py +118 -0
  11. loop_interpolation/_fold_setup.py +39 -0
  12. loop_interpolation/_geological_interpolator.py +920 -0
  13. loop_interpolation/_interpolator_builder.py +251 -0
  14. loop_interpolation/_interpolator_factory.py +167 -0
  15. loop_interpolation/_interpolatortype.py +20 -0
  16. loop_interpolation/_operator.py +44 -0
  17. loop_interpolation/_p1interpolator.py +299 -0
  18. loop_interpolation/_p2interpolator.py +317 -0
  19. loop_interpolation/_regularisation.py +110 -0
  20. loop_interpolation/_solver_pipeline.py +138 -0
  21. loop_interpolation/_solver_strategy.py +218 -0
  22. loop_interpolation/_surfe_wrapper.py +211 -0
  23. loop_interpolation/_svariogram.py +133 -0
  24. loop_interpolation/_validation.py +604 -0
  25. loop_interpolation/constraints.py +473 -0
  26. loop_interpolation/fold_function/__init__.py +39 -0
  27. loop_interpolation/fold_function/_base_fold_rotation_angle.py +219 -0
  28. loop_interpolation/fold_function/_fourier_series_fold_rotation_angle.py +131 -0
  29. loop_interpolation/fold_function/_lambda_fold_rotation_angle.py +53 -0
  30. loop_interpolation/loopsolver/__init__.py +2 -0
  31. loop_interpolation/loopsolver/admm_constant_norm.py +118 -0
  32. loop_interpolation/loopsolver/admm_method.py +25 -0
  33. loop_interpolation/loopsolver/admm_solver.py +463 -0
  34. loop_interpolation/loopsolver/version.py +1 -0
  35. loop_interpolation-0.0.1.dist-info/METADATA +34 -0
  36. loop_interpolation-0.0.1.dist-info/RECORD +39 -0
  37. loop_interpolation-0.0.1.dist-info/WHEEL +5 -0
  38. loop_interpolation-0.0.1.dist-info/licenses/LICENSE +21 -0
  39. loop_interpolation-0.0.1.dist-info/top_level.txt +1 -0
@@ -0,0 +1,237 @@
1
+ """
2
+ Finite difference interpolator with fold constraints.
3
+ """
4
+ from __future__ import annotations
5
+
6
+ from typing import Callable
7
+
8
+ import numpy as np
9
+ from loop_common.logging import get_logger as getLogger
10
+
11
+ from ._finite_difference_interpolator import FiniteDifferenceInterpolator
12
+ from ._fold_norm_alignment import resolve_fold_norm_target
13
+ from ._fold_setup import setup_with_fold_constraints
14
+ from ._interpolatortype import InterpolatorType
15
+ from ._regularisation import DirectionalRegularisation
16
+
17
+ logger = getLogger(__name__)
18
+
19
+
20
+ _DEFAULT_FOLD_REGULARISATION = object()
21
+
22
+
23
+ from ._fold_event import FoldEvent
24
+
25
+
26
+ class FDFoldInterpolator(FiniteDifferenceInterpolator):
27
+ """
28
+ Finite difference interpolator that supports anisotropic fold
29
+ regularisation.
30
+
31
+ Analogous to :class:`DiscreteFoldInterpolator` (which works on a
32
+ tetrahedral P1 mesh) but applied to a regular Cartesian grid. The fold
33
+ geometry is evaluated at every grid node and used to build direction-
34
+ dependent second-derivative regularisation constraints via
35
+ :meth:`minimise_directional_gradient_change`.
36
+
37
+ The fold constraints mirror the four families in the P1 version:
38
+
39
+ 1. **Fold orientation** – gradient orthogonal to the deformed foliation.
40
+ 2. **Fold axis** – gradient orthogonal to the fold axis.
41
+ 3. **Fold normalisation** – unit gradient magnitude in the fold-normal
42
+ direction.
43
+ 4. **Fold regularisation** – anisotropic smoothness: stronger along the
44
+ fold normal and fold axis, weaker across the fold.
45
+
46
+ Parameters
47
+ ----------
48
+ grid
49
+ A structured Cartesian grid (``StructuredGrid`` / rectilinear grid).
50
+ fold : FoldEvent, optional
51
+ Fold geometry provider with a ``get_deformed_orientation`` method.
52
+ data : dict, optional
53
+ Initial constraint data forwarded to the parent interpolator.
54
+ """
55
+
56
+ def __init__(self, grid, fold: FoldEvent | None = None, data=None):
57
+ FiniteDifferenceInterpolator.__init__(self, grid, data=data)
58
+ self.type = InterpolatorType.FINITE_DIFFERENCE
59
+ self.fold = fold
60
+
61
+ # ------------------------------------------------------------------
62
+ # Setup
63
+ # ------------------------------------------------------------------
64
+
65
+ def setup_interpolator(self, **kwargs):
66
+ """
67
+ Set up the interpolator and add fold constraints.
68
+
69
+ Accepted keyword arguments (all optional):
70
+
71
+ fold_weights : dict
72
+ Per-constraint weight overrides forwarded to
73
+ :meth:`add_fold_constraints`. Keys are the same as the
74
+ parameters of that method (e.g. ``fold_orientation``,
75
+ ``fold_regularisation``, …).
76
+ All other kwargs are forwarded to the parent
77
+ :meth:`FiniteDifferenceInterpolator.setup_interpolator`.
78
+ """
79
+ return setup_with_fold_constraints(
80
+ fold=self.fold,
81
+ kwargs=kwargs,
82
+ interpolator_name=self.__class__.__name__,
83
+ base_setup=super().setup_interpolator,
84
+ add_fold_constraints=self.add_fold_constraints,
85
+ finalize_report=self.finalize_setup_diagnostics_report,
86
+ )
87
+
88
+ # ------------------------------------------------------------------
89
+ # Fold constraints
90
+ # ------------------------------------------------------------------
91
+
92
+ def add_fold_constraints(
93
+ self,
94
+ fold_orientation: float | None = 10.0,
95
+ fold_axis_w: float | None = 10.0,
96
+ fold_regularisation=_DEFAULT_FOLD_REGULARISATION,
97
+ fold_normalisation: float | None = 1.0,
98
+ fold_norm: float | None = -1.0,
99
+ dgz_alignment: str = "warn",
100
+ mask_fn: Callable | None = None,
101
+ ):
102
+ """
103
+ Add fold geometry constraints to the finite difference system.
104
+
105
+ Fold direction vectors are evaluated at every grid *node* by calling
106
+ ``self.fold.get_deformed_orientation(self.support.nodes)``. The
107
+ returned vectors are then used to build:
108
+
109
+ * Gradient-orientation constraints (dot product = 0) for the
110
+ deformed foliation plane normal and the fold axis.
111
+ * A norm constraint forcing the gradient magnitude in the fold-normal
112
+ direction to be ``fold_norm``.
113
+ * Anisotropic regularisation using directional second derivatives,
114
+ applied with different weights for the three fold-geometry
115
+ directions.
116
+
117
+ Parameters
118
+ ----------
119
+ fold_orientation : float or None
120
+ Weight for the constraint that :math:`\\nabla f` is perpendicular
121
+ to the deformed foliation (i.e. lies in the axial plane).
122
+ Pass ``None`` to skip.
123
+ fold_axis_w : float or None
124
+ Weight for the constraint that :math:`\\nabla f` is perpendicular
125
+ to the fold axis. Pass ``None`` to skip.
126
+ fold_regularisation : list of three floats or None
127
+ Weights ``[w0, w1, w2]`` for the anisotropic regularisation
128
+ applied in the fold-normal, deformed-orientation, and fold-axis
129
+ directions respectively. A larger ``w0`` (fold-normal direction)
130
+ keeps the gradient smooth *across* the fold; smaller ``w1``/``w2``
131
+ allow it to vary more freely along the fold hinge. Defaults to
132
+ ``[0.1, 0.01, 0.01]``. Pass ``None`` to skip entirely.
133
+ fold_normalisation : float or None
134
+ Weight for the norm constraint. Pass ``None`` to skip.
135
+ fold_norm : float or None
136
+ Target gradient projection in the fold-normal direction. The
137
+ default is ``-1.0`` to align with the common convention where
138
+ ``dgz`` is opposite to foliation normals.
139
+ dgz_alignment : {"none", "warn", "correct"}
140
+ How to handle detected sign mismatch between ``dgz`` and normal
141
+ constraints (if present). ``warn`` logs only, ``correct`` flips
142
+ the effective ``fold_norm`` sign, and ``none`` skips checks.
143
+ mask_fn : callable or None
144
+ If provided, called with ``(n_nodes, 3)`` node positions; nodes
145
+ for which the function returns ``True`` are excluded from all fold
146
+ constraints.
147
+ """
148
+ if fold_regularisation is _DEFAULT_FOLD_REGULARISATION:
149
+ fold_regularisation = [0.1, 0.01, 0.01]
150
+
151
+ # Evaluate fold geometry at every grid node.
152
+ node_positions = self.support.nodes # (n_nodes, 3)
153
+ deformed_orientation, fold_axis, dgz = self.fold.get_deformed_orientation(node_positions)
154
+ # deformed_orientation : (n_nodes, 3) – vector lying in the axial plane
155
+ # fold_axis : (n_nodes, 3) – fold hinge direction
156
+ # dgz : (n_nodes, 3) – fold normal (across-fold direction)
157
+
158
+ # Build a boolean weight mask (1 = active, 0 = excluded).
159
+ weight = np.ones(self.support.n_nodes, dtype=float)
160
+ if mask_fn is not None:
161
+ weight[mask_fn(node_positions)] = 0.0
162
+
163
+ # Convenience: points array in the format expected by
164
+ # add_gradient_orthogonal_constraints (xyz | vx vy vz | … ).
165
+ active = weight > 0.0
166
+ active_pos = node_positions[active] # (n_active, 3)
167
+
168
+ # 1. Fold orientation: ∇f · deformed_orientation = 0
169
+ if fold_orientation is not None:
170
+ logger.info(f"Adding fold orientation constraint w = {fold_orientation}")
171
+ self.add_gradient_orthogonal_constraints(
172
+ active_pos,
173
+ deformed_orientation[active],
174
+ w=fold_orientation,
175
+ name="fold orientation",
176
+ )
177
+
178
+ # 2. Fold axis: ∇f · fold_axis = 0
179
+ if fold_axis_w is not None:
180
+ logger.info(f"Adding fold axis constraint w = {fold_axis_w}")
181
+ self.add_gradient_orthogonal_constraints(
182
+ active_pos,
183
+ fold_axis[active],
184
+ w=fold_axis_w,
185
+ name="fold axis",
186
+ )
187
+
188
+ # 3. Fold normalisation: ∇f · dgz = fold_norm
189
+ if fold_normalisation is not None:
190
+ target_norm = resolve_fold_norm_target(
191
+ fold=self.fold,
192
+ normal_constraints=self.get_norm_constraints(),
193
+ fold_norm=fold_norm,
194
+ dgz_alignment=dgz_alignment,
195
+ logger=logger,
196
+ default_fold_norm=-1.0,
197
+ )
198
+ logger.info(f"Adding fold normalisation constraint w = {fold_normalisation}")
199
+ self.add_gradient_orthogonal_constraints(
200
+ active_pos,
201
+ dgz[active],
202
+ w=fold_normalisation,
203
+ b=target_norm,
204
+ name="fold normalisation",
205
+ )
206
+
207
+ # 4. Anisotropic regularisation: directional second derivatives.
208
+ if fold_regularisation is not None:
209
+ logger.info(
210
+ f"Adding fold regularisation w = {fold_regularisation[0]}, "
211
+ f"{fold_regularisation[1]}, {fold_regularisation[2]}"
212
+ )
213
+
214
+ def _masked_direction(vectors):
215
+ masked = np.asarray(vectors, dtype=float).copy()
216
+ masked[~active] = 0.0
217
+ return masked
218
+
219
+ self.add_directional_regularisation(
220
+ (
221
+ DirectionalRegularisation(
222
+ weight=fold_regularisation[0],
223
+ direction=_masked_direction(dgz),
224
+ name="fold regularisation 1",
225
+ ),
226
+ DirectionalRegularisation(
227
+ weight=fold_regularisation[1],
228
+ direction=_masked_direction(deformed_orientation),
229
+ name="fold regularisation 2",
230
+ ),
231
+ DirectionalRegularisation(
232
+ weight=fold_regularisation[2],
233
+ direction=_masked_direction(fold_axis),
234
+ name="fold regularisation 3",
235
+ ),
236
+ )
237
+ )