iactrace.telescope

The Telescope class and related components for building optical systems.

Telescope Class

The main class representing an optical telescope system:

class iactrace.telescope.Telescope

Bases: Module

IACT telescope configuration as an Equinox Module.

Stores mirrors, lenses, obstructions, and sensors as object lists for polymorphic dispatch while maintaining JAX compatibility.

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, sensors=None, name='telescope', lens_groups=None)

Initialize Telescope.

Args:

mirror_groups: List of Mirror groups (reflective elements) obstruction_groups: List of Obstruction groups sensors: List of sensor objects name: Telescope name lens_groups: List of Lens groups (refractive elements)

mirror_groups = <dataclasses._MISSING_TYPE object>

lens_groups = <dataclasses._MISSING_TYPE object>

obstruction_groups = <dataclasses._MISSING_TYPE object>

sensors = <dataclasses._MISSING_TYPE object>

name = <dataclasses._MISSING_TYPE object>

property optical_groups

Return all optical groups (mirrors + lenses) combined.

This property provides a unified view of all optical elements for ray tracing through mixed reflective/refractive systems.

render(sources, values, source_type='point', sensor_idx=0, debug=False)

Render sources through telescope.

Args:

sources: Source positions (N, 3) or directions (N, 3) values: Flux values (N,) source_type: ‘point’ or ‘parallel’ sensor_idx: Which sensor to use debug: If True, return raw hits instead of accumulated image

Returns:

Rendered image or (pts, values) if debug=True

Note:

Shadowing is automatically applied if obstruction_groups is non-empty. Use telescope.clear_obstructions() to render without shadowing.

trace(ray_origins, ray_directions, values, sensor_idx=0, debug=False)

Trace classical rays through the full optical system.

Unlike __call__ which samples rays from primary mirror surfaces, this method traces rays from arbitrary external origins through the full optical system, including intersection with primary mirrors (stage 0). Per-mirror reflectivity is applied at each surface.

Args:

ray_origins: Ray starting positions (N, 3) ray_directions: Ray directions (N, 3), should be normalized values: Ray intensities (N,) sensor_idx: Which sensor to use debug: If True, return raw hits instead of accumulated image

Returns:

Rendered image or (pts, values) if debug=True

Note:

Shadowing is automatically applied if obstruction_groups is non-empty.

classmethod from_yaml(filename, integrator, key=None)

Load from YAML config.

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

Save telescope configuration to a YAML file.

This is the reverse of from_yaml() - it extracts the telescope configuration and saves it in a format that can be loaded back with from_yaml().

Note:

Some runtime state (sampling, perturbation) is not preserved in the YAML. When reloading, you’ll need to provide an integrator to resample.

Args:

filename: Output file path. precision: Number of decimal places for float values. overwrite: If True, overwrite existing file. If False, raise

FileExistsError if file exists.

Returns:

Path to the saved file.

Raises:

FileExistsError: If file exists and overwrite is False.

to_dict()

Convert telescope to a configuration dictionary.

Returns a dictionary in the same format as YAML configuration files, suitable for serialization or inspection.

Returns:

Configuration dictionary with telescope, mirror_templates, mirrors, obstructions, and sensors sections.

resample_mirrors(integrator, key)

Resample all mirrors with specified integrator.

Args:

integrator: Integrator object key: jax.random.key

Returns:

New telescope with resampled mirrors

set_mirror_positions(group_idx, positions)

Set positions for all mirrors in a group.

Args:

group_idx: Index of mirror group positions: New positions array (N, 3)

Returns:

New Telescope with updated mirror positions

set_mirror_rotations(group_idx, rotations)

Set rotations for all mirrors in a group.

Args:

group_idx: Index of mirror group rotations: New rotations array (N, 3) in degrees (Euler angles)

Returns:

New Telescope with updated mirror rotations

scale_mirror_weights(group_idx, scale_factors)

Scale reflectivity for mirrors in a group.

Args:

group_idx: Index of mirror group scale_factors: Scale factors per mirror (N,) or single value

Returns:

New Telescope with scaled mirror reflectivity

apply_roughness(roughness)

Apply roughness to all telescope mirrors.

Args:

roughness: Surface roughness in arcseconds

Returns:

New Telescope with updated roughness for mirrors

