physicaloptix 0.0.1__py3-none-any.whl

physicaloptix/__init__.py

@@ -0,0 +1,22 @@
+"""physicaloptix -- physical optics (PSFs and diffraction) for the HWO suite.
+
+A downstream consumer of optixstuff that produces PSFs via dLux, parallel to
+coronagraphoto (image sim) and jaxedith (ETC). optixstuff stays free of dLux and
+physical optics; diffraction lives here, with dLux as the (hidden, swappable)
+backend.
+
+``DLuxCoronagraph`` implements optixstuff's ``AbstractCoronagraph``, so
+coronagraphoto / jaxedith get dLux-propagated PSFs by dependency injection: build
+one from an optixstuff primary and hand it over, no dLux in sight.
+"""
+
+from physicaloptix._version import __version__
+from physicaloptix.apertures import to_dlux_aperture
+from physicaloptix.coronagraph import DLuxCoronagraph, psf
+
+__all__ = [
+    "DLuxCoronagraph",
+    "__version__",
+    "psf",
+    "to_dlux_aperture",
+]

physicaloptix/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.0.1'
+__version_tuple__ = version_tuple = (0, 0, 1)
+
+__commit_id__ = commit_id = None

physicaloptix/apertures.py

@@ -0,0 +1,51 @@
+"""Render optixstuff primaries into dLux apertures (the optixstuff -> dLux seam).
+
+This is where the (unavoidable) translation from an optixstuff hardware
+description to a dLux object lives -- once, dispatched by primary type, so callers
+work with optixstuff objects and never construct dLux apertures by hand.
+"""
+
+import functools
+
+import dLux as dl
+import numpy as np
+from optixstuff import SegmentedPrimary, SimplePrimary
+
+
+@functools.singledispatch
+def to_dlux_aperture(primary):
+    """Render an optixstuff primary into a dLux aperture layer.
+
+    Register a new primary type with ``@to_dlux_aperture.register`` rather than
+    branching here -- O(primary types), not a growing if/elif.
+
+    Args:
+        primary: An :class:`optixstuff.AbstractPrimary` concrete instance.
+
+    Returns:
+        A dLux aperture layer (e.g. ``MultiAperture`` or ``CircularAperture``).
+    """
+    raise NotImplementedError(f"no dLux adapter for {type(primary).__name__}")
+
+
+@to_dlux_aperture.register
+def _(primary: SegmentedPrimary):
+    centres = np.asarray(primary.segment_centres_m)
+    seg_rmax = float(primary.segment_flat_to_flat_m) / np.sqrt(3.0)
+    segments = []
+    for x, y in centres:
+        transform = dl.CoordTransform(
+            translation=[float(x), float(y)], rotation=float(np.pi / 6)
+        )  # flat-top hexagons
+        segments.append(
+            dl.RegPolyAperture(
+                nsides=6, rmax=seg_rmax, transformation=transform, softening=1.0
+            )
+        )
+    return dl.MultiAperture(segments, normalise=True)
+
+
+@to_dlux_aperture.register
+def _(primary: SimplePrimary):
+    # no segment geometry -> model the circumscribing circle
+    return dl.CircularAperture(radius=float(primary.diameter_m) / 2.0, normalise=True)

physicaloptix/coronagraph.py

