obdeect-propagation 0.8.0__tar.gz

obdeect_propagation-0.8.0/CMakeLists.txt

@@ -0,0 +1,84 @@
+cmake_minimum_required(VERSION 3.20)
+project(obdeect_propagation LANGUAGES CXX)
+
+option(OBDEECT_PROPAGATION_BUILD_TESTING "Build the C++ tests" ON)
+if(DEFINED SKBUILD_PLATLIB_DIR)
+  set(OBDEECT_PROPAGATION_BUILD_PYTHON_API_DEFAULT ON)
+else()
+  set(OBDEECT_PROPAGATION_BUILD_PYTHON_API_DEFAULT OFF)
+endif()
+option(OBDEECT_PROPAGATION_BUILD_PYTHON_API "Build the Python extension" ${OBDEECT_PROPAGATION_BUILD_PYTHON_API_DEFAULT})
+option(OBDEECT_PROPAGATION_BUILD_TOOLS "Build the obdeect propagation run command-line tool" ON)
+
+# The stream component: the target of the combined build, else the stream sources next to
+# this component (builds from the repository), else an installed package (sdist builds).
+if(NOT TARGET obdeect::stream)
+  if(EXISTS ${CMAKE_CURRENT_SOURCE_DIR}/../stream/CMakeLists.txt)
+    set(OBDEECT_STREAM_BUILD_TESTING OFF CACHE BOOL "" FORCE)
+    set(OBDEECT_STREAM_BUILD_TOOLS OFF CACHE BOOL "" FORCE)
+    set(OBDEECT_STREAM_BUILD_CAPI OFF CACHE BOOL "" FORCE)
+    set(OBDEECT_STREAM_BUILD_PYTHON_API OFF CACHE BOOL "" FORCE)
+    set(OBDEECT_STREAM_INSTALL OFF CACHE BOOL "" FORCE)
+    add_subdirectory(${CMAKE_CURRENT_SOURCE_DIR}/../stream ${CMAKE_CURRENT_BINARY_DIR}/stream)
+    message(STATUS "obdeect propagation: using the stream sources in ../stream")
+  else()
+    find_package(Python 3.14 COMPONENTS Interpreter)
+    if(Python_Interpreter_FOUND AND NOT obdeect_stream_DIR)
+      execute_process(COMMAND "${Python_EXECUTABLE}" -m obdeect.stream --cmake-dir
+                      OUTPUT_VARIABLE obdeect_stream_DIR OUTPUT_STRIP_TRAILING_WHITESPACE ERROR_QUIET)
+    endif()
+    find_package(obdeect_stream CONFIG REQUIRED)
+    message(STATUS "obdeect propagation: using the installed stream package ${obdeect_stream_VERSION} (${obdeect_stream_DIR})")
+  endif()
+endif()
+
+# Header-only, standard-library-only core.
+add_library(obdeect_propagation_core INTERFACE)
+target_include_directories(obdeect_propagation_core INTERFACE ${CMAKE_CURRENT_SOURCE_DIR}/cpp/include)
+target_compile_features(obdeect_propagation_core INTERFACE cxx_std_20)
+target_link_libraries(obdeect_propagation_core INTERFACE obdeect::stream)
+# Identical floating-point results for any thread count and chunk size on one
+# platform: no implicit fused multiply-add contraction.
+target_compile_options(obdeect_propagation_core INTERFACE -ffp-contract=off)
+
+function(obdeect_propagation_enable_warnings target)
+  target_compile_options(${target} PRIVATE -Wall -Wextra -Wpedantic -Werror)
+endfunction()
+
+if(OBDEECT_PROPAGATION_BUILD_PYTHON_API)
+  find_package(Python 3.14 COMPONENTS Interpreter Development.Module REQUIRED)
+  execute_process(COMMAND "${Python_EXECUTABLE}" -m nanobind --cmake_dir
+                  OUTPUT_VARIABLE nanobind_DIR OUTPUT_STRIP_TRAILING_WHITESPACE
+                  COMMAND_ERROR_IS_FATAL ANY)
+  find_package(nanobind CONFIG REQUIRED)
+  nanobind_add_module(_core NB_STATIC cpp/bindings/core.cpp)
+  target_link_libraries(_core PRIVATE obdeect_propagation_core)
+  obdeect_propagation_enable_warnings(_core)
+  install(TARGETS _core LIBRARY DESTINATION obdeect/propagation)
+endif()
+
+if(OBDEECT_PROPAGATION_BUILD_TOOLS)
+  add_executable(obdeect-propagation-run cpp/tools/propagate.cpp)
+  target_link_libraries(obdeect-propagation-run PRIVATE obdeect_propagation_core)
+  obdeect_propagation_enable_warnings(obdeect-propagation-run)
+  # Wheels: inside the package, run through `obdeect propagation run`.
+  if(DEFINED SKBUILD_PLATLIB_DIR)
+    install(TARGETS obdeect-propagation-run RUNTIME DESTINATION obdeect/propagation/bin)
+  endif()
+endif()
+
+if(OBDEECT_PROPAGATION_BUILD_TESTING)
+  enable_testing()
+  foreach(test_name version transmission thinning pipeline profile refraction timing
+                    propagator scattering stream_contract physics)
+    add_executable(obdeect_propagation_test_${test_name} cpp/tests/test_${test_name}.cpp)
+    target_link_libraries(obdeect_propagation_test_${test_name} PRIVATE obdeect_propagation_core)
+    # check.hpp lives with the stream tests; tests are built from the repository only, never from an sdist.
+    target_include_directories(obdeect_propagation_test_${test_name} PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../stream/cpp/tests)
+    # Reference data: cpp/tests/data (see test_transmission.cpp).
+    target_compile_definitions(obdeect_propagation_test_${test_name}
+                               PRIVATE OBDEECT_PROPAGATION_TEST_DATA_DIR="${CMAKE_CURRENT_SOURCE_DIR}/cpp/tests/data")
+    obdeect_propagation_enable_warnings(obdeect_propagation_test_${test_name})
+    add_test(NAME ${test_name} COMMAND obdeect_propagation_test_${test_name})
+  endforeach()
+endif()

