iactrace.telescope

The Telescope class and helper modules for building optical systems.

Telescope Class

class iactrace.telescope.Telescope

Bases: Module

IACT telescope optical system as an Equinox Module.

The Telescope owns the full optical path including the camera frame (position and orientation of the detector plane). After ray tracing, rays are transformed into the camera frame so that the Camera class operates purely in its local coordinate system.

Optical elements (mirrors and lenses) are stored separately for clarity, but can be accessed together via the optical_groups property for unified ray tracing through mixed reflective/refractive systems.

__init__(mirror_groups, obstruction_groups=None, name='telescope', lens_groups=None, camera_position=None, camera_rotation=None)

Initialize Telescope.

Parameters:

• mirror_groups – List of Mirror groups (reflective elements)

• obstruction_groups – List of Obstruction groups

• name – Telescope name

• lens_groups – List of Lens groups (refractive elements)

• camera_position (ndarray (3,)) – Camera origin in world coordinates. Defaults to [0, 0, 0].

• camera_rotation (ndarray (3,)) – Camera orientation as Euler angles in degrees. Defaults to [0, 0, 0].

mirror_groups = <dataclasses._MISSING_TYPE object>

lens_groups = <dataclasses._MISSING_TYPE object>

obstruction_groups = <dataclasses._MISSING_TYPE object>

name = <dataclasses._MISSING_TYPE object>

camera_position = <dataclasses._MISSING_TYPE object>

camera_rotation = <dataclasses._MISSING_TYPE object>

property optical_groups

Return all optical groups (mirrors + lenses) combined.

render(sources, values, source_type='point', *, wavelength=None)

Describe a render through the optics; do not execute yet.

Returns a LazyRayBundle packaging this telescope’s optics and camera frame with the given sources. Downstream camera methods (Camera.image, Camera.response_matrix, Camera.collect) consume it directly: image and response_matrix fold per primary element so the full ray buffer is never materialised; collect materialises (per-ray output cannot be folded).

Parameters:

• sources (ndarray (N, 3)) – Source positions, or directions for a parallel source.

• values (ndarray (N,)) – Source strengths. For ‘parallel’ these are irradiances on the aperture; for ‘point’ they are radiant intensities, and the irradiance each primary sample sees is value / d^2 for that sample’s distance d to the source.

• source_type – ‘point’ or ‘parallel’.

• wavelength – A scalar (None -> DEFAULT_WAVELENGTH) or a Spectrum, which draws one wavelength per ray.

Raises:

ValueError – if wavelength is an array. A render generates its own rays, so an array has nothing to line up with.

trace(ray_origins, ray_directions, values, record_trajectory=False, *, wavelength=None)

Trace rays from arbitrary origins through the full optical system.

Parameters:

• ray_origins (ndarray (N, 3)) – Ray starting positions.

• ray_directions (ndarray (N, 3)) – Ray directions, should be normalized.

• values (ndarray (N,)) – Ray intensities.

• record_trajectory – When True, also record the per-stage ray path for diagnostics / 3D visualization (see iactrace.viz.show_telescope).

• wavelength – A scalar (None -> DEFAULT_WAVELENGTH), a per-ray (N,) array, or a Spectrum, which draws one wavelength per ray.

Returns:

• A TraceResult, as every tracer

• returns. Its rays are in the camera’s local coordinate system;

• pass them to camera.collect() or camera.image() for

• detection – rays = telescope.trace(origins, directions, values).rays rays, trajectory = telescope.trace(…, record_trajectory=True)

• trajectory is None unless record_trajectory was set, in

• which case the Trajectory holds

• the source point, each optical stage’s landing point, and finally

• the converging leg’s landing on the camera reference plane.

• rays stops on the last optic (the sensor intersection happens

• downstream in Camera); the trajectory adds that last leg for

• display.

• The trajectory is in the world frame (the frame

• iactrace.viz.show_telescope draws the optics in), not the

• camera frame rays is reframed into.

classmethod from_yaml(filename, n_samples=100, *, key)

Load a telescope from a standalone telescope YAML file.

The telescope file describes only the optical system and the camera frame. Load the camera separately via Camera.from_yaml.

Parameters:

• filename – Path to telescope YAML file.

• n_samples – Number of Monte Carlo samples per mirror element.