apply_roughness_to_group(group_idx, roughness)

Apply roughness to a specific mirror group.

Args:

group_idx: Index of mirror group roughness: Surface roughness in arcseconds

Returns:

New Telescope with updated roughness for specified group

apply_misalignment_to_group(group_idx, sigma_h, sigma_v, key)

Apply random Gaussian misalignment to mirror orientations.

Adds random perturbations to the horizontal and vertical angles of each mirror in the specified group, drawn from independent Gaussian distributions.

Args:

group_idx: Index of mirror group to modify sigma_h: Standard deviation of horizontal misalignment in arcseconds sigma_v: Standard deviation of vertical misalignment in arcseconds key: JAX random key for reproducibility

Returns:

New Telescope with randomly misaligned mirrors

apply_displacement_to_group(group_idx, sigma_z, key)

Apply random Gaussian displacement to mirrors along the z-axis.

Adds random perturbations to the z-coordinate of each mirror position in the specified group, drawn from a Gaussian distribution.

Args:

group_idx: Index of mirror group to modify sigma_z: Standard deviation of z-axis displacement (same units as positions) key: JAX random key for reproducibility

Returns:

New Telescope with randomly displaced mirrors

apply_focal_error_to_group(group_idx, sigma, key, relative=False)

Apply random Gaussian error to mirror focal lengths.

Perturbs the focal length of each mirror and converts back to curvature. For spherical/parabolic mirrors: f = 1/(2c), c = 1/(2f).

Args:

group_idx: Index of mirror group to modify sigma: Error magnitude:

• If relative=True: fractional error (e.g., 0.01 for 1%)

• If relative=False: absolute error in same units as focal length

key: JAX random key for reproducibility relative: If True, apply relative (percentage) error; if False, absolute

Returns:

New Telescope with perturbed mirror curvatures

apply_conic_error_to_group(group_idx, sigma, key)

Apply random Gaussian error to mirror conic constants.

Args:

group_idx: Index of mirror group to modify sigma: Standard deviation of conic constant error key: JAX random key for reproducibility

Returns:

New Telescope with perturbed mirror conic constants

apply_aspheric_error_to_group(group_idx, sigmas, key)

Apply random Gaussian errors to mirror aspheric coefficients.

Each aspheric term can have its own sigma value.

Args:

group_idx: Index of mirror group to modify sigmas: Standard deviations per aspheric term (K,). If fewer sigmas

than terms, remaining terms get zero error.

key: JAX random key for reproducibility

Returns:

New Telescope with perturbed mirror aspheric coefficients

set_mirror_curvatures(group_idx, curvatures)

Set curvatures for all mirrors in a group.

Args:

group_idx: Index of mirror group curvatures: New curvatures array (N,)

Returns:

New Telescope with updated mirror curvatures

set_mirror_conics(group_idx, conics)

Set conic constants for all mirrors in a group.

Args:

group_idx: Index of mirror group conics: New conic constants array (N,)

Returns:

New Telescope with updated mirror conic constants

set_mirror_aspherics(group_idx, aspherics)

Set aspheric coefficients for all mirrors in a group.

Args:

group_idx: Index of mirror group aspherics: New aspheric coefficients array (N, K) where K is number of terms

Returns:

New Telescope with updated mirror aspheric coefficients

scale_mirror_curvatures(group_idx, scale_factors)

Scale curvatures for mirrors in a group.

Args:

group_idx: Index of mirror group scale_factors: Scale factors per mirror (N,) or single value

Returns:

New Telescope with scaled mirror curvatures

offset_mirror_curvatures(group_idx, offsets)

Add offset to curvatures for mirrors in a group.

Args:

group_idx: Index of mirror group offsets: Offsets per mirror (N,) or single value to add

Returns:

New Telescope with offset mirror curvatures

set_focal_lengths(group_idx, focal_lengths)

Set mirror curvatures to achieve target focal lengths.

For spherical/parabolic mirrors: c = 1/(2f).

Args:

group_idx: Index of mirror group focal_lengths: Target focal lengths array (N,)

Returns:

New Telescope with curvatures set for target focal lengths

get_mirrors_by_stage(stage)

Get indices of mirror groups at a specific optical stage.

Args:

stage: Optical stage (0=primary, 1=secondary, etc.)

