os-optics-kit 0.1.0__py3-none-any.whl

os_optics_kit/__init__.py

@@ -0,0 +1,9 @@
+"""os-optics-kit: tools, cases and agent skills for OS Optics.
+
+The tools are modules of this package and subcommands of ``os-optics-kit``; the cases and skills ship as package
+data. The engine (``os_optics``, PyPI ``os-optics``) is imported only by the functions that need it.
+"""
+
+from ._version import __version__
+
+__all__ = ["__version__"]

os_optics_kit/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

os_optics_kit/_data/baseline.json

@@ -0,0 +1,16 @@
+{
+  "schema": "os-optics-kit.baseline",
+  "schema_version": 1,
+  "kit_version": "0.1.0",
+  "engine": {
+    "distribution": "os-optics",
+    "requirement": ">=0.12,<0.13",
+    "verified_version": "0.12.0"
+  },
+  "catalog": {
+    "version": "2026-10-28.1",
+    "schema_version": "3.2",
+    "sha256": "7d7f5f0a6fa1db7ce32503a6a1d86c5bdcd167035782b47b73c2ac00fc1acf30"
+  },
+  "python": ["3.11", "3.14"]
+}

os_optics_kit/_data/cases/beam-expander/CASE.md

@@ -0,0 +1,52 @@
+---
+name: beam-expander
+title: Catalog beam expander: swap a lens, sweep its spacing, restore collimation
+summary: A Keplerian beam expander of two catalog plano-convex lenses (f = 50 mm and 100 mm, 780 nm, 1 mm waist) reaches its 1.9961 mm output waist. The studies swap L2 for a 100.3 mm fused-silica lens, sweep L2 along the beam and apply the best shift.
+engine: 0.12.0
+catalog: 2026-10-28.1
+project: project.json
+tools: candidates, edit, sweep, compare, plot, report
+tags: catalog, beam-expander, lens-swap, parameter-sweep, edit-by-id
+license: MIT
+---
+
+## What it shows
+
+`project.json` is the engine's reference design `os-optics project example --kind beam_expander`; its components
+pin catalog release 2026-10-28.1. The target `expanded_waist` (waist radius of the output beam, a collimation
+measure) asks for 1.9961 mm ± 1 %. The study files edit the design by ID: swapping L2 for the 100.3 mm lens breaks
+collimation (`expanded_waist` 1.4407 mm, UNMET, while the radius at the plane, `output_beam_radius`, stays MET);
+a twelve-sample sweep of the L2 position finds +0.54 mm (1.99645 mm, 5 of 12 samples PASS); applying it passes.
+
+## Run
+
+```bash
+os-optics project run project.json --out-dir run
+os-optics results targets run
+os-optics-kit candidates --category LENS --form PLANO_CONVEX_LENS --wavelength-nm 780 \
+  --range focal_length_mm=95..105 --range outer_diameter_mm=12.7..12.7 --near focal_length_mm=100 --limit 8
+os-optics-kit edit project.json --edits studies/beam_expander_swap_l2.json --out swapped.json --run swapped-run
+os-optics-kit sweep studies/beam_expander_l2_sweep.json --base swapped.json --out l2-sweep
+os-optics-kit plot sweep l2-sweep --y target:expanded_waist
+os-optics-kit edit swapped.json --edits studies/beam_expander_move_l2.json --out final.json --run final-run
+os-optics-kit compare run swapped-run final-run --project final.json --out compare
+os-optics-kit report l2-sweep --project final.json --plots l2-sweep/plots --changes swapped.changes.json
+```
+
+## Targets
+
+| Target | Metric | Plane | Bound | Verified |
+| --- | --- | --- | --- | --- |
+| `expanded_waist` | `waist_radius_x_mm` | `output` | 1.99612 mm ± 1 % | 1.99607 mm, MET |
+
+## Baseline
+
+os-optics 0.12.0, catalog 2026-10-28.1: run status PASS (`expected.json`).
+`os-optics-kit cases verify beam-expander` repeats the run and compares it.
+
+## Files
+
+- `project.json`, `expected.json`: the design and its verified outcome.
+- `studies/beam_expander_swap_l2.json`, `studies/beam_expander_l2_sweep.json`, `studies/beam_expander_move_l2.json`:
+  the lens swap, the L2 sweep and the final move.
+- `README.md`, `README.zh-CN.md`, `images/`: the illustrated page.

