# Source core User view: [sources](../sources.md). 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.9` else `normalise(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}`. - `Stream` enum 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`) - `photons` finite, `>= 0`, `<= 2^53`. - Frame is sky, T or C (not ground, not any other code). - Spectrum: Fixed `value` positive-within-limits; UniformRange `0 < low <= high` both positive-within-limits; InverseSquare `low < high` strictly, both positive-within-limits; Tabulated non-empty with `lower` positive-within-limits and `upper` within limits. - Pulse: Fixed within limits; UniformRange `low <= high` within limits; Gaussian mean and `sigma >= 0` finite within limits; Exponential mean and `tau >= 0`; ComplexPulse all three widths `>= 0` and finite within limits and `delay` within limits (an infinite width is an error); Tabulated non-empty, `lower`/`upper` within limits. - Star: no target; `towards_source` finite, `|norm - 1| <= 1e-9`, `z > 0`; distance `+inf` (plane wave) or positive-within-limits (so 1e200 is an error); `disk_radius_m` positive-within-limits; `disk_z_m`, `start_z_m` within limits. - Emitter: `position` within limits; `pointing` finite, unit to 1e-9; angular: FixedAngle `0 <= u0 <= 2`; FilledCone `0 < u0 <= 2`; TabulatedAngular non-empty with `lower >= 0` and `upper <= 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.