so3g · sotodlib · design note

Instrument-centred pointing for sidelobe masks

Branch chervias/instrument_centered_coordinates in both repositories · uncommitted at the time of writing

This note describes how instrument-centred coordinates were added to the so3g projection engine and to sotodlib's P.for_tod, and how sidelobe cuts for the Moon and Sun now use them. It goes through the quaternion chain, the one change needed in the C++ kernel, how roll and polarization angle are handled, the conventions of the resulting maps, and what has been checked on real LAT data.

Why a different frame

The previous sidelobe code (coords/sidelobes.py) used object-centred coordinates. A fixed rotation, evaluated at mid-observation, moved the Moon to (0,0) with the zenith "up". Each detector's pointing was then expressed in that frame. That answers the question "where was the telescope looking when it saw the object?"

Instrument-centred coordinates answer the question we actually care about: "where was the object, relative to the detector, when it was seen?" A sidelobe is a feature of the instrument. In a frame attached to the instrument it stays in one place, while in the object-centred frame it is smeared by the changing orientation of the instrument relative to the object. The extreme case is the Moon at the zenith with a thin vertical sidelobe. Every azimuth of a constant-elevation scan sees the Moon through that sidelobe, so the object-centred map shows a ring (and a disk after several elevations) instead of a line.

The quaternion chain

so3g quaternions are in (1, i, j, k) order. A rotation qB<A takes coordinates in frame A to frame B, and products chain as qC<A = qC<B qB<A. A pointing is where the local ẑ axis ends up. For the usual celestial projection the kernel evaluates, per detector d and sample t:

q[d,t] = qNS<CS · qbore[t] · qdet[d]

Here qbore is CelestialSightLine.Q, which for real data is qpoint.azel2bore(az, el, …) · Rz(π + roll), and qdet = rotation_xieta(ξ, η, γ). The object-centred version adds a constant qmoon⁻¹ on the left, which keeps the same form.

For instrument-centred coordinates the roles of detector and object swap. We want the object seen from each detector:

q[d,t] = qto_eq · qdet[d]⁻¹ · qbore[t]⁻¹ · qsrc[t]

Read right to left:

Only the product qbore⁻¹ · qsrc enters. If both are expressed in celestial coordinates through a common horizon-to-celestial rotation H, then (H qb)⁻¹ (H qs) = qb⁻¹ qs, so H cancels exactly. The implementation therefore reuses the standard, full-precision CelestialSightLine.az_el boresight together with the source's RA/Dec, and never forms horizon quaternions itself.

Why the kernel had to change

Every so3g projection routine is built around one product, computed inside the C++ loop for each (detector, sample):

quatd qdet = (*qbore) * (*qofs);   // q_bore[t] · q_ofs[d]

The per-detector factor is always on the right. In the instrument-centred chain the per-detector factor qdet⁻¹ is left of the per-sample one, so the chain doesn't fit f(t) · qdet. Nothing is more expensive; the ordering just doesn't match what the engine does.

After grouping, the chain always has the form A[d] · X[t]. Two ways to fit that into so3g were considered:

  1. Transpose the problem. Pass A[d] as the "boresight" and X[t] as the "focal plane". This needs no C++ change, but every output comes back as [nsamp, ndet]. Signal, cuts, thread ranges and responsivities would all have to be transposed to match. Rejected.
  2. Let the kernel multiply in either order. Add a flag so the product is qofs[d] · qbore[t]. The data layout stays [ndet, nsamp], and every existing feature (all projections, tiling, bilinear interpolation, HEALPix, threads, cuts, weights) works unchanged. This is what was implemented.
NORMAL (det_left = False) q_bore[t] (nsamp) · q_ofs[d] (ndet) celestial / object-centred INSTRUMENT-CENTRED (det_left = True) q_ofs[d] = A[d] q_to_eq·Rz(r0)·q_det⁻¹·Rz(−r0) · q_bore[t] = X[t] Rz(roll)·q_bore⁻¹·q_src same buffers, same layout, only the product order flips