os_optics_kit/_data/cases/beam-expander/README.md

@@ -0,0 +1,38 @@
+# Catalog beam expander
+
+Two catalog plano-convex lenses (f = 50 mm and 100 mm, N-BK7, 12.7 mm diameter) expand a 780 nm Gaussian beam with a
+1 mm waist radius twice. The target `expanded_waist` asks for an output waist radius of 1.9961 mm ± 1 %, a measure
+of collimation. The components pin catalog release 2026-10-28.1.
+
+![Section along the lens axis: L1 focuses, L2 collimates, the plane output receives the expanded beam](images/section.png)
+
+![Isometric view of the expander](images/iso.png)
+
+## Run it
+
+```bash
+os-optics-kit cases copy beam-expander --dest .
+cd beam-expander
+os-optics project run project.json --out-dir run
+os-optics results targets run
+```
+
+## Results
+
+| Target | Value | Bound | Assessment |
+| --- | --- | --- | --- |
+| `expanded_waist` | 1.99607 mm | 1.99612 mm ± 1 % | MET |
+
+## Swap a lens and restore collimation
+
+The study files in `studies/` change the design by ID with `os-optics-kit edit` and `os-optics-kit sweep`:
+
+| Step | Design | `expanded_waist` | Outcome |
+| --- | --- | --- | --- |
+| Swap L2 for a fused-silica lens, f = 100.3 mm | `swapped.json` | 1.4407 mm | FAIL |
+| Sweep L2 along the beam, −1 … +2 mm, 12 samples | `l2-sweep/` | 0.7323 … 2.0098 mm | 5 PASS, 7 FAIL |
+| Move L2 by the best shift, +0.54 mm | `final.json` | 1.99645 mm | PASS |
+
+The beam radius at the output plane (`output_beam_radius`, added by the swap) stays within 1 % throughout: the
+waist radius reacts to collimation, the radius at one plane barely does. Verified with os-optics 0.12.0 and catalog
+2026-10-28.1; run status PASS.

os_optics_kit/_data/cases/beam-expander/README.zh-CN.md

@@ -0,0 +1,36 @@
+# 目录扩束器
+
+两片目录中的平凸透镜（f = 50 mm 与 100 mm，N-BK7，直径 12.7 mm）把波长 780 nm、束腰半径 1 mm 的高斯光束扩束两倍。
+目标 `expanded_waist` 要求输出束腰半径为 1.9961 mm ± 1 %，用于衡量准直程度。元件固定在目录版本 2026-10-28.1。
+
+![沿透镜光轴的截面：L1 聚焦，L2 准直，output 面接收扩束后的光束](images/section.png)
+
+![扩束器的等轴测视图](images/iso.png)
+
+## 运行
+
+```bash
+os-optics-kit cases copy beam-expander --dest .
+cd beam-expander
+os-optics project run project.json --out-dir run
+os-optics results targets run
+```
+
+## 结果
+
+| 目标 | 数值 | 界限 | 评估 |
+| --- | --- | --- | --- |
+| `expanded_waist` | 1.99607 mm | 1.99612 mm ± 1 % | MET |
+
+## 更换透镜并恢复准直
+
+`studies/` 中的研究文件通过 `os-optics-kit edit` 与 `os-optics-kit sweep` 按 ID 修改设计：
+
+| 步骤 | 设计 | `expanded_waist` | 结果 |
+| --- | --- | --- | --- |
+| 把 L2 换成熔融石英透镜，f = 100.3 mm | `swapped.json` | 1.4407 mm | FAIL |
+| 沿光束扫描 L2，−1 … +2 mm，12 个样本 | `l2-sweep/` | 0.7323 … 2.0098 mm | 5 个 PASS，7 个 FAIL |
+| 按最佳位移 +0.54 mm 移动 L2 | `final.json` | 1.99645 mm | PASS |
+
+输出面上的光束半径（换镜时新增的 `output_beam_radius`）始终在 1 % 以内：束腰半径对准直敏感，单个面上的半径几乎不变。
+已用 os-optics 0.12.0 与目录 2026-10-28.1 验证；运行状态 PASS。

os_optics_kit/_data/cases/beam-expander/expected.json