Returns:

List of mirror group indices at the specified stage

get_mirror_count()

Get total number of mirrors across all groups.

Returns:

Total mirror count

add_sensor(sensor)

Add a new sensor group to the telescope.

Args:

sensor: SensorGroup to add

Returns:

New Telescope with added sensor group

replace_sensor(sensor, idx=0)

Replace sensor group by index.

Args:

sensor: SensorGroup replacement idx: Index of sensor group to replace (default: 0)

Returns:

New Telescope with replaced sensor group

Raises:

IndexError: If index is out of range

remove_sensor(idx=0)

Remove a sensor group by index.

Args:

idx: Index of sensor group to remove (default: 0)

Returns:

New Telescope with sensor group removed

Raises:

IndexError: If idx is out of range

set_sensor_positions(idx, positions)

Set positions for all sensors in a group.

Args:

idx: Index of sensor group positions: New positions array (N, 3)

Returns:

New Telescope with updated sensor positions

set_sensor_rotations(idx, rotations)

Set rotations for all sensors in a group.

Args:

idx: Index of sensor group rotations: New rotations array (N, 3) Euler angles in degrees

Returns:

New Telescope with updated sensor rotations

focus(delta_z, sensor_idx=0)

Adjust all sensor positions in a group along optical axis for focus.

Args:

delta_z: Distance to move sensors along z-axis (positive = away from mirrors) sensor_idx: Index of sensor group to adjust (default: 0)

Returns:

New Telescope with adjusted sensor positions

get_sensor_count()

Get number of sensor groups.

Returns:

Number of sensor groups

with_ste(sensor_idx=0)

Convert sensor group to straight-through estimator variant.

Returns a new telescope with the specified sensor group converted to use straight-through estimation: hard assignment in forward pass, differentiable interpolation (bilinear for square, barycentric for hex) in backward pass.

Args:

sensor_idx: Index of sensor group to convert

Returns:

New Telescope with converted sensor group

Raises:

IndexError: If sensor_idx is out of range TypeError: If sensor type is not supported for conversion

add_obstruction(obstruction)

Add an obstruction group to the telescope.

Args:

obstruction: Obstruction group to add

Returns:

New Telescope with obstruction group added

remove_obstruction(group_idx)

Remove an obstruction group by index.

Args:

group_idx: Index of obstruction group to remove

Returns:

New Telescope with obstruction group removed

Raises:

IndexError: If group_idx is out of range

clear_obstructions()

Remove all obstructions from telescope.

Returns:

New Telescope with no obstructions

get_obstruction_count()

Get total number of obstructions across all groups.

Returns:

Total obstruction count

clone()

Create a deep copy of the telescope.

Returns:

Independent copy of the telescope

get_info()

Get summary information about telescope configuration.

Returns:

Dictionary with telescope statistics and properties including: name, mirror counts, sensor info, obstruction count, bounding box.

Mirror Groups

Classes for representing groups of mirror facets:

class iactrace.telescope.MirrorGroup

Bases: OpticalGroupBase

Base class for grouped mirrors with shared surface type and aperture type.

config_type = <dataclasses._MISSING_TYPE object>

positions = <dataclasses._MISSING_TYPE object>

rotations = <dataclasses._MISSING_TYPE object>

aperture_samples = <dataclasses._MISSING_TYPE object>

perturbation_angles = <dataclasses._MISSING_TYPE object>

perturbation_scale = <dataclasses._MISSING_TYPE object>

perturbation_key = <dataclasses._MISSING_TYPE object>

reflectivity = <dataclasses._MISSING_TYPE object>

optical_stage = <dataclasses._MISSING_TYPE object>

property interaction

Mirrors always reflect.

abstractmethod get_surface(mirror_idx)

Return the surface object for a specific mirror.

abstractmethod check_aperture(x, y, mirror_idx)

Check if points (x, y) are within aperture of specified mirror.

abstractmethod get_sampling_params()

Return structured dict with geometry parameters for sampling.

abstractmethod transform_to_world()

Compute geometry from current surface params and transform to world coordinates.

Computes points/normals/weights dynamically from aperture_samples and current surface parameters (curvature, conic, aspheric), then transforms to world coordinates with perturbation applied.

Returns:

Tuple of (points_world, normals_world, weights) arrays

