jcmsuite-torch 1.0.0__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.
@@ -0,0 +1,25 @@
1
+ """Optional PyTorch integration for solver-driven result data.
2
+
3
+ The public names are re-exported from the implementation module so ordinary
4
+ ``jcmsuite`` imports do not load PyTorch.
5
+ """
6
+
7
+ from . import results
8
+ from .core import solve
9
+ from .types import (
10
+ ComplexDerivative,
11
+ DerivativeBinding,
12
+ RealDerivative,
13
+ SolverDerivative,
14
+ )
15
+ from .validation import validate_inputs
16
+
17
+ __all__ = [
18
+ "ComplexDerivative",
19
+ "DerivativeBinding",
20
+ "RealDerivative",
21
+ "SolverDerivative",
22
+ "results",
23
+ "solve",
24
+ "validate_inputs",
25
+ ]
@@ -0,0 +1,488 @@
1
+ """Conversion of solver derivative payloads to Torch autograd values."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from collections.abc import Callable, Mapping
6
+ from typing import cast
7
+
8
+ import numpy as np
9
+
10
+ from .coordinate_policy import (
11
+ binding_labels,
12
+ coordinate_labels,
13
+ expand_coordinates,
14
+ incomplete_labels,
15
+ missing_pair,
16
+ )
17
+ from .types import BindingMap, TorchTensor
18
+ from .validation import is_tensor
19
+
20
+
21
+ def is_derivative_key(key: object) -> bool:
22
+ """Return whether a solver mapping key contains derivative metadata."""
23
+
24
+ return key == "derivatives" or (isinstance(key, str) and key.startswith("d_"))
25
+
26
+
27
+ def numeric_tensor(
28
+ value: object, torch_module: object, *, device: object
29
+ ) -> TorchTensor | None:
30
+ if not isinstance(value, (int, float, complex, list, tuple)) and not hasattr(
31
+ value, "dtype"
32
+ ):
33
+ return None
34
+ as_tensor: Callable[..., TorchTensor] = cast(
35
+ Callable[..., TorchTensor], getattr(torch_module, "as_tensor")
36
+ )
37
+ try:
38
+ tensor_input: object = value
39
+ if isinstance(value, (list, tuple)) and any(
40
+ isinstance(item, np.ndarray) for item in value
41
+ ):
42
+ tensor_input = np.asarray(value)
43
+ return as_tensor(tensor_input, device=device)
44
+ except (TypeError, ValueError):
45
+ return None
46
+
47
+
48
+ def reduce_gradient(
49
+ gradient: TorchTensor, input_value: TorchTensor, torch_module: object
50
+ ) -> TorchTensor:
51
+ while getattr(gradient, "ndim") > getattr(input_value, "ndim"):
52
+ gradient = cast(TorchTensor, getattr(gradient, "sum")(dim=0))
53
+ for axis, size in enumerate(tuple(getattr(input_value, "shape"))):
54
+ if size == 1 and getattr(gradient, "shape")[axis] != 1:
55
+ gradient = cast(
56
+ TorchTensor, getattr(gradient, "sum")(dim=axis, keepdim=True)
57
+ )
58
+ return gradient
59
+
60
+
61
+ def _disable_materialized_grads(context: object) -> None:
62
+ """Disable zero materialization when the context supports it."""
63
+ setter: object = getattr(context, "set_materialize_grads", None)
64
+ if callable(setter):
65
+ cast(Callable[[bool], None], setter)(False)
66
+
67
+
68
+ def _connect_sensitivity(
69
+ value: TorchTensor,
70
+ hessians: tuple[TorchTensor, ...],
71
+ coordinates: tuple[TorchTensor, ...],
72
+ torch_module: object,
73
+ labels: tuple[str, ...],
74
+ ) -> TorchTensor:
75
+ """Connect one detached sensitivity to curvature and reject third order."""
76
+ function_base: type[object] = cast(
77
+ type[object], getattr(getattr(torch_module, "autograd"), "Function")
78
+ )
79
+
80
+ class ThirdOrderBoundary(function_base): # type: ignore[misc, valid-type]
81
+ generate_vmap_rule = True
82
+
83
+ @staticmethod
84
+ def forward(source: TorchTensor, anchor: TorchTensor) -> TorchTensor:
85
+ return source
86
+
87
+ @staticmethod
88
+ def setup_context(
89
+ context: object, inputs: tuple[object, ...], output: object
90
+ ) -> None:
91
+ _disable_materialized_grads(context)
92
+
93
+ @staticmethod
94
+ def backward(
95
+ context: object, output_gradient: TorchTensor | None
96
+ ) -> tuple[object, ...]:
97
+ del context, output_gradient
98
+ raise RuntimeError(
99
+ "Third-order solver derivatives are unavailable for pair "
100
+ f"{labels!r}."
101
+ )
102
+
103
+ class SensitivityValue(function_base): # type: ignore[misc, valid-type]
104
+ generate_vmap_rule = True
105
+
106
+ @staticmethod
107
+ def forward(source: TorchTensor, *arguments: TorchTensor) -> TorchTensor:
108
+ return source
109
+
110
+ @staticmethod
111
+ def setup_context(
112
+ context: object, inputs: tuple[object, ...], output: object
113
+ ) -> None:
114
+ _disable_materialized_grads(context)
115
+ setattr(context, "hessians", inputs[1 : len(hessians) + 1])
116
+ setattr(context, "coordinates", inputs[len(hessians) + 1 :])
117
+
118
+ @staticmethod
119
+ def backward(
120
+ context: object, output_gradient: TorchTensor | None
121
+ ) -> tuple[object, ...]:
122
+ selected_hessians: tuple[TorchTensor, ...] = tuple(
123
+ cast(tuple[TorchTensor, ...], getattr(context, "hessians"))
124
+ )
125
+ selected_coordinates: tuple[TorchTensor, ...] = tuple(
126
+ cast(tuple[TorchTensor, ...], getattr(context, "coordinates"))
127
+ )
128
+ if output_gradient is None:
129
+ return (None,) * (
130
+ 1 + len(selected_hessians) + len(selected_coordinates)
131
+ )
132
+ coordinate_gradients: list[TorchTensor] = []
133
+ for hessian, coordinate in zip(
134
+ selected_hessians, selected_coordinates, strict=True
135
+ ):
136
+ product: TorchTensor = cast(
137
+ TorchTensor,
138
+ getattr(torch_module, "conj")(output_gradient) * hessian,
139
+ )
140
+ real_gradient: TorchTensor = cast(
141
+ TorchTensor, getattr(torch_module, "real")(product)
142
+ )
143
+ reduced: TorchTensor = reduce_gradient(
144
+ real_gradient, coordinate, torch_module
145
+ )
146
+ coordinate_gradients.append(
147
+ cast(
148
+ TorchTensor,
149
+ getattr(ThirdOrderBoundary, "apply")(reduced, coordinate),
150
+ )
151
+ )
152
+ return (
153
+ None,
154
+ *([None] * len(selected_hessians)),
155
+ *coordinate_gradients,
156
+ )
157
+
158
+ apply_function: Callable[..., object] = cast(
159
+ Callable[..., object], getattr(SensitivityValue, "apply")
160
+ )
161
+ return apply_function(value, *hessians, *coordinates)
162
+
163
+
164
+ def attach_gradient(
165
+ value: TorchTensor,
166
+ derivatives: tuple[TorchTensor, ...],
167
+ inputs: tuple[TorchTensor, ...],
168
+ binding_indices: tuple[tuple[int, ...], ...],
169
+ torch_module: object,
170
+ *,
171
+ higher_order_error: str | None = None,
172
+ ) -> TorchTensor:
173
+ function_base: type[object] = cast(
174
+ type[object], getattr(getattr(torch_module, "autograd"), "Function")
175
+ )
176
+
177
+ class SolverValue(function_base): # type: ignore[misc, valid-type]
178
+ @staticmethod
179
+ def forward(source: TorchTensor, *arguments: TorchTensor) -> TorchTensor:
180
+ return source
181
+
182
+ @staticmethod
183
+ def setup_context(
184
+ context: object, inputs: tuple[TorchTensor, ...], output: TorchTensor
185
+ ) -> None:
186
+ _disable_materialized_grads(context)
187
+ context.derivatives = inputs[1 : len(derivatives) + 1] # type: ignore[attr-defined]
188
+ context.higher_order_error = higher_order_error # type: ignore[attr-defined]
189
+
190
+ @staticmethod
191
+ def backward(
192
+ context: object, output_gradient: TorchTensor | None
193
+ ) -> tuple[object, ...]:
194
+ if output_gradient is None:
195
+ absent_stored: tuple[TorchTensor, ...] = tuple(
196
+ context.derivatives # type: ignore[attr-defined]
197
+ )
198
+ return (None,) * (1 + len(absent_stored) + len(inputs))
199
+ unavailable: str | None = getattr(context, "higher_order_error")
200
+ if unavailable is not None and getattr(torch_module, "is_grad_enabled")():
201
+ raise RuntimeError(unavailable)
202
+ stored: tuple[TorchTensor, ...] = tuple(context.derivatives) # type: ignore[attr-defined]
203
+ input_gradients: list[object] = [None] * len(inputs)
204
+ for input_index, derivative_indices in enumerate(binding_indices):
205
+ if not derivative_indices:
206
+ continue
207
+ gradient: TorchTensor = cast(
208
+ TorchTensor,
209
+ getattr(torch_module, "real")(
210
+ getattr(torch_module, "conj")(output_gradient)
211
+ * stored[derivative_indices[0]]
212
+ ),
213
+ )
214
+ if len(derivative_indices) > 1:
215
+ imaginary: TorchTensor = cast(
216
+ TorchTensor,
217
+ getattr(torch_module, "real")(
218
+ getattr(torch_module, "conj")(output_gradient)
219
+ * stored[derivative_indices[1]]
220
+ ),
221
+ )
222
+ gradient = cast(
223
+ TorchTensor,
224
+ getattr(gradient, "__add__")(
225
+ getattr(imaginary, "__rmul__")(1j)
226
+ ),
227
+ )
228
+ reduced: TorchTensor = reduce_gradient(
229
+ gradient, inputs[input_index], torch_module
230
+ )
231
+ input_gradients[input_index] = reduced
232
+ return (None, *([None] * len(stored)), *input_gradients)
233
+
234
+ @staticmethod
235
+ def jvp(
236
+ context: object,
237
+ source_tangent: TorchTensor | None,
238
+ *argument_tangents: TorchTensor | None,
239
+ ) -> TorchTensor:
240
+ stored: tuple[TorchTensor, ...] = tuple(context.derivatives) # type: ignore[attr-defined]
241
+ input_tangents: list[TorchTensor | None] = list(
242
+ argument_tangents[len(stored) :]
243
+ )
244
+ tangent: TorchTensor = cast(
245
+ TorchTensor, getattr(torch_module, "zeros_like")(stored[0])
246
+ )
247
+ for input_index, derivative_indices in enumerate(binding_indices):
248
+ input_tangent: TorchTensor | None = input_tangents[input_index]
249
+ if input_tangent is None or not derivative_indices:
250
+ continue
251
+ first_derivative_index: int = derivative_indices[0]
252
+ if len(derivative_indices) > 1:
253
+ contribution = cast(
254
+ TorchTensor,
255
+ getattr(stored[first_derivative_index], "__mul__")(
256
+ getattr(torch_module, "real")(input_tangent)
257
+ ),
258
+ )
259
+ contribution = cast(
260
+ TorchTensor,
261
+ getattr(contribution, "__add__")(
262
+ getattr(stored[derivative_indices[1]], "__mul__")(
263
+ getattr(torch_module, "imag")(input_tangent)
264
+ )
265
+ ),
266
+ )
267
+ else:
268
+ contribution = cast(
269
+ TorchTensor,
270
+ getattr(stored[first_derivative_index], "__mul__")(
271
+ input_tangent
272
+ ),
273
+ )
274
+ tangent = cast(TorchTensor, getattr(tangent, "__add__")(contribution))
275
+ return tangent
276
+
277
+ apply_function: Callable[..., object] = cast(
278
+ Callable[..., object], getattr(SolverValue, "apply")
279
+ )
280
+ return apply_function(value, *derivatives, *inputs)
281
+
282
+
283
+ def connect_value(
284
+ converted: object,
285
+ derivative_mapping: Mapping[str, object],
286
+ bindings: BindingMap,
287
+ inputs: tuple[TorchTensor, ...],
288
+ torch_module: object,
289
+ second_derivatives: Mapping[str, Mapping[str, object]] | None = None,
290
+ third_order_boundary: bool = False,
291
+ payload_path: str = "field",
292
+ ) -> object:
293
+ if not is_tensor(converted, torch_module):
294
+ return converted
295
+ derivative_values: list[TorchTensor] = []
296
+ binding_indices: list[tuple[int, ...]] = []
297
+ labels_by_binding: list[tuple[str, ...]] = []
298
+ available_labels: set[str] = set()
299
+ for binding in bindings.values():
300
+ labels: tuple[str, ...] = binding_labels(binding)
301
+ indices: list[int] = []
302
+ for label in labels:
303
+ raw: object = derivative_mapping.get(label)
304
+ if raw is None:
305
+ continue
306
+ available_labels.add(label)
307
+ if isinstance(raw, Mapping):
308
+ raw = raw.get("field")
309
+ derivative: TorchTensor | None = numeric_tensor(
310
+ raw, torch_module, device=getattr(converted, "device", "cpu")
311
+ )
312
+ if derivative is None:
313
+ raise ValueError(
314
+ f"Solver derivative label {label!r} is unavailable for payload "
315
+ f"{payload_path!r}."
316
+ )
317
+ indices.append(len(derivative_values))
318
+ derivative_values.append(derivative)
319
+ binding_indices.append(tuple(indices))
320
+ labels_by_binding.append(labels)
321
+ absent_labels: tuple[str, ...] = incomplete_labels(
322
+ coordinate_labels(bindings), available_labels
323
+ )
324
+ if absent_labels:
325
+ if available_labels:
326
+ raise ValueError(
327
+ "First-order solver derivatives are incomplete for payload "
328
+ f"{payload_path!r}; missing labels {sorted(absent_labels)!r}."
329
+ )
330
+ return converted
331
+ higher_order_error: str | None = None
332
+ # Complex inputs contribute two independent real coordinates. Keep the
333
+ # solver labels in binding order so the Hessian is assembled in precisely
334
+ # the same packed coordinate convention as the first derivative.
335
+ expected_labels: tuple[str, ...] = coordinate_labels(bindings)
336
+ coordinates: tuple[TorchTensor, ...] = expand_coordinates(
337
+ bindings, inputs, torch_module
338
+ )
339
+ pair_map: Mapping[str, Mapping[str, object]] = second_derivatives or {}
340
+ available_pairs: bool = any(pair_map.get(label) for label in expected_labels)
341
+ unavailable_pair: tuple[str, str] | None = missing_pair(expected_labels, pair_map)
342
+ if unavailable_pair is not None:
343
+ higher_order_error = (
344
+ "Second-order solver data is incomplete or unavailable for pair "
345
+ f"{unavailable_pair[0]!r}, {unavailable_pair[1]!r}, numeric payload "
346
+ f"{payload_path!r}."
347
+ )
348
+ elif available_pairs:
349
+ for binding_index, labels in enumerate(labels_by_binding):
350
+ for direction_index, first_label in enumerate(labels):
351
+ stored_index: int = binding_indices[binding_index][direction_index]
352
+ current: TorchTensor = derivative_values[stored_index]
353
+ hessian_row: list[TorchTensor] = []
354
+ pair_labels: list[str] = []
355
+ for second_label in expected_labels:
356
+ pair: object = pair_map[first_label][second_label]
357
+ if isinstance(pair, Mapping):
358
+ pair = pair.get("field")
359
+ pair_tensor: TorchTensor | None = numeric_tensor(
360
+ pair, torch_module, device=getattr(current, "device", "cpu")
361
+ )
362
+ if pair_tensor is None:
363
+ raise ValueError(
364
+ f"Second derivative pair {first_label!r}, "
365
+ f"{second_label!r}, numeric payload {payload_path!r} "
366
+ "is not numeric."
367
+ )
368
+ hessian_row.append(pair_tensor)
369
+ pair_labels.append(f"{first_label!r}, {second_label!r}")
370
+ derivative_values[stored_index] = _connect_sensitivity(
371
+ current,
372
+ tuple(hessian_row),
373
+ coordinates,
374
+ torch_module,
375
+ tuple(pair_labels),
376
+ )
377
+ elif expected_labels:
378
+ higher_order_error = (
379
+ "Second-order solver data is unavailable for pair "
380
+ f"{expected_labels[0]!r}, {expected_labels[0]!r}, numeric payload "
381
+ f"{payload_path!r}."
382
+ )
383
+ if third_order_boundary:
384
+ higher_order_error = (
385
+ "Third-order solver derivatives are unavailable for sensitivity "
386
+ f"{labels_by_binding[0][0]!r}, numeric payload {payload_path!r}."
387
+ )
388
+ return attach_gradient(
389
+ converted,
390
+ tuple(derivative_values),
391
+ inputs,
392
+ tuple(binding_indices),
393
+ torch_module,
394
+ higher_order_error=higher_order_error,
395
+ )
396
+
397
+
398
+ def is_hidden_export_key(key: object) -> bool:
399
+ """Return whether a solver mapping key is exposed through a separate view."""
400
+
401
+ return key == "header" or is_derivative_key(key)
402
+
403
+
404
+ def convert_mapping(
405
+ mapping: object,
406
+ *,
407
+ bindings: BindingMap,
408
+ inputs: tuple[TorchTensor, ...],
409
+ torch_module: object,
410
+ derivative_mapping: Mapping[str, object] | None = None,
411
+ second_derivative_mapping: Mapping[str, Mapping[str, object]] | None = None,
412
+ _path: str = "",
413
+ third_order_boundary: bool = False,
414
+ ) -> object:
415
+ if isinstance(mapping, Mapping):
416
+ result: dict[object, object] = {}
417
+ nested: object = mapping.get("derivatives")
418
+ branches: Mapping[str, object] = (
419
+ cast(Mapping[str, object], nested) if isinstance(nested, Mapping) else {}
420
+ )
421
+ active: Mapping[str, object] = (
422
+ derivative_mapping if derivative_mapping is not None else branches
423
+ )
424
+ second_active: Mapping[str, Mapping[str, object]] = (
425
+ second_derivative_mapping or {}
426
+ )
427
+ for key, value in mapping.items():
428
+ if is_hidden_export_key(key):
429
+ continue
430
+ child_path: str = str(key) if not _path else f"{_path}.{key}"
431
+ child: dict[str, object] = {
432
+ label: branch.get(key) if isinstance(branch, Mapping) else branch
433
+ for label, branch in active.items()
434
+ }
435
+ second_child: dict[str, dict[str, object]] = {
436
+ first: {
437
+ second: branch.get(key) if isinstance(branch, Mapping) else branch
438
+ for second, branch in branches_by_second.items()
439
+ }
440
+ for first, branches_by_second in second_active.items()
441
+ }
442
+ converted: object = convert_mapping(
443
+ value,
444
+ bindings=bindings,
445
+ inputs=inputs,
446
+ torch_module=torch_module,
447
+ derivative_mapping=child or None,
448
+ second_derivative_mapping=second_child or None,
449
+ _path=child_path,
450
+ third_order_boundary=third_order_boundary,
451
+ )
452
+ result[key] = (
453
+ connect_value(
454
+ converted,
455
+ child,
456
+ bindings,
457
+ inputs,
458
+ torch_module,
459
+ second_child or None,
460
+ payload_path=child_path,
461
+ third_order_boundary=third_order_boundary,
462
+ )
463
+ if active
464
+ else converted
465
+ )
466
+ return result
467
+ tensor: TorchTensor | None = numeric_tensor(
468
+ mapping,
469
+ torch_module,
470
+ device=getattr(inputs[0], "device", "cpu") if inputs else "cpu",
471
+ )
472
+ if tensor is not None:
473
+ return tensor
474
+ if isinstance(mapping, (list, tuple)):
475
+ return type(mapping)(
476
+ convert_mapping(
477
+ item,
478
+ bindings=bindings,
479
+ inputs=inputs,
480
+ torch_module=torch_module,
481
+ derivative_mapping=derivative_mapping,
482
+ second_derivative_mapping=second_derivative_mapping,
483
+ _path=_path,
484
+ third_order_boundary=third_order_boundary,
485
+ )
486
+ for item in mapping
487
+ )
488
+ return mapping
@@ -0,0 +1,82 @@
1
+ """Shared policy for expanding solver bindings into real coordinates."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from collections.abc import Mapping
6
+ from typing import Callable, cast
7
+
8
+ from .types import BindingMap, ComplexDerivative, RealDerivative, TorchTensor
9
+
10
+
11
+ def binding_labels(binding: RealDerivative | ComplexDerivative) -> tuple[str, ...]:
12
+ """Return the ordered real solver coordinates owned by one binding."""
13
+ if isinstance(binding, RealDerivative):
14
+ return (binding.label,)
15
+ return (binding.real, binding.imaginary)
16
+
17
+
18
+ def coordinate_labels(bindings: BindingMap) -> tuple[str, ...]:
19
+ """Expand bindings in their declared order to ordered real coordinates."""
20
+ return tuple(
21
+ label for binding in bindings.values() for label in binding_labels(binding)
22
+ )
23
+
24
+
25
+ def expand_coordinates(
26
+ bindings: BindingMap, inputs: tuple[TorchTensor, ...], torch_module: object
27
+ ) -> tuple[TorchTensor, ...]:
28
+ """Expand complex inputs into real/imaginary tensors in label order."""
29
+ coordinates: list[TorchTensor] = []
30
+ for index, binding in enumerate(bindings.values()):
31
+ value: TorchTensor = inputs[index]
32
+ labels: tuple[str, ...] = binding_labels(binding)
33
+ if len(labels) == 1:
34
+ coordinates.append(value)
35
+ else:
36
+ real: Callable[[object], TorchTensor] = cast(
37
+ Callable[[object], TorchTensor], getattr(torch_module, "real")
38
+ )
39
+ imag: Callable[[object], TorchTensor] = cast(
40
+ Callable[[object], TorchTensor], getattr(torch_module, "imag")
41
+ )
42
+ coordinates.extend((real(value), imag(value)))
43
+ return tuple(coordinates)
44
+
45
+
46
+ def incomplete_labels(
47
+ required: tuple[str, ...], available: set[str]
48
+ ) -> tuple[str, ...]:
49
+ """Return unavailable required first derivatives in coordinate order."""
50
+ return tuple(label for label in required if label not in available)
51
+
52
+
53
+ def missing_pair(
54
+ labels: tuple[str, ...],
55
+ pairs: Mapping[str, Mapping[str, object]],
56
+ second_labels: tuple[str, ...] | None = None,
57
+ ) -> tuple[str, str] | None:
58
+ """Return the first required unavailable pair, preserving coordinate order."""
59
+ columns: tuple[str, ...] = labels if second_labels is None else second_labels
60
+ return next(
61
+ (
62
+ (first, second)
63
+ for first in labels
64
+ for second in columns
65
+ if second not in pairs.get(first, {})
66
+ or pairs.get(first, {}).get(second) is None
67
+ ),
68
+ None,
69
+ )
70
+
71
+
72
+ def missing_pairs(
73
+ labels: tuple[str, ...], pairs: Mapping[str, Mapping[str, object]]
74
+ ) -> tuple[tuple[str, str], ...]:
75
+ """Return every unavailable required pair in coordinate traversal order."""
76
+ return tuple(
77
+ (first, second)
78
+ for first in labels
79
+ for second in labels
80
+ if second not in pairs.get(first, {})
81
+ or pairs.get(first, {}).get(second) is None
82
+ )