simsit 1.0.0__py3-none-any.whl

simsit/__init__.py

@@ -0,0 +1,23 @@
+from . import tools
+from .cadence import SimpleCadence
+from .catalog import GaiaStarCatalog, MockStarCatalog
+from .instrument import Instrument
+from .passband import Passband
+from .tracker import InertialTracker, OrbitTracker, SiderealTracker, sidereal_tracker
+from .wcs import radialWCS, radial_wcs
+
+__all__ = [
+    "tools",
+    "SimpleCadence",
+    "GaiaStarCatalog",
+    "MockStarCatalog",
+    "Instrument",
+    "Passband",
+    "InertialTracker",
+    "OrbitTracker",
+    "sidereal_tracker",
+    "radial_wcs",
+    # Backward-compatible aliases
+    "SiderealTracker",
+    "radialWCS",
+]

simsit/_version.py

@@ -0,0 +1,4 @@
+__version__ = "1.0.0"
+
+_base_version = __version__.split("rc", 1)[0]
+__version_info__ = tuple(map(int, _base_version.split(".")))

simsit/backend.py

@@ -0,0 +1,235 @@
+"""SSATK observation boundary: GCRF states in SI and explicit GPS/Time epochs."""
+
+import astropy.units as u
+import numpy as np
+import ssatk
+from astropy.coordinates import EarthLocation
+from astropy.time import Time, TimeDelta
+
+
+EARTH_RADIUS_M = ssatk.constants.WGS72_EARTH_RADIUS
+OBSERVATION_MODES = ("geometric", "apparent")
+__all__ = [
+    "as_time", "observation_mode", "orbit_from_state", "keplerian_propagator",
+    "states", "sky_coordinates", "observer_from_location", "observer_location",
+    "catalog_to_apparent", "find_passes", "refine_pass",
+    "lambertian_reflection", "thermal_emission", "faceted_reflection", "facets_from_config",
+]
+
+
+def as_time(time):
+    """Accept Astropy Time or explicitly interpreted numeric GPS seconds."""
+    if isinstance(time, Time):
+        result = time
+    else:
+        if np.ma.getmaskarray(time).any():
+            raise ValueError("Epochs must not be masked.")
+        values = np.asarray(time)
+        if values.dtype.kind not in "iuf":
+            raise TypeError("Epochs must be Astropy Time or numeric GPS seconds.")
+        result = Time(values, format="gps")
+    if np.any(result.mask):
+        raise ValueError("Epochs must not be masked.")
+    if result.ndim > 1 or not np.isfinite(result.gps).all():
+        raise ValueError("Epochs must be finite scalars or one-dimensional arrays.")
+    return result
+
+
+def observation_mode(mode):
+    """Validate the shared satellite pointing/rendering convention."""
+    if mode not in OBSERVATION_MODES:
+        raise ValueError(f"Observation mode must be one of {OBSERVATION_MODES}.")
+    return mode
+
+
+def _gcrf(frame):
+    if frame != "GCRF":
+        raise ValueError("Orbit states must use GCRF; transform other frames explicitly.")
+
+
+def _values(value, unit):
+    if np.ma.getmaskarray(value).any():
+        raise ValueError("Physical inputs must not be masked.")
+    if isinstance(value, u.Quantity):
+        value = value.to_value(unit)
+    result = np.asarray(value, dtype=float)
+    if not np.isfinite(result).all():
+        raise ValueError("Physical inputs must be finite.")
+    return result
+
+
+def orbit_from_state(position_m, velocity_m_s, time, *, frame="GCRF"):
+    """Construct an SSATK orbit from one finite GCRF SI state."""
+    _gcrf(frame)
+    position = _values(position_m, u.m)
+    velocity = _values(velocity_m_s, u.m / u.s)
+    epoch = as_time(time)
+    if (position.shape != (3,) or velocity.shape != (3,)
+            or not np.isfinite(position).all() or not np.isfinite(velocity).all()
+            or not epoch.isscalar):
+        raise ValueError("One finite position, velocity and scalar epoch are required.")
+    return ssatk.Orbit(position, velocity, epoch)
+
+
+def keplerian_propagator():
+    """Return the two-body SSATK propagator used by synthetic orbit examples."""
+    return ssatk.KeplerianPropagator()
+
+
+def states(orbit, time, *, propagator=None, frame="GCRF"):
+    """Return positions in meters and velocities in m/s, both in GCRF."""
+    _gcrf(frame)
+    kwargs = {} if propagator is None else {"propagator": propagator}
+    return ssatk.rv(orbit, as_time(time), **kwargs)
+
+
+def sky_coordinates(orbit, time, *, observer, propagator=None, mode="geometric"):
+    """Return RA/Dec in radians and range in meters at photon arrival time.
+
+    ``geometric`` uses simultaneous object/site positions. ``apparent`` asks
+    SSATK for iterative light-time and observer-velocity aberration correction.
+    Both use the same GCRF axes; neither adds atmospheric refraction.
+    """
+    observation_mode(mode)
+    kwargs = {} if propagator is None else {"propagator": propagator}
+    return ssatk.radec(
+        orbit, as_time(time), observer=observer,
+        obsAngleCorrection=None if mode == "geometric" else "exact", **kwargs,
+    )
+
+
+def observer_from_location(location):
+    """Construct an SSATK Earth observer from a scalar WGS84 EarthLocation."""
+    if not isinstance(location, EarthLocation) or not location.isscalar:
+        raise TypeError("A scalar EarthLocation is required.")
+    _values(location.itrs.cartesian.xyz, u.m)
+    return ssatk.EarthObserver(
+        lon=location.lon.to_value(u.deg), lat=location.lat.to_value(u.deg),
+        elevation=location.height.to_value(u.m),
+    )
+
+
+def observer_location(observer):
+    """Recover a terrestrial site through the observer's public SI ITRS state."""
+    itrs = _values(observer.itrs, u.m)
+    if itrs.shape != (3,) or not np.isfinite(itrs).all():
+        raise ValueError("An Earth observer must expose one finite ITRS position in meters.")
+    return EarthLocation.from_geocentric(*itrs, unit=u.m)
+
+
+def catalog_to_apparent(ra, dec, time, **kwargs):
+    """Convert J2000 stellar coordinates through SSATK's astrometry bridge.
+
+    RA/Dec are radians, proper motions are mu_alpha*/mu_delta in mas/year,
+    and parallax is arcseconds. Without an observer this is geocentric.
+    """
+    ra = _values(ra, u.rad)
+    dec = _values(dec, u.rad)
+    for name, unit in (("pmra", u.mas / u.yr), ("pmdec", u.mas / u.yr), ("parallax", u.arcsec)):
+        if name in kwargs:
+            kwargs[name] = _values(kwargs[name], unit)
+    return ssatk.ssapy.utils.catalog_to_apparent(ra, dec, as_time(time), **kwargs)
+
+
+def find_passes(orbit, observers, time, duration, step, **kwargs):
+    """SSATK pass search; duration/step are explicit time quantities."""
+    intervals = []
+    for value in (duration, step):
+        if isinstance(value, TimeDelta):
+            seconds = value.sec
+        elif isinstance(value, u.Quantity):
+            seconds = value.to_value(u.s)
+        else:
+            raise TypeError("Pass intervals must be TimeDelta or time quantities.")
+        if np.ndim(seconds) or not np.isfinite(seconds) or seconds <= 0:
+            raise ValueError("Pass intervals must be finite positive scalar durations.")
+        intervals.append(seconds * u.s)
+    return ssatk.ssapy.compute.find_passes(
+        orbit, observers, as_time(time), *intervals, **kwargs,
+    )
+
+
+def refine_pass(orbit, observer, time, **kwargs):
+    return ssatk.ssapy.compute.refine_pass(orbit, observer, as_time(time), **kwargs)
+
+
+def _physical_position(position_gcrf_m):
+    """Validate and normalize one explicit physical GCRF position."""
+    position = _values(position_gcrf_m, u.m)
+    if position.shape != (3,):
+        raise ValueError("Physical model position must be one GCRF vector in meters.")
+    return position
+
+
+def _physical_observer(observer, time=None):
+    """Validate an observer accepted by SSATK's physical models."""
+    if isinstance(observer, EarthLocation):
+        if not observer.isscalar:
+            raise TypeError("A physical model observer must be scalar.")
+        _values(observer.itrs.cartesian.xyz, u.m)
+        return observer
+    if isinstance(observer, ssatk.EarthObserver):
+        return observer
+    if hasattr(observer, "getRV"):
+        if time is None:
+            raise ValueError("Resolving an orbital observer requires an explicit epoch.")
+        observer, _ = observer.getRV(as_time(time))
+    position = _values(observer, u.m)
+    if position.shape != (3,):
+        raise ValueError("A physical model observer must be a GCRF vector in meters.")
+    return position
+
+
+def lambertian_reflection(position_gcrf_m, time, observer, **kwargs):
+    """Call SSATK's released Lambertian reflection model at an explicit state."""
+    from ssatk.compute.lambertian_magnitude import lambertian_reflection as model
+
+    return model(
+        _physical_position(position_gcrf_m),
+        observer=_physical_observer(observer, time),
+        time=as_time(time),
+        **kwargs,
+    )
+
+
+def thermal_emission(position_gcrf_m, time, observer, **kwargs):
+    """Call SSATK's released gray-body thermal model at an explicit state."""
+    from ssatk.compute.lambertian_magnitude import thermal_emission as model
+
+    return model(
+        _physical_position(position_gcrf_m),
+        observer=_physical_observer(observer, time),
+        time=as_time(time),
+        **kwargs,
+    )
+
+
+def faceted_reflection(position_gcrf_m, time, observer, *, quaternion, facets, **kwargs):
+    """Call SSATK's released faceted reflection model at an explicit state."""
+    from ssatk.compute.faceted_magnitude import faceted_reflection as model
+
+    if np.asarray(quaternion).shape != (4,):
+        raise ValueError("Physical model quaternion must be one [w, x, y, z] vector.")
+    if not np.isfinite(np.asarray(quaternion, dtype=float)).all():
+        raise ValueError("Physical model quaternion must be finite.")
+    return model(
+        _physical_position(position_gcrf_m),
+        quaternion=np.asarray(quaternion, dtype=float),
+        facets=tuple(facets),
+        observer=_physical_observer(observer, time),
+        time=as_time(time),
+        **kwargs,
+    )
+
+
+def facets_from_config(facets):
+    """Construct explicit SSATK facets; no mesh or optical properties are inferred."""
+    return tuple(facet if isinstance(facet, ssatk.Facet) else ssatk.Facet(**facet) for facet in facets)
+
+
+def normed(vector):
+    return ssatk.normed(vector)
+
+
+def norm(vector):
+    return ssatk.norm(vector)