abstractmethod to_config(index)

Convert a single mirror at index to a config dict.

Args:

index: Index of the mirror within the group.

Returns:

Configuration dictionary for this mirror (without template).

abstractmethod get_surface_params(index)

Get surface parameters for a single mirror.

Args:

index: Index of the mirror within the group.

Returns:

Dictionary with curvature, conic, aspheric coefficients.

abstractmethod classmethod from_config(configs, templates, optical_stage=0)

Create a MirrorGroup from a list of config dicts.

Args:

configs: List of mirror configurations with aperture, position, etc. templates: Dictionary of surface templates. optical_stage: Optical stage (0=primary, 1=secondary, etc.).

Returns:

New MirrorGroup instance.

__len__()

Return number of mirrors in group.

__init__(positions, rotations, aperture_samples, perturbation_angles, perturbation_scale, perturbation_key, reflectivity, optical_stage)

class iactrace.telescope.AsphericDiskMirrorGroup

Bases: MirrorGroup

Group of mirrors with aspheric surfaces and circular/annular apertures.

Each mirror has individual surface parameters (curvature, conic, aspherics). Supports optional center hole via inner_radii parameter. Geometry is computed dynamically from aperture_samples and current surface parameters.

config_type = 'circular'

__init__(positions, rotations, curvatures, conics, aspherics, radii, optical_stage=0, offsets=None, inner_radii=None)

Create group from positions, rotations, per-mirror surface params, and radii.

curvatures = <dataclasses._MISSING_TYPE object>

conics = <dataclasses._MISSING_TYPE object>

aspherics = <dataclasses._MISSING_TYPE object>

radii = <dataclasses._MISSING_TYPE object>

offsets = <dataclasses._MISSING_TYPE object>

inner_radii = <dataclasses._MISSING_TYPE object>

get_surface(mirror_idx)

Return the surface object for a specific mirror.

check_aperture(x, y, mirror_idx)

Check if points (x, y) are within mirror aperture (between inner and outer radius).

get_sampling_params()

Return structured dict with geometry parameters for sampling.

transform_to_world()

Compute geometry from current surface params and transform to world coordinates.

to_config(index)

Convert mirror at index to config dict.

get_surface_params(index)

Get surface parameters for a single mirror.

classmethod from_config(configs, templates, optical_stage=0)

Create AsphericDiskMirrorGroup from config dicts.

class iactrace.telescope.AsphericPolygonMirrorGroup

Bases: MirrorGroup

Group of mirrors with aspheric surfaces and polygon apertures (same vertex count).

Each mirror has individual surface parameters (curvature, conic, aspherics). Geometry is computed dynamically from aperture_samples and current surface parameters.

config_type = 'polygon'

__init__(positions, rotations, curvatures, conics, aspherics, vertices_list, optical_stage=0, offsets=None)

Create group from positions, rotations, per-mirror surface params, and vertices.

curvatures = <dataclasses._MISSING_TYPE object>

conics = <dataclasses._MISSING_TYPE object>

aspherics = <dataclasses._MISSING_TYPE object>

vertices = <dataclasses._MISSING_TYPE object>

n_vertices = <dataclasses._MISSING_TYPE object>

offsets = <dataclasses._MISSING_TYPE object>

get_surface(mirror_idx)

Return the surface object for a specific mirror.

check_aperture(x, y, mirror_idx)

Check if points (x, y) are within mirror aperture (convex polygon).

get_sampling_params()

Return structured dict with geometry parameters for sampling.

transform_to_world()

Compute geometry from current surface params and transform to world coordinates.

to_config(index)

Convert mirror at index to config dict.

get_surface_params(index)

Get surface parameters for a single mirror.

classmethod from_config(configs, templates, optical_stage=0)

Create AsphericPolygonMirrorGroup from config dicts.

Lens Groups

Classes for representing refractive optical elements:

class iactrace.telescope.LensGroup

Bases: OpticalGroupBase

Base class for grouped refractive elements with shared aperture type.

Defines the interface for lens groups, similar to MirrorGroup for mirrors. Concrete implementations (AsphericDiskLensGroup, PlanoSlabGroup) define the specific surface type and aperture geometry.

Required attributes (defined by subclasses):