@@ -0,0 +1,10 @@
+{
+  "catalog": "2026-10-28.1",
+  "engine": "0.12.0",
+  "schema": "os-optics-kit.case-expected",
+  "schema_version": 1,
+  "status": "PASS",
+  "targets": {
+    "expanded_waist": "MET"
+  }
+}

os_optics_kit/_data/cases/beam-expander/project.json

@@ -0,0 +1,160 @@
+{
+  "components": [
+    {
+      "custom_part": {
+        "custom_part_key": "user-laser",
+        "description": "User-supplied laser source."
+      },
+      "instance_id": "SRC",
+      "nominal_pose": {
+        "position_mm": [
+          -200.0,
+          0.0,
+          0.0
+        ],
+        "quaternion_wxyz": [
+          0.5,
+          0.5,
+          0.5,
+          0.5
+        ]
+      },
+      "optical_role": "source",
+      "retained_dofs": [],
+      "selected_parameters": [],
+      "source_model": {
+        "m2": 1.0,
+        "model_kind": "GAUSSIAN_BEAM",
+        "polarization": {
+          "angle_deg": 0.0,
+          "kind": "LINEAR"
+        },
+        "power_w": 0.001,
+        "waist_position_mm": 0.0,
+        "waist_radius_mm": 1.0,
+        "wavelength_nm": 780.0
+      }
+    },
+    {
+      "instance_id": "L1",
+      "nominal_pose": {
+        "position_mm": [
+          0.0,
+          0.0,
+          0.0
+        ],
+        "quaternion_wxyz": [
+          0.5,
+          0.5,
+          0.5,
+          0.5
+        ]
+      },
+      "optical_role": "lens",
+      "product": {
+        "catalog_version": "2026-10-28.1",
+        "optical_sku": "OS-OPT-LENS-PCX-D12P7-F50-T2P6-R25P8-NBK7-AR400-1100-W587P6"
+      },
+      "retained_dofs": [
+        {
+          "axis": "Tx",
+          "control": "MANUAL",
+          "frame": "COMPONENT_LOCAL"
+        },
+        {
+          "axis": "Ty",
+          "control": "MANUAL",
+          "frame": "COMPONENT_LOCAL"
+        },
+        {
+          "axis": "Tz",
+          "control": "NUMERICAL",
+          "frame": "COMPONENT_LOCAL"
+        }
+      ],
+      "selected_parameters": []
+    },
+    {
+      "instance_id": "L2",
+      "nominal_pose": {
+        "position_mm": [
+          152.841,
+          0.0,
+          0.0
+        ],
+        "quaternion_wxyz": [
+          0.5,
+          0.5,
+          -0.5,
+          -0.5
+        ]
+      },
+      "optical_role": "lens",
+      "product": {
+        "catalog_version": "2026-10-28.1",
+        "optical_sku": "OS-OPT-LENS-PCX-D12P7-F100-T2P2-R51P5-NBK7-AR400-1100-W587P6"
+      },
+      "retained_dofs": [
+        {
+          "axis": "Tx",
+          "control": "MANUAL",
+          "frame": "COMPONENT_LOCAL"
+        },
+        {
+          "axis": "Ty",
+          "control": "MANUAL",
+          "frame": "COMPONENT_LOCAL"
+        },
+        {
+          "axis": "Tz",
+          "control": "NUMERICAL",
+          "frame": "COMPONENT_LOCAL"
+        }
+      ],
+      "selected_parameters": []
+    }
+  ],
+  "materials": [],
+  "observations": [
+    {
+      "absorbing": false,
+      "aperture": {
+        "center_offset_mm": [
+          0.0,
+          0.0
+        ],
+        "obstruction_radius_mm": 0.0,
+        "radius_mm": 12.5,
+        "shape": "circle"
+      },
+      "medium": "air",
+      "observation_id": "output",
+      "pose": {
+        "position_mm": [
+          252.841,
+          0.0,
+          0.0
+        ],
+        "quaternion_wxyz": [
+          0.5,
+          0.5,
+          0.5,
+          0.5
+        ]
+      }
+    }
+  ],
+  "project_schema_version": "2.0",
+  "schema": "opensci.project",
+  "targets": [
+    {
+      "metric": "waist_radius_x_mm",
+      "observation_id": "output",
+      "parameters": [],
+      "target_id": "expanded_waist",
+      "target_value": 1.9961240310077522,
+      "tolerance_rel": 0.01,
+      "unit": "mm"
+    }
+  ]
+}