simsit/brightness.py

@@ -0,0 +1,279 @@
+"""Bounded physical satellite brightness through public SSATK models."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+import astropy.units as u
+import numpy as np
+
+from . import backend
+from .instrument import Instrument
+
+__all__ = ["PhysicalBrightness", "model_from_config"]
+
+
+_LAMBERTIAN_KEYS = {
+    "radius_m", "albedo", "include_sun", "include_earthshine", "include_moonshine",
+    "k_extinction", "solar_const", "t_sun", "r_sun_radius", "r_earth",
+    "albedo_earth", "olr_earth", "t_earth_lw", "r_moon", "albedo_moon",
+    "atmosphere_top_m", "f_nu_ab_zero",
+}
+_FACETED_KEYS = {
+    "include_sun", "include_earthshine", "include_moonshine", "k_extinction",
+    "solar_const", "t_sun", "r_sun_radius", "r_earth", "albedo_earth",
+    "olr_earth", "t_earth_lw", "r_moon", "albedo_moon", "atmosphere_top_m",
+    "f_nu_ab_zero",
+    "facets", "quaternion", "self_shadowing", "shadow_epsilon",
+    "check_line_of_sight",
+}
+_THERMAL_KEYS = {"temperature_K", "emissivity", "include_thermal"}
+
+
+def model_from_config(instrument, config):
+    """Validate an explicit physical or constant photometry configuration."""
+    if not isinstance(config, Mapping) or config.get("model") not in ("constant", "lambertian", "faceted"):
+        raise ValueError("photometry.model must be constant, lambertian or faceted.")
+    allowed = {"model", "params", "spectral_relative_tolerance", "max_spectral_samples"}
+    if set(config) - allowed:
+        raise ValueError("Unknown photometry configuration fields.")
+    if config["model"] == "constant":
+        if config.get("params") or set(config) - {"model", "params"}:
+            raise ValueError("Constant photometry does not use physical-model parameters.")
+        return None
+    params = dict(config.get("params", {}))
+    if config["model"] == "faceted":
+        params["facets"] = backend.facets_from_config(params.get("facets", ()))
+    return PhysicalBrightness(
+        instrument, model=config["model"], params=params,
+        spectral_relative_tolerance=config.get("spectral_relative_tolerance", 1e-4),
+        max_spectral_samples=config.get("max_spectral_samples", 257),
+    )
+
+
+def _finite_scalar(value, name, *, minimum=None, maximum=None, strict_min=False):
+    if isinstance(value, (bool, np.bool_)) or np.ma.getmaskarray(value).any():
+        raise ValueError(f"{name} must be an unmasked numeric scalar.")
+    if isinstance(value, u.Quantity):
+        value = value.to_value(u.dimensionless_unscaled)
+    if np.ndim(value) or not np.isfinite(value):
+        raise ValueError(f"{name} must be a finite scalar.")
+    value = float(value)
+    if minimum is not None and (value <= minimum if strict_min else value < minimum):
+        relation = "greater than" if strict_min else "at least"
+        raise ValueError(f"{name} must be {relation} {minimum}.")
+    if maximum is not None and value > maximum:
+        raise ValueError(f"{name} must be at most {maximum}.")
+    return value
+
+
+def _passband_domain(instrument):
+    if not isinstance(instrument, Instrument):
+        raise TypeError("instrument must be a simsit.Instrument.")
+    if instrument.passband is None:
+        raise ValueError("Physical brightness requires an explicit instrument passband.")
+    wavelengths = instrument.passband.wavelength_nm.astype(float) * 1e-9
+    if not np.isfinite(wavelengths).all() or np.any(wavelengths <= 0):
+        raise ValueError("Instrument passband wavelengths must be finite and positive.")
+    return wavelengths
+
+
+def _grid(domain, count):
+    points = list(domain)
+    target = min(9, count)
+    while len(points) < target:
+        points = sorted(points)
+        gaps = np.log(points[1:]) - np.log(points[:-1])
+        index = int(np.argmax(gaps))
+        points.append(float(np.sqrt(points[index] * points[index + 1])))
+    return np.asarray(sorted(points), dtype=float)
+
+
+def _widest_log_midpoints(wavelengths, count):
+    gaps = np.log(wavelengths[1:]) - np.log(wavelengths[:-1])
+    order = np.argsort(gaps)[::-1][:count]
+    return np.sqrt(wavelengths[order] * wavelengths[order + 1])
+
+
+class PhysicalBrightness:
+    """Estimate incident detector photons from an explicit SSATK brightness model.
+
+    SSATK supplies band-integrated irradiance using gray Lambertian reflection
+    and blackbody approximations for solar/planetary sources.  This class
+    queries narrow bands and treats their mean as ``F_lambda``; it does not
+    add spacecraft spectroscopy, orbit propagation, attitude inference, or
+    detector QE/gain.  The adaptive estimate is bounded by
+    ``max_spectral_samples`` and the stated relative tolerance.
+    """
+
+    def __init__(
+        self,
+        instrument,
+        model="lambertian",
+        params=None,
+        spectral_relative_tolerance=1e-4,
+        max_spectral_samples=257,
+    ):
+        self.instrument = instrument
+        self.model = model
+        if params is not None and not isinstance(params, Mapping):
+            raise TypeError("params must be a mapping of physical-model parameters.")
+        self.params = dict(params or {})
+        self.spectral_relative_tolerance = _finite_scalar(
+            spectral_relative_tolerance, "spectral_relative_tolerance",
+            minimum=0.0, strict_min=True, maximum=1.0,
+        )
+        if (not isinstance(max_spectral_samples, (int, np.integer))
+                or max_spectral_samples < 2):
+            raise ValueError("max_spectral_samples must be an integer of at least 2.")
+        self.max_spectral_samples = int(max_spectral_samples)
+        domain = _passband_domain(instrument)
+        if self.max_spectral_samples < len(domain):
+            raise ValueError("max_spectral_samples must include every passband knot.")
+        if model not in ("lambertian", "faceted"):
+            raise ValueError("model must be 'lambertian' or 'faceted'.")
+        allowed = _LAMBERTIAN_KEYS if model == "lambertian" else _FACETED_KEYS
+        thermal_keys = _THERMAL_KEYS if model == "lambertian" else set()
+        unsupported = sorted(set(self.params) - allowed - thermal_keys)
+        if unsupported:
+            raise ValueError(f"Unsupported {model} physical-model parameters: {unsupported}.")
+        if model == "lambertian" and not {"radius_m", "albedo"} <= self.params.keys():
+            raise ValueError("lambertian brightness requires explicit radius_m and albedo.")
+        self._validate_params()
+
+    def _validate_params(self):
+        params = self.params
+        units = {
+            "radius_m": u.m, "r_sun_radius": u.m, "r_earth": u.m, "r_moon": u.m,
+            "atmosphere_top_m": u.m, "shadow_epsilon": u.m,
+            "temperature_K": u.K, "t_sun": u.K, "t_earth_lw": u.K,
+            "solar_const": u.W / u.m**2, "olr_earth": u.W / u.m**2,
+            "f_nu_ab_zero": u.W / u.m**2 / u.Hz,
+        }
+        for key, value in tuple(params.items()):
+            if isinstance(value, u.Quantity):
+                params[key] = value.to_value(units.get(key, u.dimensionless_unscaled))
+        for key, value in params.items():
+            if key in {
+                "facets", "quaternion", "include_sun", "include_earthshine",
+                "include_moonshine", "include_thermal", "self_shadowing",
+                "check_line_of_sight",
+            }:
+                continue
+            if key in {"albedo", "albedo_earth", "albedo_moon", "emissivity"}:
+                _finite_scalar(value, key, minimum=0.0, maximum=1.0)
+            elif key == "temperature_K" or key in {"t_sun", "t_earth_lw"}:
+                _finite_scalar(value, key, minimum=0.0, strict_min=True)
+            elif key == "radius_m":
+                _finite_scalar(value, key, minimum=0.0, strict_min=True)
+            else:
+                _finite_scalar(value, key, minimum=0.0)
+        for key in {
+            "include_sun", "include_earthshine", "include_moonshine",
+            "include_thermal", "self_shadowing", "check_line_of_sight",
+        } & params.keys():
+            if not isinstance(params[key], (bool, np.bool_)):
+                raise TypeError(f"{key} must be boolean.")
+        if self.model == "faceted":
+            if "facets" not in params or "quaternion" not in params:
+                raise ValueError("faceted brightness requires facets and quaternion.")
+            if "temperature_K" in params or "emissivity" in params or params.get("include_thermal"):
+                raise ValueError("faceted thermal emission is not exposed by SSATK 1.1.4.")
+            quaternion = np.asarray(params["quaternion"], dtype=float)
+            norm = np.linalg.norm(quaternion)
+            if (quaternion.shape != (4,) or not np.isfinite(quaternion).all()
+                    or not np.isfinite(norm) or not np.isclose(norm, 1.0, rtol=1e-6, atol=1e-8)):
+                raise ValueError("quaternion must be one finite [w, x, y, z] vector.")
+            if len(params["facets"]) == 0:
+                raise ValueError("facets must not be empty.")
+            for facet in params["facets"]:
+                _finite_scalar(facet.area, "facet.area", minimum=0, strict_min=True)
+                normal = np.asarray(facet.normal_body, dtype=float)
+                if normal.shape != (3,) or not np.isfinite(normal).all() or np.linalg.norm(normal) == 0:
+                    raise ValueError("Facet normals must be finite nonzero body-frame vectors.")
+                reflectivity = facet.diffuse_reflectivity
+                if isinstance(reflectivity, Mapping):
+                    reflectivity = reflectivity.get("custom")
+                if reflectivity is None:
+                    raise ValueError("Facets require diffuse reflectivity for the custom spectral band.")
+                _finite_scalar(reflectivity, "facet.diffuse_reflectivity", minimum=0, maximum=1)
+        if self.model == "lambertian" and (
+            "temperature_K" in params or "emissivity" in params or params.get("include_thermal")
+        ) and "temperature_K" not in params:
+            raise ValueError("temperature_K is required when thermal parameters are supplied.")
+
+    def _band_irradiance(self, position, time, observer, lo, hi):
+        kwargs = dict(self.params)
+        kwargs.pop("temperature_K", None)
+        kwargs.pop("emissivity", None)
+        include_thermal = bool(
+            kwargs.pop("include_thermal", "temperature_K" in self.params)
+        )
+        if self.model == "lambertian":
+            kwargs.setdefault("radius_m", 1.0)
+            reflection = backend.lambertian_reflection(
+                position, time, observer, band=(lo, hi), **kwargs,
+            )
+        else:
+            reflection = backend.faceted_reflection(
+                position, time, observer, band=(lo, hi), **kwargs,
+            )
+        value = float(reflection["irradiance_inband_total_at_observer_W_m2"])
+        if include_thermal:
+            thermal = backend.thermal_emission(
+                position, time, observer, band=(lo, hi),
+                radius_m=kwargs.get("radius_m", 1.0),
+                albedo=kwargs.get("albedo", 0.3),
+                temperature_K=self.params["temperature_K"],
+                emissivity=self.params.get("emissivity"),
+                k_extinction=kwargs.get("k_extinction", 0.16),
+                r_earth=kwargs.get("r_earth", 6378137.0),
+                atmosphere_top_m=kwargs.get("atmosphere_top_m", 100000.0),
+            )
+            value += float(thermal["irradiance_inband_total_at_observer_W_m2"])
+        if not np.isfinite(value) or value < 0:
+            raise ValueError("SSATK physical model returned invalid irradiance.")
+        return value / (hi - lo)
+
+    def _spectrum(self, position, time, observer, wavelengths):
+        flux = np.empty(wavelengths.size)
+        for index, wavelength in enumerate(wavelengths):
+            lo = wavelength * (1.0 - 5.0e-5)
+            hi = wavelength * (1.0 + 5.0e-5)
+            flux[index] = self._band_irradiance(position, time, observer, lo, hi)
+        return wavelengths * u.m, flux * u.W / u.m**2 / u.m
+
+    def photon_rate(self, position_gcrf_m, time, observer):
+        """Return incident photons/sec after the optical passband only."""
+        position = backend._physical_position(position_gcrf_m)
+        epoch = backend.as_time(time)
+        if not epoch.isscalar:
+            raise ValueError("Physical brightness requires one scalar epoch.")
+        observer = backend._physical_observer(observer, epoch)
+        domain = _passband_domain(self.instrument)
+        wavelengths = _grid(domain, self.max_spectral_samples)
+        previous = None
+        while True:
+            wavelength, flux = self._spectrum(position, epoch, observer, wavelengths)
+            rate = self.instrument.spectral_photon_rate(wavelength, flux)
+            value = float(rate.to_value(1 / u.s))
+            if not np.isfinite(value) or value < 0:
+                raise ValueError("Instrument spectral integration returned invalid photons/sec.")
+            if previous is not None and (
+                value == previous == 0.0
+                or (
+                    abs(value - previous)
+                    <= self.spectral_relative_tolerance
+                    * max(abs(value), abs(previous), 1e-300)
+                )
+            ):
+                return rate.to(1 / u.s)
+            if wavelengths.size >= self.max_spectral_samples:
+                raise RuntimeError(
+                    "Physical brightness spectral estimate did not converge within "
+                    f"{self.max_spectral_samples} samples."
+                )
+            previous = value
+            room = self.max_spectral_samples - wavelengths.size
+            midpoints = _widest_log_midpoints(wavelengths, room)
+            wavelengths = np.unique(np.concatenate((wavelengths, midpoints)))

simsit/cadence.py

@@ -0,0 +1,95 @@
+"""
+Observation cadence models for simulation.
+"""
+
+import numpy as np
+import astropy.units as u
+from astropy.time import Time, TimeDelta
+
+__all__ = ["SimpleCadence"]
+
+
+class SimpleCadence:
+    """
+    Uniformly spaced exposure cadence during the illuminated portion of a pass.
+
+    Parameters
+    ----------
+    exptime : astropy.time.TimeDelta, astropy.units.Quantity, or float
+        Exposure duration. Bare floats are interpreted as seconds.
+    delay : astropy.time.TimeDelta, astropy.units.Quantity, or float
+        Time between successive shutter openings. Bare floats are interpreted
+        as seconds.
+    """
+
+    def __init__(self, exptime, delay):
+        self.exptime = self._as_timedelta(exptime, "exptime")
+        self.delay = self._as_timedelta(delay, "delay")
+
+        if self.exptime.sec <= 0:
+            raise ValueError("exptime must be positive.")
+        if self.delay.sec <= 0:
+            raise ValueError("delay must be positive.")
+
+    @staticmethod
+    def _as_timedelta(value, name):
+        if isinstance(value, TimeDelta):
+            delta = value
+            if np.asarray(delta.sec).ndim != 0:
+                raise ValueError(f"{name} must be a scalar duration.")
+        elif isinstance(value, u.Quantity):
+            if not value.isscalar:
+                raise ValueError(f"{name} must be a scalar duration.")
+            delta = TimeDelta(value.to_value(u.s), format="sec")
+        else:
+            value = np.asarray(value)
+            if value.ndim != 0:
+                raise ValueError(f"{name} must be a scalar duration.")
+            seconds = float(value)
+            if not np.isfinite(seconds):
+                raise ValueError(f"{name} must be finite.")
+            delta = TimeDelta(seconds, format="sec")
+
+        if not np.all(np.isfinite(delta.sec)):
+            raise ValueError(f"{name} must be finite.")
+        return delta
+
+    def get_times(self, pass_):
+        """
+        Return exposure start and end times for a pass.
+
+        Parameters
+        ----------
+        ``pass_`` : dict
+            Pass description, typically returned by
+            ``simsit.backend.refine_pass``.
+
+        Returns
+        -------
+        t_start, t_end : astropy.time.Time
+            Arrays of exposure start and end times.
+        """
+        if not pass_["illumAtStart"] and not pass_["illumAtEnd"]:
+            return Time([], format="mjd"), Time([], format="mjd")
+
+        if pass_["illumAtStart"]:
+            t_start = pass_["tStart"]
+        else:
+            t_start = pass_["tTerminator"]
+
+        if pass_["illumAtEnd"]:
+            t_end = pass_["tEnd"]
+        else:
+            t_end = pass_["tTerminator"]
+
+        available = (t_end - t_start).sec
+        if available < self.exptime.sec:
+            return Time([], format="mjd"), Time([], format="mjd")
+
+        count = int(
+            np.floor((available - self.exptime.sec) / self.delay.sec + 1e-12)
+        ) + 1
+        offsets = np.arange(count, dtype=float) * self.delay.sec
+        starts = t_start + TimeDelta(offsets, format="sec")
+        ends = starts + self.exptime
+        return starts, ends