Python API#
The package exports the optical model and the helpers below; everything else is internal. Units are metres, nanoseconds and nanometres. For frames, see Optical models.
Optical models#
- class obdeect.ray_tracing.model.OpticalModel(document)[source]#
A compiled optical model, ready for tracing.
The model is immutable; its SHA-256 identifies it in every result.
- Parameters:
document (dict[str, Any])
- property document: dict[str, Any]#
Return a copy of the compiled document.
- classmethod from_records(records, read_file, *, configuration_seed, zenith_deg=None, propagation_group_index=1.0, provenance=None)[source]#
Compile simulation-models parameter records (see
compiler.compile_model).- Parameters:
records (Mapping[str, dict[str, Any]])
read_file (Callable[[str], str])
configuration_seed (int)
zenith_deg (float | None)
propagation_group_index (float)
provenance (dict[str, Any] | None)
- Return type:
- classmethod from_simulation_models(root, model, version, *, configuration_seed, zenith_deg=None)[source]#
Compile a telescope model from a simulation-models checkout.
- Parameters:
root (Path)
model (str)
version (str)
configuration_seed (int)
zenith_deg (float | None)
- Return type:
- property has_structure: bool#
True if the model’s own geometry shadows instead of
telescope_transmission.
- property sampling_area_m2: float#
Area of the disk on which star photons are sampled.
- property focal_surface_z_m: float#
Height of the focal plane, or of the focal-surface vertex, in the telescope frame.
- property axes_offset_m: tuple[float, float, float]#
Offset O [m, telescope frame] of the optical origin from the telescope sphere centre.
A ground-frame point P is traced at R P - O in the telescope frame, with R the input rotation of trace_bunches, so the dish sits at +O relative to the rotation axes. Zero for models without an axes offset.
- property propagation_group_index: float#
Group index of air the photon times use.
- max_incoming_obscurer_z_m()[source]#
Highest z [m, telescope frame] of any obscurer on the incoming leg, or None.
Each obscurer is bounded from above: a plate by its centre plus its aperture’s circumradius, a cylinder or frustum by its end points plus the outer end radii (wall thickness included), a polyhedron by its highest vertex. Photons starting below this height never meet those obscurers.
- Return type:
float | None
- emitter_photons(emitted, *, seed, position_m, intensity, axis=(0.0, 0.0, 1.0), pulse=None, wavelength_nm=400.0, disk=None, first_id=0)[source]#
Photons of a point emitter (a calibration light source) that cross a disk.
The emitter at position_m (telescope frame) sends emitted photons into 4 pi with the relative intensity per solid angle intensity (angles from axis [deg], values; linear in 1 - cos(angle), zero beyond the last angle) and emission times from the relative density pulse (times [ns], values; None: all at 0). Photons are made only on their way through disk (centre, unit normal, radius [m]; default the star-light disk). Their weights are in [0, 1], and their number is Poisson distributed, so keeping each photon with the probability of its weight gives the photons crossing the disk; the sum of weights estimates their mean number. Start positions are the emitter, times are emission times.
- Parameters:
emitted (float)
seed (int)
position_m (tuple[float, float, float])
intensity (tuple[ndarray, ndarray])
axis (tuple[float, float, float])
pulse (tuple[ndarray, ndarray] | None)
wavelength_nm (float)
disk (tuple[tuple[float, float, float], tuple[float, float, float], float] | None)
first_id (int)
- Return type:
dict[str, ndarray]
- trace_emitter(emitted, **options)[source]#
Make and trace the photons of a point emitter (see trace_emitter_blocks).
Returns the photons of all blocks reaching the focal surface with a positive weight.
- Parameters:
emitted (float)
options (Any)
- Return type:
dict[str, ndarray]
- trace_emitter_blocks(emitted, *, seed, position_m, intensity, axis=(0.0, 0.0, 1.0), pulse=None, wavelength_nm=400.0, disk=None, first_id=0, direct=False, threads=0, block_size=250000)[source]#
Make and trace the photons of a point emitter, block_size photons at a time.
The photons are those of emitter_photons, traced as by trace; memory is bounded by one block. Yields, for each block (at least one), the photons reaching the focal surface with a positive weight: position_m, direction, time_ns and weight of the trace, and wavelength_nm. The photons do not depend on block_size.
- Parameters:
emitted (float)
seed (int)
position_m (tuple[float, float, float])
intensity (tuple[ndarray, ndarray])
axis (tuple[float, float, float])
pulse (tuple[ndarray, ndarray] | None)
wavelength_nm (float)
disk (tuple[tuple[float, float, float], tuple[float, float, float], float] | None)
first_id (int)
direct (bool)
threads (int)
block_size (int)
- Return type:
Iterator[dict[str, ndarray]]
- star_photons(count, *, seed, towards_source=(0.0, 0.0, 1.0), distance_m=inf, wavelength_nm=400.0, first_id=0)[source]#
Sample photons from a star or a point source.
towards_source is the unit vector to the source in the telescope frame (+z along the optical axis, towards the sky); distance_m is the source distance from the dish vertex, the centre of the sampled disk. Times are zero for the wavefront at that point.
- Parameters:
count (int)
seed (int)
towards_source (tuple[float, float, float])
distance_m (float)
wavelength_nm (float)
first_id (int)
- Return type:
dict[str, ndarray]
- trace(photons, *, seed, apply_responses=True, threads=0, direct=False, outputs=None, detected_only=False, classify_losses=True, pool=None)[source]#
Trace photons; returns per-photon arrays (see docs/python-guide.md).
photons holds position_m (n, 3), direction (n, 3), wavelength_nm, time_ns, weight and photon_id. With apply_responses False only geometry acts (weights unchanged); threads 0 uses every core. direct photons start inside the telescope on their way to the focal surface (e.g. from a flasher): mirrors and telescope transmission do not act, the obscurers of that leg do.
outputs lists the columns to return (None: all of them); asking only for what is used saves memory traffic. With detected_only just the photons with status
detectedare returned, in input order, and the extra columnindex(their row in the input) becomes available. An unknown column raisesValueError.With classify_losses False a photon that misses the primary mirror is reported as
missed_primaryeven where it would beblockedbefore missing it; detected photons are the same either way.With a pool (a ThreadPool) its threads run the work and threads is ignored; the results are the same.
- Parameters:
photons (Mapping[str, ndarray])
seed (int)
apply_responses (bool)
threads (int)
direct (bool)
outputs (Sequence[str] | None)
detected_only (bool)
classify_losses (bool)
pool (ThreadPool | None)
- Return type:
dict[str, ndarray]
- obscurer_hits(photons, *, seed, threads=0)[source]#
Which obscurers shade the light: a diagnostic, slower than trace.
The photons are traced without obscurers (geometry only, mirror scattering from seed as in trace); along the path of each one that then reaches the focal surface, every obscurer it meets is listed. Per obscurer, in model order, the result holds
id,name,groupand the summed input weights of the photons whose pathcrossedit, that it absorbs (first: the first obscurer on the path) and that only it meets (sole: without it they would be detected).unobscuredanddetectedare the summed weights of the photons reaching the focal surface without and with the obscurers.- Parameters:
photons (Mapping[str, ndarray])
seed (int)
threads (int)
- Return type:
dict[str, Any]
- trace_bunches(bunches, *, seed, event=0, telescope=0, frame_rotation, frame_offset_m, length_unit_m, plane_z, acceptance=None, wavelength_density=None, wavelength_law=None, roulette=True, classify_losses=True, normalise_transmission=False, pool=None, threads=0)[source]#
Trace photon bunches of an air shower (see docs/batch-tracing.md).
bunches holds x, y, cx, cy, time_ns, zem, size, wavelength_nm (all float32; wavelength 0 means “sample one from wavelength_density or wavelength_law”) and bunch_id (uint64, unique per bunch for one seed). The random draws are keyed on (seed, event, telescope, bunch, sub-photon), as in the other components. frame_rotation (3 x 3, input to telescope frame), frame_offset_m, length_unit_m (metres per input length unit) and plane_z (input units) place the input plane in the telescope frame. The native tracer applies the model’s axes_offset_m O_t (telescope frame): with zero frame_offset_m, a ground-frame point P is traced at R P - O_t = R (P - O_g), where O_g = R.T O_t is in the ground frame. This assumes frame_rotation is the ground-to-telescope rotation at the zenith angle the model was compiled for. acceptance is
(wavelength_nm, zem_m, values)with values (n_wavelength, n_zem) in [0, 1]; wavelength_density is(nm, values). wavelength_law is(lo_nm, hi_nm): it samples wavelength-0 bunches, with density proportional to 1/lambda^2 on [lo_nm, hi_nm] (1 <= lo_nm < hi_nm), continuous in nm. Give at most one of wavelength_density and wavelength_law.Each photon of a bunch is thinned by the acceptance and the model’s response bound, traced, and, with roulette, kept with the probability min(1, weight / bound) (survivors have weight 1; without roulette they carry that capped ratio as weight). Returns the surviving photons as columns position_m, direction, time_ns, weight, wavelength_nm, bunch_index (input row) and sub_photon, in input order. Invalid input raises
ValueErrorbefore any tracing. With normalise_transmission the roulette weight and bound are relative to the telescope transmission’s on-axis value (the caller applies that value itself). The result does not depend on threads or pool.- Parameters:
bunches (Mapping[str, ndarray])
seed (int)
event (int)
telescope (int)
frame_rotation (ndarray)
frame_offset_m (Sequence[float])
length_unit_m (float)
plane_z (float)
acceptance (tuple[ndarray, ndarray, ndarray] | None)
wavelength_density (tuple[ndarray, ndarray] | None)
wavelength_law (tuple[float, float] | None)
roulette (bool)
classify_losses (bool)
normalise_transmission (bool)
pool (ThreadPool | None)
threads (int)
- Return type:
dict[str, ndarray]
- obdeect.ray_tracing.model.trace_many(requests, *, seed, pool)[source]#
Trace the photons of several models in one job on pool.
Each request is
(model, photons, options); options may hold apply_responses, direct, outputs, detected_only and classify_losses with the meaning and defaults of OpticalModel.trace. The result is the list of the dicts that one OpticalModel.trace call per request returns, with the same values; the blocks and models share the pool’s threads, which keeps them busy when single blocks are small.- Parameters:
requests (Sequence[tuple[OpticalModel, Mapping[str, ndarray], Mapping[str, Any]]])
seed (int)
pool (ThreadPool)
- Return type:
list[dict[str, ndarray]]
Photon streams#
- obdeect.ray_tracing.stream.trace_stream(model, input, output, *, seed, threads=0, telescopes=None, pointing=None, telescope_transmission='full')[source]#
Trace the photons of a photon stream and write the camera-frame photons.
Parameters#
- model: OpticalModel
Optical model of the telescope type.
- input, output: str or path-like
Photon-stream files; “-” is standard input or output.
- seed: int
Run seed (non-negative). Draws are keyed on (seed, event, telescope, photon), as in the other components.
- threads: int
Worker threads (0 uses every core); results do not depend on it.
- telescopes: iterable of int or None
Telescope ids to trace; other telescopes are dropped. None traces all.
- pointing: (float, float) or None
Telescope (zenith, azimuth) [deg]; azimuth in the array frame (x north, y west), as simtools’ telescope phi. None takes it from the run keys telescope_pointing_zenith_rad and telescope_pointing_azimuth_rad [rad]. Ground-frame photons need one of the two; the event header has no pointing.
- telescope_transmission: “full” or “angular”
“full” applies the telescope transmission t(theta), including its on-axis value t0. “angular” applies t(theta) / t0 only; the efficiency status then leaves t0 as the pending factor
telescope_transmission_constantfor the downstream camera module. Models without telescope transmission reject “angular”.
Returns#
- dict
Counts of
events,photons_inandphotons_out.
Raises#
- ModelError
For an invalid stream, a missing pointing (ground-frame photons only), an unsupported frame or column, or an efficiency status that says a factor is already applied, and for an unknown telescope_transmission or “angular” with a model that has none.
- Parameters:
model (OpticalModel)
input (Any)
output (Any)
seed (int)
threads (int)
telescopes (Iterable[int] | None)
pointing (tuple[float, float] | None)
telescope_transmission (str)
- Return type:
dict[str, int]
- obdeect.ray_tracing.stream.ground_to_telescope_rotation(theta_deg, phi_deg)[source]#
Rotation R with p_telescope = R p_ground for a telescope at zenith theta, azimuth phi.
The ground frame has x north, y west and z up (the array frame, as simtools
ground_direction_to_telescope_frame). phi is the telescope azimuth in that frame, not the CORSIKA propagation azimuth of a shower. The telescope frame has +z along the optical axis. A shower that propagates along -axis maps to direction (0, 0, -1).- Parameters:
theta_deg (float)
phi_deg (float)
- Return type:
ndarray
- obdeect.ray_tracing.stream.minimum_input_plane_height_m(model, theta_deg, phi_deg=0.0)[source]#
Height [m] of the ground-frame input plane above the telescope sphere centre.
The plane lies above every incoming obscurer in the pointing direction, with the axes offset and a margin included (see
trace_bunches).- Parameters:
model (OpticalModel)
theta_deg (float)
phi_deg (float)
- Return type:
float
Analysis#
- obdeect.ray_tracing.psf.containment(x, y, weights=None, fraction=0.8)[source]#
Centroid and the radius around it containing fraction of the weight.
- Parameters:
x (ndarray)
y (ndarray)
weights (ndarray | None)
fraction (float)
- Return type:
dict
- obdeect.ray_tracing.psf.summary(arrivals, sampling_area_m2, fraction=0.8)[source]#
Status counts, effective area and focal-plane PSF of one traced source.
The effective area is the detected fraction of the sampled photons times the sampled area, weighted by the traced optical weights.
- Parameters:
arrivals (dict[str, ndarray])
sampling_area_m2 (float)
fraction (float)
- Return type:
dict[str, Any]
Compilation#
- obdeect.ray_tracing.compiler.compile_model(records, read_file, *, configuration_seed, zenith_deg=None, propagation_group_index=1.0, provenance=None)[source]#
Return the optical model as a JSON-serialisable dictionary.
Parameters#
- records
simulation-models parameter records by name (
value,unit, …).- read_file
Returns the text of the file named by a parameter (its
value).- configuration_seed
Seed of the one-time random mirror errors (focal lengths, placement, alignment). The realised geometry is stored in the model.
- zenith_deg
Telescope zenith angle for zenith-dependent focus and alignment errors; None uses the reference angle of each parameter.
- propagation_group_index
Group refractive index of air at the telescope, for arrival times.
- provenance
Identity of the model (name, version, site), stored unchanged.
- Parameters:
records (Mapping[str, dict[str, Any]])
read_file (Callable[[str], str])
configuration_seed (int)
zenith_deg (float | None)
propagation_group_index (float)
provenance (dict[str, Any] | None)
- Return type:
dict[str, Any]
- obdeect.ray_tracing.repository.read_telescope(root, model, version)[source]#
Records of model in production version (a full or a patch production), following design-model inheritance, plus the site’s air group index at the observation level.
- Parameters:
root (Path)
model (str)
version (str)
- Return type:
TelescopeRecords