positions: (N, 3) center positions rotations: (N, 3) Euler angles in degrees n_inside: (N,) refractive index of material n_outside: float, ambient refractive index (default 1.0) transmittance: (N,) bulk transmission coefficient optical_stage: int, 0=primary, 1=secondary, etc.

config_type = ''

positions = <dataclasses._MISSING_TYPE object>

rotations = <dataclasses._MISSING_TYPE object>

n_inside = <dataclasses._MISSING_TYPE object>

transmittance = <dataclasses._MISSING_TYPE object>

aperture_samples = <dataclasses._MISSING_TYPE object>

perturbation_angles = <dataclasses._MISSING_TYPE object>

perturbation_scale = <dataclasses._MISSING_TYPE object>

perturbation_key = <dataclasses._MISSING_TYPE object>

n_outside = 1.0

optical_stage = 0

abstract property interaction

Return the type of optical interaction (REFRACT or SLAB).

abstractmethod get_surface(element_idx)

Return the surface object for a specific element.

abstractmethod check_aperture(x, y, element_idx)

Check if points (x, y) are within aperture of specified element.

abstractmethod get_sampling_params()

Return structured dict with geometry parameters for sampling.

abstractmethod transform_to_world()

Compute geometry from current surface params and transform to world coordinates.

Returns:

Tuple with at minimum (points_world, normals_world, weights, n_inside, transmittance). SLAB types also return thickness.

abstractmethod to_config(index)

Convert a single lens element at index to a config dict.

abstractmethod classmethod from_config(configs, **kwargs)

Create a LensGroup from a list of config dicts.

__len__()

Return number of elements in group.

__init__(positions, rotations, n_inside, transmittance, aperture_samples, perturbation_angles, perturbation_scale, perturbation_key, n_outside=1.0, optical_stage=0)

class iactrace.telescope.AsphericDiskLensGroup

Bases: LensGroup

Group of refractive elements with aspheric surfaces and circular apertures.

This models a single refractive surface (e.g., one side of a lens). For a complete lens with two surfaces, use two AsphericDiskLensGroup instances. For parallel-sided windows, use PlanoSlabGroup instead.

config_type = 'aspheric_disk'

__init__(positions, rotations, curvatures, conics, aspherics, radii, n_inside, optical_stage=0, n_outside=1.0, transmittance=None, offsets=None)

Create lens group.

Args:

positions: Element center positions (N, 3) rotations: Euler angles in degrees (N, 3) curvatures: Surface curvatures (N,) conics: Conic constants (N,) aspherics: Aspheric coefficients (N, K) radii: Aperture radii (N,) n_inside: Refractive index of material (N,) or scalar optical_stage: Stage in optical system (0=primary, etc.) n_outside: Ambient refractive index (default 1.0) transmittance: Bulk transmission (N,), default 1.0 offsets: Surface offsets (N, 2), default zeros

positions = <dataclasses._MISSING_TYPE object>

rotations = <dataclasses._MISSING_TYPE object>

curvatures = <dataclasses._MISSING_TYPE object>

conics = <dataclasses._MISSING_TYPE object>

aspherics = <dataclasses._MISSING_TYPE object>

radii = <dataclasses._MISSING_TYPE object>

n_inside = <dataclasses._MISSING_TYPE object>

offsets = <dataclasses._MISSING_TYPE object>

transmittance = <dataclasses._MISSING_TYPE object>

aperture_samples = <dataclasses._MISSING_TYPE object>

perturbation_angles = <dataclasses._MISSING_TYPE object>

perturbation_scale = <dataclasses._MISSING_TYPE object>

perturbation_key = <dataclasses._MISSING_TYPE object>

property interaction

Return the type of optical interaction (REFRACT or SLAB).

get_surface(element_idx)

Return the surface object for a specific element.

check_aperture(x, y, element_idx)

Check if points (x, y) are within aperture of specified element.

get_sampling_params()

Return structured dict with geometry parameters for sampling.

transform_to_world()

Transform to world coordinates.

Returns:

Tuple of (points, normals, weights, n_inside, transmittance)

to_config(index)

Convert lens element at index to config dict.

classmethod from_config(configs, **kwargs)

Create AsphericDiskLensGroup from config dicts.

class iactrace.telescope.PlanoSlabGroup

Bases: LensGroup