obdeect_propagation-0.8.0/PKG-INFO

@@ -0,0 +1,49 @@
+Metadata-Version: 2.4
+Name: obdeect-propagation
+Version: 0.8.0
+Summary: Atmospheric propagation of Cherenkov and artificial-source photons
+Author: obdeect contributors
+License-Expression: BSD-3-Clause
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: C++
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Requires-Python: >=3.14
+Requires-Dist: numpy>=2.3
+Requires-Dist: obdeect-stream==0.8.0
+Provides-Extra: dev
+Requires-Dist: nanobind>=3.1; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: myst-parser; extra == "docs"
+Requires-Dist: pydata-sphinx-theme; extra == "docs"
+Requires-Dist: pyyaml; extra == "docs"
+Requires-Dist: sphinx; extra == "docs"
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.8; extra == "plot"
+Description-Content-Type: text/markdown
+
+# obdeect-propagation
+
+Atmospheric propagation for Cherenkov-telescope simulations: extinction, refraction and timing
+from the refractive-index profile, optional single scattering, and early photon thinning. The
+C++20 core uses only the standard library. It has a Python API and works on photon streams.
+
+```sh
+pip install obdeect-propagation  # this component only (also installs obdeect-stream)
+pip install obdeect              # all obdeect components
+```
+
+Requires Python 3.14 or higher.
+
+## Commands
+
+```sh
+obdeect propagation run --transmission atm.dat --site-altitude 2156 --seed 1 -i in.ps -o out.ps
+obdeect propagation convert-table ...       # convert an atmospheric transmission table
+```
+
+Full documentation and the repository README: https://github.com/gammasim/obdeect

obdeect_propagation-0.8.0/README.md

@@ -0,0 +1,21 @@
+# obdeect-propagation
+
+Atmospheric propagation for Cherenkov-telescope simulations: extinction, refraction and timing
+from the refractive-index profile, optional single scattering, and early photon thinning. The
+C++20 core uses only the standard library. It has a Python API and works on photon streams.
+
+```sh
+pip install obdeect-propagation  # this component only (also installs obdeect-stream)
+pip install obdeect              # all obdeect components
+```
+
+Requires Python 3.14 or higher.
+
+## Commands
+
+```sh
+obdeect propagation run --transmission atm.dat --site-altitude 2156 --seed 1 -i in.ps -o out.ps
+obdeect propagation convert-table ...       # convert an atmospheric transmission table
+```
+
+Full documentation and the repository README: https://github.com/gammasim/obdeect