os_optics_kit/_data/cases/beam-expander/studies/beam_expander_l2_sweep.json

@@ -0,0 +1,61 @@
+{
+ "description": "Sweep of the L2 position along the beam (design +X) of the edited beam expander (--base: the Project written with beam_expander_swap_l2.json). Each sample moves L2 by the value with a rigid transform in the design frame. Both output targets are recorded: expanded_waist (waist_radius_x_mm) changes strongly with spacing because the nearly collimated output has a Rayleigh range of metres and its waist moves by metres per millimetre of defocus; output_beam_radius (beam_radius_mm at the plane 100 mm after L2) changes by less than 0.1 % over the same range. Feasible: expanded_waist PASS; best: smallest |expanded_waist - 1.9961240310077522 mm|.",
+ "parameters": [
+  {
+   "name": "l2_shift",
+   "unit": "mm",
+   "values": [
+    -1,
+    -0.5,
+    0,
+    0.25,
+    0.4,
+    0.5,
+    0.54,
+    0.55,
+    0.6,
+    0.7,
+    1,
+    2
+   ],
+   "ops": [
+    {
+     "op": "transform",
+     "selector": {
+      "ids": [
+       "L2"
+      ]
+     },
+     "translation_mm": [
+      "$value",
+      0,
+      0
+     ],
+     "frame": "design"
+    }
+   ]
+  }
+ ],
+ "max_evaluations": 20,
+ "constraints": [
+  {
+   "target": "expanded_waist",
+   "assessment": [
+    "MET"
+   ]
+  }
+ ],
+ "derived": [
+  {
+   "name": "waist_error_mm",
+   "op": "abs_diff",
+   "a": "target:expanded_waist",
+   "b": 1.9961240310077522,
+   "unit": "mm"
+  }
+ ],
+ "objective": {
+  "column": "derived:waist_error_mm",
+  "sense": "minimize"
+ }
+}

os_optics_kit/_data/cases/beam-expander/studies/beam_expander_move_l2.json

@@ -0,0 +1,22 @@
+{
+ "description": "Apply the best sweep sample to the edited beam expander: move L2 by 540 um along design +X (given in um, converted to mm by os-optics-kit edit).",
+ "ops": [
+  {
+   "op": "transform",
+   "selector": {
+    "ids": [
+     "L2"
+    ]
+   },
+   "translation_mm": [
+    {
+     "value": 540,
+     "unit": "um"
+    },
+    0,
+    0
+   ],
+   "frame": "design"
+  }
+ ]
+}

os_optics_kit/_data/cases/beam-expander/studies/beam_expander_swap_l2.json

@@ -0,0 +1,22 @@
+{
+ "description": "Edit of the catalog beam_expander example (os-optics project example --kind beam_expander). Op 0 adds target output_beam_radius: beam_radius_mm (1/e^2 radius at the output plane) with the same target value and 1 % tolerance as the example's expanded_waist target (waist_radius_x_mm: radius of the waist the output beam has or had, a collimation measure). Op 1 replaces L2 (N-BK7, focal length 100 mm) by the fused-silica plano-convex lens with focal length 100.3 mm listed by os-optics-kit candidates for 780 nm (catalog 2026-10-28.1); L2 keeps its pose, so the pair is no longer afocal.",
+ "ops": [
+  {
+   "op": "add_target",
+   "target": {
+    "target_id": "output_beam_radius",
+    "metric": "beam_radius_mm",
+    "observation_id": "output",
+    "unit": "mm",
+    "target_value": 1.9961240310077522,
+    "tolerance_rel": 0.01,
+    "parameters": []
+   }
+  },
+  {
+   "op": "set_component_product",
+   "instance_id": "L2",
+   "optical_sku": "OS-OPT-LENS-PCX-D12P7-F100P3-T2P2-R46-UVFS-AR400-1100-W587P6"
+  }
+ ]
+}

os_optics_kit/_data/cases/detector-measurements/CASE.md