Group of flat parallel-sided windows (slabs).

Rays refract at entry, propagate through material, and refract at exit. For parallel surfaces, exiting ray direction equals entering direction.

Use case: camera entrance windows, protective covers, filters.

config_type = 'plano_slab'

__init__(positions, rotations, radii, thickness, n_inside, optical_stage=0, n_outside=1.0, transmittance=None)

Create flat window group.

Args:

positions: Window center positions (N, 3) rotations: Euler angles in degrees (N, 3) radii: Aperture radii (N,) thickness: Window thickness (N,) or scalar n_inside: Refractive index (N,) or scalar optical_stage: Stage in optical system n_outside: Ambient refractive index (default 1.0) transmittance: Bulk transmission (N,), default 1.0

positions = <dataclasses._MISSING_TYPE object>

rotations = <dataclasses._MISSING_TYPE object>

radii = <dataclasses._MISSING_TYPE object>

curvatures = <dataclasses._MISSING_TYPE object>

conics = <dataclasses._MISSING_TYPE object>

aspherics = <dataclasses._MISSING_TYPE object>

offsets = <dataclasses._MISSING_TYPE object>

thickness = <dataclasses._MISSING_TYPE object>

n_inside = <dataclasses._MISSING_TYPE object>

transmittance = <dataclasses._MISSING_TYPE object>

aperture_samples = <dataclasses._MISSING_TYPE object>

perturbation_angles = <dataclasses._MISSING_TYPE object>

perturbation_scale = <dataclasses._MISSING_TYPE object>

perturbation_key = <dataclasses._MISSING_TYPE object>

property interaction

Return the type of optical interaction (REFRACT or SLAB).

get_surface(element_idx)

Return the surface object for a specific element.

check_aperture(x, y, element_idx)

Check if points (x, y) are within aperture of specified element.

get_sampling_params()

Return structured dict with geometry parameters for sampling.

transform_to_world()

Transform to world coordinates.

Returns:

Tuple of (points, normals, weights, n_inside, transmittance, thickness)

to_config(index)

Convert slab element at index to config dict.

classmethod from_config(configs, **kwargs)

Create PlanoSlabGroup from config dicts.

Operations

Functional operations for modifying telescope configurations (e.g., for optimization):

iactrace.telescope.operations.resample_mirrors(telescope, integrator, key)

Resample all mirrors with specified integrator

Args:

telescope: Telescope instance integrator: Integrator object key: jax.random.key

Returns:

New telescope with resampled mirrors

iactrace.telescope.operations.set_mirror_positions(telescope, group_idx, positions)

Set positions for all mirrors in a group.

Args:

telescope: Telescope instance group_idx: Index of mirror group positions: New positions array (N, 3)

Returns:

New Telescope with updated mirror positions

iactrace.telescope.operations.set_mirror_rotations(telescope, group_idx, rotations)

Set rotations for all mirrors in a group.

Args:

telescope: Telescope instance group_idx: Index of mirror group rotations: New rotations array (N, 3) in degrees (Euler angles)

Returns:

New Telescope with updated mirror rotations

iactrace.telescope.operations.scale_mirror_weights(telescope, group_idx, scale_factors)

Scale reflectivity for mirrors in a group.

Args:

telescope: Telescope instance group_idx: Index of mirror group scale_factors: Scale factors per mirror (N,) or single value

Returns:

New Telescope with scaled mirror reflectivity

iactrace.telescope.operations.apply_roughness(telescope, roughness)

Apply roughness to all telescope mirrors

Args:

telescope: Telescope instance roughness: Surface roughness in arcseconds

Returns:

New Telescope with updated roughness for mirrors

iactrace.telescope.operations.apply_roughness_to_group(telescope, group_idx, roughness)

Apply roughness to a specific mirror group.

Args:

telescope: Telescope instance group_idx: Index of mirror group roughness: Surface roughness in arcseconds

Returns:

New Telescope with updated roughness for specified group

iactrace.telescope.operations.apply_misalignment_to_group(telescope, group_idx, sigma_h, sigma_v, key)

Apply random Gaussian misalignment to mirror orientations.

Adds random perturbations to the horizontal and vertical angles of each mirror in the specified group, drawn from independent Gaussian distributions.

Args:

telescope: Telescope instance group_idx: Index of mirror group to modify sigma_h: Standard deviation of horizontal misalignment in arcseconds sigma_v: Standard deviation of vertical misalignment in arcseconds key: JAX random key for reproducibility

Returns:

New Telescope with randomly misaligned mirrors

iactrace.telescope.operations.apply_displacement_to_group(telescope, group_idx, sigma_z, key)

Apply random Gaussian distance adjustment to mirrors along the z-axis.

Adds random perturbations to the z-coordinate of each mirror position in the specified group, drawn from a Gaussian distribution.

Args:

telescope: Telescope instance group_idx: Index of mirror group to modify sigma_z: Standard deviation of z-axis displacement (same units as positions) key: JAX random key for reproducibility

Returns:

New Telescope with randomly displaced mirrors

iactrace.telescope.operations.set_mirror_curvatures(telescope, group_idx, curvatures)

Set curvatures for all mirrors in a group.

Args:

telescope: Telescope instance group_idx: Index of mirror group curvatures: New curvatures array (N,)

Returns:

New Telescope with updated mirror curvatures

iactrace.telescope.operations.set_mirror_conics(telescope, group_idx, conics)

Set conic constants for all mirrors in a group.

Args:

telescope: Telescope instance group_idx: Index of mirror group conics: New conic constants array (N,)

Returns:

New Telescope with updated mirror conic constants

iactrace.telescope.operations.set_mirror_aspherics(telescope, group_idx, aspherics)

Set aspheric coefficients for all mirrors in a group.

Args:

telescope: Telescope instance group_idx: Index of mirror group aspherics: New aspheric coefficients array (N, K) where K is number of terms

Returns:

New Telescope with updated mirror aspheric coefficients

iactrace.telescope.operations.scale_mirror_curvatures(telescope, group_idx, scale_factors)

Scale curvatures for mirrors in a group.

Args:

telescope: Telescope instance group_idx: Index of mirror group scale_factors: Scale factors per mirror (N,) or single value

Returns:

New Telescope with scaled mirror curvatures

iactrace.telescope.operations.offset_mirror_curvatures(telescope, group_idx, offsets)

Add offset to curvatures for mirrors in a group.

Args:

telescope: Telescope instance group_idx: Index of mirror group offsets: Offsets per mirror (N,) or single value to add

Returns:

New Telescope with offset mirror curvatures

iactrace.telescope.operations.set_focal_lengths(telescope, group_idx, focal_lengths)

Set mirror curvatures to achieve target focal lengths.

For spherical/parabolic mirrors: c = 1/(2f).

Args:

telescope: Telescope instance group_idx: Index of mirror group focal_lengths: Target focal lengths array (N,)

Returns:

New Telescope with curvatures set for target focal lengths

iactrace.telescope.operations.apply_conic_error_to_group(telescope, group_idx, sigma, key)

Apply random Gaussian error to mirror conic constants.

Args:

telescope: Telescope instance group_idx: Index of mirror group to modify sigma: Standard deviation of conic constant error key: JAX random key for reproducibility

Returns:

New Telescope with perturbed mirror conic constants

iactrace.telescope.operations.apply_aspheric_error_to_group(telescope, group_idx, sigmas, key)

Apply random Gaussian errors to mirror aspheric coefficients.

Each aspheric term can have its own sigma value.

Args:

telescope: Telescope instance group_idx: Index of mirror group to modify sigmas: Standard deviations per aspheric term (K,) where K is number of terms.

If fewer sigmas than terms, remaining terms get zero error. If more sigmas than terms, extra sigmas are ignored.

key: JAX random key for reproducibility

Returns:

New Telescope with perturbed mirror aspheric coefficients

iactrace.telescope.operations.apply_focal_error_to_group(telescope, group_idx, sigma, key, relative=False)

Apply random Gaussian error to mirror focal lengths.

Perturbs the focal length of each mirror and converts back to curvature. For spherical/parabolic mirrors: f = 1/(2c), c = 1/(2f).

Args:

telescope: Telescope instance group_idx: Index of mirror group to modify sigma: Error magnitude:

• If relative=True: fractional error (e.g., 0.01 for 1%)

• If relative=False: absolute error in same units as focal length

key: JAX random key for reproducibility relative: If True, apply relative (percentage) error; if False, absolute