obdeect_propagation-0.8.0/cpp/bindings/core.cpp

@@ -0,0 +1,26 @@
+// Python.h must precede all standard headers (it sets feature-test macros such as
+// _POSIX_C_SOURCE), so the nanobind headers come first.
+#include <nanobind/nanobind.h>
+#include <nanobind/stl/tuple.h>
+
+#include "extinction_bindings.hpp"
+#include "obdeect/propagation/version.hpp"
+#include "profile_bindings.hpp"
+#include "propagator_bindings.hpp"
+#include "scattering_bindings.hpp"
+
+#include <tuple>
+
+namespace nb = nanobind;
+
+NB_MODULE(_core, module) {
+  module.doc() = "obdeect propagation native core";
+  module.def("core_version", [] {
+    return std::make_tuple(obdeect::propagation::version_major, obdeect::propagation::version_minor,
+                           obdeect::propagation::version_patch);
+  });
+  bind_extinction(module);
+  bind_profile(module);
+  bind_propagator(module);
+  bind_scattering(module);
+}

obdeect_propagation-0.8.0/cpp/bindings/extinction_bindings.hpp

@@ -0,0 +1,238 @@
+#pragma once
+
+// nanobind bindings of the atmosphere step: TransmissionTable and apply_extinction.
+// Included by core.cpp only; the C++ core stays free of Python.
+
+#include <nanobind/nanobind.h>
+#include <nanobind/ndarray.h>
+#include <nanobind/stl/string.h>
+#include <nanobind/stl/tuple.h>
+
+#include "obdeect/propagation/extinction.hpp"
+#include "obdeect/propagation/pipeline.hpp"
+#include "obdeect/propagation/thinning.hpp"
+#include "obdeect/propagation/transmission.hpp"
+#include "obdeect/propagation/wavelength.hpp"
+
+#include "obdeect/stream/format.hpp"
+#include "obdeect/stream/photons.hpp"
+
+#include <algorithm>
+#include <cstddef>
+#include <cstdint>
+#include <stdexcept>
+#include <string>
+#include <tuple>
+#include <utility>
+#include <vector>
+
+namespace obdeect_propagation_bindings {
+
+namespace nb = nanobind;
+
+using DoubleArray = nb::ndarray<const double, nb::ndim<1>, nb::c_contig, nb::device::cpu>;
+using FloatArray = nb::ndarray<const float, nb::ndim<1>, nb::c_contig, nb::device::cpu>;
+
+// Hand a vector to Python without copying; the returned array owns the vector.
+template <class T> nb::ndarray<nb::numpy, T, nb::ndim<1>> to_numpy(std::vector<T> values) {
+  if (values.capacity() == 0) {
+    values.reserve(1); // a non-null data pointer also for empty arrays
+  }
+  auto *holder = new std::vector<T>(std::move(values));
+  nb::capsule owner(holder, [](void *p) noexcept { delete static_cast<std::vector<T> *>(p); });
+  return nb::ndarray<nb::numpy, T, nb::ndim<1>>(holder->data(), {holder->size()}, owner);
+}
+
+inline std::vector<double> to_vector(const DoubleArray &array) {
+  return std::vector<double>(array.data(), array.data() + array.size());
+}
+
+inline void bind_table(nb::module_ &module) {
+  using obdeect::propagation::TransmissionTable;
+  nb::class_<TransmissionTable>(module, "TransmissionTable")
+      .def(nb::new_([](const std::string &path, double site_altitude_m) {
+             return TransmissionTable::from_file(path, site_altitude_m);
+           }),
+           nb::arg("path"), nb::arg("site_altitude_m"))
+      .def_prop_ro("observation_level_m", &TransmissionTable::observation_level_m)
+      .def_prop_ro("first_wavelength_nm", &TransmissionTable::first_wavelength_nm)
+      .def_prop_ro("last_wavelength_nm", &TransmissionTable::last_wavelength_nm)
+      .def(
+          "optical_depth",
+          [](const TransmissionTable &self, const DoubleArray &wavelength_nm,
+             const DoubleArray &height_m) {
+            if (height_m.size() != wavelength_nm.size()) {
+              throw std::invalid_argument("arrays must have the same length");
+            }
+            std::vector<double> out(wavelength_nm.size());
+            for (std::size_t i = 0; i < out.size(); ++i) {
+              out[i] = self.optical_depth<double>(wavelength_nm.data()[i], height_m.data()[i]);
+            }
+            return to_numpy(std::move(out));
+          },
+          nb::arg("wavelength_nm"), nb::arg("height_m"))
+      .def(
+          "transmission",
+          [](const TransmissionTable &self, const DoubleArray &wavelength_nm,
+             const DoubleArray &zem_m, const DoubleArray &airmass) {
+            const std::size_t n = wavelength_nm.size();
+            if (zem_m.size() != n || airmass.size() != n) {
+              throw std::invalid_argument("arrays must have the same length");
+            }
+            std::vector<double> out(n);
+            for (std::size_t i = 0; i < n; ++i) {
+              out[i] = self.transmission<double>(wavelength_nm.data()[i], zem_m.data()[i],
+                                                 airmass.data()[i]);
+            }
+            return to_numpy(std::move(out));
+          },
+          nb::arg("wavelength_nm"), nb::arg("zem_m"), nb::arg("airmass"))
+      .def(
+          "transmission2",
+          [](const TransmissionTable &self, const DoubleArray &wavelength_nm,
+             const DoubleArray &zem_m, const DoubleArray &airmass, const DoubleArray &od_tel,
+             const DoubleArray &od_focus) {
+            const std::size_t n = wavelength_nm.size();
+            if (zem_m.size() != n || airmass.size() != n || od_tel.size() != n ||
+                od_focus.size() != n) {
+              throw std::invalid_argument("arrays must have the same length");
+            }
+            std::vector<double> out(n);
+            for (std::size_t i = 0; i < n; ++i) {
+              out[i] = self.transmission2<double>(wavelength_nm.data()[i], zem_m.data()[i],
+                                                  airmass.data()[i], od_tel.data()[i],
+                                                  od_focus.data()[i]);
+            }
+            return to_numpy(std::move(out));
+          },
+          nb::arg("wavelength_nm"), nb::arg("zem_m"), nb::arg("airmass"), nb::arg("od_tel"),
+          nb::arg("od_focus"))
+      .def(
+          "telescope_depths",
+          [](const TransmissionTable &self, double telescope_altitude_m, double pathlen_m) {
+            const auto depths = self.telescope_depths(telescope_altitude_m, pathlen_m);
+            return nb::make_tuple(
+                to_numpy(std::vector<double>(depths.od_tel.begin(), depths.od_tel.end())),
+                to_numpy(std::vector<double>(depths.od_focus.begin(), depths.od_focus.end())));
+          },
+          nb::arg("telescope_altitude_m"), nb::arg("pathlen_m") = 0.0);
+}
+
+// Map a column name of the Python API to its obdeect stream column.
+inline obdeect::stream::Column column_from_name(const std::string &name) {
+  for (std::uint32_t c = 0; c < obdeect::stream::n_columns; ++c) {
+    const auto column = static_cast<obdeect::stream::Column>(c);
+    if (name == obdeect::stream::column_name(column)) {
+      return column;
+    }
+  }
+  throw std::invalid_argument("unknown photon column: " + name);
+}
+
+// Input columns given as equal-length float32 arrays, keyed by column name. The arrays
+// are not copied; mask is the set of columns given (also when there are no rows).
+struct InputColumns {
+  std::vector<std::pair<obdeect::stream::Column, FloatArray>> arrays;
+  std::size_t rows{};
+  std::uint32_t mask{};
+};
+
+inline InputColumns input_columns(const nb::dict &columns) {
+  InputColumns input;
+  for (auto item : columns) {
+    const auto column = column_from_name(nb::cast<std::string>(item.first));
+    const auto array = nb::cast<FloatArray>(item.second);
+    if (!input.arrays.empty() && array.size() != input.rows) {
+      throw std::invalid_argument("photon columns differ in length");
+    }
+    input.rows = array.size();
+    input.mask |= obdeect::stream::column_bit(column);
+    input.arrays.emplace_back(column, array);
+  }
+  return input;
+}
+
+// Chunk of rows [offset, offset + count) of the input; first_index is the index of row
+// offset among all photons. count must be at most obdeect::stream::max_chunk_rows.
+inline obdeect::stream::PhotonChunk slice_chunk(const InputColumns &input, std::size_t offset,
+                                                std::size_t count, std::uint64_t first_index) {
+  obdeect::stream::PhotonChunk chunk;
+  chunk.first_index = first_index;
+  chunk.resize(count, input.mask);
+  for (const auto &[column, array] : input.arrays) {
+    const float *begin = array.data() + offset;
+    std::copy(begin, begin + count, chunk[column].begin());
+  }
+  return chunk;
+}
+
+inline void bind_apply(nb::module_ &module) {
+  module.def(
+      "apply_extinction",
+      [](const nb::dict &columns, const obdeect::propagation::TransmissionTable &table,
+         double telescope_altitude_m, const DoubleArray &envelope_wavelength,
+         const DoubleArray &envelope_value, std::uint64_t seed, std::uint32_t event,
+         std::uint32_t telescope, std::uint64_t first_index, bool weighted,
+         std::tuple<double, double> wavelength_range, double pathlen_m) {
+        const obdeect::propagation::Envelope envelope(to_vector(envelope_wavelength),
+                                                      to_vector(envelope_value));
+        const auto depths = table.telescope_depths(telescope_altitude_m, pathlen_m);
+        obdeect::propagation::ExtinctionSettings settings;
+        settings.table = &table;
+        settings.depths = &depths;
+        settings.envelope = &envelope;
+        settings.wavelengths = {std::get<0>(wavelength_range), std::get<1>(wavelength_range)};
+        settings.seed = seed;
+        settings.event = event;
+        settings.telescope = telescope;
+        settings.weighted = weighted;
+
+        // The input is processed in slices of at most 2^16 rows (the PhotonChunk limit). Each
+        // slice keeps its photon index (first_index + offset), so the random draws do not
+        // depend on slicing; the output index continues across slices.
+        const InputColumns input = input_columns(columns);
+        // Output columns: the input columns plus the wavelength and p columns, which the
+        // pipeline always produces, also when no photon survives.
+        const std::uint32_t output_mask =
+            input.mask | obdeect::stream::column_bit(obdeect::stream::Column::wavelength) |
+            obdeect::stream::column_bit(obdeect::stream::Column::p);
+        std::vector<std::vector<float>> out(obdeect::stream::n_columns);
+        std::uint64_t out_index = 0;
+        for (std::size_t offset = 0; offset < input.rows;
+             offset += obdeect::stream::max_chunk_rows) {
+          const std::size_t rows =
+              std::min<std::size_t>(obdeect::stream::max_chunk_rows, input.rows - offset);
+          obdeect::stream::PhotonChunk slice =
+              slice_chunk(input, offset, rows, first_index + offset);
+          for (auto &chunk : obdeect::propagation::apply_extinction_chunk(std::move(slice),
+                                                                          settings, out_index)) {
+            for (std::uint32_t c = 0; c < obdeect::stream::n_columns; ++c) {
+              if (chunk.has(static_cast<obdeect::stream::Column>(c))) {
+                out[c].insert(out[c].end(), chunk.columns[c].begin(), chunk.columns[c].end());
+              }
+            }
+            out_index += chunk.rows();
+          }
+        }
+        nb::dict result;
+        for (std::uint32_t c = 0; c < obdeect::stream::n_columns; ++c) {
+          const auto column = static_cast<obdeect::stream::Column>(c);
+          if ((output_mask >> c) & 1U) {
+            result[obdeect::stream::column_name(column)] = nb::cast(to_numpy(std::move(out[c])));
+          }
+        }
+        return result;
+      },
+      nb::arg("columns"), nb::arg("table"), nb::arg("telescope_altitude_m"),
+      nb::arg("envelope_wavelength"), nb::arg("envelope_value"), nb::arg("seed"), nb::arg("event"),
+      nb::arg("telescope"), nb::arg("first_index"), nb::arg("weighted"),
+      nb::arg("wavelength_range"), nb::arg("pathlen_m") = 0.0);
+}
+
+} // namespace obdeect_propagation_bindings
+
+// Register TransmissionTable and apply_extinction on the extension module.
+inline void bind_extinction(nanobind::module_ &module) {
+  obdeect_propagation_bindings::bind_table(module);
+  obdeect_propagation_bindings::bind_apply(module);
+}

