optiland-sms 0.1.1__tar.gz

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,13 @@
1
+ optiland-sms
2
+ Copyright 2026 ray-tracing-shapely authors and contributors
3
+
4
+ This product includes software developed by the ray-tracing-shapely
5
+ authors and contributors, licensed under the Apache License 2.0.
6
+
7
+ This distribution contains no code derived from the Ray Optics
8
+ Simulation project; all 10 of its source files were written for
9
+ this project.
10
+
11
+ It does not depend on the core distribution, ray-tracing-shapely, which
12
+ does contain such code (see its own NOTICE): it reads that project's
13
+ profile.json files only.
@@ -0,0 +1,133 @@
1
+ Metadata-Version: 2.4
2
+ Name: optiland-sms
3
+ Version: 0.1.1
4
+ Summary: Miñano-Benítez SMS nonimaging profiles as an Optiland entry-point surface-geometry plugin
5
+ Author: ray-tracing-shapely authors and contributors
6
+ Author-email: Michele Benetti <michele@tiberavon.com>
7
+ License-Expression: Apache-2.0
8
+ Project-URL: Homepage, https://github.com/tiberavon/optiland-sms
9
+ Project-URL: Repository, https://github.com/tiberavon/optiland-sms
10
+ Keywords: optiland,ray-tracing,optics,sms,nonimaging
11
+ Classifier: Development Status :: 3 - Alpha
12
+ Classifier: Intended Audience :: Science/Research
13
+ Classifier: Operating System :: OS Independent
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3.11
16
+ Classifier: Programming Language :: Python :: 3.12
17
+ Classifier: Programming Language :: Python :: 3.13
18
+ Classifier: Topic :: Scientific/Engineering :: Physics
19
+ Requires-Python: >=3.11
20
+ Description-Content-Type: text/markdown
21
+ License-File: NOTICE.txt
22
+ Requires-Dist: optiland>=0.6.3
23
+ Provides-Extra: torch
24
+ Requires-Dist: torch; extra == "torch"
25
+ Provides-Extra: dev
26
+ Requires-Dist: pytest>=7.0.0; extra == "dev"
27
+ Requires-Dist: torch; extra == "dev"
28
+ Dynamic: license-file
29
+
30
+ # optiland-sms
31
+
32
+ [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.24416270.svg)](https://doi.org/10.5281/zenodo.24416270)
33
+
34
+ Miñano–Benítez SMS (Simultaneous Multiple Surface) lens surfaces in
35
+ [Optiland](https://github.com/optiland/optiland)'s sequential engine: a spline span of a
36
+ [`ray_tracing_shapely`](https://github.com/tiberavon/ray-tracing-shapely) `profile.json` becomes a
37
+ surface of revolution, traced exactly and, under Optiland's torch backend, differentiable with
38
+ respect to the spline's points.
39
+
40
+ The surface type `sms_spline` is registered through Optiland's `optiland.surfaces` entry point:
41
+ once the package is installed, Optiland finds it without an import and without any change to
42
+ Optiland.
43
+
44
+ ## Install
45
+
46
+ ```bash
47
+ pip install optiland-sms # numpy only
48
+ pip install "optiland-sms[torch]" # with torch, for gradients
49
+ ```
50
+
51
+ It needs Optiland 0.6.3 or later. It does not need `ray_tracing_shapely`: it reads that project's
52
+ profile files.
53
+
54
+ ## Use
55
+
56
+ ```python
57
+ from optiland.optic import Optic
58
+ from optiland.materials import IdealMaterial
59
+ from optiland.physical_apertures import RadialAperture
60
+ from optiland_sms import read_meridian
61
+
62
+ profile = "lens.profile.json" # a revolve profile whose faces are spline spans
63
+ front = read_meridian(profile, "N", reverse=True)
64
+ back = read_meridian(profile, "X", reverse=True)
65
+
66
+ op = Optic()
67
+ op.surfaces.add(index=0, thickness=10.0)
68
+ op.surfaces.add(index=1, surface_type="sms_spline", profile=profile, span="N", reverse=True,
69
+ thickness=front.vertex_along_axis - back.vertex_along_axis,
70
+ material=IdealMaterial(n=1.5), is_stop=True,
71
+ aperture=RadialAperture(front.rim_radius))
72
+ op.surfaces.add(index=2, surface_type="sms_spline", profile=profile, span="X", reverse=True,
73
+ thickness=5.0, aperture=RadialAperture(back.rim_radius))
74
+ op.surfaces.add(index=3)
75
+ ```
76
+
77
+ - `span` is the span's short label; `reverse` says that light travels against the profile's axis
78
+ direction.
79
+ - Take thicknesses from `vertex_along_axis`: a spline's vertex is where the curve meets the axis,
80
+ between its points, not one of them.
81
+ - Set each aperture to the surface's `rim_radius`. Beyond the rim the surface continues along the
82
+ rim's tangent, only so that the intersection solve sees a smooth surface.
83
+
84
+ For gradients, select the torch backend in float64 and make a surface's `points` a leaf:
85
+
86
+ ```python
87
+ import optiland.backend as be
88
+
89
+ be.set_backend("torch")
90
+ be.set_precision("float64")
91
+ be.grad_mode.enable()
92
+ geometry = op.surfaces.surfaces[1].geometry
93
+ geometry.points = geometry.points.detach().clone().requires_grad_(True)
94
+ # trace, compute a merit, merit.backward(); geometry.points.grad holds the gradient
95
+ ```
96
+
97
+ ## What it covers
98
+
99
+ - **Refraction-only lenses whose faces are surfaces of revolution**, one spline span per face,
100
+ from the axis to the rim.
101
+ - **Not** mirrors or total internal reflection, which do not fit a sequential trace; not Optiland's
102
+ non-sequential engine, which has no plugin hook; not faces made of several spans.
103
+
104
+ The reader refuses what it cannot represent, and says why.
105
+
106
+ ## How it is checked
107
+
108
+ On the RR lens of Chaves, *Introduction to Nonimaging Optics*, Example 9.1 (`tests/fixtures/`):
109
+ - the surface reproduces the profile's samples (sag to 1e-15, normals to 1e-13 rad) and its curve
110
+ between them;
111
+ - numpy and torch trace the same rays to 1e-11 (Optiland's solve stops at its own tolerance);
112
+ - the gradient agrees with a central finite difference to 1e-5 relative (1e-6 measured).
113
+
114
+ ```bash
115
+ pip install -e ".[dev]"
116
+ pytest
117
+ ```
118
+
119
+ ## Citing
120
+
121
+ If you use this software, please cite it, and the ray-tracing-shapely project whose profiles it
122
+ reads. `CITATION.cff` carries the metadata for both; GitHub formats it from the *Cite this
123
+ repository* link.
124
+
125
+ This project: [doi:10.5281/zenodo.24416270](https://doi.org/10.5281/zenodo.24416270). That is the
126
+ *concept* DOI, which always resolves to the latest release. Each release also has its own DOI, to
127
+ cite when a result must be pinned to the exact version it came from.
128
+
129
+ ray-tracing-shapely: [doi:10.5281/zenodo.23991020](https://doi.org/10.5281/zenodo.23991020).
130
+
131
+ ## Licence
132
+
133
+ Apache-2.0. See `NOTICE.txt`.
@@ -0,0 +1,104 @@
1
+ # optiland-sms
2
+
3
+ [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.24416270.svg)](https://doi.org/10.5281/zenodo.24416270)
4
+
5
+ Miñano–Benítez SMS (Simultaneous Multiple Surface) lens surfaces in
6
+ [Optiland](https://github.com/optiland/optiland)'s sequential engine: a spline span of a
7
+ [`ray_tracing_shapely`](https://github.com/tiberavon/ray-tracing-shapely) `profile.json` becomes a
8
+ surface of revolution, traced exactly and, under Optiland's torch backend, differentiable with
9
+ respect to the spline's points.
10
+
11
+ The surface type `sms_spline` is registered through Optiland's `optiland.surfaces` entry point:
12
+ once the package is installed, Optiland finds it without an import and without any change to
13
+ Optiland.
14
+
15
+ ## Install
16
+
17
+ ```bash
18
+ pip install optiland-sms # numpy only
19
+ pip install "optiland-sms[torch]" # with torch, for gradients
20
+ ```
21
+
22
+ It needs Optiland 0.6.3 or later. It does not need `ray_tracing_shapely`: it reads that project's
23
+ profile files.
24
+
25
+ ## Use
26
+
27
+ ```python
28
+ from optiland.optic import Optic
29
+ from optiland.materials import IdealMaterial
30
+ from optiland.physical_apertures import RadialAperture
31
+ from optiland_sms import read_meridian
32
+
33
+ profile = "lens.profile.json" # a revolve profile whose faces are spline spans
34
+ front = read_meridian(profile, "N", reverse=True)
35
+ back = read_meridian(profile, "X", reverse=True)
36
+
37
+ op = Optic()
38
+ op.surfaces.add(index=0, thickness=10.0)
39
+ op.surfaces.add(index=1, surface_type="sms_spline", profile=profile, span="N", reverse=True,
40
+ thickness=front.vertex_along_axis - back.vertex_along_axis,
41
+ material=IdealMaterial(n=1.5), is_stop=True,
42
+ aperture=RadialAperture(front.rim_radius))
43
+ op.surfaces.add(index=2, surface_type="sms_spline", profile=profile, span="X", reverse=True,
44
+ thickness=5.0, aperture=RadialAperture(back.rim_radius))
45
+ op.surfaces.add(index=3)
46
+ ```
47
+
48
+ - `span` is the span's short label; `reverse` says that light travels against the profile's axis
49
+ direction.
50
+ - Take thicknesses from `vertex_along_axis`: a spline's vertex is where the curve meets the axis,
51
+ between its points, not one of them.
52
+ - Set each aperture to the surface's `rim_radius`. Beyond the rim the surface continues along the
53
+ rim's tangent, only so that the intersection solve sees a smooth surface.
54
+
55
+ For gradients, select the torch backend in float64 and make a surface's `points` a leaf:
56
+
57
+ ```python
58
+ import optiland.backend as be
59
+
60
+ be.set_backend("torch")
61
+ be.set_precision("float64")
62
+ be.grad_mode.enable()
63
+ geometry = op.surfaces.surfaces[1].geometry
64
+ geometry.points = geometry.points.detach().clone().requires_grad_(True)
65
+ # trace, compute a merit, merit.backward(); geometry.points.grad holds the gradient
66
+ ```
67
+
68
+ ## What it covers
69
+
70
+ - **Refraction-only lenses whose faces are surfaces of revolution**, one spline span per face,
71
+ from the axis to the rim.
72
+ - **Not** mirrors or total internal reflection, which do not fit a sequential trace; not Optiland's
73
+ non-sequential engine, which has no plugin hook; not faces made of several spans.
74
+
75
+ The reader refuses what it cannot represent, and says why.
76
+
77
+ ## How it is checked
78
+
79
+ On the RR lens of Chaves, *Introduction to Nonimaging Optics*, Example 9.1 (`tests/fixtures/`):
80
+ - the surface reproduces the profile's samples (sag to 1e-15, normals to 1e-13 rad) and its curve
81
+ between them;
82
+ - numpy and torch trace the same rays to 1e-11 (Optiland's solve stops at its own tolerance);
83
+ - the gradient agrees with a central finite difference to 1e-5 relative (1e-6 measured).
84
+
85
+ ```bash
86
+ pip install -e ".[dev]"
87
+ pytest
88
+ ```
89
+
90
+ ## Citing
91
+
92
+ If you use this software, please cite it, and the ray-tracing-shapely project whose profiles it
93
+ reads. `CITATION.cff` carries the metadata for both; GitHub formats it from the *Cite this
94
+ repository* link.
95
+
96
+ This project: [doi:10.5281/zenodo.24416270](https://doi.org/10.5281/zenodo.24416270). That is the
97
+ *concept* DOI, which always resolves to the latest release. Each release also has its own DOI, to
98
+ cite when a result must be pinned to the exact version it came from.
99
+
100
+ ray-tracing-shapely: [doi:10.5281/zenodo.23991020](https://doi.org/10.5281/zenodo.23991020).
101
+
102
+ ## Licence
103
+
104
+ Apache-2.0. See `NOTICE.txt`.
@@ -0,0 +1,59 @@
1
+ """
2
+ Python-specific module: optiland_sms package
3
+ Copyright 2026 ray-tracing-shapely authors and contributors
4
+
5
+ Licensed under the Apache License, Version 2.0 (the "License");
6
+ you may not use this file except in compliance with the License.
7
+ You may obtain a copy of the License at
8
+
9
+ http://www.apache.org/licenses/LICENSE-2.0
10
+
11
+ Unless required by applicable law or agreed to in writing, software
12
+ distributed under the License is distributed on an "AS IS" BASIS,
13
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14
+ See the License for the specific language governing permissions and
15
+ limitations under the License.
16
+
17
+ Python translation Copyright 2026 ray-tracing-shapely authors and contributors
18
+
19
+ Licensed under the Apache License, Version 2.0 (the "License");
20
+ you may not use this file except in compliance with the License.
21
+ You may obtain a copy of the License at
22
+
23
+ http://www.apache.org/licenses/LICENSE-2.0
24
+
25
+ ===============================================================================
26
+ optiland_sms
27
+ ===============================================================================
28
+ Registers ray_tracing_shapely's SMS (Minano-Benitez Simultaneous Multiple
29
+ Surface) lens surfaces with Optiland's sequential engine, as the surface type
30
+ "sms_spline", through Optiland's ``optiland.surfaces`` entry point: no import
31
+ of this package and no edit to Optiland is needed.
32
+
33
+ The input is a ``profile.json``: one spline span of a revolve profile becomes
34
+ a surface of revolution whose meridian is the profile's own curve
35
+ (``geometry.SMSSplineGeometry``). Under Optiland's torch backend a trace
36
+ through it is differentiable with respect to the spline's points.
37
+
38
+ What it is for: refraction-only lenses (an RR) in the sequential engine. A
39
+ mirror or a total internal reflection does not fit a sequential trace, and
40
+ Optiland's non-sequential engine has no plugin hook: those designs reach 3D
41
+ through the ray_tracing_shapely_optiland scene bridge instead.
42
+
43
+ Modules:
44
+ - meridian: one spline span, read and checked, in a surface's (r, z) frame.
45
+ - geometry: the surface, an Optiland NewtonRaphsonGeometry.
46
+ - register: the entry point.
47
+
48
+ Named for Optiland's audience (entry-point discovery is a channel into
49
+ Optiland's own users). See dev_doc/architecture/components/optiland_sms_plugin.md.
50
+ ===============================================================================
51
+ """
52
+
53
+ from .geometry import SMSSplineGeometry
54
+ from .meridian import Meridian, read_meridian
55
+ from .register import SURFACE_TYPE, register
56
+
57
+ __version__ = "0.1.1"
58
+
59
+ __all__ = ["SMSSplineGeometry", "Meridian", "read_meridian", "register", "SURFACE_TYPE", "__version__"]
@@ -0,0 +1,250 @@
1
+ """
2
+ Python-specific module: geometry
3
+ Copyright 2026 ray-tracing-shapely authors and contributors
4
+
5
+ Licensed under the Apache License, Version 2.0 (the "License");
6
+ you may not use this file except in compliance with the License.
7
+ You may obtain a copy of the License at
8
+
9
+ http://www.apache.org/licenses/LICENSE-2.0
10
+
11
+ Unless required by applicable law or agreed to in writing, software
12
+ distributed under the License is distributed on an "AS IS" BASIS,
13
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14
+ See the License for the specific language governing permissions and
15
+ limitations under the License.
16
+
17
+ ===============================================================================
18
+ GEOMETRY -- a spline meridian as an Optiland sequential surface
19
+ ===============================================================================
20
+ ``SMSSplineGeometry`` is a surface of revolution about the local z axis whose
21
+ meridian is a profile's spline span (``meridian.read_meridian``). It is an
22
+ Optiland ``NewtonRaphsonGeometry``: it gives the sag and the normal, and
23
+ Optiland's own solve finds where a ray meets it. Under the torch backend that
24
+ solve gives first-order gradients through the converged intersection (its
25
+ one-step implicit correction).
26
+
27
+ The sag is the profile's own curve, not a second curve through its points.
28
+ At a radius r:
29
+
30
+ 1. the piece of the meridian whose radius range holds r is found;
31
+ 2. the piece's parameter u where r(u) = r is found by Newton's method from a
32
+ linear guess, detached from the gradient; the radius is strictly monotonic
33
+ on every piece (the reader checks it), so the root is unique;
34
+ 3. one more Newton step, attached, makes u's derivative the exact first-order
35
+ one (the implicit function theorem), with respect to r and to the points;
36
+ 4. the sag is z(u).
37
+
38
+ The normal comes from the meridian's tangent at u: dz/dr = z'(u) / r'(u).
39
+ Beyond the rim the sag goes on along the rim's tangent, so a Newton iterate
40
+ that strays past the rim sees a smooth surface; the aperture limits the rays.
41
+
42
+ The spline's points are held as a backend array (``self.points``): under
43
+ torch it can be a leaf that requires a gradient, and a trace is then
44
+ differentiable with respect to the points. The tangents stay fixed.
45
+ ===============================================================================
46
+ """
47
+
48
+ from __future__ import annotations
49
+
50
+ from typing import Any, Dict
51
+
52
+ import numpy as np
53
+ import optiland.backend as be
54
+ from optiland.coordinate_system import CoordinateSystem
55
+ from optiland.geometries.newton_raphson import NewtonRaphsonGeometry
56
+
57
+ from .meridian import Meridian, ProfileLike, hermite_point, load_profile, read_meridian
58
+
59
+ # Newton steps on r(u) = r before the attached one. The guess is linear on a
60
+ # piece of a cubic, and the convergence quadratic: six reach rounding.
61
+ DETACHED_STEPS = 6
62
+
63
+
64
+ def _detach(x):
65
+ return x.detach() if hasattr(x, "detach") else x
66
+
67
+
68
+ class SMSSplineGeometry(NewtonRaphsonGeometry):
69
+ """A surface of revolution whose meridian is a profile.json spline span.
70
+
71
+ Args:
72
+ coordinate_system: The surface's coordinate system; its vertex is
73
+ where the span meets the axis.
74
+ profile: The profile, as a dict or the path of its JSON file.
75
+ span: The span's short label.
76
+ reverse: Whether light travels against the profile's axis direction,
77
+ so local +z runs against it.
78
+ tol: Tolerance of Optiland's intersection solve.
79
+ max_iter: Iteration limit of that solve.
80
+
81
+ Attributes:
82
+ meridian: The span as read (``meridian.Meridian``).
83
+ points: The spline's points (n, 2) as (r, z), a backend array.
84
+ tangents: The unit tangents (n, 2), a backend array.
85
+ rim_radius: The radius of the span's end away from the axis.
86
+ """
87
+
88
+ def __init__(
89
+ self,
90
+ coordinate_system: CoordinateSystem,
91
+ profile: ProfileLike,
92
+ span: str,
93
+ reverse: bool = False,
94
+ tol: float = 1e-10,
95
+ max_iter: int = 100,
96
+ ) -> None:
97
+ self.profile = load_profile(profile)
98
+ self.span = span
99
+ self.reverse = bool(reverse)
100
+ self.meridian: Meridian = read_meridian(self.profile, span, reverse=self.reverse)
101
+ self.points = be.array(np.array(self.meridian.points, dtype=float))
102
+ self.tangents = be.array(np.array(self.meridian.tangents, dtype=float))
103
+ pieces = self.meridian.pieces
104
+ self._k = np.array([q.k for q in pieces], dtype=np.int64)
105
+ self._u_from = np.array([q.u_from for q in pieces], dtype=float)
106
+ self._u_to = np.array([q.u_to for q in pieces], dtype=float)
107
+ self.rim_radius = float(self.meridian.rim_radius)
108
+ super().__init__(coordinate_system, self._seed_radius(), 0.0, tol, max_iter)
109
+ self.is_symmetric = True
110
+
111
+ def __str__(self) -> str:
112
+ return "SMS Spline"
113
+
114
+ # --- the meridian, on the backend ------------------------------------------
115
+
116
+ def _coefficients(self):
117
+ """Each piece's cubic in r and in z: four (pieces,) arrays each."""
118
+ p, t = self.points, self.tangents
119
+ k = self._k
120
+ p0, p1 = p[k], p[k + 1]
121
+ h = be.sqrt(be.sum((p1 - p0) ** 2, axis=1))
122
+ m0, m1 = t[k] * h[:, None], t[k + 1] * h[:, None]
123
+ a = p0
124
+ b = m0
125
+ c = -3 * p0 - 2 * m0 + 3 * p1 - m1
126
+ d = 2 * p0 + m0 - 2 * p1 + m1
127
+ return (a[:, 0], b[:, 0], c[:, 0], d[:, 0]), (a[:, 1], b[:, 1], c[:, 1], d[:, 1])
128
+
129
+ @staticmethod
130
+ def _cubic(co, u):
131
+ a, b, c, d = co
132
+ return a + u * (b + u * (c + u * d))
133
+
134
+ @staticmethod
135
+ def _cubic_d(co, u):
136
+ _, b, c, d = co
137
+ return b + u * (2 * c + 3 * u * d)
138
+
139
+ def _knots(self, cr):
140
+ """The radius at each piece's two ends, detached: (pieces,) arrays."""
141
+ u_from, u_to = be.array(self._u_from), be.array(self._u_to)
142
+ cr_d = tuple(_detach(x) for x in cr)
143
+ return self._cubic(cr_d, u_from), self._cubic(cr_d, u_to)
144
+
145
+ def _solve(self, r):
146
+ """For each radius: the piece, the cubic's coefficients there, and u."""
147
+ cr, cz = self._coefficients()
148
+ r_from, r_to = self._knots(cr)
149
+ r_d = _detach(r)
150
+ n = len(self._k)
151
+ idx = be.searchsorted(r_to, r_d)
152
+ idx = be.clip(idx, 0, n - 1)
153
+ u_from, u_to = be.array(self._u_from)[idx], be.array(self._u_to)[idx]
154
+ ra, rb = r_from[idx], r_to[idx]
155
+ crs = tuple(x[idx] for x in cr)
156
+ czs = tuple(x[idx] for x in cz)
157
+ crs_d = tuple(_detach(x) for x in crs)
158
+ # The radius inside the piece (beyond the rim, the rim: the sag is
159
+ # extended along the rim's tangent below).
160
+ r_in = be.clip(r_d, 0.0, self.rim_radius)
161
+ frac = (r_in - ra) / (rb - ra)
162
+ u = u_from + frac * (u_to - u_from)
163
+ lo, hi = be.minimum(u_from, u_to), be.maximum(u_from, u_to)
164
+ for _ in range(DETACHED_STEPS):
165
+ u = u - (self._cubic(crs_d, u) - r_in) / self._cubic_d(crs_d, u)
166
+ u = be.minimum(be.maximum(u, lo), hi)
167
+ u = _detach(u)
168
+ # The attached step: u's first derivative is the implicit one.
169
+ r_att = be.where(r_d > self.rim_radius, be.zeros_like(r) + self.rim_radius, r)
170
+ u = u - (self._cubic(crs, u) - r_att) / self._cubic_d(crs, u)
171
+ return crs, czs, u
172
+
173
+ def _radius(self, x, y):
174
+ # A tiny floor keeps the derivative of the radius finite on the axis,
175
+ # where the meridian is flat and the sag's derivative is zero anyway.
176
+ return be.sqrt(x**2 + y**2 + 1e-300)
177
+
178
+ def _sag_and_slope(self, x, y):
179
+ x, y = be.array(x), be.array(y)
180
+ r = self._radius(x, y)
181
+ shape = r.shape
182
+ r = be.ravel(r)
183
+ crs, czs, u = self._solve(r)
184
+ z = self._cubic(czs, u)
185
+ slope = self._cubic_d(czs, u) / self._cubic_d(crs, u)
186
+ beyond = r > self.rim_radius
187
+ z = be.where(beyond, z + slope * (r - self.rim_radius), z)
188
+ return be.reshape(z, shape), be.reshape(slope, shape), be.reshape(r, shape)
189
+
190
+ # --- NewtonRaphsonGeometry --------------------------------------------------
191
+
192
+ def sag(self, x=0, y=0):
193
+ """The sag at (x, y): the meridian's z at the radius hypot(x, y).
194
+
195
+ Args:
196
+ x: The x-coordinate(s).
197
+ y: The y-coordinate(s).
198
+
199
+ Returns:
200
+ The sag, the shape of x and y.
201
+ """
202
+ return self._sag_and_slope(x, y)[0]
203
+
204
+ def _surface_normal(self, x, y):
205
+ """The unit normal (nx, ny, nz) at (x, y), with nz < 0 (Optiland's convention)."""
206
+ _, slope, r = self._sag_and_slope(x, y)
207
+ x, y = be.array(x), be.array(y)
208
+ dfdx, dfdy = slope * x / r, slope * y / r
209
+ mag = be.sqrt(dfdx**2 + dfdy**2 + 1)
210
+ return dfdx / mag, dfdy / mag, -1 / mag
211
+
212
+ def _seed_radius(self) -> float:
213
+ """The radius of Optiland's seed sphere: the sphere through the vertex and the rim.
214
+
215
+ Optiland starts its intersection solve where a ray meets the base
216
+ sphere. A ray the sphere does not reach has no start, and some
217
+ Optiland releases leave it non-finite. The sphere through the vertex
218
+ and the rim point reaches the whole aperture (its radius is at least
219
+ the rim's), which the vertex's own radius of curvature need not: the
220
+ RR's front face curves more at its vertex than its rim radius allows.
221
+ Infinite (a plane) for a flat meridian.
222
+ """
223
+ last = self.meridian.pieces[-1]
224
+ r, z = hermite_point(self.meridian.points, self.meridian.tangents, last.k, last.u_to)
225
+ if abs(z) < 1e-12 * max(r, 1e-300):
226
+ return float("inf")
227
+ return (r * r + z * z) / (2.0 * z)
228
+
229
+ # --- Optiland's other hooks -------------------------------------------------
230
+
231
+ def flip(self) -> None:
232
+ """Turn the surface round: light now travels the other way along the axis."""
233
+ self.__init__(self.cs, self.profile, self.span, not self.reverse, self.tol, self.max_iter)
234
+
235
+ def scale(self, scale_factor: float) -> None:
236
+ """Not supported: a profile's coordinates are its design's."""
237
+ raise NotImplementedError("an SMS spline surface is not scaled; scale the profile instead.")
238
+
239
+ def to_dict(self) -> Dict[str, Any]:
240
+ data = super().to_dict()
241
+ data.update({"profile": self.profile, "span": self.span, "reverse": self.reverse})
242
+ return data
243
+
244
+ @classmethod
245
+ def from_dict(cls, data: Dict[str, Any]) -> "SMSSplineGeometry":
246
+ missing = {"cs", "profile", "span"} - data.keys()
247
+ if missing:
248
+ raise ValueError(f"Missing required keys: {missing}")
249
+ return cls(CoordinateSystem.from_dict(data["cs"]), data["profile"], data["span"],
250
+ data.get("reverse", False), data.get("tol", 1e-10), data.get("max_iter", 100))