• key – JAX random key for sampling and roughness.

to_yaml(filename, precision=6, overwrite=True)

Save the telescope configuration to a standalone YAML file.

Parameters:

• filename – Output file path.

• precision – Number of decimal places for float values.

• overwrite – If True, overwrite existing file.

Return type:

Path to the saved file.

to_dict()

Convert telescope to a telescope-only configuration dictionary.

focus(delta_z)

Adjust camera position along the camera’s local z-axis (optical axis).

set_camera_position(position)

Set the camera position in world coordinates.

set_camera_rotation(rotation)

Set the camera rotation (Euler angles in degrees).

stage(idx)

Return the OpticalElementGroup at optical_stage == idx.

stage_indices()

Sorted list of all optical stages present.

stages_of_kind(kind)

Sorted stages whose group has the given kind (‘mirror’, ‘lens’, ‘slab’).

property n_stages

property n_mirror_elements

property n_lens_elements

set_positions(stage, positions)

set_rotations(stage, rotations)

apply_displacement(stage, sigma_z, key)

apply_misalignment(stage, sigma_h, sigma_v, key)

apply_roughness(stage, sigma)

set_curvatures(stage, curvatures)

set_conics(stage, conics)

set_aspherics(stage, aspherics)

scale_curvatures(stage, factor)

offset_curvatures(stage, offset)

apply_conic_error(stage, sigma, key)

apply_aspheric_error(stage, sigmas, key)

apply_zernike_error(stage, sigmas, key)

apply_astigmatism(stage, sigma, key)

apply_coma(stage, sigma, key)

apply_trefoil(stage, sigma, key)

resample(stage, key)

set_reflectivity(stage, reflectivity)

scale_reflectivity(stage, factor)

set_transmittance(stage, transmittance)

scale_transmittance(stage, factor)

set_refractive_index(stage, index)

set_thickness(stage, thickness)

set_focal_lengths(stage, focal_lengths, n_outside=1.0, wavelength=400.0)

apply_focal_error(stage, sigma, key, relative=False, n_outside=1.0, wavelength=400.0)

add_obstruction(obstruction)

remove_obstruction(group_idx)

clear_obstructions()

get_obstruction_count()

get_info()

Optical Element Composition

Mirrors and lenses are both represented as OpticalElementGroup instances composed from a surface, an aperture, an interaction, and an optional BSDF (see iactrace.core). The helper submodules below provide builders that assemble the right combination for common optical elements.

Mirror builders

iactrace.telescope.mirrors.mirror_group(*, positions, rotations, curvatures, conics, aspherics, offsets, aperture, reflectivity=1.0, sample_key, reflectivity_curve=None, bsdf=None, optical_stage=0, n_samples=100)

Canonical reflective OpticalElementGroup builder.

Takes pre-shaped per-element arrays plus a pre-built aperture and an optional BSDF instance, and assembles the surface + interaction + group wiring.

Parameters:

• positions (ndarray (N, 3)) – Per-element vertex positions.

• rotations (ndarray (N, 3)) – Per-element Euler angles in degrees.

• curvatures (ndarray (N,)) – Per-element curvatures 1/R.

• conics (ndarray (N,)) – Per-element Schwarzschild conic constants.

• aspherics (ndarray (N, K)) – Per-element even aspheric coefficients [A4, A6, …]. ; column i multiplies r^(2i + 4).

• offsets (ndarray (N, 2)) – Per-element surface decentering. Use jnp.zeros((N, 2)) for a centred disk.

• aperture – Pre-built aperture.

• reflectivity (ndarray (N,)) – Per-element bulk reflectivity in [0, 1].

• reflectivity_curve – Optional R(theta, lambda) ResponseCurve multiplying reflectivity per ray; None (default) is a flat response.

• sample_key – JAX PRNG key used for aperture sampling and BSDF.

• bsdf – Optional BSDF instance. None leaves the element perfectly specular (the OpticalElementGroup constructor fills in a zero-scale GaussianBSDF).

• optical_stage – Stage index within the Telescope; each group in a telescope must have a unique stage.

• n_samples – Monte Carlo samples per element per render.

Return type:

A ready-to-use OpticalElementGroup.

