From a829445fb5a574ed421dbc99a6c6db7c1f55f8f9 Mon Sep 17 00:00:00 2001
From: Michael McCrackan <mmccrack@login29.chn.perlmutter.nersc.gov>
Date: Tue, 17 Mar 2026 08:31:46 -0700
Subject: [PATCH 1/7] det_match updates

---
 sotodlib/coords/det_match.py | 56 +++++++++++++++++++++++++++++-------
 1 file changed, 45 insertions(+), 11 deletions(-)

diff --git a/sotodlib/coords/det_match.py b/sotodlib/coords/det_match.py
index 90107e92b..a6908e48f 100644
--- a/sotodlib/coords/det_match.py
+++ b/sotodlib/coords/det_match.py
@@ -196,6 +196,7 @@ def apply_design_properties(smurf_res, design_res, in_place=False, apply_pointin
         'mux_bondpad', 'mux_subband', 'mux_band', 'mux_channel',
         'mux_layout_pos'
     ]
+
     if apply_pointing:
         design_props += ['xi', 'eta', 'gamma']
 
@@ -613,10 +614,11 @@ class MatchParams:
     unassigned_slots: int = 1000
     freq_offset_mhz: float = 0.0
     freq_width: float = 2.
-    dist_width: float =0.01
+    dist_width: float = 0.01
     unmatched_good_res_pen: float = 10.
     good_res_qi_thresh: float = 100e3
     enforce_pointing_reqs: bool = False
+    allow_unassigned_to_assigned: bool = True
 
     assigned_bg_unmatched_pen: float = 100000
     unassigned_bg_unmatched_pen: float = 10000
@@ -706,6 +708,11 @@ def _get_biadjacency_matrix(self) -> np.ndarray:
         m = src_arr['is_north'][:, None] != dst_arr['is_north'][None, :]
         mat[m] = np.inf
 
+        src_no_match = np.isin(src_arr['det_type'], ['NC'])
+        dst_no_match = np.isin(dst_arr['det_type'], ['NC'])
+        mat[src_no_match, :] = np.inf
+        mat[:, dst_no_match] = np.inf
+
         if self.match_pars.enforce_pointing_reqs:
             # Det types of DARK and SLOT are allowed to may or may not have
             # pointing data. For these types of detectors, the cost is left
@@ -714,11 +721,6 @@ def _get_biadjacency_matrix(self) -> np.ndarray:
             src_has_pointing = np.isfinite(src_arr['xi']) & np.isfinite(src_arr['eta'])
             dst_has_pointing = np.isfinite(dst_arr['xi']) & np.isfinite(dst_arr['eta'])
 
-            src_no_match = np.isin(src_arr['det_type'], ['NC'])
-            dst_no_match = np.isin(dst_arr['det_type'], ['NC'])
-            mat[src_no_match, :] = np.inf
-            mat[:, dst_no_match] = np.inf
-
             src_pointing_forbidden = np.isin(src_arr['det_type'], ['UNRT', 'SQID', 'BARE'])
             dst_pointing_forbidden = np.isin(dst_arr['det_type'], ['UNRT', 'SQID', 'BARE'])
             m = src_pointing_forbidden[:, None] & dst_has_pointing[None, :]
@@ -733,19 +735,51 @@ def _get_biadjacency_matrix(self) -> np.ndarray:
             m = (~src_has_pointing[:, None]) & dst_pointing_required[None, :]
             mat[m] = np.inf
 
+        # These should always have BG = -1
+        src_unassigned_type = np.isin(src_arr['det_type'], ['UNRT', 'SQID', 'BARE'])
+        dst_unassigned_type = np.isin(dst_arr['det_type'], ['UNRT', 'SQID', 'BARE'])
+        # pointing or tuneset have unassigned type (shouldn't ever happen)
+        m = src_unassigned_type[:, None] & (dst_arr['bg'][None, :] !=-1)
+        mat[m] = np.inf
+        # Design or pointing have unassigned type (should happen)
+        m = dst_unassigned_type[None, :] & (src_arr['bg'][:, None] !=-1)
+        mat[m] = np.inf
+
         # Frequency offset
         df = src_arr['res_freq'][:, None] - dst_arr['res_freq'][None, :]
         df -= self.match_pars.freq_offset_mhz
         mat += np.exp((np.abs(df / self.match_pars.freq_width)) ** 2)
 
         # BG mismatch
-        bgs_mismatch = src_arr['bg'][:, None] != dst_arr['bg'][None, :]
-        bgs_unassigned = (src_arr['bg'][:, None] == -1) | (dst_arr['bg'][None, :] == -1)
+        # bgs_mismatch = src_arr['bg'][:, None] != dst_arr['bg'][None, :]
+        # bgs_unassigned = (src_arr['bg'][:, None] == -1) | (dst_arr['bg'][None, :] == -1)
+
+        # m = bgs_mismatch & bgs_unassigned
+        # mat[m] += self.match_pars.unassigned_bg_mismatch_pen
+        # m = bgs_mismatch & (~bgs_unassigned)
+        # mat[m] += self.match_pars.assigned_bg_mismatch_pen
+
+        # design or pointing unassigned
+        dst_unassigned = (dst_arr['bg'][None, :] == -1)
+        # pointing or tune unassigned
+        src_unassigned = (src_arr['bg'][:, None] == -1)
+
+        # whether or not to match unassigned bg to assigned bgs
+        # don't want matches when matching from design to pointing
+        m = dst_unassigned & (~src_unassigned)
+        if not self.match_pars.allow_unassigned_to_assigned:
+            mat[m] = np.inf
+        else:
+            mat[m] += self.match_pars.unassigned_bg_mismatch_pen
 
-        m = bgs_mismatch & bgs_unassigned
+        # match assigned bg to unassigned bg
+        m = (~dst_unassigned) & src_unassigned
         mat[m] += self.match_pars.unassigned_bg_mismatch_pen