@@ -0,0 +1,120 @@
+"""A dLux-backed optixstuff coronagraph.
+
+``DLuxCoronagraph`` satisfies optixstuff's ``AbstractCoronagraph`` interface, so
+coronagraphoto / jaxedith consume it as any other coronagraph -- the dLux optical
+system is hidden inside. This is the sibling of yippy's sampled-YIP coronagraph:
+yippy interpolates a precomputed PSF table, this propagates live (freeze-to-table
+is a planned bridge).
+"""
+
+import dLux as dl
+import equinox as eqx
+import jax.numpy as jnp
+import numpy as np
+from optixstuff.coronagraph import AbstractCoronagraph
+
+from physicaloptix.apertures import to_dlux_aperture
+
+ARCSEC = 180.0 / np.pi * 3600.0  # arcsec per radian
+
+
+class DLuxCoronagraph(AbstractCoronagraph):
+    """An optixstuff coronagraph whose PSFs come from live dLux propagation.
+
+    Build it from an optixstuff primary with :meth:`from_primary`; it then
+    satisfies the ``AbstractCoronagraph`` interface (``on_axis_psf`` /
+    ``off_axis_psf`` plus the scalar ETC methods).
+
+    No coronagraph mask is modelled yet, so ``on_axis_psf`` is presently the
+    telescope PSF -- a suppression-free degenerate coronagraph. Adding an
+    occulter / Lyot-stop layer is the next step.
+    """
+
+    _aperture: eqx.Module
+    _diameter_m: float
+    _wf_npixels: int = eqx.field(static=True)
+    pixel_scale_lod: float
+    IWA: float
+    OWA: float
+    _raw_contrast: float
+    _core_throughput: float
+
+    def __init__(
+        self,
+        aperture: eqx.Module,
+        diameter_m: float,
+        *,
+        wf_npixels: int = 256,
+        pixel_scale_lod: float = 0.25,
+        IWA: float = 3.0,
+        OWA: float = 30.0,
+        raw_contrast: float = 1e-10,
+        core_throughput: float = 0.2,
+    ) -> None:
+        """Wrap a dLux aperture as an optixstuff coronagraph."""
+        self._aperture = aperture
+        self._diameter_m = diameter_m
+        self._wf_npixels = wf_npixels
+        self.pixel_scale_lod = pixel_scale_lod
+        self.IWA = IWA
+        self.OWA = OWA
+        self._raw_contrast = raw_contrast
+        self._core_throughput = core_throughput
+
+    @classmethod
+    def from_primary(cls, primary, **kwargs) -> "DLuxCoronagraph":
+        """Build from an optixstuff primary (the optixstuff -> dLux seam)."""
+        return cls(to_dlux_aperture(primary), float(primary.diameter_m), **kwargs)
+
+    def _optics(self, pixel_scale_rad, npixels):
+        return dl.AngularOpticalSystem(
+            wf_npixels=self._wf_npixels,
+            diameter=self._diameter_m,
+            layers=[("pupil", self._aperture)],
+            psf_npixels=int(npixels),
+            psf_pixel_scale=float(pixel_scale_rad) * ARCSEC,
+            oversample=1,
+        )
+
+    # -- image interface (consumed by coronagraphoto) ---------------------
+    def on_axis_psf(self, wavelength_nm, pixel_scale_rad, npixels):
+        """On-axis PSF via dLux (telescope PSF until a mask is added)."""
+        optics = self._optics(pixel_scale_rad, npixels)
+        return optics.propagate(jnp.array([wavelength_nm * 1e-9]))
+
+    def off_axis_psf(self, wavelength_nm, separation_lod, pixel_scale_rad, npixels):
+        """Off-axis (planet) PSF, placed along +x by convention."""
+        optics = self._optics(pixel_scale_rad, npixels)
+        wl_m = wavelength_nm * 1e-9
+        offset = jnp.array([separation_lod * wl_m / self._diameter_m, 0.0])
+        return optics.propagate(jnp.array([wl_m]), offset)
+
+    # -- scalar interface (consumed by jaxedith) -- placeholders ----------
+    def throughput(self, separation_lod, wavelength_nm, *, time_s=0.0):
+        """Core throughput (constant eta_p placeholder)."""
+        return self._core_throughput
+
+    def core_area(self, separation_lod, wavelength_nm, *, time_s=0.0):
+        """Photometric core area in (lambda/D)^2 (placeholder)."""
+        return 1.0
+
+    def core_mean_intensity(self, separation_lod, wavelength_nm, *, time_s=0.0):
+        """Mean stellar leakage (constant raw_contrast placeholder)."""
+        return self._raw_contrast
+
+    def occulter_transmission(self, separation_lod, wavelength_nm, *, time_s=0.0):
+        """Off-axis sky transmission (no occulter modelled -> 1)."""
+        return 1.0
+
+    def __repr__(self):
+        """One-line summary."""
+        return (
+            f"DLuxCoronagraph(D={self._diameter_m:.3g} m, "
+            f"wf_npix={self._wf_npixels}, no mask [telescope PSF])"
+        )
+
+
+def psf(primary, wavelength_nm, pixel_scale_rad, npixels, **kwargs):
+    """One-liner facade: optixstuff primary -> on-axis PSF, no visible dLux."""
+    coro = DLuxCoronagraph.from_primary(primary, **kwargs)
+    return coro.on_axis_psf(wavelength_nm, pixel_scale_rad, npixels)