iactrace.telescope.mirrors.spherical(*, position, focal_length, radius, rotation=(0.0, 0.0, 0.0), inner_radius=0.0, reflectivity=1.0, reflectivity_curve=None, bsdf_scale=0.0, optical_stage=0, n_samples=100, key)

Build a spherical mirror as a single-element group.

Uses c = 1 / (2 * focal_length) with conic = 0. Set inner_radius > 0 for an annular mirror.

Parameters:

• position (ndarray (3,)) – Mirror vertex in world coordinates.

• focal_length – Paraxial focal length in metres (positive = concave).

• radius – Outer disk radius in metres.

• rotation – Euler angles in degrees. Defaults to no rotation.

• inner_radius – Inner hole radius in metres. Zero for a solid disk.

• reflectivity – Bulk reflectivity in [0, 1].

• reflectivity_curve – Optional R(theta, lambda) ResponseCurve multiplying it.

• bsdf_scale (ndarray (0 disables)) – Gaussian roughness sigma in arcseconds.

• optical_stage – Stage index within the Telescope.

• n_samples – Monte Carlo samples per render call.

• key – JAX PRNG key.

iactrace.telescope.mirrors.parabolic(*, position, focal_length, radius, rotation=(0.0, 0.0, 0.0), inner_radius=0.0, reflectivity=1.0, reflectivity_curve=None, bsdf_scale=0.0, optical_stage=0, n_samples=100, key)

Build a parabolic mirror as a single-element group.

Uses c = 1 / (2 * focal_length) and conic = -1, matching the reference configs/BASIC/Cassegrain_telescope.yaml primary (focal_length=0.4 -> curvature=1.25).

Takes the same parameters as spherical.

iactrace.telescope.mirrors.aspheric(*, position, curvature, radius, rotation=(0.0, 0.0, 0.0), conic=0.0, aspheric_coeffs=None, inner_radius=0.0, reflectivity=1.0, reflectivity_curve=None, bsdf_scale=0.0, optical_stage=0, n_samples=100, key)

Build a general aspheric mirror as a single-element group.

Fully explicit version of spherical / parabolic.

Parameters:

• position (ndarray (3,)) – Mirror vertex in world coordinates.

• curvature – Paraxial curvature 1/R in m^-1.

• radius – Outer disk radius in metres.

• rotation – Euler angles in degrees. Defaults to no rotation.

• conic – Schwarzschild conic constant. 0 spherical, -1 parabolic, -1 < k < 0 prolate ellipsoid, k < -1 hyperboloid.

• aspheric_coeffs – Even aspheric coefficients [A4, A6, …], i.e. aspheric_coeffs[i] multiplies r^(2i + 4). The polynomial starts at r^4.

• inner_radius – see spherical.

• reflectivity – see spherical.

• reflectivity_curve – see spherical.

• bsdf_scale – see spherical.

• optical_stage – see spherical.

• n_samples – see spherical.

• key – see spherical.

iactrace.telescope.mirrors.disk_array(*, positions, rotations, curvatures, radii, conics=None, aspheric_coeffs=None, inner_radii=None, reflectivities=None, reflectivity_curve=None, bsdf_scales=None, offsets=None, optical_stage=0, n_samples=100, key)

Build a batched N-element disk-aperture mirror group.

Use this for segmented primary mirrors.

Parameters:

• positions (ndarray (N, 3)) – Per-element vertex positions.

• rotations (ndarray (N, 3)) – Per-element Euler angles in degrees.

• curvatures (ndarray (N,)) – Per-element curvatures 1/R.

• radii (ndarray (N,)) – Outer disk radii.

• conics (ndarray (N,)) – Per-element conic constants. Defaults to zeros (spherical).

• aspheric_coeffs (ndarray (N, K)) – Per-element aspheric coefficients. None disables aspherics.

• inner_radii (ndarray (N,)) – Per-element central hole radii. Defaults to zeros.

• reflectivities (ndarray (N,)) – Per-element bulk reflectivities. Defaults to ones.

• reflectivity_curve – Optional R(theta, lambda) ResponseCurve shared by every element, multiplying reflectivities per ray.

• bsdf_scales (ndarray (N,)) – Per-element Gaussian BSDF roughness in arcseconds. Zero (the default) disables the BSDF.

