Python usage#

from obdeect.ray_tracing import DETECTED, OpticalModel

model = OpticalModel.from_simulation_models(
    "../simulation-models", "LSTN-01", "7.0.0", configuration_seed=1, zenith_deg=20.0
)
photons = model.star_photons(100_000, seed=2, towards_source=(0.0087, 0.0, 0.99996))
arrivals = model.trace(photons, seed=2)
image = arrivals["position_m"][arrivals["status"] == DETECTED]

OpticalModel.from_records(records, read_file, ...) compiles parameter records held in memory. save and load store the model as JSON.

trace takes photons as arrays: position_m (n, 3), direction (n, 3, unit vectors), wavelength_nm, time_ns, weight and photon_id (uint64; a photon’s random numbers depend only on the seed and its id). It returns, per photon:

Array

Meaning

status

index into STATUS_NAMES: detected, missed_primary, missed_secondary, missed_focal_surface, blocked, invalid_input, numerical_failure

terminal_surface

id of the surface the photon ended on (focal surface, obscurer, mirror)

position_m, direction

at the focal surface, or where the photon was lost

path_length_m, time_ns

geometric path; time with the model’s group index

weight

input weight times the applied responses; zero when lost

primary_point_m, primary_surface, primary_incidence_deg

reflection on the primary

secondary_point_m, secondary_surface, secondary_incidence_deg

reflection on the secondary (NaN for single-mirror telescopes)

focal_incidence_deg

angle to the focal-surface normal

trace returns all 14 arrays by default. Request only what you use:

detected = model.trace(
    photons,
    seed=2,
    outputs=("position_m", "direction", "time_ns", "weight", "index"),
    detected_only=True,
)

outputs lists the arrays to return; an unknown name raises ValueError. With detected_only=True, only detected photons are returned, in input order, and index gives each one’s row in the input. Values match the full trace for any threads.

classify_losses=False (default True) reports a photon missing the primary as missed_primary, even if an incoming obscurer would have blocked it first. This skips the obscurer search; detected photons are the same either way.