Orange: per-detector quaternions (the FocalPlane). Teal: per-sample quaternions (the CelestialSightLine). With det_left the engine receives the same two buffers and only reverses the multiplication.

so3g changes

C++ (src/Projection.cxx, include/Projection.h)

Python (python/proj/)

sotodlib: P.for_tod(..., instrument_centered=…)

P gained a det_left attribute, passed to Assembly.attach in _get_asm. P.for_tod has a new keyword instrument_centered. When it is set to a source name ('moon', 'sun', any name planets.get_source_pos accepts), for_tod:

  1. checks that comps == 'T', that geom is given, that rot is None, and that boresight_equ isn't used, raising ValueError otherwise. Roll is needed, so the boresight must be az/el/roll.
  2. builds the boresight with the standard CelestialSightLine.az_el (same site, weather and qpoint options as usual), or uses a sight= passed in;
  3. gets the focal plane with helpers.get_fplane (for ξ, η and the responsivities);
  4. calls the new get_instrument_centered(sight, fp, roll, source, timestamps, site), and returns a P with det_left=True.

get_instrument_centered builds the two factors:

X[t] = Rz(roll[t]) · qbore[t]⁻¹ · qsrc[t]stored as sight.Q A[d] = Ry(π/2) · Rz(roll₀) · rotation_xieta(ξd, ηd, 0)⁻¹ · Rz(−roll₀)stored as fp.quats

roll₀ is the circular mean of the roll. A warning is logged if the roll strays more than 0.1° from it. The responsivities are copied from the original focal plane.

The source position comes from the new planets.get_source_quat(name, timestamps, site, dt=600). It evaluates get_source_pos (skyfield, topocentric for the given site) on a grid with at most 600 s spacing, unwraps RA, interpolates linearly to every sample, and returns rotation_lonlat(ra, dec). For the Moon the linear-interpolation error at 600 s is well below an arcsecond. A one-hour observation needs only about seven ephemeris evaluations.

Roll and polarization angle

Roll: making the frame telescope-fixed

The boresight quaternion factors as qbore = qtel · Rz(roll). Here qtel is the orientation of the telescope structure (qpoint's az/el part, together with so3g's fixed Rz(π)) and Rz(roll) turns the focal plane relative to it. The chain without any roll handling gives a frame that rotates with the focal plane. The sidelobes don't rotate with roll, so the roll is removed as proposed: qto_eq is replaced by qto_eq · Rz(roll). Substituting qbore shows what that does:

qto_eq · Rz(roll) · qdet⁻¹ · Rz(−roll) · qtel⁻¹ · qsrc = qto_eq · [ Rz(roll) · qdet · Rz(−roll) ]⁻¹ · qtel⁻¹ · qsrc

So the roll correction amounts to conjugating each detector quaternion by the roll. Rz(roll)·qdet moves the detector's (ξ, η) into telescope-structure coordinates. The trailing Rz(−roll) aligns the detector frame's local axes with the telescope axes instead of the rotated focal-plane axes. The result is the source relative to each detector, on axes fixed to the telescope structure.

For this to be a per-detector constant, the conjugation uses the mean roll roll₀, while X[t] keeps the exact per-sample Rz(roll[t]). With constant roll (a SAT at fixed boresight rotation, or a LAT constant-elevation scan with the corotator fixed) the result is exact. If roll varies, only the rotation of the small detector offsets is approximated; the telescope-frame position of the source stays exact.

Polarization angle: γ = 0

rotation_xieta(ξ, η, γ) = Rz(φ)·Ry(θ)·Rz(γ−φ) has its local axes rotated by the polarization angle γ. In the normal chain that is the point: the resulting ψ is the polarization angle on the sky. With qdet⁻¹ on the left, though, the final Rz(φ−γ) would rotate each detector's whole map about the detector by −γ. Detectors with different γ would then disagree on where the sidelobe is. The detector quaternions are therefore rebuilt with γ = 0 from the decomposed ξ, η, and the mode only allows comps='T'. The HWP sign flip on γ doesn't matter here for the same reason.

Map conventions

Sidelobe cuts (coords/sidelobes.py)