obdeect_propagation-0.8.0/cpp/bindings/profile_bindings.hpp

@@ -0,0 +1,126 @@
+#pragma once
+
+// Python API for the atmospheric profile, refraction tables and timing. Included by core.cpp
+// after the nanobind headers. Arrays are one-dimensional float64 and are copied per call.
+
+#include <nanobind/nanobind.h>
+#include <nanobind/ndarray.h>
+#include <nanobind/stl/string.h>
+
+#include "extinction_bindings.hpp" // to_numpy
+#include "obdeect/propagation/profile.hpp"
+#include "obdeect/propagation/refraction.hpp"
+#include "obdeect/propagation/timing.hpp"
+
+#include <cstddef>
+#include <cstdint>
+#include <stdexcept>
+#include <string>
+#include <utility>
+#include <vector>
+
+namespace nb = nanobind;
+
+namespace obdeect_propagation_bindings {
+
+using ConstArray = nb::ndarray<const double, nb::ndim<1>, nb::c_contig, nb::device::cpu>;
+
+inline std::vector<double> copy_values(const ConstArray &values) {
+  std::vector<double> copy(values.shape(0));
+  for (std::size_t i = 0; i < copy.size(); ++i)
+    copy[i] = values(i);
+  return copy;
+}
+
+template <class Function>
+nb::ndarray<nb::numpy, double, nb::ndim<1>> map_values(const ConstArray &heights,
+                                                       Function function) {
+  std::vector<double> out(heights.shape(0));
+  for (std::size_t i = 0; i < out.size(); ++i)
+    out[i] = function(heights(i));
+  return to_numpy(std::move(out));
+}
+
+} // namespace obdeect_propagation_bindings
+
+inline void bind_profile(nb::module_ &module) {
+  using obdeect::propagation::AtmosphereProfile;
+  using obdeect::propagation::RefractionTables;
+  using obdeect_propagation_bindings::ConstArray;
+  using obdeect_propagation_bindings::copy_values;
+  using obdeect_propagation_bindings::map_values;
+  using obdeect_propagation_bindings::to_numpy;
+
+  nb::class_<AtmosphereProfile>(module, "AtmosphereProfile")
+      .def(nb::new_([](const std::string &path) { return AtmosphereProfile::from_file(path); }),
+           nb::arg("path"),
+           "Read an atmprof table (altitude km, density, "
+           "thickness, n-1).")
+      .def_prop_ro("levels", &AtmosphereProfile::levels)
+      .def_prop_ro("bottom_m", &AtmosphereProfile::bottom_m)
+      .def_prop_ro("top_m", &AtmosphereProfile::top_m)
+      .def(
+          "density",
+          [](const AtmosphereProfile &p, const ConstArray &h) {
+            return map_values(h, [&p](double x) { return p.density(x); });
+          },
+          nb::arg("height_m"), "Density [g/cm^3] at heights [m a.s.l.] (spline table lookup).")
+      .def(
+          "thickness",
+          [](const AtmosphereProfile &p, const ConstArray &h) {
+            return map_values(h, [&p](double x) { return p.thickness(x); });
+          },
+          nb::arg("height_m"), "Thickness [g/cm^2] at heights [m a.s.l.] (spline table lookup).")
+      .def(
+          "refractive_index_minus_one",
+          [](const AtmosphereProfile &p, const ConstArray &h) {
+            return map_values(h, [&p](double x) { return p.refractive_index_minus_one(x); });
+          },
+          nb::arg("height_m"), "n-1 at heights [m a.s.l.] (spline table lookup).")
+      .def(
+          "group_index",
+          [](const AtmosphereProfile &p, double observation_level_m) {
+            return obdeect::propagation::ambient_group_index(p, observation_level_m);
+          },
+          nb::arg("observation_level_m"), "Refractive index n at the observation level.");
+
+  nb::class_<RefractionTables>(module, "RefractionTables")
+      .def(nb::init<AtmosphereProfile, double>(), nb::arg("profile"),
+           nb::arg("observation_level_m"),
+           "Refraction tables for a profile and observation level [m a.s.l.].")
+      .def_prop_ro("etadsn", &RefractionTables::etadsn)
+      .def_prop_ro("observation_level_m",
+                   [](const RefractionTables &t) { return t.observation_level_cm() / 100.; });
+
+  module.def(
+      "refract",
+      [](const RefractionTables &tables, const ConstArray &h, const ConstArray &cx,
+         const ConstArray &cy, const ConstArray &x, const ConstArray &y, const ConstArray &t) {
+        const std::size_t n = h.shape(0);
+        if (cx.shape(0) != n || cy.shape(0) != n || x.shape(0) != n || y.shape(0) != n ||
+            t.shape(0) != n)
+          throw std::invalid_argument("refract: all arrays must have the same length");
+        std::vector<double> ux = copy_values(cx), uy = copy_values(cy), px = copy_values(x),
+                            py = copy_values(y), pt = copy_values(t);
+        std::vector<bool> bent(n);
+        for (std::size_t i = 0; i < n; ++i) {
+          const double height = h(i);
+          bent[i] = obdeect::propagation::bend(tables, height, ux[i], uy[i], px[i], py[i], pt[i]);
+        }
+        std::vector<std::uint8_t> flags(bent.begin(), bent.end());
+        return nb::make_tuple(to_numpy(std::move(ux)), to_numpy(std::move(uy)),
+                              to_numpy(std::move(px)), to_numpy(std::move(py)),
+                              to_numpy(std::move(pt)), to_numpy(std::move(flags)));
+      },
+      nb::arg("tables"), nb::arg("height_m"), nb::arg("cx"), nb::arg("cy"), nb::arg("x_m"),
+      nb::arg("y_m"), nb::arg("t_ns"),
+      "Bend photons emitted at height_m with direction (cx, cy) and position (x_m, y_m) at the "
+      "observation level; returns (cx, cy, x_m, y_m, t_ns, bent) as numpy arrays, bent as uint8.");
+
+  module.def("straight_path_air_delay_ns", &obdeect::propagation::straight_path_air_delay_ns,
+             nb::arg("profile"), nb::arg("height_low_m"), nb::arg("height_high_m"),
+             nb::arg("zenith_rad"),
+             "Extra light travel time over a straight path between two heights [ns].");
+  module.def("propagation_time_ns", &obdeect::propagation::propagation_time_ns, nb::arg("path_m"),
+             nb::arg("group_index"), "Light travel time over a path in a medium [ns].");
+}

