iactrace.io

Everything iactrace reads from or writes to a file: telescope and camera configuration as YAML, and the result of a scan as .npz.

For how the package is layered, and what to touch when adding a new schema variant or a new file format, see the module docstring of iactrace.io.

Configuration

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.

Parameters:

• 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.

Parameters:

filename – Path to camera YAML file.

Return type:

Camera object.

Builders

Take an already-parsed dictionary, for a caller that read the YAML itself.

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.

Parameters:

• telescope – The Telescope object to save.

• 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.

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.

Parameters:

• camera – The Camera object to save.

• 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.

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.

Parameters:

camera – The Camera object to convert.

Return type:

Configuration dictionary suitable for YAML serialization.

Schemas

The grammar a config file is validated against.

class iactrace.io.TelescopeConfigSchema

Bases: ConfigModel

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).

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.

model_config = {'extra': 'forbid'}

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

class iactrace.io.CameraFileSchema

Bases: ConfigModel

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.

sensors

model_config = {'extra': 'forbid'}

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

Exceptions

exception iactrace.io.YAMLConfigError

Bases: Exception

Raised when YAML configuration is invalid.

Effective-aperture tables

iactrace.io.aperture_table.FORMAT = 'iactrace-aperture-table'

Marker identifying an effective-aperture archive

iactrace.io.aperture_table.FORMAT_VERSION = '1.0'

Format version, major.minor.

iactrace.io.aperture_table.load_aperture_table(filename)

Read an effective-aperture table written by save_aperture_table.

Parameters:

filename – Path to the .npz archive.

Return type:

The EffectiveApertureTable.

Raises:

ValueError – if the file is not an aperture table, or is a format version this reader does not know.

iactrace.io.aperture_table.read_aperture_table_arrays(filename)

The table’s fields as plain arrays, without constructing the table.

Parameters:

filename – Path to the .npz archive.

Returns:

• {origin, step, offset, values, on_axis_area, wavelengths,

• spectral_area, meta}, ready to hand to the table’s constructor.

iactrace.io.aperture_table.save_aperture_table(table, filename, *, overwrite=True, compress=True)

Write an effective-aperture table to a .npz file.

Parameters:

• table – The EffectiveApertureTable to write.

• filename – Output path.

• overwrite – If False, refuse to replace an existing file.

• compress – Store deflated.

Return type:

The path written.

Raises:

FileExistsError – if the file exists and overwrite is False.

iactrace.io.save_aperture_table(table, filename, *, overwrite=True, compress=True)

Write an effective-aperture table to a .npz file.

Parameters:

• table – The EffectiveApertureTable to write.

• filename – Output path.

• overwrite – If False, refuse to replace an existing file.

• compress – Store deflated.

Return type:

The path written.

Raises:

FileExistsError – if the file exists and overwrite is False.

iactrace.io.load_aperture_table(filename)

Read an effective-aperture table written by save_aperture_table.

Parameters:

filename – Path to the .npz archive.

Return type:

The EffectiveApertureTable.

Raises:

ValueError – if the file is not an aperture table, or is a format version this reader does not know.

iactrace.io.read_aperture_table_arrays(filename)

The table’s fields as plain arrays, without constructing the table.

Parameters:

filename – Path to the .npz archive.

Returns:

• {origin, step, offset, values, on_axis_area, wavelengths,

• spectral_area, meta}, ready to hand to the table’s constructor.

iactrace.io.FORMAT = 'iactrace-aperture-table'

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to ‘strict’.

iactrace.io.FORMAT_VERSION = '1.0'

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to ‘strict’.