API reference: primary beams

PrimaryBeam

Abstract supertype of the analytic primary-beam models (GaussianBeam, AiryBeam, PolynomialBeam). Every subtype implements power_response(beam, θ, freq).

GaussianBeam(hpbw, reffreq)
GaussianBeam(freq; diameter, k=1.02)

A circular Gaussian power pattern, exp(-4ln2·(θ/HPBW)²), HPBW the half-power beam width (rad) at reffreq (Hz) — scales as 1/freq at other frequencies. The second form derives HPBW = k·λ/diameter (k≈1.02 is the standard illuminated-aperture factor; k=1.22 is the diffraction-limited/Airy value). hpbw/reffreq/freq/diameter/k must all be finite and positive.

AiryBeam(diameter; blockage=0.0)

The diffraction pattern of a uniformly illuminated circular aperture of diameter metres (an optional central obstruction of blockage metres — the sub-reflector shadow — modelled as a second, negated Airy term, the standard closed form for an annular aperture): voltage(x) = [2·J₁(x)/x − ε²·2·J₁(εx)/(εx)] / (1−ε²), x = π·diameter·θ/λ, ε = blockage/diameter. diameter must be finite and positive; blockage must be finite, 0 ≤ blockage < diameter (blockage == diameter makes ε == 1, a 0/0 singularity in the annular-aperture formula above; blockage > diameter is unphysical).

PolynomialBeam(coeffs, maxrad, reffreq)

A polynomial primary-beam fit in the CASA PBMath1DPoly convention: pb(x) = 1 + Σₖ coeffs[k]·x^(2k), x = (freq/1e9)·rad2deg(θ)*60 (GHz · arcmin), valid for θ ≤ maxrad (rad) — 0 beyond that radius. No coefficients are bundled; provide a real telescope's fitted table (e.g. from CASA's own data) or use GaussianBeam / AiryBeam instead. maxrad/reffreq must be finite and positive; every entry of coeffs must be finite.

EllipticalGaussianBeam(hpbw_major, hpbw_minor, pa, reffreq)

A Gaussian power pattern elongated along position angle pa (rad, from north through east — the MDirection convention): half-power widths hpbw_major ≥ hpbw_minor (rad) at reffreq (Hz, scaling as 1/freq, like GaussianBeam). power_response needs a 2-D (dlon, dlat) offset, not a scalar θ — see pointing_offset. hpbw_major/hpbw_minor/reffreq must be finite and positive, with hpbw_major ≥ hpbw_minor; pa must be finite.

SquintBeam(base::PrimaryBeam, squint)

Wraps base, offsetting its effective centre by squint = (dlon, dlat) (rad) — models feed/beam squint (e.g. a circularly-polarized feed's polarization-dependent pointing offset). Needs a 2-D offset (a scalar θ is ambiguous once the beam isn't centred on the boresight). Both components of squint must be finite (no sign/magnitude restriction — a squint offset can point anywhere).

power_response(beam::PrimaryBeam, θ, freq=reffreq(beam)) -> Float64

The primary-beam power response (0–1) at angular offset θ (rad, from the pointing centre) and frequency freq (Hz).

voltage_response(beam, θ, freq=reffreq(beam)) -> Float64

sqrt(power_response(beam, θ, freq)) — the voltage (amplitude) pattern. θ is a scalar offset (rad) or a (dlon, dlat) tangent-plane pair (see pointing_offset — required for EllipticalGaussianBeam / SquintBeam).

attenuate(beam, flux, θ, freq=reffreq(beam)) -> Float64

flux * power_response(beam, θ, freq) — the apparent flux of a source of true flux flux seen through the beam at offset θ (scalar or (dlon, dlat), see voltage_response).

correct_flux(beam, apparent_flux, θ, freq=reffreq(beam)) -> Float64

The primary-beam correction: apparent_flux / power_response(beam, θ, freq) (θ scalar or (dlon, dlat), see voltage_response).

angular_separation(d1::MDirection, d2::MDirection) -> Float64

The great-circle angle (rad) between two directions in the same reference frame — measconvert one first if they differ. Use as the θ argument to power_response / voltage_response.

pointing_offset(pointing::MDirection, target::MDirection) -> (dlon, dlat)

The 2-D tangent-plane offset (rad) of target from pointing — a small-angle projection, dlon = (target.lon−pointing.lon)·cos(pointing.lat), dlat = target.lat−pointing.lat. Both directions must be in the same reference frame. Use as the offset argument to EllipticalGaussianBeam / SquintBeam — a beam that needs the offset direction, not just its magnitude.

reffreq(beam::PrimaryBeam) -> Float64

The reference frequency (Hz) a beam's parameters (FWHM, diameter) were specified at.