• offsets (ndarray (N, 2)) – Per-element surface decentering. Defaults to zeros.

• optical_stage – Stage index shared by all elements in this group.

• n_samples – Monte Carlo samples per element per render.

• key – JAX PRNG key for aperture sampling and BSDF.

Lens builders

iactrace.telescope.lenses.refractive_group(*, positions, rotations, curvatures, conics, aspherics, offsets, aperture, index, transmittance=1.0, transmittance_curve=None, sample_key, optical_stage=0, n_samples=100)

Canonical builder for refractive OpticalElementGroup instances.

Assembles an AsphericSurfaceGroup + RefractInteraction + group wiring from pre-shaped arrays. Use this for curved single-surface refracting lenses with any aperture type.

Parameters:

• positions (ndarray (N, 3)) – Per-element vertex positions.

• rotations (ndarray (N, 3)) – Per-element Euler angles in degrees.

• curvatures (ndarray (N,)) – Per-element curvatures 1/R.

• conics (ndarray (N,)) – Per-element conic constants.

• aspherics (ndarray (N, K)) – Per-element even aspheric coefficients [A4, A6, …]. ; column i multiplies r^(2i + 4).

• offsets (ndarray (N, 2)) – Per-element surface decentering.

• aperture – Pre-built aperture sized to N.

• index – Refractive index of the glass – a number (or per-element (N,) array) for a non-dispersive lens, or a RefractiveIndex model (tabulated, Sellmeier) for a dispersive one. The ambient index on the incident side is not stored: the render loop reads it dynamically from each ray’s current medium (see RefractInteraction).

• transmittance (ndarray (N,)) – Per-element bulk transmittance in [0, 1].

• transmittance_curve – Optional T(theta, lambda) ResponseCurve multiplying transmittance per ray; None (default) uses bare-interface Fresnel.

• sample_key – JAX PRNG key for aperture sampling.

• optical_stage – Stage index within the Telescope.

• n_samples – Monte Carlo samples per element per render.

iactrace.telescope.lenses.slab_group(*, positions, rotations, aperture, index, thickness, transmittance=1.0, transmittance_curve=None, sample_key, optical_stage=0, n_samples=100)

Canonical builder for parallel-sided slab (window) groups.

Parameters:

• positions (ndarray (N, 3)) – Per-element front-surface positions.

• rotations (ndarray (N, 3)) – Per-element Euler angles in degrees.

• aperture – Pre-built aperture sized to N.

• index – Refractive index of the window – a number (or per-element (N,) array) for a constant window, or a RefractiveIndex model for a dispersive one. The ambient index is not stored: the render loop reads it dynamically from each ray’s current medium (see SlabInteraction).

• thickness (ndarray (N,)) – Per-element slab thickness in metres.

• transmittance (ndarray (N,)) – Per-element bulk transmittance in [0, 1].

• transmittance_curve – Optional T(theta, lambda) ResponseCurve for the whole slab, multiplying transmittance per ray; None (default) uses the bare-window Fresnel product.

• sample_key – JAX PRNG key for aperture sampling.

• optical_stage – Stage index within the Telescope.

• n_samples – Monte Carlo samples per element per render.

iactrace.telescope.lenses.aspheric_lens(*, position, curvature, radius, rotation=(0.0, 0.0, 0.0), conic=0.0, aspheric_coeffs=None, index=1.5, transmittance=1.0, transmittance_curve=None, optical_stage=0, n_samples=100, key)

Build a general aspheric-disk refracting lens as a single-element group.

The single-element sugar over refractive_group: you supply the raw curvature, conic constant and optional aspheric coefficients.

Parameters:

• position (ndarray (3,)) – Vertex position in world coordinates.

• curvature – Surface curvature 1/R in m^-1.

• radius – Outer disk radius in metres.

• rotation – Euler angles in degrees. Defaults to no rotation.

• conic – Schwarzschild conic constant.

• aspheric_coeffs – Even aspheric coefficients [A4, A6, …], i.e. aspheric_coeffs[i] multiplies r^(2i + 4).

• index – Refractive index of the glass – a number (default 1.5) or a RefractiveIndex model for a dispersive lens.

• transmittance – Bulk transmittance in [0, 1]. Defaults to 1.0.

