Added esis.optics.FieldStop class. (#12)

Author: roytsmart

esis/optics/__init__.py

@@ -6,10 +6,12 @@
 from ._front_apertures import FrontAperture
 from ._central_obscurations import CentralObscuration
 from ._primary_mirrors import PrimaryMirror
+from ._field_stops import FieldStop
 
 __all__ = [
     "abc",
     "FrontAperture",
     "CentralObscuration",
     "PrimaryMirror",
+    "FieldStop",
 ]

esis/optics/_field_stops/__init__.py

@@ -0,0 +1,9 @@
+from ._field_stops import (
+    AbstractFieldStop,
+    FieldStop,
+)
+
+__all__ = [
+    "AbstractFieldStop",
+    "FieldStop",
+]

esis/optics/_field_stops/_field_stops.py

@@ -0,0 +1,105 @@
+import abc
+import dataclasses
+import numpy as np
+import astropy.units as u
+import named_arrays as na
+import optika
+
+__all__ = [
+    "FieldStop",
+]
+
+
+@dataclasses.dataclass(eq=False, repr=False)
+class AbstractFieldStop(
+    optika.mixins.Printable,
+    optika.mixins.Translatable,
+):
+    """
+    An interface describing the field stop of the instrument.
+    """
+
+    @property
+    @abc.abstractmethod
+    def num_folds(self) -> int:
+        """
+        The order of the rotational symmetry of the optical system.
+        """
+
+    @property
+    def num_sides(self) -> int:
+        """
+        The number of sides of the field stop's aperture.
+        """
+        return self.num_folds
+
+    @property
+    @abc.abstractmethod
+    def radius_clear(self) -> u.Quantity | na.AbstractScalar:
+        """
+        The distance from the center to a vertex of the clear aperture.
+        """
+
+    @property
+    def width_clear(self) -> u.Quantity:
+        """
+        The width of the clear aperture from edge to edge.
+        """
+        return 2 * self.radius_clear * np.cos(360 * u.deg / self.num_sides / 2)
+
+    @property
+    @abc.abstractmethod
+    def radius_mechanical(self) -> u.Quantity | na.AbstractScalar:
+        """
+        The radius of the exterior edge of the field stop.
+        """
+
+    @property
+    def surface(self) -> optika.surfaces.Surface:
+        """
+        Represent this object as an :mod:`optika` surface.
+        """
+        return optika.surfaces.Surface(
+            name="field stop",
+            aperture=optika.apertures.RegularPolygonalAperture(
+                radius=self.radius_clear,
+                num_vertices=self.num_sides,
+            ),
+            aperture_mechanical=optika.apertures.CircularAperture(
+                radius=self.radius_mechanical,
+            ),
+            is_field_stop=True,
+            transformation=self.transformation,
+        )
+
+
+@dataclasses.dataclass(eq=False, repr=False)
+class FieldStop(
+    AbstractFieldStop,
+):
+    """
+    A model of the field stop of the instrument.
+
+    This element restricts the field of view of the spectrograph to simplify
+    the inversion process.
+    """
+
+    num_folds: int = 0
+    """
+    The order of the rotational symmetry of the optical system.
+    """
+
+    radius_clear: u.Quantity | na.AbstractScalar = 0 * u.mm
+    """
+    The distance from the center to a vertex of the clear aperture.
+    """
+
+    radius_mechanical: u.Quantity | na.AbstractScalar = 0 * u.mm
+    """
+    The radius of the exterior edge of the field stop.
+    """
+
+    translation: u.Quantity | na.AbstractCartesian3dVectorArray = 0 * u.mm
+    """
+    A transformation which can arbitrarily translate this object.
+    """

esis/optics/_field_stops/_field_stops_test.py

@@ -0,0 +1,82 @@
+import pytest
+import numpy as np
+import astropy.units as u
+import named_arrays as na
+import optika
+import optika._tests.test_mixins
+import esis
+
+
+class AbstractTestAbstractFieldStop(
+    optika._tests.test_mixins.AbstractTestPrintable,
+    optika._tests.test_mixins.AbstractTestTranslatable,
+):
+    def test_num_folds(
+        self,
+        a: esis.optics.abc.AbstractFieldStop,
+    ):
+        result = a.num_folds
+        assert isinstance(result, int)
+        assert result >= 0
+
+    def test_num_sides(
+        self,
+        a: esis.optics.abc.AbstractFieldStop,
+    ):
+        result = a.num_sides
+        assert isinstance(result, int)
+        assert result >= 0
+
+    def test_radius_clear(
+        self,
+        a: esis.optics.abc.AbstractFieldStop,
+    ):
+        result = a.radius_clear
+        assert isinstance(na.as_named_array(result), na.AbstractScalar)
+        assert na.unit_normalized(result).is_equivalent(u.mm)
+        assert np.all(result >= 0)
+
+    def test_width_clear(
+        self,
+        a: esis.optics.abc.AbstractFieldStop,
+    ):
+        result = a.width_clear
+        assert isinstance(na.as_named_array(result), na.AbstractScalar)
+        assert na.unit_normalized(result).is_equivalent(u.mm)
+
+    def test_radius_mechanical(
+        self,
+        a: esis.optics.abc.AbstractFieldStop,
+    ):
+        result = a.radius_mechanical
+        assert isinstance(na.as_named_array(result), na.AbstractScalar)
+        assert na.unit_normalized(result).is_equivalent(u.mm)
+        assert np.all(result >= 0)
+
+    def test_surface(
+        self,
+        a: esis.optics.abc.AbstractFieldStop,
+    ):
+        result = a.surface
+        assert isinstance(result, optika.surfaces.Surface)
+        assert result.is_field_stop
+        assert result.aperture is not None
+        assert result.aperture_mechanical is not None
+
+
+@pytest.mark.parametrize(
+    argnames="a",
+    argvalues=[
+        esis.optics.FieldStop(),
+        esis.optics.FieldStop(
+            num_folds=8,
+            radius_clear=5 * u.mm,
+            radius_mechanical=10 * u.mm,
+            translation=na.Cartesian3dVectorArray(z=200) * u.mm,
+        ),
+    ],
+)
+class TestFieldStop(
+    AbstractTestAbstractFieldStop,
+):
+    pass

esis/optics/abc.py

@@ -5,9 +5,11 @@
 from ._front_apertures import AbstractFrontAperture
 from ._central_obscurations import AbstractCentralObscuration
 from ._primary_mirrors import AbstractPrimaryMirror
+from ._field_stops import AbstractFieldStop
 
 __all__ = [
     "AbstractFrontAperture",
     "AbstractCentralObscuration",
     "AbstractPrimaryMirror",
+    "AbstractFieldStop",
 ]