Returns:

New Telescope with perturbed mirror curvatures

iactrace.telescope.operations.get_mirrors_by_stage(telescope, stage)

Get indices of mirror groups at a specific optical stage.

Args:

telescope: Telescope instance stage: Optical stage (0=primary, 1=secondary, etc.)

Returns:

List of mirror group indices at the specified stage

iactrace.telescope.operations.get_mirror_count(telescope)

Get total number of mirrors across all groups.

Args:

telescope: Telescope instance

Returns:

Total mirror count

iactrace.telescope.operations.add_sensor(telescope, sensor)

Add a new sensor group to the telescope.

Args:

telescope: Telescope instance sensor: SensorGroup to add

Returns:

New Telescope with added sensor group

iactrace.telescope.operations.replace_sensor(telescope, sensor, idx=0)

Replace sensor group by index.

Args:

telescope: Telescope instance sensor: SensorGroup replacement idx: Index of sensor group to replace (default: 0)

Returns:

New telescope with replaced sensor group

Raises:

IndexError: If index is out of range

iactrace.telescope.operations.remove_sensor(telescope, idx=0)

Remove a sensor group by index.

Args:

telescope: Telescope instance idx: Index of sensor group to remove (default: 0)

Returns:

New Telescope with sensor group removed

Raises:

IndexError: If idx is out of range

iactrace.telescope.operations.set_sensor_positions(telescope, group_idx, positions)

Set positions for all sensors in a group.

Args:

telescope: Telescope instance group_idx: Index of sensor group positions: New positions array (N, 3)

Returns:

New Telescope with updated sensor positions

iactrace.telescope.operations.set_sensor_rotations(telescope, group_idx, rotations)

Set rotations for all sensors in a group.

Args:

telescope: Telescope instance group_idx: Index of sensor group rotations: New rotations array (N, 3) Euler angles in degrees

Returns:

New Telescope with updated sensor rotations

iactrace.telescope.operations.focus(telescope, delta_z, sensor_idx=0)

Adjust all sensor positions in a group along optical axis (z-axis) for focus.

Args:

telescope: Telescope instance delta_z: Distance to move sensors along z-axis (positive = away from mirrors) sensor_idx: Index of sensor group to adjust (default: 0)

Returns:

New Telescope with adjusted sensor positions

iactrace.telescope.operations.get_sensor_count(telescope)

Get number of sensor groups.

Args:

telescope: Telescope instance

Returns:

Number of sensor groups

iactrace.telescope.operations.get_total_sensor_count(telescope)

Get total number of individual sensors across all groups.

Args:

telescope: Telescope instance

Returns:

Total number of sensors

iactrace.telescope.operations.with_ste(telescope, sensor_idx=0)

Convert sensor group to straight-through estimator variant.

Returns a new telescope with the specified sensor group converted to use straight-through estimation: hard assignment in forward pass, differentiable interpolation (bilinear for square, barycentric for hex) in backward pass.

Args:

telescope: Telescope instance sensor_idx: Index of sensor group to convert

Returns:

New Telescope with converted sensor group

Raises:

IndexError: If sensor_idx is out of range TypeError: If sensor type is not supported for conversion

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

Add an obstruction group

Args:

telescope: Telescope instance obstruction: Obstruction group to add to telescope

Returns:

New Telescope with obstruction group added

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

Remove an obstruction group by index.

Args:

telescope: Telescope instance group_idx: Index of obstruction group to remove

Returns:

New Telescope with obstruction group removed

Raises:

IndexError: If group_idx is out of range

iactrace.telescope.operations.clear_obstructions(telescope)

Remove all obstructions from telescope.

Args:

telescope: Telescope instance

Returns:

New Telescope with no obstructions

iactrace.telescope.operations.get_obstruction_count(telescope)

Get total number of obstructions across all groups.

Args:

telescope: Telescope instance

Returns:

Total obstruction count

iactrace.telescope.operations.clone(telescope)

Create a deep copy of the telescope.

Args:

telescope: Telescope instance

Returns:

Independent copy of the telescope

iactrace.telescope.operations.get_info(telescope)

Get summary information about telescope configuration.

Args:

telescope: Telescope instance

Returns:

Dictionary with telescope statistics and properties