@@ -0,0 +1,56 @@
+---
+name: detector-measurements
+title: Detector linearity and reference-channel normalization
+summary: A 1 mW, 532 nm beam is split 50:50 onto a signal and a reference detector, each with a 2.5 mm radius active area. Two synthetic data sets with known answers calibrate the signal detector's linearity and normalize slow source drift by the reference channel.
+engine: 0.12.0
+catalog: none
+project: project.json
+tools: measurements
+tags: catalog-free, measurements, detector, calibration, beam-splitter, reference-channel
+license: MIT
+---
+
+## What it shows
+
+`project.json` is the measurement setup: Gaussian source `SRC` (0.5 mm waist), native plate splitter `BS`
+(R = T = 0.5) at 45°, absorbing planes `signal` (transmitted) and `reference` (reflected) 100 mm away. The run confirms
+that each detector receives 0.5 mW and that the beam (0.5046 mm radius) fits the active area, the conditions the
+analysis assumes. `os-optics-kit measurements` subtracts dark readings, optionally divides by the reference
+channel, fits a line and checks the RMSE. The CSV readings are synthetic, with deliberate bad rows:
+
+| Data | Rows used | Fit |
+| --- | --- | --- |
+| `data/detector_response.csv` | 7 of 10 | 2 V/mW · P + 0.005 V, RMSE 0.002 V |
+| `data/reference_drift.csv` | 8 of 13 | ratio 0.4, slope 0, RMSE 0 |
+
+Both analyses return WARNING (rows excluded) with the RMSE target PASS.
+
+## Run
+
+```bash
+os-optics project run project.json --out-dir run
+os-optics results targets run
+os-optics-kit measurements data/detector_response.csv --x input_power_mW --signal signal_V \
+  --background dark_V --x-unit mW --signal-unit V --maximum-rmse 0.003 --out detector
+os-optics-kit measurements data/reference_drift.csv --x time_s --signal signal_V --background dark_V \
+  --x-unit s --signal-unit V --reference reference_V --reference-background reference_dark_V \
+  --reference-unit V --maximum-rmse 0.000000000001 --out reference
+```
+
+## Targets
+
+| Target | Metric | Plane | Bound | Verified |
+| --- | --- | --- | --- | --- |
+| `signal_power`, `reference_power` | `power_W` | `signal`, `reference` | 0.5 mW ± 1 % | 0.5 mW, MET |
+| `signal_beam_radius`, `reference_beam_radius` | `beam_radius_mm` | `signal`, `reference` | ≤ 1 mm | 0.5046 mm, MET |
+
+## Baseline
+
+os-optics 0.12.0, no catalog: run status PASS (`expected.json`).
+`os-optics-kit cases verify detector-measurements` repeats the run and compares it.
+
+## Files
+
+- `project.json`, `expected.json`: the setup and its verified outcome.
+- `data/`: the two CSV files and their construction and attribution (`data/README.md`).
+- `README.md`, `README.zh-CN.md`, `images/top.png`: the illustrated page.

os_optics_kit/_data/cases/detector-measurements/README.md

@@ -0,0 +1,37 @@
+# Detector linearity and reference-channel normalization
+
+A 1 mW, 532 nm laser beam is split 50:50 by a plate beam splitter. The transmitted half reaches the signal detector,
+the reflected half the reference detector; both detectors have a 2.5 mm radius active area. The engine run confirms
+the power on each detector and that the beam fits the active area. Two synthetic data sets then calibrate the
+signal detector and remove slow source drift with the reference channel.
+
+![Top view: source SRC, splitter BS, signal detector along +X and reference detector along +Y](images/top.png)
+
+## Run it
+
+```bash
+os-optics-kit cases copy detector-measurements --dest .
+cd detector-measurements
+os-optics project run project.json --out-dir run
+os-optics-kit measurements data/detector_response.csv --x input_power_mW --signal signal_V \
+  --background dark_V --x-unit mW --signal-unit V --maximum-rmse 0.003 --out detector
+```
+
+## Results
+
+| Target | Value | Bound | Assessment |
+| --- | --- | --- | --- |
+| `signal_power` | 0.5 mW | 0.5 mW ± 1 % | MET |
+| `reference_power` | 0.5 mW | 0.5 mW ± 1 % | MET |
+| `signal_beam_radius` | 0.5046 mm | ≤ 1 mm | MET |
+| `reference_beam_radius` | 0.5046 mm | ≤ 1 mm | MET |
+
+| Data | Rows used | Fitted response |
+| --- | --- | --- |
+| `data/detector_response.csv` (dark-subtracted signal vs incident power) | 7 of 10 | 2 V/mW · P + 0.005 V, RMSE 0.002 V |
+| `data/reference_drift.csv` (signal / reference, both dark-subtracted, over 7 s) | 8 of 13 | 0.4, constant, RMSE 0 |
+
+Both channels drift by 7 % over the scan; their ratio does not. Rows with a missing or invalid reading or a
+non-positive dark-subtracted reference are excluded and listed in `processed.csv`; the analyses report WARNING for the exclusions and PASS for the
+RMSE targets. `data/README.md` gives the formulas behind the data and their attribution. Verified with
+os-optics 0.12.0; run status PASS.