obdeect_propagation-0.8.0/cpp/bindings/propagator_bindings.hpp

@@ -0,0 +1,111 @@
+#pragma once
+
+// Python API of the atmosphere stage: obdeect.propagation.propagate on stream files (the stream I/O
+// is the C++ core's). Included by core.cpp after the nanobind headers.
+
+#include <nanobind/nanobind.h>
+#include <nanobind/stl/map.h>
+#include <nanobind/stl/optional.h>
+#include <nanobind/stl/pair.h>
+#include <nanobind/stl/string.h>
+#include <nanobind/stl/tuple.h>
+#include <nanobind/stl/vector.h>
+
+#include "obdeect/propagation/propagator.hpp"
+
+#include <cstdint>
+#include <fstream>
+#include <map>
+#include <optional>
+#include <stdexcept>
+#include <string>
+#include <tuple>
+#include <utility>
+#include <vector>
+
+namespace nb = nanobind;
+
+inline void bind_propagator(nb::module_ &module) {
+  module.def(
+      "propagate",
+      [](const std::string &input_path, const std::string &output_path,
+         const std::optional<std::string> &transmission_path, double site_altitude_m,
+         const std::optional<std::string> &profile_path,
+         const std::vector<std::pair<std::string, std::string>> &envelope_paths,
+         const std::optional<std::tuple<double, double>> &wavelength_range, std::uint64_t seed,
+         bool weighted, bool store_p, const std::optional<std::string> &scattering_path,
+         std::uint32_t scattering_points, double pathlen_m,
+         const std::map<std::int64_t, double> &telescope_pathlen_m, bool geometry_only) {
+        obdeect::propagation::PropagatorConfig config;
+        config.geometry_only = geometry_only;
+        config.default_pathlen_m = pathlen_m;
+        for (const auto &[id, metres] : telescope_pathlen_m) {
+          if (id < 1 || id > static_cast<std::int64_t>(obdeect::stream::max_telescope)) {
+            throw std::invalid_argument("telescope_pathlen_m: telescope ids are 1-based");
+          }
+          config.telescope_pathlen_m[static_cast<std::uint32_t>(id)] = metres;
+        }
+        if (transmission_path) {
+          config.transmission.emplace(obdeect::propagation::TransmissionTable::from_file(
+              *transmission_path, site_altitude_m));
+          config.transmission_source = *transmission_path;
+        }
+        config.site_altitude_m = site_altitude_m;
+        if (profile_path) {
+          config.profile.emplace(obdeect::propagation::AtmosphereProfile::from_file(*profile_path));
+          config.profile_source = *profile_path;
+        }
+        for (const auto &[name, path] : envelope_paths) {
+          config.envelope.push_back(obdeect::propagation::read_envelope_file(name, path));
+        }
+        if (wavelength_range) {
+          config.wavelength_range = obdeect::propagation::WavelengthRange{
+              std::get<0>(*wavelength_range), std::get<1>(*wavelength_range)};
+        }
+        config.seed = seed;
+        config.mode = weighted ? obdeect::propagation::OutputMode::weighted
+                               : obdeect::propagation::OutputMode::thinned;
+        config.store_p = store_p;
+        if (scattering_path) {
+          config.scattering.enabled = true;
+          config.scattering.points_per_photon = scattering_points;
+          config.scattering_table.emplace(
+              obdeect::propagation::ScatteringTable::from_file(*scattering_path));
+          config.scattering_source = *scattering_path;
+        }
+
+        if (obdeect::propagation::same_file(input_path, output_path)) {
+          throw std::invalid_argument("input and output are the same file: " + input_path);
+        }
+        std::ifstream in(input_path, std::ios::binary);
+        if (!in) {
+          throw std::runtime_error("cannot open input stream: " + input_path);
+        }
+        std::ofstream out(output_path, std::ios::binary);
+        if (!out) {
+          throw std::runtime_error("cannot open output stream: " + output_path);
+        }
+        const obdeect::propagation::PropagationSummary summary =
+            obdeect::propagation::propagate_stream(in, out, std::move(config));
+        out.close();
+        nb::dict result;
+        result["photons_in"] = summary.photons_in;
+        result["photons_out"] = summary.photons_out;
+        result["dropped"] = summary.dropped;
+        result["weight_out"] = summary.weight_out;
+        return result;
+      },
+      nb::arg("input_path"), nb::arg("output_path"), nb::arg("transmission_path"),
+      nb::arg("site_altitude_m"), nb::arg("profile_path") = nb::none(),
+      nb::arg("envelope_paths") = std::vector<std::pair<std::string, std::string>>{},
+      nb::arg("wavelength_range") = nb::none(), nb::arg("seed"), nb::arg("weighted") = false,
+      nb::arg("store_p") = false, nb::arg("scattering_path") = nb::none(),
+      nb::arg("scattering_points") = std::uint32_t{8}, nb::arg("pathlen_m") = 0.0,
+      nb::arg("telescope_pathlen_m") = std::map<std::int64_t, double>{},
+      nb::arg("geometry_only") = false,
+      "Run the atmosphere stage on a photon stream file (geometry_only: no extinction, see "
+      "docs/propagation.md). envelope_paths: (name, file) pairs of "
+      "two-column text tables (nm, value). scattering_path: optional scattering table (single "
+      "scattering of the primaries, off when None). pathlen_m: path inside each telescope [m]; "
+      "telescope_pathlen_m: {telescope_id (1-based): metres} overrides.");
+}