Source model#

A source emits photons from a point (an emitter) or as a parallel beam (a star). Photons are written as photon stream chunks in the frame of the source.

Model#

Part

Choices

Geometry

emitter: position, pointing, angular profile. star: parallel beam (infinite distance) or point source at finite distance, on a disc

Angular profile

isotropic, cone (one angle), filled_cone, lambertian (cos theta), gauss (sigma in deg), rayleigh, table (angle in deg, value)

Spectrum

fixed (nm), uniform, inverse_square (1/lambda^2, Cherenkov), table

Pulse

fixed (ns), tophat (full width, delay), gauss (sigma, mean), exponential (decay, mean), complex (flat, Gauss r.m.s., decay, delay), table

Count

photons: mean number emitted into 4 pi (emitter) or on the disc (star)

Target

optional, emitters only: disc (weighted) or sphere (cone)

Profiles are relative: an emitter with profile P emits all photons with directions distributed as P. Times are emission times at the source. A star’s times are the wavefront arrival at the disc centre (ray-tracing convention).

from obdeect.sources.source import emit

flasher = {
    "frame": "camera",
    "photons": 1e6,
    "emitter": {
        "position_m": [0.0, 0.0, 1.5],
        "pointing": [0.0, 0.0, -1.0],
        "angular": {"kind": "filled_cone", "angle_deg": 11.0},
    },
    "spectrum": {"kind": "fixed", "wavelength_nm": 385.0},
    "pulse": {"kind": "tophat", "width_ns": 2.5},
    "target": {"kind": "disc", "centre_m": [0.0, 0.0, 0.0],
               "normal": [0.0, 0.0, 1.0], "radius_m": 1.2},
}
photons = emit(flasher, seed=3)   # float32 arrays: x y z cx cy cz t w wavelength

iter_chunks emits large counts (at most 2^16 rows per chunk); emit_chunk(..., first_index=, rows=) emits any slice.

Frames and units#

  • Frames: sky (absolute), telescope (T, z along the optical axis), camera (C). Ground is not a source frame. The frame is stored in the chunk.

  • Lengths in metres, times in ns, wavelengths in nm, angles in degrees (the core takes u = 1 - cos(theta)).

  • Directions are unit vectors of the propagation direction. cz < 0 is downward, as in ray tracing and stream format.

  • Without a target, w = 1 for every photon.

Targets (importance sampling)#

Most photons of a calibration lamp miss the telescope. A target generates only photons that can reach it.

  • disc: candidates are uniform points on the disc. Weight w = I(theta) / I_max (h / r)^3, the probability that the emitted photon reaches the disc (h distance from emitter to disc plane, r to the point). Candidate count photons R^2 / (4 h^2) for an isotropic emitter (general: I_max / (2 pi integral(I du)) x pi R^2 / h^2). Sum of weights = expected photons on the disc. Efficient when the profile covers the disc; narrow cones off the disc give mostly w = 0.

  • sphere: directions sampled in the cone containing the sphere, w = 1, count photons (1 - cos theta_max) / 2. Isotropic emitters only.

Conventions#

  • Emitter count: floor(mean) plus one with probability equal to the fraction (not Poisson). The mean is the same; weights are not thinned.

  • Units are SI-like (m, ns, nm, deg). Every photon has weight 1, except disc targets and bunches (bunch_size photons per row in the tools).

  • Gaussian pulse parameters are sigma: sigma = FWHM / 2.35482.

  • Tool spellings map to dictionary kinds: Cone: = cone, FilledCone: = filled_cone, Parallel = cone at 0 deg, Gauss-rms: = gauss, Rayleigh = rayleigh, Cherenkov:a:b = inverse_square; Simple:, Gauss:, Exp:, Complex: are pulse kinds.

  • Tables are passed as arrays, not read from files.

  • Refraction and airlight belong to obdeect propagation. The Gaussian spectrum is not available.

Random numbers: Random numbers.