os_optics_kit/_data/cases/detector-measurements/README.zh-CN.md

@@ -0,0 +1,35 @@
+# 探测器线性度与参考通道归一化
+
+1 mW、532 nm 的激光束由平板分束镜按 50:50 分开：透射光到达信号探测器，反射光到达参考探测器；两个探测器的有效区域
+半径均为 2.5 mm。引擎运行确认每个探测器上的功率，并确认光束落在有效区域之内。随后用两组合成数据标定信号探测器，
+并借助参考通道消除光源的缓慢漂移。
+
+![俯视图：光源 SRC、分束镜 BS、沿 +X 的信号探测器与沿 +Y 的参考探测器](images/top.png)
+
+## 运行
+
+```bash
+os-optics-kit cases copy detector-measurements --dest .
+cd detector-measurements
+os-optics project run project.json --out-dir run
+os-optics-kit measurements data/detector_response.csv --x input_power_mW --signal signal_V \
+  --background dark_V --x-unit mW --signal-unit V --maximum-rmse 0.003 --out detector
+```
+
+## 结果
+
+| 目标 | 数值 | 界限 | 评估 |
+| --- | --- | --- | --- |
+| `signal_power` | 0.5 mW | 0.5 mW ± 1 % | MET |
+| `reference_power` | 0.5 mW | 0.5 mW ± 1 % | MET |
+| `signal_beam_radius` | 0.5046 mm | ≤ 1 mm | MET |
+| `reference_beam_radius` | 0.5046 mm | ≤ 1 mm | MET |
+
+| 数据 | 使用行数 | 拟合响应 |
+| --- | --- | --- |
+| `data/detector_response.csv`（扣除暗读数的信号对入射功率） | 10 行中 7 行 | 2 V/mW · P + 0.005 V，RMSE 0.002 V |
+| `data/reference_drift.csv`（信号 / 参考，均扣除暗读数，7 s 内） | 13 行中 8 行 | 0.4，恒定，RMSE 0 |
+
+两个通道在扫描期间都漂移了 7 %，二者之比保持不变。读数缺失或无效、或扣除暗读数后参考值非正的行被排除，并列在 `processed.csv` 中；
+两项分析因排除行而报告 WARNING，RMSE 目标为 PASS。`data/README.md` 给出数据的构造公式与来源说明。
+已用 os-optics 0.12.0 验证；运行状态 PASS。

os_optics_kit/_data/cases/detector-measurements/data/README.md

