iactrace.io

Functions for loading and saving telescope and camera configurations.

Loaders

iactrace.io.load_telescope_config(filename, n_samples=100, *, key)

Load a telescope from a standalone telescope YAML file.

The file describes optics (mirrors, lenses, obstructions) and the camera frame (telescope.camera_position and telescope.camera_rotation). A camera is loaded separately via load_camera_config() / Camera.from_yaml().

Args:

filename: Path to the telescope YAML file. n_samples: Number of Monte Carlo samples per mirror element. key: JAX random key for sampling and roughness.

iactrace.io.load_camera_config(filename)

Load a Camera from a standalone camera YAML file.

Sensor positions in the file are interpreted as camera-local coordinates, so no telescope is needed.

Args:

filename: Path to camera YAML file.

Returns:

Camera object.

Builders

iactrace.io.build_telescope_config(config, n_samples, key)

Build a Telescope from a telescope configuration dictionary.

iactrace.io.build_camera_config(config)

Build a Camera from a camera configuration dictionary.

Sensor positions are interpreted as camera-local coordinates.

Savers

iactrace.io.save_telescope(telescope, filename, precision=8, overwrite=True)

Save a Telescope object to a standalone telescope YAML file.

Args:

telescope: The Telescope object to save. filename: Output file path. precision: Number of decimal places for float values. overwrite: If True, overwrite existing file.

Returns:

Path to the saved file.

iactrace.io.save_camera(camera, filename, precision=6, overwrite=True)

Save a Camera to a standalone YAML file.

Sensor positions are written in camera-local coordinates.

Args:

camera: The Camera object to save. filename: Output file path. precision: Number of decimal places for float values. overwrite: If True, overwrite existing file.

Returns:

Path to the saved file.

iactrace.io.telescope_to_dict(telescope)

Convert a Telescope to a telescope-only configuration dictionary.

iactrace.io.camera_to_dict(camera)

Convert a Camera to a standalone configuration dictionary.

Sensor positions are written in camera-local coordinates.

Args:

camera: The Camera object to convert.

Returns:

Configuration dictionary suitable for YAML serialization.

Schemas

class iactrace.io.TelescopeConfigSchema

Bases: BaseModel

Top-level schema for a telescope-only YAML file.

Describes the optical system (mirrors, lenses, obstructions) plus the camera frame (where rays should be delivered) in world coordinates. Sensor layout and detector response live in a separate camera file (see CameraFileSchema).

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

telescope

mirror_templates

mirrors

lenses

obstructions

validate_template_references()

Validate that all mirror template references exist.

A mirror with no template (fully self-contained) has nothing to check here.

validate_optical_stages()

Each optical stage may contain only one optical group.

Mirrors and lenses are each grouped per stage by the adapter; having a mirror and a lens at the same stage, or elements of different aperture types at the same stage, would build two groups for that stage and trip the same check in Telescope.__init__ with a far less actionable error.

class iactrace.io.CameraFileSchema

Bases: BaseModel

Top-level schema for a standalone camera YAML file.

A camera file is a list of sensors; each sensor group carries its own detector geometry and detection chain (concentrator / gap / photosensor), so different groups can run different chains.

Sensor positions are always in the camera-local frame. There is no world-frame mode: loading interprets every sensors[*].position as an offset from the camera origin, and saving writes them the same way. Unknown top-level keys (e.g. a hopeful frame: world tag) raise ValidationError thanks to extra="forbid".

The telescope and the camera frame live in the telescope YAML (TelescopeConfigSchema.telescope.camera_position / camera_rotation); the camera file knows nothing about the world.

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

sensors

Exceptions

exception iactrace.io.YAMLConfigError

Bases: Exception

Raised when YAML configuration is invalid.