iactrace 0.10.1__tar.gz

iactrace-0.10.1/CHANGELOG.md

@@ -0,0 +1,116 @@
+# Changelog
+
+## v0.10.1 (2026-08-07)
+
+### Fix
+
+- **core**: fixed shadowing bug for point sources, switched to 1/d^2 scaling for point source
+- **core**: account for opl if slab is first element, salt downstream of first surface dependent on id now, clarify aspheric convention
+
+## v0.10.0 (2026-08-06)
+
+### Feat
+
+- **trajectory**: unified treatment of trajectories between components, fixed bugs in viz
+- **viz,-core**: added the ability to save trajectories for the optical trace, added methods to visualize traces for optics and detection_chain
+
+### Fix
+
+- **docs,-core**: fixed documentation and removed bugs from formatting. fixed some problems with normalization and polygonal apertures
+- **core**: fixed issue with surface relocalization
+- **core,-viz**: fixed a bug in the intersection logic, leading to the wrong root being chosen for conics. also made float32 computation more stable by propagating to local object reference. improved visualization of traced rays. refactored telescope3d by breaking up into files
+
+### Refactor
+
+- **ruff**: reformat and fixes with ruff
+- **ruff,-tests**: reformated with ruff, changed default setting of laye_vs_eager test to not be on pixel boundary
+
+## v0.9.1 (2026-08-06)
+
+### Fix
+
+- **core, docs**: fixed angle conventions, more info
+
+## v0.9.0 (2026-07-18)
+
+### BREAKING CHANGE
+
+- Closes #11
+
+### Feat
+
+- **core,tests,camera**: refactored tests to be more concentrated and better motivated, refactored to reduce code duplication and increase polymorphism, restructured camera module
+- **camera**: created a combined tracing chain, including photosensor surface, allowing for peeking
+- **core**: added an alive flag to ray bundles, to avoid confusing properties regarding value and hit mask
+- **camera**: added okumura cone prototype
+- **camera,configs,io,viz,tests**: implemented a detection chain that allows for concentrators and complicated photosensors
+- **core**: added angle dependent coatings via tabulation
+
+### Fix
+
+- **configs**: changed the ordering of the modules to reflective of the way it is done in sim_telarray
+- **core,-surfaces**: added more surface types, fixed shadowing bug for tracing
+- **configs**: improved telescope shadowing (no baffling instead of monolithic camera enclosure, to avoid incorrect self shadowing. also added a best guess okumura cone to LSTCam
+- **configs**: Added winston cones to flashcam, nectarcam and HESS2cam
+- **configs,viz**: added winston cone to HESS1U, fixed relative position of mirrors in the context of coordinate conventions, added visualization of the sensor grid
+- **core**: fix that there is no shadowing applied in the last leg to the focal plane, improved focal plane analysis
+- **camera**: fixed roundtripping issues with camera and coatings
+- **camera,core,io**: fixed bugs regarding mirroring, io and camera rays
+- **io**: fixed bsdf not bein correctly serialized
+
+### Refactor
+
+- **refactor**: refactored camera module, slimmed tests, better io for surfaces
+- **format,-doc**: ruff formatting and small doc changes regarding conventions
+
+## v0.8.0 (2026-06-11)
+
+### Feat
+
+- **opl**: make opl behave as expected, weighted with index of refraction, add distance to source or initial mirror
+
+### Fix
+
+- **viz**: fixed 3D visualization to correctly handle transparency in jupyter notebooks
+
+## v0.7.0 (2026-05-12)
+
+### Feat
+
+- **configs**: added configs for the SST telescope with CHECS camera
+- **io,viz**: enabled both apertures types for slabs and lenses for plotting and io
+- **analysis,camera,viz**: improved plotting and combined plotting path for sensors, added analysis tools such as focal plane and fixed multi-sensor groups
+
+### Fix
+
+- **benchmarks**: fixed benchmark to mvoe from MCIntegrator to direct sampling
+- **surfaces**: bug in aspheric surface formula squared unnecessarily
+
+### Refactor
+
+- **docs,configs**: adjusted docs to reflect new structure, split configs into telescope/camera, ran ruff
+- **iactrace**: major refactor of architecture, better support for lens optics
+- **utils**: removed utils path, unneccessary for new sampling method
+
+## v0.6.1 (2026-05-06)
+
+### Fix
+
+- **viz**: changed hexshow colorscaling to follow the same logic as squareshow via plt.Normalize
+- **operations**: changed mirror displacement to go along the local mirror z axis, similar to simtel_array
+- **core**: fixed bug in conic intersection
+
+### Perf
+
+- **core**: bypass NR for pure conics
+
+## v0.6.0 (2026-02-09)
+
+### BREAKING CHANGE
+
+- initial project setup
+
+### Feat
+
+- add changelog
+- initial release

iactrace-0.10.1/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Gerrit Roellinghoff
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

iactrace-0.10.1/MANIFEST.in

@@ -0,0 +1,10 @@
+prune configs
+prune licenses
+prune benchmarks
+prune docs
+prune tests
+exclude asv.conf.json
+
+include LICENSE
+include README.md
+include CHANGELOG.md

iactrace-0.10.1/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: iactrace
+Version: 0.10.1
+Summary: JAX-based optical ray tracing for Imaging Atmospheric Cherenkov Telescopes
+Author-email: Gerrit Roellinghoff <gerrit.roellinghoff@fau.de>
+Maintainer-email: Gerrit Roellinghoff <gerrit.roellinghoff@fau.de>
+License: BSD-3-Clause
+Project-URL: Homepage, https://github.com/GerritRo/iactrace
+Project-URL: Documentation, https://gerritro.github.io/iactrace/
+Project-URL: Repository, https://github.com/GerritRo/iactrace.git
+Project-URL: Issues, https://github.com/GerritRo/iactrace/issues
+Keywords: ray-tracing,optics,cherenkov,telescope,jax,differentiable,iact,astronomy,astrophysics
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: jax>=0.4.20
+Requires-Dist: jaxlib>=0.4.20
+Requires-Dist: numpy>=1.22.0
+Requires-Dist: matplotlib>=3.5.0
+Requires-Dist: trimesh>=3.15.0
+Requires-Dist: equinox>=0.11.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: jupyter>=1.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: nbclient>=0.7.0; extra == "dev"
+Requires-Dist: types-PyYAML>=6.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: optax>=0.2.6; extra == "dev"
+Requires-Dist: asv>=0.6.0; extra == "dev"
+Requires-Dist: virtualenv>=20.0; extra == "dev"
+Requires-Dist: commitizen>=3.12.0; extra == "dev"
+Provides-Extra: gpu
+Requires-Dist: jax[cuda12]; extra == "gpu"
+Provides-Extra: docs
+Requires-Dist: sphinx; extra == "docs"
+Requires-Dist: furo; extra == "docs"
+Requires-Dist: sphinx-automodapi; extra == "docs"
+Requires-Dist: sphinx-design; extra == "docs"
+Requires-Dist: myst-nb; extra == "docs"
+Dynamic: license-file
+
+# IACTrace
+
+![Python](https://img.shields.io/badge/python-3.12%2B-blue)
+[![License](https://img.shields.io/badge/license-BSD--3--Clause-green)](LICENSE)
+[![Checked with mypy](http://www.mypy-lang.org/static/mypy_badge.svg)](http://mypy-lang.org/)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![codecov](https://codecov.io/gh/GerritRo/iactrace/branch/main/graph/badge.svg)](https://codecov.io/gh/GerritRo/iactrace)
+
+**JAX-based optical ray tracing for Imaging Atmospheric Cherenkov Telescopes**
+
+IACTrace is a differentiable ray tracing library for simulating the optical properties of IACT (Imaging Atmospheric Cherenkov Telescope) systems. Built on JAX and Equinox, it supports automatic differentiation for optimization and inverse problems.
+
+## Features
+
+- Differentiable ray tracing with JAX
+- Multi-stage optical systems: segmented primaries, secondary mirrors, lenses and windows
+- Square and hexagonal sensor arrays with per-pixel light concentrators (Winston / Okumura cones)
+- Physical photodetectors: PMTs, SiPMs can be connected in-line with concentrators
+- Aspheric, Zernike and freeform surfaces, plus error models (roughness, misalignment, figure errors)
+- Obstruction modeling (cylinders, boxes, spheres, oriented boxes, triangles)
+- YAML-based telescope and camera configuration
+- Response matrix calculation
+
+## Installation
+```bash
+pip install iactrace
+```
+Or straight from the repository:
+
+```bash
+pip install git+https://github.com/GerritRo/iactrace/
+```
+
+For development:
+```bash
+git clone https://github.com/GerritRo/iactrace.git
+cd iactrace
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+Telescope and camera are configured with separate YAML files and loaded
+independently.
+
+```python
+import jax
+import jax.numpy as jnp
+from iactrace import Telescope, Camera
+
+# Random key for Monte Carlo ray sampling.
+key = jax.random.key(0)
+
+# Load the telescope (optics + camera frame) and the camera (sensor layout).
+telescope = Telescope.from_yaml("configs/HESS/CT3.yaml", n_samples=256, key=key)
+camera = Camera.from_yaml("configs/HESS/HESS1U.yaml")
+
+# Simulate an on-axis astronomical source (parallel light).
+directions = jnp.array([[0.0, 0.0, -1.0]])
+values = jnp.array([1.0])
+
+# render() traces rays through the optics and returns a lazy ray bundle;
+# camera.image() folds it into the pixel image.
+ray_bundle = telescope.render(directions, values, source_type="parallel")
+image = camera.image(ray_bundle)
+```
+
+See the [Quick Start guide](https://gerritro.github.io/iactrace/getting_started/quickstart.html)
+for point sources, off-axis geometry, and visualization.
+
+## Documentation
+
+Full documentation and examples are available at: **https://gerritro.github.io/iactrace/**
+
+### Building Documentation Locally
+
+```bash
+pip install -e ".[docs]"
+cd docs && make html
+```
+
+## License
+
+BSD-3-Clause License - see [LICENSE](LICENSE) for details.
+
+## Citation
+
+If you use IACTrace in your research, please cite this repository.

iactrace-0.10.1/README.md

@@ -0,0 +1,88 @@
+# IACTrace
+
+![Python](https://img.shields.io/badge/python-3.12%2B-blue)
+[![License](https://img.shields.io/badge/license-BSD--3--Clause-green)](LICENSE)
+[![Checked with mypy](http://www.mypy-lang.org/static/mypy_badge.svg)](http://mypy-lang.org/)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![codecov](https://codecov.io/gh/GerritRo/iactrace/branch/main/graph/badge.svg)](https://codecov.io/gh/GerritRo/iactrace)
+
+**JAX-based optical ray tracing for Imaging Atmospheric Cherenkov Telescopes**
+
+IACTrace is a differentiable ray tracing library for simulating the optical properties of IACT (Imaging Atmospheric Cherenkov Telescope) systems. Built on JAX and Equinox, it supports automatic differentiation for optimization and inverse problems.
+
+## Features
+
+- Differentiable ray tracing with JAX
+- Multi-stage optical systems: segmented primaries, secondary mirrors, lenses and windows
+- Square and hexagonal sensor arrays with per-pixel light concentrators (Winston / Okumura cones)
+- Physical photodetectors: PMTs, SiPMs can be connected in-line with concentrators
+- Aspheric, Zernike and freeform surfaces, plus error models (roughness, misalignment, figure errors)
+- Obstruction modeling (cylinders, boxes, spheres, oriented boxes, triangles)
+- YAML-based telescope and camera configuration
+- Response matrix calculation
+
+## Installation
+```bash
+pip install iactrace
+```
+Or straight from the repository:
+
+```bash
+pip install git+https://github.com/GerritRo/iactrace/
+```
+
+For development:
+```bash
+git clone https://github.com/GerritRo/iactrace.git
+cd iactrace
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+Telescope and camera are configured with separate YAML files and loaded
+independently.
+
+```python
+import jax
+import jax.numpy as jnp
+from iactrace import Telescope, Camera
+
+# Random key for Monte Carlo ray sampling.
+key = jax.random.key(0)
+
+# Load the telescope (optics + camera frame) and the camera (sensor layout).
+telescope = Telescope.from_yaml("configs/HESS/CT3.yaml", n_samples=256, key=key)
+camera = Camera.from_yaml("configs/HESS/HESS1U.yaml")
+
+# Simulate an on-axis astronomical source (parallel light).
+directions = jnp.array([[0.0, 0.0, -1.0]])
+values = jnp.array([1.0])
+
+# render() traces rays through the optics and returns a lazy ray bundle;
+# camera.image() folds it into the pixel image.
+ray_bundle = telescope.render(directions, values, source_type="parallel")
+image = camera.image(ray_bundle)
+```
+
+See the [Quick Start guide](https://gerritro.github.io/iactrace/getting_started/quickstart.html)
+for point sources, off-axis geometry, and visualization.
+
+## Documentation
+
+Full documentation and examples are available at: **https://gerritro.github.io/iactrace/**
+
+### Building Documentation Locally
+
+```bash
+pip install -e ".[docs]"
+cd docs && make html
+```
+
+## License
+
+BSD-3-Clause License - see [LICENSE](LICENSE) for details.
+
+## Citation
+
+If you use IACTrace in your research, please cite this repository.

iactrace-0.10.1/iactrace/__init__.py

@@ -0,0 +1,59 @@
+import jax
+
+from .camera import (
+    PMT,
+    Camera,
+    Concentrator,
+    ConstantQE,
+    DetectionChain,
+    HexagonalSensorGroup,
+    OkumuraCone,
+    PhotoDetector,
+    SensorGroup,
+    SquareSensorGroup,
+    WinstonCone,
+)
+from .core import LazyRayBundle, RayBundle, TraceResult, Trajectory
+from .io import save_camera, save_telescope
+from .telescope import Telescope
+from .viz import (
+    add_trajectories,
+    show_camera,
+    show_image,
+    show_sensor_chain,
+    show_telescope,
+)
+
+__version__ = "0.10.1"
+
+jax.config.update("jax_default_matmul_precision", "highest")
+
+__all__ = [
+    "Telescope",
+    "Camera",
+    "RayBundle",
+    "LazyRayBundle",
+    "Trajectory",
+    "TraceResult",
+    "Concentrator",
+    "WinstonCone",
+    "OkumuraCone",
+    "DetectionChain",
+    # Sensors
+    "SensorGroup",
+    "SquareSensorGroup",
+    "HexagonalSensorGroup",
+    # PhotoDetector
+    "PhotoDetector",
+    "ConstantQE",
+    "PMT",
+    # Visualization
+    "show_image",
+    "show_telescope",
+    "show_camera",
+    "show_sensor_chain",
+    "add_trajectories",
+    # I/O
+    "save_telescope",
+    "save_camera",
+]

iactrace-0.10.1/iactrace/analysis/__init__.py

@@ -0,0 +1,13 @@
+from .focal_surface import (
+    AsphericFocalSurface,
+    FlatFocalPlane,
+    FocalSurface,
+    FocalSurfaceHits,
+)
+
+__all__ = [
+    "FocalSurface",
+    "FlatFocalPlane",
+    "AsphericFocalSurface",
+    "FocalSurfaceHits",
+]

iactrace-0.10.1/iactrace/analysis/focal_surface.py

@@ -0,0 +1,216 @@
+from __future__ import annotations
+
+from abc import abstractmethod
+
+import equinox as eqx
+import jax
+import jax.numpy as jnp
+from jax import Array
+
+from ..core.intersections import (
+    intersect_conic,
+    intersect_plane,
+    newton_raphson_intersect,
+)
+from ..core.ray_bundle import LazyRayBundle, RayBundle
+from ..core.surfaces import sag_raw
+from ..core.transforms import euler_to_matrix
+
+
+class FocalSurfaceHits(eqx.Module):
+    """Result of intersecting a :class:`RayBundle` with a :class:`FocalSurface`.
+
+    All arrays have leading dimension ``n_rays`` and are aligned with the input
+    bundle. Dead rays appear with ``hit_mask = False`` and meaningless values
+    in the position/direction arrays: always filter with ``hit_mask`` (or
+    :attr:`alive`) before using ``xy_local`` for plotting or statistics.
+
+    Attributes:
+        xy_local: Tangent-plane coordinates at the hit, in the surface-local
+            frame (n_rays, 2).
+        z_local: Sag of the surface at the hit (n_rays,). Always 0 for a flat
+            focal plane.
+        t: Ray parameter at the hit; equals the world-frame distance travelled
+            from ``ray_bundle.origins`` to the surface (n_rays,).
+        hit_mask: Liveness at the surface (n_rays,): ``True`` for a ray that
+            was still alive on arrival **and** crossed this surface. This is
+            the input bundle's ``alive`` flag ANDed with a real intersection,
+            so a ray lost upstream (shadowed, off-aperture) is ``False`` here
+            even if its stale geometry would formally cross the surface.
+        directions_local: Ray directions in the surface-local frame (n_rays, 3).
+            Useful for chief-ray / angle-of-incidence analysis.
+        opl: Per-ray optical path length from the source wavefront to the
+            focal surface, in metres (n_rays,). Equals
+            ``ray_bundle.path_length + t * ray_bundle.n``.
+    """
+
+    xy_local: Array
+    z_local: Array
+    t: Array
+    hit_mask: Array
+    directions_local: Array
+    opl: Array
+    values: Array
+
+    @property
+    def alive(self) -> Array:
+        """Rays that reached the surface carrying light (``hit_mask & values > 0``).
+
+        The one-stop filter for photometry / spot diagrams: it excludes both
+        geometry loss (``hit_mask``) and rays attenuated to zero throughput
+        such as absorbed or totally-internally-reflected rays.
+        """
+        return self.hit_mask & (self.values > 0)
+
+
+class FocalSurface(eqx.Module):
+    """Abstract focal surface attached to the camera frame.
+
+    Subclasses implement :meth:`_intersect_local`, which receives a single ray
+    already transformed into the surface-local frame (vertex at origin, +Z
+    along the surface normal at the vertex). The base :meth:`intersect`
+    handles materialisation of lazy bundles, the world->local transform, and
+    vectorisation across rays.
+    """
+
+    position: Array  # (3,) vertex of the surface in the camera/telescope frame
+    rotation: Array  # (3,) Euler XYZ degrees; local +Z is the normal at the vertex
+
+    @abstractmethod
+    def _intersect_local(
+        self,
+        o_local: Array,
+        d_local: Array,
+    ) -> tuple[Array, Array, Array, Array]:
+        """Intersect a single local-frame ray with the surface.
+
+        Args:
+            o_local: Ray origin in the surface-local frame (3,).
+            d_local: Ray direction in the surface-local frame (3,), normalized.
+
+        Returns:
+            Tuple ``(t, xy_local, z_local, valid)`` where:
+                - ``t`` is the ray parameter (scalar),
+                - ``xy_local`` is the in-plane hit coordinate (2,),
+                - ``z_local`` is the surface sag at the hit (scalar),
+                - ``valid`` is a bool flag indicating a real intersection.
+        """
+        raise NotImplementedError
+
+    def intersect(
+        self,
+        ray_bundle: RayBundle | LazyRayBundle,
+    ) -> FocalSurfaceHits:
+        """Intersect every ray in ``ray_bundle`` with this focal surface.
+
+        Lazy bundles are materialised first; per-ray analysis cannot fold.
+        """
+        if isinstance(ray_bundle, LazyRayBundle):
+            ray_bundle = ray_bundle.materialise()
+
+        rot = euler_to_matrix(self.rotation)
+
+        o_local = (ray_bundle.origins - self.position) @ rot
+        d_local = ray_bundle.directions @ rot
+
+        t, xy_local, z_local, valid = jax.vmap(self._intersect_local)(
+            o_local,
+            d_local,
+        )
+        # Liveness at the surface: only rays that were still alive coming in
+        # and land on a real intersection.
+        hit_mask = ray_bundle.alive & valid & jnp.isfinite(t)
+
+        opl = ray_bundle.path_length + jnp.where(
+            hit_mask,
+            t * ray_bundle.n,
+            0.0,
+        )
+        return FocalSurfaceHits(
+            xy_local=xy_local,
+            z_local=z_local,
+            t=t,
+            hit_mask=hit_mask,
+            directions_local=d_local,
+            opl=opl,
+            values=ray_bundle.values,
+        )
+
+
+class FlatFocalPlane(FocalSurface):
+    """A flat focal plane.
+
+    The plane passes through ``position`` with its normal aligned with the
+    local +Z axis defined by ``rotation``. This is the same model
+    :func:`intersect_sensor` uses for sensors, just without pixel binning.
+    """
+
+    def __init__(
+        self,
+        position: Array | None = None,
+        rotation: Array | None = None,
+    ) -> None:
+        self.position = jnp.zeros(3) if position is None else jnp.asarray(position, dtype=float)
+        self.rotation = jnp.zeros(3) if rotation is None else jnp.asarray(rotation, dtype=float)
+
+    def _intersect_local(self, o_local, d_local):
+        center = jnp.zeros(3)
+        rot = jnp.eye(3)
+        xy, t = intersect_plane(o_local, d_local, center, rot)
+        valid = t < 1e10
+        z = jnp.zeros((), dtype=xy.dtype)
+        return t, xy, z, valid
+
+
+class AsphericFocalSurface(FocalSurface):
+    """A rotationally-symmetric aspheric focal surface.
+
+    Parameterisation matches :class:`AsphericSurfaceGroup`; the surface sag is
+
+        z(r) = c r^2 / (1 + sqrt(1 - (1 + k) c^2 r^2))
+               + sum_i a_i r^(2i+4)
+
+    with ``r^2 = x^2 + y^2`` in the local frame, i.e. ``aspherics[i]``
+    multiplies ``r^(2i + 4)`` -- the polynomial starts at ``r^4``, since an
+    ``r^2`` term would be degenerate with ``curvature``. The vertex sits at
+    ``position`` and the optical axis points along the local +Z (set by
+    ``rotation``). Pure conics are recovered with ``aspherics=None``;
+    ``curvature = 0`` reduces to a flat plane (Newton converges in one step
+    from the closed-form conic init).
+    """
+
+    curvature: Array
+    conic: Array
+    aspherics: Array
+
+    def __init__(
+        self,
+        position: Array | None = None,
+        rotation: Array | None = None,
+        *,
+        curvature: float | Array = 0.0,
+        conic: float | Array = 0.0,
+        aspherics: Array | None = None,
+    ) -> None:
+        self.position = jnp.zeros(3) if position is None else jnp.asarray(position, dtype=float)
+        self.rotation = jnp.zeros(3) if rotation is None else jnp.asarray(rotation, dtype=float)
+        self.curvature = jnp.asarray(curvature, dtype=float)
+        self.conic = jnp.asarray(conic, dtype=float)
+        self.aspherics = (
+            jnp.zeros((0,)) if aspherics is None else jnp.asarray(aspherics, dtype=float)
+        )
+
+    def _intersect_local(self, o_local, d_local):
+        c = self.curvature
+        k = self.conic
+        a = self.aspherics
+
+        t_init = intersect_conic(o_local, d_local, c, k)
+        t, hit_xy, valid = newton_raphson_intersect(
+            lambda x, y: sag_raw(x, y, c, k, a),
+            o_local,
+            d_local,
+            t_init,
+        )
+        z = sag_raw(hit_xy[0], hit_xy[1], c, k, a)
+        return t, hit_xy, z, valid