@@ -0,0 +1,60 @@
+# Synthetic measurement data and attribution
+
+The readings in these two CSV files are synthetic: constructed from the formulas
+below with known answers, for the `os-optics-kit measurements` analysis of this
+case ([README](../README.md)).
+
+## Detector response
+
+`detector_response.csv` has `input_power_mW` (mW), `signal_V` (V), `dark_V` (V),
+and the textual `data_origin` label. For the seven valid rows, indexed `i = 0..6`:
+
+```text
+input_power_mW = i / 10
+dark_V = 0.020
+signal_V = dark_V + 2 * input_power_mW + 0.005 + residual_V[i]
+residual_V = [0.002, -0.003, 0.001, 0, 0.001, -0.003, 0.002]
+```
+
+The residuals sum to zero and have zero covariance with x. Thus the OLS slope is
+2 V/mW, intercept is 0.005 V, and RMSE is exactly 0.002 V in real arithmetic.
+Tests accept absolute error of 1e-12 for these quantities. Three appended rows
+exercise missing signal, invalid incident power, and missing dark background.
+
+## Reference drift
+
+`reference_drift.csv` adds `time_s` (s), `reference_V` (V), and
+`reference_dark_V` (V). For eight valid rows, `time_s = i = 0..7`:
+
+```text
+reference_dark_V = 0.010
+dark_V = 0.020
+reference_V = reference_dark_V + 1 + 0.01 * i
+signal_V = dark_V + 0.4 * (1 + 0.01 * i)
+```
+
+The dark-subtracted channels grow by 7%; their quotient stays 0.4. The ratio's
+fitted slope is zero, intercept is 0.4, and RMSE is zero in real arithmetic.
+Tests use absolute tolerance 1e-12. R² is undefined for this constant response.
+Five appended rows exercise zero corrected reference, missing reference,
+invalid signal, negative corrected reference, and missing reference background.
+
+## Sources and changes
+
+The workflow ideas adapt **JunLin615 and contributors**, *Free-space Optical
+Experiment Benchmark*, at commit
+`e72ad3a9b6be12c7f0dbb00121fda23289c4e908`:
+
+- [EX-DETECT-01: Detector linearity calibration](https://github.com/JunLin615/free-space-optical-experiment-benchmark/blob/e72ad3a9b6be12c7f0dbb00121fda23289c4e908/benchmark/case_library/EX-DETECT-01.md), blob `81fc82e61aec5e3929b51f45eea4eb8c6b869817`.
+- [EX-DRIFT-01: Reference channel for slow drift](https://github.com/JunLin615/free-space-optical-experiment-benchmark/blob/e72ad3a9b6be12c7f0dbb00121fda23289c4e908/benchmark/case_library/EX-DRIFT-01.md), blob `55374f93e53046837423e909b2e55696bbe12854`.
+
+Benchmark case content is licensed under [Creative Commons Attribution 4.0
+International](https://creativecommons.org/licenses/by/4.0/), as recorded in its
+[LICENSE-CONTENT](https://github.com/JunLin615/free-space-optical-experiment-benchmark/blob/e72ad3a9b6be12c7f0dbb00121fda23289c4e908/LICENSE-CONTENT).
+These adaptations replace the detector case's illustrative 12% filter test with
+a calibrated-power scan, add explicit offsets, deterministic residuals and
+invalid records, and turn the reference case's 7% shared-drift idea into concrete
+CSV values. The Python implementation, equations for these fixtures, and actual
+data values were created for this repository. No benchmark dataset, gold answer,
+or scorer is copied. The case README explains the adapted workflows;
+generated provenance records these source links and the exact revision.

os_optics_kit/_data/cases/detector-measurements/data/detector_response.csv

@@ -0,0 +1,11 @@
+input_power_mW,signal_V,dark_V,data_origin
+0,0.027,0.020,synthetic
+0.1,0.222,0.020,synthetic
+0.2,0.426,0.020,synthetic
+0.3,0.625,0.020,synthetic
+0.4,0.826,0.020,synthetic
+0.5,1.022,0.020,synthetic
+0.6,1.227,0.020,synthetic
+0.7,,0.020,synthetic_missing_signal
+invalid,1.625,0.020,synthetic_invalid_power
+0.9,1.825,,synthetic_missing_background

os_optics_kit/_data/cases/detector-measurements/data/reference_drift.csv

@@ -0,0 +1,14 @@
+time_s,signal_V,dark_V,reference_V,reference_dark_V,data_origin
+0,0.420,0.020,1.010,0.010,synthetic
+1,0.424,0.020,1.020,0.010,synthetic
+2,0.428,0.020,1.030,0.010,synthetic
+3,0.432,0.020,1.040,0.010,synthetic
+4,0.436,0.020,1.050,0.010,synthetic
+5,0.440,0.020,1.060,0.010,synthetic
+6,0.444,0.020,1.070,0.010,synthetic
+7,0.448,0.020,1.080,0.010,synthetic
+8,0.452,0.020,0.010,0.010,synthetic_zero_corrected_reference
+9,0.456,0.020,,0.010,synthetic_missing_reference
+10,invalid,0.020,1.110,0.010,synthetic_invalid_signal
+11,0.464,0.020,0.005,0.010,synthetic_negative_corrected_reference
+12,0.468,0.020,1.130,,synthetic_missing_reference_background