obdeect 0.7.0__tar.gz → 0.7.1__tar.gz

{obdeect-0.7.0 → obdeect-0.7.1}/AGENTS.md

@@ -51,9 +51,8 @@ scope. Read the relevant code and tests first; use `docs/VALIDATION.md` and
 ## Changes and validation
 
 - Make the narrowest complete change and preserve unrelated work.
-- Do not add anything under `docs/changes/` for current work. Leave that
-  directory untouched unless the user explicitly asks for a changelog or
-  release-note change.
+- Add an appropriate Towncrier fragment under `docs/changes/` for changes
+  that should appear in the release notes.
 - Add or update a focused test for every behavioural change. Establish analytic
   kernel and primitive tests before optical-model, cross-tool, or performance tests.
 - Preserve results across photon ordering, blocks, and thread counts. Record

{obdeect-0.7.0 → obdeect-0.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: obdeect
-Version: 0.7.0
+Version: 0.7.1
 Summary: Ray tracing for imaging atmospheric Cherenkov telescopes
 Author: obdeect contributors
 License: BSD 3-Clause License
@@ -64,6 +64,8 @@ Description-Content-Type: text/markdown
   <img src="docs/_static/images/obdeect_21ratio_small.jpg" alt="Obdeect optical ray tracing for imaging atmospheric Cherenkov telescopes" width="800">
 </p>
 
+[![DOI](https://zenodo.org/badge/1376945125.svg)](https://doi.org/10.5281/zenodo.23942573)
+
 `obdeect` is a C++20 optical ray tracer for imaging atmospheric Cherenkov
 telescopes. The C++ core uses only the standard library. Python compiles
 optical models from the simulation models, traces photons, and plots results;

{obdeect-0.7.0 → obdeect-0.7.1}/README.md

@@ -4,6 +4,8 @@
   <img src="docs/_static/images/obdeect_21ratio_small.jpg" alt="Obdeect optical ray tracing for imaging atmospheric Cherenkov telescopes" width="800">
 </p>
 
+[![DOI](https://zenodo.org/badge/1376945125.svg)](https://doi.org/10.5281/zenodo.23942573)
+
 `obdeect` is a C++20 optical ray tracer for imaging atmospheric Cherenkov
 telescopes. The C++ core uses only the standard library. Python compiles
 optical models from the simulation models, traces photons, and plots results;

obdeect-0.7.1/docs/changes/31.bugfix.md

@@ -0,0 +1 @@
+Accept two components for axes offsets (as expected by the simulation models).

{obdeect-0.7.0 → obdeect-0.7.1}/docs/optical-models.md

@@ -31,15 +31,14 @@ path of the first error. Surface and obscurer ids are unique.
 
 Some telescopes have the optical origin displaced from the rotation axes. The
 sim_telarray `axes_offsets` record gives the horizontal offset between the
-azimuth and altitude axes, in the record's units (cm in sim_telarray). The
-first component is that offset; a non-zero second component (displacement
-perpendicular to the optical axis) is rejected at compile time.
+azimuth and altitude axes, followed by the altitude-to-optical-axis offset,
+in the record's units (cm in sim_telarray).
 
 The compiler stores the offset in the telescope frame, in metres, as
 `optics.axes_offset_m` = [x, y, z]. The key is written only when the offset is
-non-zero, and it needs the zenith angle of the compilation. The offset is
-`(O cos(theta), 0, O sin(theta))` for an along-axis offset `O` at zenith
-`theta`. The loader requires three numbers.
+non-zero, and it needs the zenith angle of the compilation. For components
+`(O, T)` and zenith `theta`, the offset is
+`(O cos(theta) - T, 0, O sin(theta))`. The loader requires three numbers.
 
 The offset is applied only by `trace_bunches`, which subtracts it from its frame
 offset (see [Batch tracing](batch-tracing.md)). `trace`, `star_photons` and the

{obdeect-0.7.0 → obdeect-0.7.1}/python/obdeect/compiler.py

@@ -170,13 +170,11 @@ def compile_model(
 def _axes_offset_m(p: _Parameters, zenith_deg: float | None) -> list[float]:
     """Offset of the optical origin from the telescope sphere centre, telescope frame [m].
 
-    The ``axes_offsets`` record (sim_telarray ``axes_offset``, cm) holds the horizontal offset
-    of the altitude axis from the azimuth axis, measured along x of the azimuth-rotated frame,
-    and the displacement perpendicular to the optical axis, which must be zero. A photon at
-    ground point P is then at R (P - O) in the telescope frame, where R maps the ground frame to
-    the telescope frame. R O does not depend on the azimuth, so the offset is stored in the
-    telescope frame at the compiled zenith angle: (O cos(theta), 0, O sin(theta)). Zero when the
-    record is absent or zero; a non-zero offset needs the zenith angle.
+    The ``axes_offsets`` record (sim_telarray ``axes_offset``) holds the horizontal offset
+    between the azimuth and altitude axes followed by the altitude-to-optical-axis offset.
+    The first component transforms to (along*cos(theta), 0, along*sin(theta)); the second is
+    subtracted along telescope-frame x. Zero when the record is absent or zero; a non-zero
+    offset needs the zenith angle.
     """
     if "axes_offsets" not in p:
         return [0.0, 0.0, 0.0]
@@ -184,22 +182,17 @@ def _axes_offset_m(p: _Parameters, zenith_deg: float | None) -> list[float]:
     if len(values) > 2:
         raise ModelError("axes_offsets has more than two components")
     along = number(values[0], "axes_offsets") * length_unit_m(units[0], "axes_offsets")
-    perpendicular = (
+    transverse = (
         number(values[1], "axes_offsets") * length_unit_m(units[1], "axes_offsets")
         if len(values) == 2
         else 0.0
     )
-    if perpendicular != 0.0:
-        raise NotImplementedError(
-            "a non-zero second axes_offsets component (displacement perpendicular to the optical "
-            "axis) is not supported"
-        )
-    if along == 0.0:
+    if along == 0.0 and transverse == 0.0:
         return [0.0, 0.0, 0.0]
     if zenith_deg is None:
         raise ModelError("axes_offsets needs the telescope zenith angle")
     theta = math.radians(zenith_deg)
-    return [along * math.cos(theta), 0.0, along * math.sin(theta)]
+    return [along * math.cos(theta) - transverse, 0.0, along * math.sin(theta)]
 
 
 def _sampling(p: _Parameters, optics: dict[str, Any]) -> dict[str, float]:

{obdeect-0.7.0 → obdeect-0.7.1}/python/tests/test_axes_offset.py

@@ -116,9 +116,35 @@ def test_axes_offset_follows_the_zenith_angle():
     assert model.axes_offset_m == pytest.approx((1.6, 0.0, 0.0))
 
 
-def test_non_zero_perpendicular_component_is_not_supported():
-    with pytest.raises(NotImplementedError, match="perpendicular"):
-        compiled([OFFSET_CM, 10.0])
+def test_second_axes_offset_component_is_transverse_to_the_optical_axis():
+    model = compiled([OFFSET_CM, 10.0])
+    assert model.axes_offset_m == pytest.approx((
+        OFFSET_CM / 100 * COS - 0.1,
+        0.0,
+        OFFSET_CM / 100 * SIN,
+    ))
+
+
+def test_equal_offsets_align_optical_and_azimuth_axes_at_zenith():
+    model = compiled([OFFSET_CM, OFFSET_CM], zenith_deg=0.0)
+    assert model.axes_offset_m == pytest.approx(ORIGIN)
+
+
+def test_transverse_offset_matches_explicit_frame_transform(reference):
+    model = compiled([OFFSET_CM, 10.0])
+    bunches = ground_bunches(3000)
+    # sim_telarray translates by -O before rotation and +T in telescope x.
+    frame_offset = -ROTATION @ GROUND_OFFSET_M + np.array([0.1, 0.0, 0.0])
+    expected = trace_ground(reference, bunches, 30.0, offset_m=frame_offset)
+    actual = trace_ground(model, bunches, 30.0)
+    assert len(actual["weight"]) > 0
+    for name in ("bunch_index", "position_m", "direction", "time_ns", "weight"):
+        np.testing.assert_allclose(actual[name], expected[name], atol=1e-9)
+
+
+def test_second_axes_offset_component_needs_the_zenith_angle():
+    with pytest.raises(ModelError, match="zenith"):
+        compiled([0.0, 10.0], zenith_deg=None)
 
 
 def test_axes_offset_needs_the_zenith_angle():