-        m = bgs_mismatch & (~bgs_unassigned)
-        mat[m] += self.match_pars.assigned_bg_mismatch_pen
+
+        # assigned bgs must not be mismatched
+        bgs_mismatch = src_arr['bg'][:, None] != dst_arr['bg'][None, :]
+        m = bgs_mismatch & (~dst_unassigned) & (~src_unassigned)
+        mat[m] = np.inf
 
         # If pointing, add cost if assigned too far
         dd = np.sqrt(

From 5bb46011bcd9556fba23390c7d59d2763f06598b Mon Sep 17 00:00:00 2001
From: Michael McCrackan <mmccrack@login29.chn.perlmutter.nersc.gov>
Date: Fri, 17 Apr 2026 12:56:57 -0700
Subject: [PATCH 2/7] more updates

---
 sotodlib/coords/det_match.py               | 108 ++++++++++++++-------
 sotodlib/site_pipeline/update_det_match.py |  36 +++++--
 2 files changed, 100 insertions(+), 44 deletions(-)

diff --git a/sotodlib/coords/det_match.py b/sotodlib/coords/det_match.py
index a6908e48f..0a3107e07 100644
--- a/sotodlib/coords/det_match.py
+++ b/sotodlib/coords/det_match.py
@@ -1,6 +1,6 @@
 import warnings
 from dataclasses import dataclass, fields, asdict, field
-from typing import List, Optional, Tuple, Iterator, Union
+from typing import List, Optional, Tuple, Iterator, Union, get_origin, get_args
 from copy import deepcopy
 import h5py
 
@@ -147,10 +147,10 @@ class Resonator:
     bg: int = -1
     det_x: float = np.nan
     det_y: float = np.nan
-    det_row: int = 0
-    det_col: int = 0
+    det_row: Optional[int] = None
+    det_col: Optional[int] = None
     pixel_num: int = 0
-    det_rhomb: str = ''
+    det_rhomb: Optional[str] = None
     det_pol: str = ''
     det_freq: int = 0
     det_bandpass: str = ''
@@ -190,13 +190,18 @@ def apply_design_properties(smurf_res, design_res, in_place=False, apply_pointin
         r = deepcopy(smurf_res)
 
     design_props = [
-        'bg', 'det_x', 'det_y', 'det_row', 'det_col', 'pixel_num', 'det_rhomb',
+        'bg', 'det_x', 'det_y', 'pixel_num',
         'det_pol', 'det_freq', 'det_bandpass', 'det_angle_raw_deg',
         'det_angle_actual_deg', 'det_type', 'det_id', 'is_optical',
         'mux_bondpad', 'mux_subband', 'mux_band', 'mux_channel',
         'mux_layout_pos'
     ]
 
+    # for LF
+    for attr in ('det_row', 'det_col', 'det_rhomb'):
+        if getattr(design_res, attr, None) is not None:
+            design_props.append(attr)
+
     if apply_pointing:
         design_props += ['xi', 'eta', 'gamma']
 
@@ -268,6 +273,8 @@ def as_array(self):
         dtype = []
         data = []
         for field in fields(Resonator):
+            if get_origin(field.type) is Union and type(None) in get_args(field.type):
+                continue
             if field.type == str:
                 typ = '<U50'
             else:
@@ -400,11 +407,16 @@ def from_wafer_info_file(cls, wafer_info_file, array_name, name=None,
         with h5py.File(wafer_info_file) as f:
             wafer_array = np.array(f[array_name])
 
+        # LF does not have det_row, det_col, or rhombus
+        has_det_row = 'dets:wafer.det_row' in wafer_array.dtype.names
+        has_det_col = 'dets:wafer.det_col' in wafer_array.dtype.names
+        has_rhomb = 'dets:wafer.rhombus' in wafer_array.dtype.names
+
         resonators = []
         idx = 0
         for r in wafer_array:
             is_north = r['dets:wafer.coax'] == b'N'
-            res = Resonator(
+            kwargs = dict(
                 idx=idx,
                 det_id=r['dets:det_id'].decode(),
                 mux_bondpad=r['dets:wafer.bond_pad'],
@@ -416,9 +428,6 @@ def from_wafer_info_file(cls, wafer_info_file, array_name, name=None,
                 bg=r['dets:wafer.bias_line'],
                 det_pol=r['dets:wafer.pol'],
                 det_bandpass=r['dets:wafer.bandpass'],
-                det_row=r['dets:wafer.det_row'],
-                det_col=r['dets:wafer.det_col'],
-                det_rhomb=r['dets:wafer.rhombus'],
                 det_type=r['dets:wafer.type'],
                 det_x=r['dets:wafer.x'],
                 det_y=r['dets:wafer.y'],
@@ -426,6 +435,18 @@ def from_wafer_info_file(cls, wafer_info_file, array_name, name=None,
                 is_north=is_north
             )
 
+            optional_fields = {
+                "det_row": (has_det_row, 'dets:wafer.det_row'),
+                "det_col": (has_det_col, 'dets:wafer.det_col'),
+                "rhombus": (has_rhomb, 'dets:wafer.rhombus'),
+            }
+
+            for key, (found, val) in optional_fields.items():
+                if found and field in r.dtype.names:
+                    kwargs[key] = val
+
+            res = Resonator(**kwargs)
+
             if pt_cfg is not None:
                 res.xi, res.eta, res.gamma = pt_cfg.get_pointing(res.det_x, res.det_y)
 
@@ -470,7 +491,7 @@ def from_solutions(cls, sol_file, north_is_highband=True, name=None,
             for i in range(len(labels)):
                 labels[i] = labels[i].strip()
 
-            #Helper needed for when sol file has saved ints as floats
+            # Helper needed for when sol file has saved ints as floats
             def _int(val, null_val=None): 
                 is_null = (val == 'null' or val == '')
                 if is_null and null_val is not None:
@@ -486,23 +507,41 @@ def _int(val, null_val=None):
                 # is_north = d['is_north'].lower().strip() == 'true'
                 is_north = _int(d['bias_line']) < 6
                 is_optical = (d['is_optical'].lower() == 'true')
-                r = Resonator(
-                    i, res_freq=float(d['freq_mhz']), smurf_band=_int(d['smurf_band']),
-                    bg=_int(d['bias_line']), det_x=float(d['det_x']),
-                    det_y=float(d['det_y']), det_rhomb=d['rhomb'],
-                    det_row=_int(d['det_row']), det_col=_int(d['det_col']),
+
+                kwargs = dict(
+                    i=i,
+                    res_freq=float(d['freq_mhz']),
+                    smurf_band=_int(d['smurf_band']),
+                    bg=_int(d['bias_line']),
+                    det_x=float(d['det_x']),
+                    det_y=float(d['det_y']),
                     pixel_num=_int(d['pixel_num'], null_val=-1),
-                    det_type=d['det_type'], det_id=d['detector_id'].strip(),
-                    mux_band=_int(d['mux_band']), mux_channel=_int(d['mux_channel']),
-                    mux_subband=d['mux_subband'], mux_bondpad=d['bond_pad'],
+                    det_type=d['det_type'],
+                    det_id=d['detector_id'].strip(),
+                    mux_band=_int(d['mux_band']),
+                    mux_channel=_int(d['mux_channel']),
+                    mux_subband=d['mux_subband'],
+                    mux_bondpad=d['bond_pad'],
                     det_angle_raw_deg=float(d['angle_raw_deg']),
                     det_angle_actual_deg=float(d['angle_actual_deg']),
                     mux_layout_pos=_int(d['mux_layout_position']),
-                    det_bandpass=d['bandpass'], det_pol=d['pol'],
+                    det_bandpass=d['bandpass'],
+                    det_pol=d['pol'],
                     is_optical=is_optical,
                     is_north=is_north
                 )
 
+                optional_fields = {
+                    "det_row": ('det_row', _int),
+                    "det_col": ('det_col', _int),
+                    "det_rhomb": ('rhomb', lambda x: x),
+                }
+
+                for key, (src_key, fn) in optional_fields.items():
+                    if src_key in d and d[src_key] not in (None, ''):
+                        kwargs[key] = fn(d[src_key])
+                r = Resonator(**kwargs)
+
                 if _int(d['smurf_channel']) != -1:
                     r.smurf_channel = _int(d['smurf_channel'])
 
@@ -699,8 +738,8 @@ def __init__(self, src: ResSet, dst: ResSet, match_pars: Optional[MatchParams]=N
         self.stats = self.get_stats()
 
     def _get_biadjacency_matrix(self) -> np.ndarray:
-        src_arr = self.src.as_array()
-        dst_arr = self.dst.as_array()
+        src_arr = self.src.as_array() # pointing or tuneset
+        dst_arr = self.dst.as_array() # design or pointing
 
         mat = np.zeros((len(self.src), len(self.dst)), dtype=float)
 
@@ -721,6 +760,7 @@ def _get_biadjacency_matrix(self) -> np.ndarray:
             src_has_pointing = np.isfinite(src_arr['xi']) & np.isfinite(src_arr['eta'])
             dst_has_pointing = np.isfinite(dst_arr['xi']) & np.isfinite(dst_arr['eta'])
 
+            # UNRT, SQID, and BARE must not have pointing
             src_pointing_forbidden = np.isin(src_arr['det_type'], ['UNRT', 'SQID', 'BARE'])
             dst_pointing_forbidden = np.isin(dst_arr['det_type'], ['UNRT', 'SQID', 'BARE'])
             m = src_pointing_forbidden[:, None] & dst_has_pointing[None, :]
@@ -728,6 +768,7 @@ def _get_biadjacency_matrix(self) -> np.ndarray:
             m = src_has_pointing[:, None] & dst_pointing_forbidden[None, :]
             mat[m] = np.inf
 
+            # OPTC must have pointing
             src_pointing_required = np.isin(src_arr['det_type'], ['OPTC'])
             dst_pointing_required = np.isin(dst_arr['det_type'], ['OPTC'])
             m = src_pointing_required[:, None] & (~dst_has_pointing[None, :])
@@ -738,10 +779,12 @@ def _get_biadjacency_matrix(self) -> np.ndarray:
         # These should always have BG = -1
         src_unassigned_type = np.isin(src_arr['det_type'], ['UNRT', 'SQID', 'BARE'])
         dst_unassigned_type = np.isin(dst_arr['det_type'], ['UNRT', 'SQID', 'BARE'])
-        # pointing or tuneset have unassigned type (shouldn't ever happen)
+        # pointing or tuneset have unassigned type (shouldn't ever happen since
+        # they won't have det_types yet)
         m = src_unassigned_type[:, None] & (dst_arr['bg'][None, :] !=-1)
         mat[m] = np.inf
-        # Design or pointing have unassigned type (should happen)
+        # Design or pointing have unassigned type (should happen since dst
+        # will have det_types)
         m = dst_unassigned_type[None, :] & (src_arr['bg'][:, None] !=-1)
         mat[m] = np.inf
 
@@ -750,21 +793,12 @@ def _get_biadjacency_matrix(self) -> np.ndarray:
         df -= self.match_pars.freq_offset_mhz
         mat += np.exp((np.abs(df / self.match_pars.freq_width)) ** 2)
 
-        # BG mismatch
-        # bgs_mismatch = src_arr['bg'][:, None] != dst_arr['bg'][None, :]
-        # bgs_unassigned = (src_arr['bg'][:, None] == -1) | (dst_arr['bg'][None, :] == -1)
-
-        # m = bgs_mismatch & bgs_unassigned
-        # mat[m] += self.match_pars.unassigned_bg_mismatch_pen
-        # m = bgs_mismatch & (~bgs_unassigned)
-        # mat[m] += self.match_pars.assigned_bg_mismatch_pen
-
-        # design or pointing unassigned
+        # Design or pointing unassigned
         dst_unassigned = (dst_arr['bg'][None, :] == -1)
         # pointing or tune unassigned
         src_unassigned = (src_arr['bg'][:, None] == -1)
 
-        # whether or not to match unassigned bg to assigned bgs
+        # Whether or not to match unassigned bg to assigned bgs
         # don't want matches when matching from design to pointing
         m = dst_unassigned & (~src_unassigned)
         if not self.match_pars.allow_unassigned_to_assigned:
@@ -772,11 +806,11 @@ def _get_biadjacency_matrix(self) -> np.ndarray:
         else:
             mat[m] += self.match_pars.unassigned_bg_mismatch_pen
 
-        # match assigned bg to unassigned bg
+        # Match assigned bg to unassigned bg
         m = (~dst_unassigned) & src_unassigned
         mat[m] += self.match_pars.unassigned_bg_mismatch_pen
 
-        # assigned bgs must not be mismatched
+        # Assigned bgs must not be mismatched
         bgs_mismatch = src_arr['bg'][:, None] != dst_arr['bg'][None, :]
         m = bgs_mismatch & (~dst_unassigned) & (~src_unassigned)
         mat[m] = np.inf
@@ -835,9 +869,11 @@ def _match(self):
         for r1, r2 in self.get_match_iter(include_unmatched=True):
             if r1 is None:
                 r2.matched = 0
+                r2.match_idx = -1
                 continue
             if r2 is None:
                 r1.matched = 0
+                r1.match_idx = -1
                 continue
 
             r1.matched = 1
diff --git a/sotodlib/site_pipeline/update_det_match.py b/sotodlib/site_pipeline/update_det_match.py
index 08fca4ef9..d7af70733 100644
--- a/sotodlib/site_pipeline/update_det_match.py
+++ b/sotodlib/site_pipeline/update_det_match.py
@@ -25,6 +25,14 @@
 logger.setLevel(logging.INFO)
 
 
+def get_detset_time(detset: str) -> float:
+    """
+    Gets timestamp associated with a detset. Will parse this from the detset
+    name, assuming it is of the form <stream_id>_<time>_tune.
+    """
+    return float(detset.split('_')[-2])
+
+
 @dataclass
 class UpdateDetMatchesConfig:
     """
@@ -56,6 +64,9 @@ class UpdateDetMatchesConfig:
         Name of the metadata entry in the context that contains detset info.
     detcal_meta_name: str
         Name of the metadata entry in the context that contains det_cal info.
+    ufms: Optional[List[str]]
+        List of ufm names to run update_det_match on.  Will run on all ufms
+        for which detsets exist if None.
     show_pb: bool
         Will show progress bar when scanning freq-offset.
     apply_solution_pointing: bool
@@ -95,12 +106,15 @@ class UpdateDetMatchesConfig:
     match_pars: Optional[Dict] = None
     detset_meta_name : str = 'smurf'
     detcal_meta_name: str = 'det_cal'
+    ufms: Optional[List[str]] = None
     show_pb: bool = False
     apply_solution_pointing: bool = True
     write_relpath: bool = True
     solution_type: str = 'kaiwen_handmade'
     resonator_set_dir: Optional[str] = None
     time_before_cache_failure: float = float(3600 * 24 * 7)
+    start_time: int = 0
+    stop_time: int = 2**32
 
     def __post_init__(self):
         if self.site_pipeline_root is None:
@@ -130,6 +144,9 @@ def __post_init__(self):
             if self.resonator_set_dir is None:
                 raise ValueError("Must specify resonator_set_dir for solution_type='resonator_set'")
 
+        if self.ufms is not None:
+            self.ufms = [u.lower() for u in self.ufms]
+
 
 class Runner:
     def __init__(self, cfg: UpdateDetMatchesConfig):
@@ -169,6 +186,11 @@ def __init__(self, cfg: UpdateDetMatchesConfig):
 
     def get_remaining_detsets(self) -> List[str]:
         detsets_all = set(self.detset_db.get_entries(['dataset'])['dataset'])
+        if self.cfg.ufms:
+            detsets_all = set([d for d in detsets_all if '_'.join(d.split('_')[:2]) in self.cfg.ufms])
+        ts = [get_detset_time(d) for d in detsets_all]
+        detsets_all = set([d for t, d in zip(ts, detsets_all) if t > self.cfg.start_time and t < self.cfg.stop_time])
+
         failed_detsets = set(get_failed_detsets(self.failed_detset_cache_path))
         finished_detsets = set([os.path.splitext(f)[0] for f in os.listdir(self.match_dir)])
         remaining_detsets = list(detsets_all - failed_detsets - finished_detsets)
@@ -196,13 +218,6 @@ def load_solution_set(runner: Runner, stream_id: str, wafer_slot=None):
         rs.name = 'sol'
         return rs
 
-def get_detset_time(detset: str) -> float:
-    """
-    Gets timestamp associated with a detset. Will parse this from the detset
-    name, assuming it is of the form <stream_id>_<time>_tune.
-    """
-    return float(detset.split('_')[-2])
-
 def add_to_failed_cache(cache_file, detset, msg, cfg: UpdateDetMatchesConfig):
     if time.time() - get_detset_time(detset) < cfg.time_before_cache_failure:
         logger.info(f"{detset} is too recent to add to failed cache")
@@ -287,7 +302,11 @@ def run_match(runner: Runner, detset: str) -> bool:
     finished_detsets = set([os.path.splitext(f)[0] for f in os.listdir(runner.match_dir)])
     new_detsets = []
     for detset in np.unique(aman.det_info.detset):
-        if detset not in finished_detsets:
+        if (
+            detset not in finished_detsets and
+            get_detset_time(detset) > runner.cfg.start_time and
+            get_detset_time(detset) < runner.cfg.stop_time
+        ):
             new_detsets.append(detset)
 
     logger.info(f"Loaded obs_id {obs_id}. Running matches for detsets:")
@@ -435,6 +454,7 @@ def main(config_file: str, all: bool=False):
     if all:
         update_manifests_all(runner)
         for detset in remaining_detsets:
+            logger.info(f"running: {detset}")
             run_match(runner, detset)
             update_manifests_all(runner)
     else:

From 1f31e281506edc61c2fc4db3898ad03cfa83fbff Mon Sep 17 00:00:00 2001
From: Michael McCrackan <mmccrack@login29.chn.perlmutter.nersc.gov>
Date: Fri, 17 Apr 2026 14:20:42 -0700
Subject: [PATCH 3/7] add solutions code

---
 sotodlib/coords/det_match_solutions.py | 556 +++++++++++++++++++++++++
 1 file changed, 556 insertions(+)
 create mode 100644 sotodlib/coords/det_match_solutions.py

diff --git a/sotodlib/coords/det_match_solutions.py b/sotodlib/coords/det_match_solutions.py
new file mode 100644
index 000000000..8895368e0
--- /dev/null
+++ b/sotodlib/coords/det_match_solutions.py
@@ -0,0 +1,556 @@
+from sotodlib.core import Context, AxisManager, LabelAxis
+from sotodlib.coords import det_match as dm
+from dataclasses import dataclass, field
+from typing import Optional, List, Dict, Tuple, Callable, Any
+from collections import defaultdict
+import os
+import numpy as np
+import yaml
+from copy import deepcopy
+from scipy import interpolate
+from tqdm.auto import tqdm, trange
+from copy import deepcopy
+
+import h5py
+
+from importlib import reload
+import yaml
+import sys
+
+
+@dataclass
+class SolutionsCfg:
+    """
+    Args
+    ------
+    ctx_path: str
+        Path to context file to use to pull tod metadata.
+    pointing_results_dir: str
+        Results to directory that contains pointing resutls from Tomoki's
+        workflow. Files in directory should look like:
+        ```
+        focal_plane_<obs_id>_<wafer_slot>.hdf
+        ```
+    site_pipeline_cfg_dir: str
+        Path to site-pipeline-config dir. Defaults to the env var
+        ``$SITE_PIPELINE_CONFIG_DIR``.
+    finite_xi_thresh: int
+        Minimum number of dets a pointing result must have to add it to the
+        analysis.
+    min_r2: float
+        Minimum R-squared for det pointing to be considered.
+    unassigned_slots: int:
+        Number of additional "unassigned" node to use per-side
+    wafer_info_path: str
+        Path to the wafer_info h5 file.
+    wafer_map_path: str
+        Path to the wafer map file. Defaults to ``<site-pipeline-config>/shared/detmatpping/wafer_map.yaml``.
+    Initial pointing offset: Tuple[float, float]
+        Estimated pointing offset for the boresight. This should be
+        (xi_offset, eta_offset) where both are in radians.
+    results_dir: str
+        Directory where results should be stored.
+    freq_correct_by_muxband: bool
+        If true, apply the same freq offset correction to all resonators in a mux-band.
+    tel_type: str
+        Tel type for the optics model. Either "SAT" or "LAT"
+    zemax_path: str
+        If running for a "LAT" tel_type, the path to the zemax file must be specified.
+    """
+
+    ctx_path: str
+    pointing_results_dir: str
+    results_dir: str
+    wafer_info_path: str
+    tel_type: str
+    base_obs_id: Optional[str] = None
+    zemax_path: Optional[str] = None
+    apply_roll: bool = True
+
+    ctx: Context = field(init=False)
+    pointing_field: str = "tod_pointing"
+    site_pipeline_cfg_dir: str = "$SITE_PIPELINE_CONFIG_DIR"
+    finite_xi_thresh: int = (
+        500  # Min number of dets with finite xi to consider a pointing input
+    )
+    min_r2: float = 0.9
+    unassigned_slots: int = 1200
+    wafer_map_path: Optional[str] = None
+    wafer_map: Dict[str, dict] = field(init=False)
+    match_pars: Dict[str, dict] = field(default_factory=lambda: defaultdict(dict))
+
+    initial_pointing_offset: Tuple[float, float] = (0, 0)
+    ufm_to_fp_path: Optional[str] = None
+    freq_correct_by_muxband: bool = True
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, Any]) -> "SolutionsCfg":
+        return cls(**d)
+
+    @classmethod
+    def from_yaml(cls, path: str) -> "SolutionsCfg":
+        with open(path, "r") as f:
+            return cls.from_dict(yaml.safe_load(f))
+
+    def __post_init__(self):
+        self.ctx = Context(self.ctx_path)
+
+        if not os.path.exists(self.results_dir):
+            if os.path.exists(os.path.split(self.results_dir)[0]):
+                os.makedirs(self.results_dir)
+            else:
+                raise FileNotFoundError(
+                    f"Could not find results dir or basedir: {self.results_dir}"
+                )
+
+        self.site_pipeline_cfg_dir = os.path.expandvars(self.site_pipeline_cfg_dir)
+        if self.wafer_map_path is None:
+            self.wafer_map_path = os.path.join(
+                self.site_pipeline_cfg_dir, "shared/detmapping/wafer_map.yaml"
+            )
+        with open(self.wafer_map_path, "r") as f:
+            self.wafer_map = yaml.safe_load(f)
+
+        if self.ufm_to_fp_path is None:
+            self.ufm_to_fp_path = os.path.join(
+                self.site_pipeline_cfg_dir, "shared/focalplane/ufm_to_fp.yaml"
+            )
+
+
+@dataclass
+class PointingInfo:
+    pointing: np.ndarray
+    obs_id: str
+    obs: dict
+    meta: AxisManager
+    preprocessed: bool = False
+
+
+_meta_cache = {}
+def get_meta(cfg: SolutionsCfg, obs_id: str, wafer_slot: Optional[str] = None):
+    if obs_id in _meta_cache:
+        meta = _meta_cache[obs_id]
+    else:
+        meta = cfg.ctx.get_meta(obs_id)
+        _meta_cache[obs_id] = meta
+    meta = deepcopy(meta)
+    if wafer_slot is not None:
+        meta.restrict("dets", meta.det_info.wafer_slot == wafer_slot)
+    return meta
+
+
+def load_good_pointing_info(cfg: SolutionsCfg, wafer_slot: str) -> List[PointingInfo]:
+    """
+    Load pointing data for each pointing measurement on disk
+    """
+    files = []
+    for f in os.listdir(cfg.pointing_results_dir):
+        if os.path.splitext(f)[0].split("_")[-1] == wafer_slot:
+            files.append(os.path.join(cfg.pointing_results_dir, f))
+
+    pointing_info = []
+    for f in tqdm(files):
+        d = h5py.File(f)["focal_plane"]
+        if np.sum(np.isfinite(d["xi"])) < cfg.finite_xi_thresh:
+            continue
+        obs_id = "_".join(os.path.basename(f).split("_")[2:-1])
+        obs = cfg.ctx.obsdb.get(obs_id)
+        pinfo = PointingInfo(
+            pointing=d,
+            obs_id=obs_id,
+            obs=obs,
+            meta=get_meta(cfg, obs_id, wafer_slot=wafer_slot),
+        )
+        pointing_info.append(pinfo)
+
+    return pointing_info
+
+
+def pointing_preprocess(cfg: SolutionsCfg, pinfo: PointingInfo):
+    """
+    Add tod_pointing to PointingInfo metadata, adjusting for boresight angle and
+    pointing offset.
+    """
+    meta: AxisManager = pinfo.meta
+    assert (meta.det_info.readout_id == pinfo.pointing["dets:readout_id"].astype(str)).all()
+
+    tod_pointing = AxisManager(meta.dets)
+
+    _xi = deepcopy(pinfo.pointing["xi"])
+    _eta = deepcopy(pinfo.pointing["eta"])
+    theta = 0
+    offset = cfg.initial_pointing_offset
+
+    _xi += offset[0]
+    _eta += offset[1]
+    xi = _xi * np.cos(theta) - _eta * np.sin(theta)
+    eta = _xi * np.sin(theta) + _eta * np.cos(theta)
+
+    tod_pointing.wrap("xi", xi)
+    tod_pointing.wrap("eta", eta)
+    tod_pointing.wrap("r2", pinfo.pointing["R2"])
+    tod_pointing.xi[tod_pointing.r2 < cfg.min_r2] = np.nan
+    tod_pointing.eta[tod_pointing.r2 < cfg.min_r2] = np.nan
+
+    if 'tod_pointing' in meta:
+        meta.move('tod_pointing', None)
+
+    meta.wrap("tod_pointing", tod_pointing)
+    return meta
+
+
+def merge_pointing_info(cfg: SolutionsCfg, pinfos: List[PointingInfo], base_idx=0):
+    """
+    Combine all pointing measurements into a single resonator set, with the
+    median pointing info from all. This requires a base_idx to be specified,
+    which will be the index of the PointingInfo to use to create the ResSet
+    template.  For all other PointingInfo objects, resonators will be matched to
+    the base resset based on resonance frequency, to compile all pointing
+    measurements for a given detector. The median of all measurements will be
+    used as the real value.
+    """
+    for pinfo in pinfos:
+        pointing_preprocess(cfg, pinfo)
+
+    meta = pinfos[base_idx].meta
+    stream_id = meta.det_info.stream_id[0]
+    wafer_slot = meta.det_info.wafer_slot[0]
+    base_resset = dm.ResSet.from_aman(meta, stream_id=stream_id, pointing=meta.tod_pointing)
+
+    pointing_map = {
+        r.idx: [(r.xi, r.eta)] for r in base_resset
+    }
+
+    match_pars = dm.MatchParams(
+        freq_width=cfg.match_pars["pointing"]["freq_width"],
+        dist_width=np.deg2rad(cfg.match_pars["pointing"]["dist_width"])
+    )
+
+    for i in range(len(pinfos)):
+        if i == base_idx:
+            continue
+        meta = pinfos[i].meta
+        src = dm.ResSet.from_aman(meta, stream_id=stream_id, pointing=meta.tod_pointing)
+        dst = base_resset
+        match = dm.Match(src, dst, match_pars=match_pars)
+        for rsrc, rdst in match.get_match_iter(include_unmatched=False):
+            pointing_map[rdst.idx].append((rsrc.xi, rsrc.eta))
+
+    for r in base_resset:
+        r.xi, r.eta = np.nanmedian(np.array(pointing_map[r.idx]).T, axis=1)
+
+    return base_resset, pointing_map
+
+
+def get_best_tod_pointing(cfg: SolutionsCfg, pinfos: List[PointingInfo]) -> AxisManager:
+    _readout_ids = pinfos[0].pointing["dets:readout_id"]
+
+    readout_ids = list(map(lambda bs: bs.decode(), _readout_ids))
+    dets = LabelAxis("dets", readout_ids)
+    ndets = dets.count
+
+    for pinfo in pinfos:  # Shift and rotate xi/eta per pointing observation
+        _xi = pinfo.pointing["xi"] + cfg.initial_pointing_offset[0]
+        _eta = pinfo.pointing["eta"] + cfg.initial_pointing_offset[1]
+        theta = np.deg2rad(pinfo.obs["roll_center"]) if cfg.apply_roll else 0.
+        pinfo.xi = _xi * np.cos(theta) - _eta * np.sin(theta)
+        pinfo.eta = _xi * np.sin(theta) + _eta * np.cos(theta)
+
+    xis = np.full(ndets, np.nan)
+    etas = np.full(ndets, np.nan)
+
+    for i in trange(len(readout_ids)):  # Find optimal xi/eta per readout channel
+        _xis = np.full(len(pinfos), np.nan)
+        _etas = np.full(len(pinfos), np.nan)
+        _r2s = np.full(len(pinfos), np.nan)
+        for j, pi in enumerate(pinfos):
+            rc = np.where(pi.pointing["dets:readout_id"] == readout_ids[i].encode())[0]
+            if not rc:
+                continue
+            rc = rc[0]
+            _xis[j] = pi.xi[rc]
+            _etas[j] = pi.eta[rc]
+            _r2s[j] = pi.pointing["R2"][rc]
+        xis[i] = np.nanmean(_xis[_r2s > cfg.min_r2])
+        etas[i] = np.nanmean(_etas[_r2s > cfg.min_r2])
+
+    tod_pointing = AxisManager(dets)
+    tod_pointing.wrap("xi", xis, [(0, "dets")])
+    tod_pointing.wrap("eta", etas, [(0, "dets")])
+
+    return tod_pointing
+
+
+@dataclass
+class MatchSolution:
+    match: dm.Match
+    am: AxisManager
+    match_iterations: List[dm.Match] = field(default_factory=list)
+
+
+def get_pt_offset_interp(match, sel_rad=np.deg2rad(2)) -> Tuple[Any, Any]:
+    _xis, _etas, _dxis, _detas = [], [], [], []
+    for r1, r2 in match.get_match_iter(include_unmatched=False):
+        _xis.append(r1.xi)
+        _etas.append(r1.eta)
+        _dxis.append(r1.xi - r2.xi)
+        _detas.append(r1.eta - r2.eta)
+    xis = np.array(_xis)
+    etas = np.array(_etas)
+    dxis = np.array(_dxis)
+    detas = np.array(_detas)
+
+    xi_list = np.arange(np.nanmin(xis), np.nanmax(xis), sel_rad / 2)
+    eta_list = np.arange(np.nanmin(etas), np.nanmax(etas), sel_rad / 2)
+    xi_grid, eta_grid = np.meshgrid(xi_list, eta_list)
+    dxi_data = np.full_like(xi_grid, np.nan)
+    deta_data = np.full_like(eta_grid, np.nan)
+    for i, j in np.ndindex(xi_grid.shape):
+        sel = (
+            np.sqrt((xis - xi_grid[i, j]) ** 2 + (etas - eta_grid[i, j]) ** 2) < sel_rad
+        )
+        sel &= np.isfinite(dxis) & np.isfinite(detas)
+        dxi_data[i, j] = np.nanmedian(dxis[sel])
+        deta_data[i, j] = np.nanmedian(detas[sel])
+
+    dxi_interp = interpolate.RegularGridInterpolator(
+        (xi_list, eta_list), dxi_data.T, bounds_error=False, fill_value=None
+    )
+    deta_interp = interpolate.RegularGridInterpolator(
+        (xi_list, eta_list), deta_data.T, bounds_error=False, fill_value=None
+    )
+    return dxi_interp, deta_interp
+
+
+def get_foffset_interp(
+    match, is_north, box_size=50, box_step=25
+) -> Callable[[float], float]:
+    df, f, is_norths = [], [], []
+    for r1, r2 in match.get_match_iter(include_unmatched=False):
+        df.append(r1.res_freq - r2.res_freq)
+        f.append(r1.res_freq)
+        is_norths.append(r1.is_north)
+    df_arr = np.array(df)
+    f_arr = np.array(f)
+    is_north_arr = np.array(is_norths, dtype=bool)
+
+    f0, f1 = np.min(f), np.max(f)
+    df_meds = []
+    fcs = []
+    for fc in np.arange(f0, f1, box_step):
+        sel = (f > fc - box_size / 2) & (f < fc + box_size / 2)
+        sel &= is_north_arr == is_north
+        df_meds.append(np.nanmedian(df_arr[sel]))
+        fcs.append(fc)
+
+    # Create interpolation
+    f_func = interpolate.interp1d(fcs, df_meds, fill_value="extrapolate")
+    return f_func
+
+
+@dataclass
+class MatchSolutionResult:
+    results: Dict[str, Optional[MatchSolution]]
+    am: Optional[AxisManager] = None
+    traceback: Optional[str] = None
+
+
+def match_wafer(
+    cfg: SolutionsCfg,
+    am: AxisManager,
+    stream_id: str,
+    meas_rset: Optional[dm.ResSet]
+) -> MatchSolution:
+    """
+    Create a match solution for a given wafer slot.
+
+    Args
+    ------
+    cfg: SolutionsCfg
+        Configuration object
+    am: AxisManager
+        Axis manager containing detector info about relevant wafer slot, along
+        with measured pointing data.
+    stream_id: str
+        Stream Id of the wafer
+    """
+    match_iterations = []
+
+    m = am.det_info.stream_id == stream_id
+    wafer_slot = am.det_info.wafer_slot[m][0]
+
+    if meas_rset is None:
+        src = dm.ResSet.from_aman(am, stream_id, pointing=am[cfg.pointing_field])
+    else:
+        src = meas_rset
+
+    pt_cfg = dm.PointingConfig(
+        fp_file=cfg.ufm_to_fp_path, wafer_slot=wafer_slot, tel_type=cfg.tel_type,
+        zemax_path=cfg.zemax_path,
+        roll=np.deg2rad(am.obs_info.roll_center) if cfg.apply_roll else 0.0,
+        tube_slot = am.obs_info.tube_slot
+    )
+    dst = dm.ResSet.from_wafer_info_file(cfg.wafer_info_path, stream_id, pt_cfg=pt_cfg)
+
+    # first match
+    match_pars = dm.MatchParams(
+        freq_width=cfg.match_pars["match0"]["freq_width"],
+        dist_width=np.deg2rad(cfg.match_pars["match0"]["dist_width"]),
+        enforce_pointing_reqs=True,
+        allow_unassigned_to_assigned=False,
+        unassigned_slots=cfg.unassigned_slots
+    )
+    match = dm.Match(src, dst, match_pars=match_pars, apply_dst_pointing=False)
+
+    match_iterations.append(deepcopy(match))
+    dxis, detas = [], []
+    dfs = []
+    is_north = []
+    for r1, r2 in match.get_match_iter(include_unmatched=False):
+        dxis.append(r2.xi - r1.xi)
+        detas.append(r2.eta - r1.eta)
+        dfs.append(r2.res_freq - r1.res_freq)
+        is_north.append(r2.is_north)
+    dxi = np.nanmedian(dxis)
+    deta = np.nanmedian(detas)
+
+    for r in match.src:
+        r.xi += dxi
+        r.eta += deta
+
+    match._match()
+    match_iterations.append(deepcopy(match))
+
+    if cfg.freq_correct_by_muxband:
+        da = match.dst.as_array()
+        df_arr = np.full(len(da), np.nan)
+        for i, r in enumerate(match.dst):
+            if r.matched:
+                df_arr[i] = r.res_freq - match.src[r.match_idx].res_freq
+
+        for is_north in [0, 1]:
+            for mb in np.unique(da["mux_band"]):
+                mask = (da["mux_band"] == mb) & (da["is_north"] == is_north)
+                df_med = np.nanmedian(df_arr[mask])
+                for res_idx in np.where(mask)[0]:
+                    match.dst[res_idx].res_freq -= df_med
+    else:
+        # Correct freq offset by box median interpolation
+        foffset_north = get_foffset_interp(match, True)
+        foffset_south = get_foffset_interp(match, False)
+        for r in match.dst:
+            if r.is_north:
+                r.res_freq += foffset_north(r.res_freq)
+            else:
+                r.res_freq += foffset_south(r.res_freq)
+
+    match.match_pars = dm.MatchParams(
+        freq_width=cfg.match_pars["match1"]["freq_width"],
+        dist_width=np.deg2rad(cfg.match_pars["match1"]["dist_width"]),
+        enforce_pointing_reqs=True,
+        allow_unassigned_to_assigned=False,
+        unassigned_slots=cfg.unassigned_slots
+    )
+    match._match()
+
+    dxi_interp, deta_interp = get_pt_offset_interp(match, sel_rad=np.deg2rad(2))
+    for r in match.src:
+        if np.isnan(r.xi):
+            continue
+        r.xi -= dxi_interp((r.xi, r.eta)).item()
+        r.eta -= deta_interp((r.xi, r.eta)).item()
+
+    match.match_pars.freq_width = cfg.match_pars["match2"]["freq_width"]
+    match.match_pars.dist_width = np.deg2rad(cfg.match_pars["match2"]["dist_width"])
+
+    match._match()
+
+    match_iterations.append(deepcopy(match))
+
+    return MatchSolution(
+        match=match,
+        match_iterations=match_iterations,
+        am=am,
+    )
+
+
+@dataclass
+class FullWaferSolution:
+    match_solution: MatchSolution
+    pointing_results: List[PointingInfo]
+    meta: AxisManager
+    stream_id: str
+
+
+def create_empty_match(cfg, am, wafer_slot, save=False):
+    m = am.det_info.wafer_slot == wafer_slot
+    stream_id = am.det_info.stream_id[m][0]
+    src = dm.ResSet.from_aman(am, stream_id)
+
+    if save:
+        resset_file = os.path.join(cfg.results_dir, f"{stream_id}.npy")
+        np.save(resset_file, src.as_array())
+
+    return src
+
+def save_wafer_solution(cfg: SolutionsCfg, solution: FullWaferSolution):
+    solution.stream_id
+    resset_file = os.path.join(cfg.results_dir, f"{solution.stream_id}.npy")
+    match_file = os.path.join(cfg.results_dir, "matches", f"{solution.stream_id}.h5")
+    if not os.path.exists(os.path.dirname(match_file)):
+        os.makedirs(os.path.dirname(match_file))
+
+    match = solution.match_solution.match
+    np.save(resset_file, match.merged.as_array())
+    match.save(match_file)
+
+
+def get_wafer_solution(
+    cfg: SolutionsCfg, wafer_slot: str, save=False
+) -> Optional[FullWaferSolution]:
+    pointing_results = load_good_pointing_info(cfg, wafer_slot)
+    if len(pointing_results) == 0:
+        return None
+
+    if cfg.base_obs_id is not None:
+        for i, pi in enumerate(pointing_results):
+            if pi.obs_id == cfg.base_obs_id:
+                base_idx = i
+                break
+        else:
+            raise ValueError(f"Pointing info for base obs_id not found: {cfg.base_obs_id}")
+    else:
+        base_idx = 0
+
+    meas_rset, pointing_map = merge_pointing_info(cfg, pointing_results, base_idx=base_idx)
+    # tod_pointing = get_best_tod_pointing(cfg, pointing_results)
+
+    meta = pointing_results[0].meta
+    stream_id = meta.det_info.stream_id[0]
+
+    match_solution = match_wafer(cfg, meta, stream_id, meas_rset=meas_rset)
+
+    solution = FullWaferSolution(
+        pointing_results=pointing_results,
+        match_solution=match_solution,
+        meta=meta,
+        stream_id=stream_id,
+    )
+
+    if save:
+        save_wafer_solution(cfg, solution)
+
+    return solution
+
+
+def solve_all(cfg) -> Dict[str, Optional[FullWaferSolution]]:
+    wafer_slots = ["ws0", "ws1", "ws2", "ws3", "ws4", "ws5", "ws6"]
+    results = {ws: get_wafer_solution(cfg, ws, save=True) for ws in wafer_slots}
+    return results
+
+
+if __name__ == "__main__":
+    cfg_file = sys.argv[1]
+    with open(cfg_file, "r") as f:
+        cfg = SolutionsCfg(**yaml.safe_load(f))
+    solve_all(cfg)

From e9f971ae8adc932436fdb6fd278466f9f4946f8f Mon Sep 17 00:00:00 2001
From: Michael McCrackan <mmccrack@login18.chn.perlmutter.nersc.gov>
Date: Wed, 22 Apr 2026 13:04:47 -0700
Subject: [PATCH 4/7] update docs, add to cli

---
 docs/det_match.rst                         | 25 +++++++++
 sotodlib/coords/det_match.py               |  4 +-
 sotodlib/coords/det_match_solutions.py     | 65 ++++++++++++++++------
 sotodlib/site_pipeline/cli.py              |  4 +-
 sotodlib/site_pipeline/update_det_match.py | 60 +++++++++++++-------
 5 files changed, 121 insertions(+), 37 deletions(-)

diff --git a/docs/det_match.rst b/docs/det_match.rst
index 84f42c0b2..35cb26d5d 100644
--- a/docs/det_match.rst
+++ b/docs/det_match.rst
@@ -90,10 +90,35 @@ lenient with the frequency penalty:
     )
     match = dm.Match(src, dst, match_params=mpars)
 
+Det Match Solutions
+`````````````````````````
+
+The ``det_match_solutions`` script can be used to generate "handmade" det_match
+solutions sets for all wafers from a tune file and pointing information to
+the design wafer information.  It is performs multiple matches iteratively
+while correcting for frequency and pointing offsets between them.  The major steps are:
+
+- Load pointing xi/eta information from fits to observations of point sources.
+These should be written to an h5 file under a group named ``focal_plane``.
+Multiple pointing files may be input in which case they will a match will be
+performed and the median xi/eta values will be used from all matched resonators.
+- Do the first match for the wafer using pointing, frequency, and bias line
+information.
+- Subtract the median xi/eta offset from matched detectors.  Also remove frequency
+offsets through box median interpolation.
+- Run a second match after offset correction.
+- Perform a grid based pointing offset given a selection radius in the config file.
+- Run the third match after second pointing offset correction.
+
 
 API
 -------
 .. automodule:: sotodlib.coords.det_match
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: sotodlib.coords.det_match_solutions
    :members:
    :undoc-members:
    :show-inheritance:
\ No newline at end of file
diff --git a/sotodlib/coords/det_match.py b/sotodlib/coords/det_match.py
index 0a3107e07..ea9bc7806 100644
--- a/sotodlib/coords/det_match.py
+++ b/sotodlib/coords/det_match.py
@@ -633,10 +633,12 @@ class MatchParams:
         enforce_pointing_reqs (bool):
             If this is enabled, it will enforce the following requirements when
             matching:
-
              - Resonators with OPTC det_type must have pointing data.
              - Resonators with UNRT, SQID, or BARE det_types must _not_ have pointing data.
              - Resonators with DARK or SLOT det_types may or may not have pointing data.
+        allow_unassigned_to_assigned (bool):
+            Allow resonators from dst that do not have an assigned bias group
+            to be matched to one in src that has an assigned bias group.
         assigned_bg_unmatched_pen (float):
             Penalty to apply to leaving a resonator with an assigned bg
             unmatched
diff --git a/sotodlib/coords/det_match_solutions.py b/sotodlib/coords/det_match_solutions.py
index 8895368e0..2399e04f4 100644
--- a/sotodlib/coords/det_match_solutions.py
+++ b/sotodlib/coords/det_match_solutions.py
@@ -12,9 +12,6 @@
 from copy import deepcopy
 
 import h5py
-
-from importlib import reload
-import yaml
 import sys
 
 
@@ -26,11 +23,29 @@ class SolutionsCfg:
     ctx_path: str
         Path to context file to use to pull tod metadata.
     pointing_results_dir: str
-        Results to directory that contains pointing resutls from Tomoki's
-        workflow. Files in directory should look like:
+        Results to directory that contains pointing results.  Files in
+        directory should look like:
         ```
         focal_plane_<obs_id>_<wafer_slot>.hdf
         ```
+    results_dir: str
+        Directory where results should be stored.
+    wafer_info_path: str
+        Path to the wafer_info h5 file.
+    tel_type: str
+        Tel type for the optics model. Either "SAT" or "LAT"
+    base_obs_id: str
+        Obs_id to use as a base for matching when merging multiple pointing
+        obs_ids for a wafer.  Will default to the pointing obs_id with the
+        greatest number of detectors above the min_R2 threshold.
+    zemax_path: str
+        If running for a "LAT" tel_type, the path to the zemax file must be specified.
+    apply_roll: bool
+        Whether or not to apply the obs_id roll angle.  Some pointing sets
+        may already be corrected for roll angle.
+    pointing_field: str
+        Name of sub axis manager in pointing tune axis maanger containng the
+        pointing information.
     site_pipeline_cfg_dir: str
         Path to site-pipeline-config dir. Defaults to the env var
         ``$SITE_PIPELINE_CONFIG_DIR``.
@@ -39,23 +54,37 @@ class SolutionsCfg:
         analysis.
     min_r2: float
         Minimum R-squared for det pointing to be considered.
+    sel_rad: float
+        Selection radius for grid-based interpolation pointing offset subtraction.
     unassigned_slots: int:
         Number of additional "unassigned" node to use per-side
-    wafer_info_path: str
-        Path to the wafer_info h5 file.
     wafer_map_path: str
         Path to the wafer map file. Defaults to ``<site-pipeline-config>/shared/detmatpping/wafer_map.yaml``.
+    match_pars: dict
+        Dictionary of match parameters to use for pointing obs_id merging and
+        each match iteration.  Should have the form::
+
+        match_pars:
+            pointing:
+                freq_width: 0.4
+                dist_width: 2.0
+            match0:
+                freq_width: 200
+                dist_width: 0.4
+            match1:
+                freq_width: 50
+                dist_width: 0.8
+            match2:
+                freq_width: 5
+                dist_width: 0.1
+
     Initial pointing offset: Tuple[float, float]
         Estimated pointing offset for the boresight. This should be
         (xi_offset, eta_offset) where both are in radians.
-    results_dir: str
-        Directory where results should be stored.
+    ufm_to_fp_path: str
+        Path to file that maps wafer_slot to position on focal plane.
     freq_correct_by_muxband: bool
         If true, apply the same freq offset correction to all resonators in a mux-band.
-    tel_type: str
-        Tel type for the optics model. Either "SAT" or "LAT"
-    zemax_path: str
-        If running for a "LAT" tel_type, the path to the zemax file must be specified.
     """
 
     ctx_path: str
@@ -67,22 +96,24 @@ class SolutionsCfg:
     zemax_path: Optional[str] = None
     apply_roll: bool = True
 
-    ctx: Context = field(init=False)
     pointing_field: str = "tod_pointing"
     site_pipeline_cfg_dir: str = "$SITE_PIPELINE_CONFIG_DIR"
     finite_xi_thresh: int = (
         500  # Min number of dets with finite xi to consider a pointing input
     )
     min_r2: float = 0.9
+    sel_rad: float = 2.0
     unassigned_slots: int = 1200
     wafer_map_path: Optional[str] = None
-    wafer_map: Dict[str, dict] = field(init=False)
     match_pars: Dict[str, dict] = field(default_factory=lambda: defaultdict(dict))
 
     initial_pointing_offset: Tuple[float, float] = (0, 0)
     ufm_to_fp_path: Optional[str] = None
     freq_correct_by_muxband: bool = True
 
+    ctx: Context = field(init=False)
+    wafer_map: Dict[str, dict] = field(init=False)
+
     @classmethod
     def from_dict(cls, d: Dict[str, Any]) -> "SolutionsCfg":
         return cls(**d)
@@ -444,6 +475,7 @@ def match_wafer(
             else:
                 r.res_freq += foffset_south(r.res_freq)
 
+    # Second match
     match.match_pars = dm.MatchParams(
         freq_width=cfg.match_pars["match1"]["freq_width"],
         dist_width=np.deg2rad(cfg.match_pars["match1"]["dist_width"]),
@@ -453,13 +485,14 @@ def match_wafer(
     )
     match._match()
 
-    dxi_interp, deta_interp = get_pt_offset_interp(match, sel_rad=np.deg2rad(2))
+    dxi_interp, deta_interp = get_pt_offset_interp(match, sel_rad=np.deg2rad(cfg.sel_rad))
     for r in match.src:
         if np.isnan(r.xi):
             continue
         r.xi -= dxi_interp((r.xi, r.eta)).item()
         r.eta -= deta_interp((r.xi, r.eta)).item()
 
+    # Third match
     match.match_pars.freq_width = cfg.match_pars["match2"]["freq_width"]
     match.match_pars.dist_width = np.deg2rad(cfg.match_pars["match2"]["dist_width"])
 
diff --git a/sotodlib/site_pipeline/cli.py b/sotodlib/site_pipeline/cli.py
index 399f64c37..b6257f985 100644
--- a/sotodlib/site_pipeline/cli.py
+++ b/sotodlib/site_pipeline/cli.py
@@ -59,6 +59,7 @@ def main(obs_id=None, config_file=None, logger=None):
     update_obsdb_ancil,
     make_coadd_atomic_map,
     make_cosamp_hk,
+    update_det_match,
 )
 
 # Dictionary matching element name to a submodule (which must have
@@ -81,7 +82,8 @@ def main(obs_id=None, config_file=None, logger=None):
     'update-obsdb': update_obsdb,
     'update-obsdb-ancil': update_obsdb_ancil,
     'make-cosamp-hk': make_cosamp_hk,
-    'make-coadd-atomic-map': make_coadd_atomic_map
+    'make-coadd-atomic-map': make_coadd_atomic_map,
+    'update-det-match': update_det_match,
 }
 
 CLI_NAME = 'so-site-pipeline'
diff --git a/sotodlib/site_pipeline/update_det_match.py b/sotodlib/site_pipeline/update_det_match.py
index 9e12e27cd..fc4ffe2ec 100644
--- a/sotodlib/site_pipeline/update_det_match.py
+++ b/sotodlib/site_pipeline/update_det_match.py
@@ -11,6 +11,7 @@
 import time
 
 from sotodlib.coords import det_match, optics
+from sotodlib.coords.det_match_solutions import SolutionsCfg, solve_all
 from sotodlib import core
 from sotodlib.core.metadata import ManifestDb
 from sotodlib.io.metadata import write_dataset
@@ -439,31 +440,52 @@ def update_manifests_all(runner):
 def make_parser():
     parser = argparse.ArgumentParser()
     parser.add_argument('config', type=str, help='path to config file')
-    parser.add_argument('--all', action='store_true', help='run all detsets')
+    parser.add_argument('--run-all', action='store_true', help='run all detsets')
+    parser.add_arguments('--solutions-mode', action='store_true',
+                         help='create a det_match solution set')
     return parser
 
-def main(config_file: str, all: bool=False):
-    with open(config_file, 'r') as f:
-        cfg = UpdateDetMatchesConfig(**yaml.safe_load(f))
-
-    runner = Runner(cfg)
+def main(config_file: str, run_all: bool=False, solutions_mode: bool=False):
+    """
+    Site-pipeline script to peform detector matching of tunesets to a solution
+    set.
 
-    remaining_detsets = runner.get_remaining_detsets()
-    logger.info(f"{len(remaining_detsets)} detsets to match")
-    if all:
-        update_manifests_all(runner)
-        for detset in remaining_detsets:
-            logger.info(f"running: {detset}")
-            run_match(runner, detset)
-            update_manifests_all(runner)
+    ------
+    config_file: str
+        Yaml configuration file for tuneset matching (or solution set matching
+        if solutions_mode is True).
+    run_all: bool
+        Run all detsets if True, otherwise exit after first successful match.
+    solutions_mode: bool
+        Create a det_match solution instead of matching a solution to a tuneset.
+        Requires a solutions configuration file.
+    """
+    if solutions_mode:
+        with open(config_file, "r") as f:
+            cfg = SolutionsCfg(**yaml.safe_load(f))
+        solve_all(cfg)
     else:
-        for detset in remaining_detsets:
-            success = run_match(runner, detset)
+        with open(config_file, 'r') as f:
+            cfg = UpdateDetMatchesConfig(**yaml.safe_load(f))
+
+        runner = Runner(cfg)
+
+        remaining_detsets = runner.get_remaining_detsets()
+        logger.info(f"{len(remaining_detsets)} detsets to match")
+        if run_all:
             update_manifests_all(runner)
-            if success:
-                break
+            for detset in remaining_detsets:
+                logger.info(f"running: {detset}")
+                run_match(runner, detset)
+                update_manifests_all(runner)
+        else:
+            for detset in remaining_detsets:
+                success = run_match(runner, detset)
+                update_manifests_all(runner)
+                if success:
+                    break
 
 if __name__ == '__main__':
     parser = make_parser()
     args = parser.parse_args()
-    main(args.config, all=args.all)
+    main(args.config, run_all=args.run_all, solutions_mode=args.solutions_mode)

From 8a19314aa2c8a3ef7d1c34c9e04345854468d927 Mon Sep 17 00:00:00 2001
From: Michael McCrackan <mmccrack@login18.chn.perlmutter.nersc.gov>
Date: Wed, 22 Apr 2026 13:08:53 -0700
Subject: [PATCH 5/7] fix typo

---
 sotodlib/site_pipeline/update_det_match.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/sotodlib/site_pipeline/update_det_match.py b/sotodlib/site_pipeline/update_det_match.py
index fc4ffe2ec..429037d04 100644
--- a/sotodlib/site_pipeline/update_det_match.py
+++ b/sotodlib/site_pipeline/update_det_match.py
@@ -441,7 +441,7 @@ def make_parser():
     parser = argparse.ArgumentParser()
     parser.add_argument('config', type=str, help='path to config file')
     parser.add_argument('--run-all', action='store_true', help='run all detsets')
-    parser.add_arguments('--solutions-mode', action='store_true',
+    parser.add_argument('--solutions-mode', action='store_true',
                          help='create a det_match solution set')
     return parser
 

From fb56409f11be2faacbf02d5affd167b5b53c9655 Mon Sep 17 00:00:00 2001
From: Michael McCrackan <mmccrack@login18.chn.perlmutter.nersc.gov>
Date: Wed, 22 Apr 2026 13:51:18 -0700
Subject: [PATCH 6/7] cli and doc fixes

---
 docs/det_match.rst                         | 17 ++++++++---------
 sotodlib/site_pipeline/update_det_match.py | 11 ++++++-----
 2 files changed, 14 insertions(+), 14 deletions(-)

diff --git a/docs/det_match.rst b/docs/det_match.rst
index 35cb26d5d..1ec3c0fa9 100644
--- a/docs/det_match.rst
+++ b/docs/det_match.rst
@@ -93,19 +93,18 @@ lenient with the frequency penalty:
 Det Match Solutions
 `````````````````````````
 
-The ``det_match_solutions`` script can be used to generate "handmade" det_match
+The ``det_match_solutions`` script can be used to generate "handmade" detector match
 solutions sets for all wafers from a tune file and pointing information to
 the design wafer information.  It is performs multiple matches iteratively
 while correcting for frequency and pointing offsets between them.  The major steps are:
 
-- Load pointing xi/eta information from fits to observations of point sources.
-These should be written to an h5 file under a group named ``focal_plane``.
-Multiple pointing files may be input in which case they will a match will be
-performed and the median xi/eta values will be used from all matched resonators.
-- Do the first match for the wafer using pointing, frequency, and bias line
-information.
-- Subtract the median xi/eta offset from matched detectors.  Also remove frequency
-offsets through box median interpolation.
+- Load pointing xi and eta information from fits to observations of point sources.
+  These should be written to an ``hdf5`` file under a group named ``focal_plane``.
+  Multiple pointing files may be input in which case they will a match will be
+  performed and the median xi and eta values will be used from all matched resonators.
+- Do the first match for the wafer using pointing, frequency, and bias line information.
+- Subtract the median xi and eta offset from matched detectors.  Also remove frequency
+  offsets through box median interpolation.
 - Run a second match after offset correction.
 - Perform a grid based pointing offset given a selection radius in the config file.
 - Run the third match after second pointing offset correction.
diff --git a/sotodlib/site_pipeline/update_det_match.py b/sotodlib/site_pipeline/update_det_match.py
index 429037d04..3cf74ca2c 100644
--- a/sotodlib/site_pipeline/update_det_match.py
+++ b/sotodlib/site_pipeline/update_det_match.py
@@ -437,9 +437,10 @@ def update_manifests_all(runner):
         logger.info(f"Adding {ds} to manifests")
         update_manifests(runner, ds)
 
-def make_parser():
-    parser = argparse.ArgumentParser()
-    parser.add_argument('config', type=str, help='path to config file')
+def get_parser(parser=None):
+    if parser is None:
+        parser = argparse.ArgumentParser()
+    parser.add_argument('config_file', type=str, help='path to config file')
     parser.add_argument('--run-all', action='store_true', help='run all detsets')
     parser.add_argument('--solutions-mode', action='store_true',
                          help='create a det_match solution set')
@@ -486,6 +487,6 @@ def main(config_file: str, run_all: bool=False, solutions_mode: bool=False):
                     break
 
 if __name__ == '__main__':
-    parser = make_parser()
+    parser = get_parser()
     args = parser.parse_args()
-    main(args.config, run_all=args.run_all, solutions_mode=args.solutions_mode)
+    main(args.config_file, run_all=args.run_all, solutions_mode=args.solutions_mode)

From 7d78991b71e7b42c82890dd7e697b9fc8361fe10 Mon Sep 17 00:00:00 2001
From: Michael McCrackan <mmccrack@login18.chn.perlmutter.nersc.gov>
Date: Wed, 22 Apr 2026 14:26:07 -0700
Subject: [PATCH 7/7] more docs

---
 docs/det_match.rst | 19 ++++++++++++++-----
 1 file changed, 14 insertions(+), 5 deletions(-)

diff --git a/docs/det_match.rst b/docs/det_match.rst
index 1ec3c0fa9..73085b39e 100644
--- a/docs/det_match.rst
+++ b/docs/det_match.rst
@@ -6,7 +6,7 @@ DetMatch
 The ``sotodlib.coords.det_match`` module allows us to map resonators from one
 source to another, using information such as resonator frequency, bias-line
 assignments, and pointing information. This is particularly useful to create
-a map from resonators in a SMuRF tune-file, to real detectors from either a
+a map from resonators in a SMuRF tune-file to real detectors from either a
 design-file, or a handmade solutions file based on a separate tune-file.
 
 This works by translating the detector matching problem into an instance
@@ -94,12 +94,21 @@ Det Match Solutions
 `````````````````````````
 
 The ``det_match_solutions`` script can be used to generate "handmade" detector match
-solutions sets for all wafers from a tune file and pointing information to
-the design wafer information.  It is performs multiple matches iteratively
-while correcting for frequency and pointing offsets between them.  The major steps are:
+solutions sets for all wafers.  A solution set is defined as a mapping from a tune file
+with the addition of pointing information from fits to a point source in that observation to
+the design wafer information (i.e. matching tune readout IDs to design detector IDs with
+xi and eta constraints).  Solutions are useful due to the potentially alrge frequency shifts
+between the tunesets and design frequencies.It is performs multiple matches
+sequentially while correcting for frequency and pointing offsets between them.
+
+The major steps in this script are:
 
 - Load pointing xi and eta information from fits to observations of point sources.
-  These should be written to an ``hdf5`` file under a group named ``focal_plane``.
+  These are derived by fitting TODs or maps of observations targeting point
+  sources (planets or the Moon) and are stored as a structured array in an
+  ``hdf5`` file under a group named ``focal_plane`` and should include entries
+  for all det_ids from the matching tune (NaNs are allowed). It should also include
+  an estimate of the coefficient of determination, R\ :sup:`2` for excluding bad fits.
   Multiple pointing files may be input in which case they will a match will be
   performed and the median xi and eta values will be used from all matched resonators.
 - Do the first match for the wafer using pointing, frequency, and bias line information.