otswap 0.1.0__tar.gz

otswap-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,166 @@
+name: CI
+
+# Builds and tests the C++ library, the Python module and the CMake package
+# on every push and pull request: with GCC and clang on Linux and with Apple
+# clang on macOS, warnings as errors.
+
+on: [push, pull_request]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: ${{ matrix.name }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - name: Linux GCC
+            os: ubuntu-24.04
+            cc: gcc
+            cxx: g++
+          - name: Linux clang
+            os: ubuntu-24.04
+            cc: clang
+            cxx: clang++
+          - name: macOS Apple clang
+            os: macos-latest
+            cc: clang
+            cxx: clang++
+
+    env:
+      CC: ${{ matrix.cc }}
+      CXX: ${{ matrix.cxx }}
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+
+      # GCC brings libgomp; clang on Linux needs libomp.
+      - name: Install cfitsio and OpenMP
+        if: runner.os == 'Linux'
+        run: sudo apt-get update && sudo apt-get install --yes libcfitsio-dev libomp-dev
+
+      # Homebrew's libomp is keg-only: otswap, and its installed package,
+      # find it without OpenMP_ROOT.
+      - name: Install cfitsio and libomp
+        if: runner.os == 'macOS'
+        run: |
+          brew install cfitsio libomp
+          echo "CFITSIO_ROOT=$(brew --prefix cfitsio)" >> "$GITHUB_ENV"
+
+      - name: Configure
+        run: |
+          cmake -S . -B build -DCMAKE_COMPILE_WARNING_AS_ERROR=ON | tee configure.log
+          # without OpenMP every test would still pass, serially
+          grep -q "Found OpenMP_CXX" configure.log
+
+      - name: Build
+        run: cmake --build build --parallel
+
+      - name: Test
+        run: ctest --test-dir build --output-on-failure
+
+      - name: Every translation unit is compiled without FP contraction
+        run: |
+          python3 - <<'PY'
+          import json, sys
+          entries = json.load(open("build/compile_commands.json"))
+          bad = [e["file"] for e in entries
+                 if "-ffp-contract=off" not in e.get("command", " ".join(e.get("arguments", [])))]
+          print(len(entries), "translation units;", len(bad), "without -ffp-contract=off")
+          sys.exit(1 if bad or not entries else 0)
+          PY
+
+      # The bit-identity tests compare the module with the C++ library built
+      # above; test_determinism.py compares both thread counts with the
+      # hashes recorded in tests/determinism_hashes.json.
+      - name: Build and install the module
+        run: pip install ".[test]"
+
+      - name: Python tests
+        env:
+          OTSWAP_CPP_REFERENCE: ${{ github.workspace }}/build/cpp_reference
+        run: >-
+          python -m pytest tests/test_otswap.py tests/test_rsd.py tests/test_determinism.py
+          -p no:cacheprovider -rs
+
+      # The C++ install rules are off under scikit-build-core.
+      - name: The module installs no C++ library, header or CMake file
+        run: |
+          if pip show -f otswap | grep -E '\.(a|h|cmake)$'; then
+            exit 1
+          fi
+
+      # The package must work from wherever its prefix ends up.
+      - name: Install, then move the prefix
+        run: |
+          cmake --install build --prefix "$RUNNER_TEMP/prefix"
+          mv "$RUNNER_TEMP/prefix" "$RUNNER_TEMP/moved"
+
+      - name: The installed files
+        working-directory: ${{ runner.temp }}/moved
+        run: |
+          headers=$(find include -type f | LC_ALL=C sort | tr '\n' ' ')
+          expected="include/meshsearch/MeshGrid.h include/otswap/OT.h include/otswap/RSD.h include/otswap/io.h "
+          if [ "$headers" != "$expected" ]; then
+            echo "installed headers: $headers"
+            exit 1
+          fi
+          # no path of this machine: the checkout, the build, the prefix, cfitsio
+          if grep -rlF -e "$GITHUB_WORKSPACE" -e "$RUNNER_TEMP" -e libcfitsio lib/cmake; then
+            echo "the files above hold a build-machine path"
+            exit 1
+          fi
+          # the vendored Healpix is the tests' reference only
+          if nm -C lib/libotswap.a | grep -E "T_Healpix_Base|Healpix_Tables|PlanckError"; then
+            echo "libotswap.a holds Healpix code"
+            exit 1
+          fi
+
+      # find_package(otswap CONFIG) against the moved tree
+      - name: Consume the installed package
+        run: |
+          cmake -S tests/cmake/install -B build-install-consumer -DCMAKE_PREFIX_PATH="$RUNNER_TEMP/moved"
+          cmake --build build-install-consumer
+          ./build-install-consumer/consumer
+
+      # Each example is a project of its own, built against the moved package.
+      - name: Build the C++ examples
+        run: |
+          for d in box lightcone full_recons_lightcone full_recons_box; do
+            cmake -S examples/$d -B build-examples/$d -DCMAKE_PREFIX_PATH="$RUNNER_TEMP/moved" \
+              -DCMAKE_COMPILE_WARNING_AS_ERROR=ON -DCMAKE_CXX_FLAGS="-Wall -Wextra"
+            cmake --build build-examples/$d
+          done
+
+      # With a fixed seed the C++ and the Python examples write the same files.
+      - name: Run the examples, C++ then Python, and compare their outputs
+        run: |
+          for d in box lightcone full_recons_lightcone full_recons_box; do
+            "./build-examples/$d/$d"
+            mv "examples/$d/output" "examples/$d/output-cpp"
+            python "examples/$d/$d.py"
+            diff -r "examples/$d/output-cpp" "examples/$d/output"
+          done
+
+      # add_subdirectory on the source tree: no tests, no example, no build type
+      - name: Consume the source tree as a subproject
+        run: |
+          cmake -S tests/cmake/subproject -B build-subproject-consumer -DOTSWAP_SOURCE_DIR="$GITHUB_WORKSPACE"
+          cmake --build build-subproject-consumer --parallel
+          ./build-subproject-consumer/consumer
+
+      # An installed meshsearch of the same minor version is used, not fetched.
+      - name: Build against an installed meshsearch
+        run: |
+          cmake -S . -B build-found -DOTSWAP_BUILD_TESTS=OFF -DCMAKE_PREFIX_PATH="$RUNNER_TEMP/moved" \
+            | tee found.log
+          grep -q "otswap: using meshsearch 0.2" found.log
+          test ! -d build-found/_deps/meshsearch-src
+          cmake --build build-found --parallel

otswap-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,64 @@
+name: Docs
+
+# Builds the documentation on every push and pull request, so a broken
+# reference or a malformed docstring fails here and not silently. Publishing to
+# Pages happens only from main. Deliberately separate from release.yml: a docs
+# failure must never stand between a tag and PyPI.
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: build
+    runs-on: ubuntu-24.04
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+
+      - name: Install Doxygen
+        run: sudo apt-get update && sudo apt-get install --yes doxygen
+
+      # The package is not built: the Python reference is read from the type
+      # stubs, and the C++ one from the headers.
+      - name: Install the documentation toolchain
+        run: pip install -r docs/requirements.txt
+
+      - name: Build
+        # -W: a warning is a failure. An unresolved reference or a docstring
+        # Sphinx cannot parse should break the build, not reach the site.
+        run: sphinx-build -W --keep-going -b html docs docs/_build/html
+
+      - uses: actions/upload-pages-artifact@v5
+        with:
+          path: docs/_build/html
+
+  deploy:
+    name: deploy to Pages
+    needs: build
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    runs-on: ubuntu-24.04
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    permissions:
+      pages: write
+      id-token: write
+
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v5

otswap-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,116 @@
+name: Release
+
+# Publishes to PyPI when a v* tag is pushed. Run it from the Actions tab
+# (workflow_dispatch) to build and test the artefacts without publishing.
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  sdist:
+    name: sdist
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+
+      # The version lives in pyproject.toml and in CMakeLists.txt; on a tag
+      # push the tag must name it too.
+      - name: The versions agree
+        run: |
+          version=$(python -c "import tomllib, pathlib; print(tomllib.loads(pathlib.Path('pyproject.toml').read_text())['project']['version'])")
+          cmake_version=$(sed -nE 's/^project\(otswap VERSION ([0-9.]+).*/\1/p' CMakeLists.txt)
+          if [ "$version" != "$cmake_version" ]; then
+            echo "pyproject.toml says $version and CMakeLists.txt $cmake_version"
+            exit 1
+          fi
+          if [ "$GITHUB_EVENT_NAME" = push ] && [ "${GITHUB_REF_NAME#v}" != "$version" ]; then
+            echo "tag $GITHUB_REF_NAME does not match version $version"
+            exit 1
+          fi
+
+      - name: Build
+        run: pipx run build --sdist
+
+      - name: The sdist holds no example
+        run: |
+          if tar -tzf dist/*.tar.gz | grep '/examples/'; then
+            exit 1
+          fi
+
+      - name: Check the metadata PyPI will render
+        run: pipx run twine check dist/*
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist-sdist
+          path: dist/*.tar.gz
+
+  wheels:
+    name: wheels on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-24.04, ubuntu-24.04-arm, macos-latest]
+
+    # The configuration is in pyproject.toml: every wheel is repaired,
+    # checked by tools/wheels/check_dependencies.py and tested by
+    # tools/wheels/test_wheel.sh, the bit-identity and determinism tests
+    # included.
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: pypa/cibuildwheel@v4.2.1
+        with:
+          output-dir: wheelhouse
+
+      # The C++ install rules are off under scikit-build-core.
+      - name: The wheels hold no C++ library, header, CMake file or example
+        run: |
+          python3 - <<'PY'
+          import glob, sys, zipfile
+          wheels = glob.glob("wheelhouse/*.whl")
+          bad = [f"{w}: {name}" for w in wheels for name in zipfile.ZipFile(w).namelist()
+                 if name.endswith((".a", ".h", ".cmake")) or "examples/" in name]
+          print(len(wheels), "wheels;", len(bad), "C++ library, header, CMake or example files")
+          print("\n".join(bad))
+          sys.exit(1 if bad or not wheels else 0)
+          PY
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist-${{ matrix.os }}
+          path: wheelhouse/*.whl
+
+  publish:
+    name: publish to PyPI
+    needs: [sdist, wheels]
+    if: github.event_name == 'push'
+    runs-on: ubuntu-24.04
+
+    # The trusted publisher on PyPI is configured against this environment name
+    # and this workflow's filename. Changing either means changing it there.
+    environment:
+      name: pypi
+      url: https://pypi.org/p/otswap
+
+    permissions:
+      id-token: write          # mints the OIDC token PyPI checks; no API token
+
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          pattern: dist-*
+          merge-multiple: true
+          path: dist
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

otswap-0.1.0/.gitignore

@@ -0,0 +1,22 @@
+
+build/
+build-*/
+_build/
+docs/_build/
+docs/doxygen/
+dist/
+*.egg-info/
+CMakeCache.txt
+CMakeFiles/
+cmake_install.cmake
+*.o
+*.a
+*.so
+*.dylib
+__pycache__/
+*.pyc
+.pytest_cache/
+.DS_Store
+.venv/
+examples/*/output/
+wheelhouse/

otswap-0.1.0/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+## 0.1.0 — 2026-10-08
+
+First release.
+
+### Compared with CosmoBolognaLib's OTreconstruction
+
+- The same algorithm and inputs: seeding on a mesh, then local search that
+  tries every permutation of the partners of four neighbouring tracers.
+- With a fixed seed, the result does not depend on the number of threads, and
+  is the same bit for bit on every supported platform and compiler: the
+  assignment of the randoms, their draw, the seeding and the swap loop each
+  draw from their own random stream.
+- Every tracer is examined in every sweep.
+- The seeding radius (8 mean particle separations) and the number of swap
+  neighbours (113) are named constants, not parameters.
+- Mask crossings: the adaptive search along the arc, with a limit on the
+  distinct unobserved pixels crossed (0 rejects at the first), and validity
+  kept per realization.
+- Cosmology enters as a table of redshift, comoving distance and growth rate,
+  computed from a flat w0-wa cosmology or given by the caller; no GSL.
+- The redshift-space correction is a library function for each geometry, with
+  its four steps also available on their own.
+- Table writers for every product, ASCII and FITS, with column descriptions,
+  units and header keywords.
+- A Python package on the same code.

otswap-0.1.0/CITATION.cff

@@ -0,0 +1,55 @@
+cff-version: 1.2.0
+message: "If you use otswap, please cite the paper below and CosmoBolognaLib."
+title: otswap
+abstract: >-
+  Optimal transport reconstruction of the displacement field of a tracer
+  catalogue, by local swapping.
+type: software
+authors:
+  - family-names: Sartori
+    given-names: Simone
+    email: simone.sartori@inaf.it
+version: 0.1.0
+date-released: 2026-10-08
+license: GPL-2.0-or-later
+repository-code: "https://github.com/SimoSartori/otswap"
+url: "https://simosartori.github.io/otswap/"
+preferred-citation:
+  type: article
+  title: "The Back-in-time Void Finder: dynamical identification of cosmic voids through optimal transport reconstruction"
+  authors:
+    - family-names: Sartori
+      given-names: Simone
+    - family-names: Contarini
+      given-names: Sofia
+    - family-names: Sarpa
+      given-names: Elena
+    - family-names: Degni
+      given-names: Giulia
+    - family-names: Marulli
+      given-names: Federico
+    - family-names: Escoffier
+      given-names: Stephanie
+    - family-names: Moscardini
+      given-names: Lauro
+  year: 2026
+  identifiers:
+    - type: other
+      value: "arXiv:2601.15378"
+  url: "https://arxiv.org/abs/2601.15378"
+references:
+  - type: article
+    title: "CosmoBolognaLib: C++ libraries for cosmological calculations"
+    authors:
+      - family-names: Marulli
+        given-names: Federico
+      - family-names: Veropalumbo
+        given-names: Alfonso
+      - family-names: Moresco
+        given-names: Michele
+    journal: Astronomy and Computing
+    volume: 14
+    start: 35
+    end: 42
+    year: 2016
+    doi: 10.1016/j.ascom.2016.01.005