• transmittance_curve – Optional T(theta, lambda) ResponseCurve multiplying transmittance; None (default) uses bare-interface Fresnel.

• optical_stage – Stage index within the Telescope.

• n_samples – Monte Carlo samples per element per render.

• key – JAX PRNG key for aperture sampling.

iactrace.telescope.lenses.plano_slab(*, position, radius, thickness, rotation=(0.0, 0.0, 0.0), index=1.5, transmittance=1.0, transmittance_curve=None, optical_stage=0, n_samples=100, key)

Build a flat parallel-sided window as a single-element group.

The surface is zero-curvature (flat) and rays pass through a SlabInteraction that handles entry refraction, propagation through the slab, and exit refraction.

Parameters:

• position (ndarray (3,)) – Vertex position of the front surface.

• radius – Outer disk radius in metres.

• thickness – Slab thickness in metres (along the optical axis).

• rotation – Euler angles in degrees. Defaults to no rotation.

• index – Refractive index of the slab material – a number (default 1.5) or a RefractiveIndex model for a dispersive window.

• transmittance – Bulk transmittance in [0, 1]. Defaults to 1.0.

• transmittance_curve – Optional T(theta, lambda) ResponseCurve for the window.

• optical_stage – Stage index within the Telescope.

• n_samples – Monte Carlo samples per element per render.

• key – JAX PRNG key for aperture sampling.

Obstruction builders

iactrace.telescope.obstructions.cylinder(*, p1, p2, r)

Build a single closed cylinder as a CylinderGroup of size one.

Parameters:

• p1 (ndarray (3,)) – One endpoint of the cylinder axis.

• p2 (ndarray (3,)) – The other endpoint.

• r – Cylinder radius in metres.

iactrace.telescope.obstructions.open_cylinder(*, p1, p2, r)

Build a single open cylinder (no end caps) as a size-one group.

Parameters:

• p1 (ndarray (3,)) – One endpoint of the cylinder axis.

• p2 (ndarray (3,)) – The other endpoint.

• r – Cylinder radius in metres.

iactrace.telescope.obstructions.box(*, p1, p2)

Build a single axis-aligned box as a BoxGroup of size one.

Parameters:

• p1 (ndarray (3,)) – One corner of the box.

• p2 (ndarray (3,)) – The diagonally opposite corner.

iactrace.telescope.obstructions.sphere(*, center, r)

Build a single sphere as a SphereGroup of size one.

Parameters:

• center (ndarray (3,)) – Sphere centre.

• r – Sphere radius in metres.

Operations

Functional operations for modifying telescope configurations (e.g., for calibration, error injection, optimization). All operations return new telescope instances.

iactrace.telescope.operations.set_positions(telescope, stage, positions)

Set element positions for the group at stage.

iactrace.telescope.operations.set_rotations(telescope, stage, rotations)

Set element rotations (Euler XYZ degrees) for the group at stage.

iactrace.telescope.operations.apply_displacement(telescope, stage, sigma_z, key)

Apply random Gaussian z-displacement to elements in the group at stage.

iactrace.telescope.operations.apply_misalignment(telescope, stage, sigma_h, sigma_v, key)

Apply random Gaussian tip/tilt to element orientations.

sigma_h / sigma_v are in arcseconds.

iactrace.telescope.operations.apply_roughness(telescope, stage, sigma)

Apply Gaussian BSDF roughness (arcseconds RMS) to the group at stage.

iactrace.telescope.operations.set_curvatures(telescope, stage, curvatures)

Set surface curvatures (1/R) for the group at stage.

iactrace.telescope.operations.set_conics(telescope, stage, conics)

Set surface conic constants for the group at stage.

iactrace.telescope.operations.set_aspherics(telescope, stage, aspherics)

Set surface aspheric coefficients for the group at stage.

iactrace.telescope.operations.scale_curvatures(telescope, stage, factor)

Multiply curvatures by factor (scalar or per-element).

iactrace.telescope.operations.offset_curvatures(telescope, stage, offset)

Add offset to curvatures (scalar or per-element).

iactrace.telescope.operations.apply_conic_error(telescope, stage, sigma, key)

Apply random Gaussian error to conic constants.

iactrace.telescope.operations.apply_aspheric_error(telescope, stage, sigmas, key)

Apply random Gaussian errors to aspheric coefficients.

