Source core#
User view: sources. This page lists types, validation and sampling.
Headers obdeect/sources/source.hpp, streams.hpp, vec3.hpp. Namespace obdeect::sources.
Types#
Vec3{x,y,z}double;dot,cross,norm,normalised,is_finite;orthonormal_basis(n)returns(e1, e2):e1 = normalise(n x (1,0,0))if|n.x| < 0.9elsenormalise(n x (0,1,0)),e2 = n x e1(right-handed). The basis choice fixes the azimuth zero point; it is part of the contract only where azimuths are compared with this definition.Emitter{position, pointing (unit), angular}(default pointing (0,0,+1), Isotropic).Star{towards_source (unit, z>0), distance_m (default +inf), disk_radius_m, disk_z_m, start_z_m}.Targets:
DiscTarget{centre, normal (unit), radius_m},SphereTarget{centre, radius_m},Target = monostate | DiscTarget | SphereTarget.Source{frame (default sky), geometry (Emitter|Star), spectrum (Fixed 400), pulse (Fixed 0), photons, target}.Photon{position, direction, time_ns, weight=1, wavelength_nm}.Streamenum 1..5 (see conventions),stage_sources,photon_stream_format_major = 1,source_columns= x y z cx cy cz t w wavelength (obdeect stream bit mask).
Validation (validate(source), invalid_argument)#
photonsfinite,>= 0,<= 2^53.Frame is sky, T or C (not ground, not any other code).
Spectrum: Fixed
valuepositive-within-limits; UniformRange0 < low <= highboth positive-within-limits; InverseSquarelow < highstrictly, both positive-within-limits; Tabulated non-empty withlowerpositive-within-limits andupperwithin limits.Pulse: Fixed within limits; UniformRange
low <= highwithin limits; Gaussian mean andsigma >= 0finite within limits; Exponential mean andtau >= 0; ComplexPulse all three widths>= 0and finite within limits anddelaywithin limits (an infinite width is an error); Tabulated non-empty,lower/upperwithin limits.Star: no target;
towards_sourcefinite,|norm - 1| <= 1e-9,z > 0; distance+inf(plane wave) or positive-within-limits (so 1e200 is an error);disk_radius_mpositive-within-limits;disk_z_m,start_z_mwithin limits.Emitter:
positionwithin limits;pointingfinite, unit to 1e-9; angular: FixedAngle0 <= u0 <= 2; FilledCone0 < u0 <= 2; TabulatedAngular non-empty withlower >= 0andupper <= 2 + 1e-12.DiscTarget: centre within limits, normal unit to 1e-9, radius positive-within-limits; the angular profile must not be FixedAngle;
|(centre - position) . normal| > 0(emitter not in the disc plane).SphereTarget: centre within limits, radius positive-within-limits; angular must be Isotropic;
|centre - position| > radius(emitter outside).
Counts#
expected_count(source) (validates first) =
star:
photons(mean photons on the entrance disc);emitter without target:
photons;disc target:
photons * candidates_per_photon,candidates_per_photon = I_max / (2 pi * integral_u) * pi R^2 / h^2,h = |(centre - position) . normal|; example: isotropic (I_max 1, integral 2),R = 2,h = 10:R^2/(4h^2) = 1/100;sphere target:
photons * (1 - cos_max) / 2,cos_max = sqrt(1 - (R/d)^2),d = |centre - position|.
Throws if the result is not finite or exceeds 2^53 (message mentions 2^53; a disc at
h = 1e-170 overflows). photon_count(source, seed, event, telescope) rounds the mean by the
rule in conventions (stream count, photon index 0).
Emission of photon i (sample_photon, emit)#
Draws: pulse stream -> time pulse.sample; wavelength stream -> spectrum.sample; then
geometry draws. emit(source, seed, event, telescope, first_index, rows, chunk) validates,
rejects rows > 65536 (invalid_argument), sets chunk.telescope_id, frame, first_index,
columns source_columns, and converts to float32.
Emitter without target#
u_angle = quantile(direction_u[0]) (full range, umax = 2); azimuth phi = 2 pi direction_u[1]; direction = pointing cos_theta + (e1 cos phi + e2 sin phi) sin_theta, cos_theta = 1 - u_angle, (e1,e2) = orthonormal_basis(pointing); position = emitter position; weight 1.
FixedAngle gives exactly the angle (dot(direction, pointing) = cos(angle) to 1e-6).
Sphere target (isotropic only)#
Cone about n = normalise(centre - position) with cos_max as above; cos_theta = 1 - direction_u[0] (1 - cos_max), azimuth 2 pi direction_u[1]. Weight 1. Every photon passes
within R of the centre.
Disc target#
Target stream: r = R sqrt(u0), phi = 2 pi u1, point P = centre + e1 r cos phi + e2 r sin phi with (e1,e2) = orthonormal_basis(normal). direction = (P - position)/|P - position|,
cos = clamp(dot(direction, pointing), -1, 1), weight
I(1 - cos) / I_max * (h/|P - position|)^3 (zero outside the profile). Sum of weights is the
expected number of photons reaching the disc. Example: isotropic, h = 10, R = 2: mean weight
= (solid angle / 4 pi) * 100, solid angle 2 pi (1 - 10/sqrt(104)); a 5 deg FilledCone gives
w > 0 inside and w == 0 outside (margin 1e-3 deg).
Star (plane wave, distance_m = +inf)#
Target stream: r = R_disk sqrt(u0), phi = 2 pi u1; target = (r cos phi, r sin phi, disk_z); direction = -towards_source. The ray starts where it crosses the plane
z = start_z: start = target + direction * ((start_z - target.z)/direction.z). Time added:
dot(start - centre, direction)/c with centre = (0,0,disk_z) (wavefront through the disc
centre at t = 0), on top of the pulse time. Weight 1.
Star (point source, finite distance)#
position = centre + towards_source * distance. direction = normalise(target - position).
If position.z <= start_z the photon starts at position; otherwise at the crossing of the
start plane: target + direction * ((start_z - target.z)/direction.z). Time added:
(|start - position| - distance)/c. Example: source at 20 m, direction (0.6, 0, 0.8), disc centre
height 1.5, start plane 30: start at (12, 0, 17.5), t = -20/c.
The frame is stored unchanged in the chunk. A plane-wave star or a point source above the start plane starts at z = start_z (in its frame, e.g. T); a point source at or below the start plane starts at its own position.