The masks are no longer fixed files per object. They come with the observation metadata, so each tube or wafer gets its own. The existing Enmap metadata loader wraps the map in an AxisManager as aman.sidelobes.map, a pixell enmap of shape [nfields, ny, nx], with a fields LabelAxis naming each plane, e.g. ['moon', 'sun']. Each plane is a 0/1 mask in the instrument-centred coordinates of that object.

get_cuts(aman, sidelobes="sidelobes", object_list=None, rise_tol=1°):

For each object, make_cuts:

  1. looks up the object's elevation with planets.get_source_azel at the first, middle and last sample, and returns empty cuts if it is below rise_tol at all three;
  2. builds P.for_tod(aman, comps='T', geom=mask geometry, instrument_centered=name, threads=False);
  3. replaces the focal plane's responsivities with 1, so the mask value reaches the timestream unchanged whatever the detector's T response (the earlier astype(int) could round a 1 down to 0 for T < 1);
  4. reads the mask into the timestream with from_map (nearest neighbour) and cuts every sample where it is non-zero: RangesMatrix.from_mask(tod != 0).

In site_pipeline/make_ml_map.py the call is now sidelobes.get_cuts(obs), on the fully loaded observation before downsampling, and the result is added to glitch_flags as before. The --sun-mask and --moon-mask options are no longer used.

Validation

Unit tests (added)

Real LAT observation

A single-wafer LAT observation, 35.4 min long, with commanded az 110.7°–167.8°, commanded el 120° (past the zenith) and roll 60.00° (constant to 0.001°). The Moon moved from az 0.9°, el 48.8° to az 348.5°, el 48.0°.

Spread across detectors at a fixed time should match the wafer size:

SampleSpread in lonSpread in latMedian (lon, lat)
00.61°0.42°(+36.37°, −10.05°)
106 2640.60°0.51°(+15.33°, +6.61°)
212 5280.60°0.52°(+7.04°, +9.28°)
318 7920.60°0.53°(+1.60°, +10.30°)
425 0570.60°0.52°(+6.27°, +10.09°)

The spread is constant and about the size of a wafer. The large motion of the median follows the scan and the Moon, including the axis flip past the zenith: near the Moon lat ≈ +10°, where spherical trigonometry predicts about +11° for the boresight.

Exact orientation check for the boresight. A single detector with A = Ry(π/2) sits exactly at the boresight. For it, sin(lat) must equal the Moon's direction projected on the telescope's elevation axis, m·ûel, and cos(lat)·sin(lon) must equal −m·ûaz, using the commanded boresight az/el and skyfield's apparent Moon az/el:

Samplesin(lat)m·ûelcos(lat)·sin(lon)−m·ûaz
0−0.1575−0.1574+0.6077+0.6077
60 722−0.0015−0.0014+0.4962+0.4962
121 444−0.0771−0.0771+0.5617+0.5616
182 167−0.1247−0.1246+0.5936+0.5935
242 889−0.0142−0.0141+0.5148+0.5147
303 612+0.0798+0.0799+0.4084+0.4084
364 334+0.1511+0.1512+0.2805+0.2804
425 057+0.1963+0.1964+0.1372+0.1371

They agree to about 1e-4 across the whole scan, at el = 120° and roll = 60°. The residual matches refraction, which is included in the az_el boresight but not in skyfield's az/el. This confirms the full chain through the reversed kernel product, the axis convention and the roll handling: a wrong roll sign would have shown up as a disagreement of about 60°.

Pipeline: make_ml_map.py with the metadata masks has been run on observations known to have Moon and Sun sidelobe pickup, and appears to work.

Limitations and open points

Files touched

Minimal usage:

from sotodlib import coords

# Pointing matrix in Moon instrument-centred coordinates
P = coords.pmat.P.for_tod(obs, comps='T', geom=(shape, wcs), instrument_centered='moon')
tod = P.from_map(mask)                       # mask: enmap [1, ny, nx]

# Cuts from the per-wafer masks in obs.sidelobes
cuts_moon, cuts_sun = coords.sidelobes.get_cuts(obs)   # order of obs.sidelobes.fields