iactrace.telescope.operations.apply_zernike_error(telescope, stage, sigmas, key)

Add random Gaussian Zernike figure error to the surface at stage.

Draws independent per-element coefficients for each Noll mode and composes them onto the stage’s surface: a bare aspheric mirror becomes an asphere + Zernike SumSurfaceGroup, while a surface that already carries a Zernike term has the new draw added to it (matching apply_conic_error and apply_aspheric_error, which accumulate noise rather than replace).

The Noll terms are RMS-normalized, so sigmas are RMS surface-error sigmas in metres. sigmas[m] scales Noll index m + 1: index 0 is piston (removed by the surface re-zero), 1/2 tilt, 3 defocus, 4/5 astigmatism, 6/7 coma, 8/9 trefoil, 10 spherical. Only the first 11 Noll terms are available; a longer sigmas raises.

Parameters:

• stage – Optical stage to perturb.

• sigmas (ndarray (J,)) – Per-Noll-mode RMS sigmas in metres. With J <= 11.

• key – JAX PRNG key for the coefficient draw.

iactrace.telescope.operations.apply_astigmatism(telescope, stage, sigma, key)

Add random astigmatism (Noll Z5/Z6) of RMS sigma metres per component.

iactrace.telescope.operations.apply_coma(telescope, stage, sigma, key)

Add random coma (Noll Z7/Z8) of RMS sigma metres per component.

iactrace.telescope.operations.apply_trefoil(telescope, stage, sigma, key)

Add random trefoil (Noll Z9/Z10) of RMS sigma metres per component.

iactrace.telescope.operations.resample(telescope, stage, key)

Refresh the Monte-Carlo sampling key on the group at stage.

iactrace.telescope.operations.set_reflectivity(telescope, stage, reflectivity)

Set per-element mirror reflectivity. Mirror stages only.

iactrace.telescope.operations.scale_reflectivity(telescope, stage, factor)

Multiply mirror reflectivity by factor. Mirror stages only.

Scales the bulk multiplier reflectivity; the response curve on the interaction is left untouched.

iactrace.telescope.operations.set_transmittance(telescope, stage, transmittance)

Set per-element bulk transmittance. Lens or slab stages only.

Writes the bulk multiplier transmittance; the response curve on the interaction is left untouched.

iactrace.telescope.operations.scale_transmittance(telescope, stage, factor)

Multiply bulk transmittance by factor. Lens or slab stages only.

Scales the bulk multiplier transmittance; the response curve on the interaction is left untouched.

iactrace.telescope.operations.set_refractive_index(telescope, stage, index)

Set the refractive index of a lens or slab stage.

index is a number, a per-element (N,) array, or a RefractiveIndex model for a dispersive element.

iactrace.telescope.operations.set_thickness(telescope, stage, thickness)

Set slab thickness in metres. Slab stages only.

iactrace.telescope.operations.set_focal_lengths(telescope, stage, focal_lengths, n_outside=1.0, wavelength=400.0)

Set focal lengths via curvature.

Mirror stages: c = 1 / (2 f). Lens stages (single refracting surface): c = 1 / ((n - n_outside) f), where n_outside is a design-time ambient-index assumption (default 1.0), not a value stored on the lens, and n is the lens index at the design wavelength (matters only for a dispersive lens; a constant lens ignores it).

iactrace.telescope.operations.apply_focal_error(telescope, stage, sigma, key, relative=False, n_outside=1.0, wavelength=400.0)

Perturb focal lengths by Gaussian noise; update curvatures accordingly.

Kind-aware: uses the mirror or single-refracting-lens formula. Slabs are rejected. n_outside is the design-time ambient index for the lens formula (default 1.0); wavelength is the design wavelength for a dispersive lens index (see set_focal_lengths).

iactrace.telescope.operations.add_obstruction(telescope, obstruction)

Append an obstruction group.

iactrace.telescope.operations.remove_obstruction(telescope, group_idx)

Remove the obstruction group at group_idx.

iactrace.telescope.operations.clear_obstructions(telescope)

Drop all obstruction groups.

iactrace.telescope.operations.get_obstruction_count(telescope)

Total number of obstruction elements across all groups.

iactrace.telescope.operations.get_info(telescope)

Summary dict of telescope configuration.