physicaloptix-0.0.1.dist-info/METADATA

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: physicaloptix
+Version: 0.0.1
+Summary: Physical optics (PSFs and diffraction) for the HWO direct imaging simulation suite
+Project-URL: Homepage, https://github.com/CoreySpohn/physicaloptix
+Project-URL: Issues, https://github.com/CoreySpohn/physicaloptix/issues
+Author-email: Corey Spohn <corey.a.spohn@nasa.gov>
+License: MIT License
+        
+        Copyright (c) 2026 Corey Spohn
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Requires-Python: >=3.11
+Requires-Dist: dlux
+Requires-Dist: equinox>=0.12.0
+Requires-Dist: jax>=0.4.1
+Requires-Dist: jaxlib>=0.4.1
+Requires-Dist: numpy
+Requires-Dist: optixstuff
+Provides-Extra: dev
+Requires-Dist: pre-commit; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: ipython; extra == 'docs'
+Requires-Dist: matplotlib; extra == 'docs'
+Requires-Dist: myst-nb; extra == 'docs'
+Requires-Dist: sphinx; extra == 'docs'
+Requires-Dist: sphinx-autoapi; extra == 'docs'
+Requires-Dist: sphinx-autodoc-typehints; extra == 'docs'
+Requires-Dist: sphinx-book-theme; extra == 'docs'
+Requires-Dist: sphinxcontrib-mermaid; extra == 'docs'
+Provides-Extra: test
+Requires-Dist: hypothesis; extra == 'test'
+Requires-Dist: nox; extra == 'test'
+Requires-Dist: pytest; extra == 'test'
+Requires-Dist: pytest-cov; extra == 'test'
+Description-Content-Type: text/markdown
+
+# physicaloptix
+
+Physical optics — PSFs and diffraction — for the HWO direct-imaging
+simulation suite.
+
+## What physicaloptix is
+
+`physicaloptix` turns an [optixstuff](https://github.com/CoreySpohn/optixstuff)
+hardware description into point-spread functions by wave-optics propagation,
+using [dLux](https://github.com/LouisDesdoigts/dLux) as the (hidden, swappable)
+backend. It is a downstream consumer of optixstuff — parallel to
+[coronagraphoto](https://github.com/CoreySpohn/coronagraphoto) (2D image
+simulation) and [jaxEDITH](https://github.com/CoreySpohn/jaxedith)
+(exposure-time and yield calculations) — so optixstuff itself stays free of
+diffraction code.
+
+The key piece is `DLuxCoronagraph`, which implements optixstuff's
+`AbstractCoronagraph`. Build one from an optixstuff primary and hand it to any
+downstream tool: it is consumed as an `AbstractCoronagraph`, so coronagraphoto
+and jaxEDITH get dLux-propagated PSFs by dependency injection, without depending
+on physicaloptix or dLux themselves.
+
+```python
+import physicaloptix as po
+
+coro = po.DLuxCoronagraph.from_primary(primary)      # optixstuff in, dLux hidden
+psf = coro.on_axis_psf(600.0, pixel_scale_rad, npix)  # PSF out
+```
+
+## What physicaloptix is *not*
+
+- **Not a hardware model.** The telescope / coronagraph / detector description
+  lives in [optixstuff](https://github.com/CoreySpohn/optixstuff); physicaloptix
+  consumes it.
+- **Not a PSF interpolator.** That's [yippy](https://github.com/CoreySpohn/yippy)'s
+  job (a sampled YIP table). physicaloptix is its functional sibling — live
+  propagation — and both back the same `AbstractCoronagraph` slot.
+- **Not a scene model.** Stars, planets, disks, and zodi live in
+  [skyscapes](https://github.com/CoreySpohn/skyscapes).
+
+## Architecture
+
+Built on [JAX](https://github.com/google/jax),
+[Equinox](https://github.com/patrick-kidger/equinox), and
+[dLux](https://github.com/LouisDesdoigts/dLux), `physicaloptix` provides:
+
+- **The optixstuff -> dLux adapter** — `to_dlux_aperture`, a `singledispatch`
+  that renders each optixstuff primary type into a dLux aperture (segmented hex
+  -> `MultiAperture`, simple circular -> `CircularAperture`).
+- **A dLux-backed coronagraph** — `DLuxCoronagraph`, an optixstuff
+  `AbstractCoronagraph` producing `on_axis_psf` / `off_axis_psf` by propagation.
+- **A facade** — `psf(primary, ...)`, a one-liner from primary to PSF.
+
+### Ecosystem position
+
+```mermaid
+flowchart TB
+    optix["<b>optixstuff</b><br/>Telescope · Coronagraph · Detector · OpticalPath"]
+    physopt["<b>physicaloptix</b><br/>dLux-backed PSFs / diffraction<br/>DLuxCoronagraph"]
+    yippy["<b>yippy</b><br/>Sampled-YIP PSF interpolation"]
+    corono["<b>coronagraphoto</b><br/>2D image simulation"]
+    jaxedith["<b>jaxEDITH</b><br/>Exposure-time / yield"]
+
+    optix --> physopt
+    optix --> yippy
+    physopt -- AbstractCoronagraph --> corono
+    physopt -- AbstractCoronagraph --> jaxedith
+    yippy -- AbstractCoronagraph --> corono
+```
+
+## Installation
+
+```bash
+pip install physicaloptix
+```
+
+## Status
+
+This package is in early development (pre-v0.1.0). No coronagraph mask
+(focal-plane / Lyot) is modelled yet, so `on_axis_psf` is currently the
+telescope PSF.

physicaloptix-0.0.1.dist-info/RECORD

@@ -0,0 +1,8 @@
+physicaloptix/__init__.py,sha256=CFZNG7wy-mOo87TP16QT2Mt-SA_-KlgV33mo_j1dcP4,802
+physicaloptix/_version.py,sha256=8OsTLsIVB9D0HdPTmt5rVwyVUBe9xTVGkRslXicxzkM,520
+physicaloptix/apertures.py,sha256=pwbTyD1iinoEDQftkp5q-F6hN5f7JT_l8uOY2TQ3I-o,1752
+physicaloptix/coronagraph.py,sha256=hxUNB4TTWYM040TL7BVBsAOYbVhrrS3qKoXQqKUVGgE,4626
+physicaloptix-0.0.1.dist-info/METADATA,sha256=H8_ClrZvm15mFGf4XmpGr3Mg-_65plW0XYRLjuB-8ig,5930
+physicaloptix-0.0.1.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+physicaloptix-0.0.1.dist-info/licenses/LICENSE,sha256=66ed08OMdjt-G3WoW0mfxmaAt-zqSwZ2A0kvPklkwwQ,1068
+physicaloptix-0.0.1.dist-info/RECORD,,

physicaloptix-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

physicaloptix-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Corey Spohn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.