morseframes 0.1.0a1__tar.gz

morseframes-0.1.0a1/.github/workflows/ci.yml

@@ -0,0 +1,71 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
+jobs:
+  test:
+    name: C++ and Python (${{ matrix.os }}, Python ${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python-version: ["3.11"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Upgrade pip
+        run: python -m pip install --upgrade pip
+
+      - name: Configure C++
+        run: cmake -S . -B build -DMORSEFRAMES_BUILD_GUDHI_TOOLS=OFF
+
+      - name: Build C++
+        run: cmake --build build --parallel
+
+      - name: Test C++
+        run: ctest --test-dir build --output-on-failure --timeout 120
+
+      - name: Install Python package
+        run: python -m pip install -e .
+
+      - name: Smoke-test native Python package
+        run: python -c "import morseframes as mf; print(mf.__version__, mf.cpp_backend_available()); assert mf.cpp_backend_available()"
+
+      - name: Test pure-Python fallback
+        run: MORSEFRAMES_DISABLE_CPP_BACKEND=1 python -m unittest discover -s python/tests -p "test_*.py"
+
+      - name: Run Python quickstart
+        run: python python/examples/quickstart.py
+
+  docs:
+    name: Documentation
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install documentation dependencies
+        run: python -m pip install -r docs/requirements.txt
+
+      - name: Check generated benchmark summary
+        run: python tools/render_benchmark_summary.py --check
+
+      - name: Build documentation
+        run: MORSEFRAMES_DISABLE_CPP_BACKEND=1 python -m sphinx -W --keep-going -b html docs docs/_build/html

morseframes-0.1.0a1/.github/workflows/publish.yml

@@ -0,0 +1,115 @@
+name: Publish Python Package
+
+on:
+  workflow_dispatch:
+    inputs:
+      repository:
+        description: "Package registry to publish to"
+        required: true
+        default: testpypi
+        type: choice
+        options:
+          - testpypi
+          - pypi
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+  CIBW_BUILD: "cp310-* cp311-* cp312-*"
+  CIBW_SKIP: "*-musllinux_*"
+  CIBW_TEST_COMMAND: >-
+    python -c "import morseframes as mf;
+    assert mf.__version__ == '0.1.0a1';
+    assert mf.cpp_backend_available();
+    print(mf.__version__, mf.cpp_backend_available())"
+
+jobs:
+  sdist:
+    name: Source distribution
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build source distribution
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build --sdist --outdir dist
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: sdist
+          path: dist/*.tar.gz
+
+  wheels:
+    name: Wheels (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - uses: pypa/cibuildwheel@v4.1.0
+        with:
+          output-dir: wheelhouse
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels-${{ matrix.os }}
+          path: wheelhouse/*.whl
+
+  publish-testpypi:
+    name: Publish to TestPyPI
+    if: github.event_name == 'workflow_dispatch' && inputs.repository == 'testpypi'
+    needs: [sdist, wheels]
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: dist
+          merge-multiple: true
+
+      - uses: pypa/gh-action-pypi-publish@v1.14.0
+        with:
+          packages-dir: dist
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    name: Publish to PyPI
+    if: github.event_name == 'release' || (github.event_name == 'workflow_dispatch' && inputs.repository == 'pypi')
+    needs: [sdist, wheels]
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: dist
+          merge-multiple: true
+
+      - uses: pypa/gh-action-pypi-publish@v1.14.0
+        with:
+          packages-dir: dist

morseframes-0.1.0a1/.gitignore

@@ -0,0 +1,34 @@
+build/
+build-*/
+cmake-build-*/
+CMakeFiles/
+CMakeCache.txt
+CTestTestfile.cmake
+CMakeInit.txt
+Makefile
+build.ninja
+.ninja_deps
+.ninja_log
+.cmake/
+.skbuild-info.json
+cmake_install.cmake
+
+__pycache__/
+*.py[cod]
+*.so
+*.dylib
+*.a
+*.o
+*.egg-info/
+dist/
+.pytest_cache/
+
+*.aux
+*.log
+*.out
+*.toc
+docs/*_prose.tex
+docs/experiments_morse_persistence*.pdf
+docs/_build/
+
+.DS_Store

morseframes-0.1.0a1/.readthedocs.yaml

@@ -0,0 +1,13 @@
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+
+sphinx:
+  configuration: docs/conf.py
+
+python:
+  install:
+    - requirements: docs/requirements.txt

morseframes-0.1.0a1/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+All notable changes to MorseFrames are recorded here.
+
+## 0.1.0a1 - 2026-06-20
+
+Initial public alpha release.
+
+### Added
+
+- Header-only C++ core for filtered simplicial complexes.
+- Python interface with pure-Python fallback and optional nanobind backend.
+- Morse sequence strategies: saturated, F-Min, F-Max, same-level reduction,
+  plateau-greedy, and flooding variants.
+- Reference and coreference map construction.
+- Morse-reference and Morse-coreference persistence over `Z_2` and prime
+  fields `F_p`.
+- Simplex-tree-like builder for constructing complexes.
+- Experimental GUDHI-facing adapter for `Simplex_tree`.
+- Plotly demonstration for inspecting Morse critical data on a triangulated
+  square.
+- Reproducible benchmark scripts and generated public benchmark table
+  fragments.
+- Read the Docs documentation, including overview, quickstart, minimal
+  examples, and Morse-data inspection guide.
+- GitHub Actions CI for C++, Python, and documentation builds.
+
+### Notes
+
+- This is research software. Public APIs are useful for experiments, but may
+  still evolve while the paper and GUDHI integration mature.

morseframes-0.1.0a1/CITATION.cff

@@ -0,0 +1,21 @@
+cff-version: 1.2.0
+message: "If you use MorseFrames in academic work, please cite it using this metadata."
+type: software
+title: "MorseFrames"
+authors:
+  - family-names: Najman
+    given-names: Laurent
+abstract: >-
+  Experimental C++ and Python software for Morse sequences, reference and
+  coreference maps, Morse complexes, and Morse-based persistent homology.
+version: "0.1.0a1"
+date-released: "2026-06-20"
+license: MIT
+repository-code: "https://github.com/lnajman/morseframes"
+url: "https://morseframes.readthedocs.io/"
+keywords:
+  - persistent homology
+  - discrete Morse theory
+  - Morse sequence
+  - computational topology
+  - simplicial complex

morseframes-0.1.0a1/CMakeLists.txt

@@ -0,0 +1,188 @@
+cmake_minimum_required(VERSION 3.16)
+
+if(CMAKE_HOST_SYSTEM_NAME STREQUAL "Darwin" AND NOT CMAKE_OSX_ARCHITECTURES)
+    set(_MORSEFRAMES_PYTHON_FOR_ARCH "")
+    if(DEFINED Python_EXECUTABLE)
+        set(_MORSEFRAMES_PYTHON_FOR_ARCH "${Python_EXECUTABLE}")
+    elseif(DEFINED PYTHON_EXECUTABLE)
+        set(_MORSEFRAMES_PYTHON_FOR_ARCH "${PYTHON_EXECUTABLE}")
+    endif()
+
+    if(_MORSEFRAMES_PYTHON_FOR_ARCH)
+        execute_process(
+            COMMAND "${_MORSEFRAMES_PYTHON_FOR_ARCH}" -c
+                    "import platform; print(platform.machine())"
+            OUTPUT_VARIABLE _MORSEFRAMES_PYTHON_ARCH
+            RESULT_VARIABLE _MORSEFRAMES_PYTHON_ARCH_RESULT
+            OUTPUT_STRIP_TRAILING_WHITESPACE
+        )
+        if(_MORSEFRAMES_PYTHON_ARCH_RESULT EQUAL 0
+           AND (_MORSEFRAMES_PYTHON_ARCH STREQUAL "arm64"
+                OR _MORSEFRAMES_PYTHON_ARCH STREQUAL "x86_64"))
+            set(CMAKE_OSX_ARCHITECTURES "${_MORSEFRAMES_PYTHON_ARCH}"
+                CACHE STRING "Build architectures for macOS" FORCE)
+        endif()
+    endif()
+endif()
+
+project(morseframes LANGUAGES CXX)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_CXX_EXTENSIONS OFF)
+
+if(DEFINED SKBUILD)
+    set(MORSEFRAMES_DEFAULT_BUILD_PYTHON ON)
+    set(MORSEFRAMES_DEFAULT_BUILD_TESTS OFF)
+    set(MORSEFRAMES_DEFAULT_BUILD_EXAMPLES OFF)
+    set(MORSEFRAMES_DEFAULT_BUILD_GUDHI_TOOLS OFF)
+else()
+    set(MORSEFRAMES_DEFAULT_BUILD_PYTHON OFF)
+    set(MORSEFRAMES_DEFAULT_BUILD_TESTS ON)
+    set(MORSEFRAMES_DEFAULT_BUILD_EXAMPLES ON)
+    set(MORSEFRAMES_DEFAULT_BUILD_GUDHI_TOOLS ON)
+endif()
+
+option(MORSEFRAMES_BUILD_PYTHON
+    "Build nanobind Python extension"
+    ${MORSEFRAMES_DEFAULT_BUILD_PYTHON})
+option(MORSEFRAMES_BUILD_TESTS
+    "Build MorseFrames C++ tests"
+    ${MORSEFRAMES_DEFAULT_BUILD_TESTS})
+option(MORSEFRAMES_BUILD_EXAMPLES
+    "Build MorseFrames C++ examples"
+    ${MORSEFRAMES_DEFAULT_BUILD_EXAMPLES})
+option(MORSEFRAMES_BUILD_GUDHI_TOOLS
+    "Build optional GUDHI Simplex_tree integration tests and benchmark when headers are available"
+    ${MORSEFRAMES_DEFAULT_BUILD_GUDHI_TOOLS})
+set(MORSEFRAMES_GUDHI_INCLUDE_DIR "" CACHE PATH
+    "Optional path to a GUDHI include directory containing gudhi/Simplex_tree.h")
+set(MORSEFRAMES_BOOST_INCLUDE_DIR "" CACHE PATH
+    "Optional path to a Boost include directory needed by GUDHI headers")
+
+if(MORSEFRAMES_BUILD_GUDHI_TOOLS)
+    if(NOT MORSEFRAMES_GUDHI_INCLUDE_DIR)
+        find_path(MORSEFRAMES_GUDHI_INCLUDE_DIR
+            NAMES gudhi/Simplex_tree.h
+            HINTS
+                ENV GUDHI_ROOT
+                ENV GUDHI_DIR
+            PATH_SUFFIXES include
+            DOC "Path to a GUDHI include directory containing gudhi/Simplex_tree.h")
+    endif()
+
+    if(NOT MORSEFRAMES_BOOST_INCLUDE_DIR)
+        find_path(MORSEFRAMES_BOOST_INCLUDE_DIR
+            NAMES boost/core/empty_value.hpp
+            HINTS
+                ENV BOOST_ROOT
+                ENV Boost_ROOT
+                ENV CONDA_PREFIX
+            PATH_SUFFIXES include
+            DOC "Path to a Boost include directory needed by GUDHI headers")
+    endif()
+endif()
+
+add_library(morseframes INTERFACE)
+target_include_directories(morseframes INTERFACE
+    ${CMAKE_CURRENT_SOURCE_DIR}/include
+)
+
+if(MORSEFRAMES_BUILD_TESTS)
+    add_executable(morseframes_tests
+        tests/test_morse_reference.cpp
+    )
+    target_link_libraries(morseframes_tests PRIVATE morseframes)
+endif()
+
+if(MORSEFRAMES_BUILD_EXAMPLES)
+    add_executable(morseframes_example_barcode
+        examples/example_barcode.cpp
+    )
+    target_link_libraries(morseframes_example_barcode PRIVATE morseframes)
+endif()
+
+if(MORSEFRAMES_BUILD_GUDHI_TOOLS
+   AND MORSEFRAMES_GUDHI_INCLUDE_DIR
+   AND EXISTS "${MORSEFRAMES_GUDHI_INCLUDE_DIR}/gudhi/Simplex_tree.h"
+   AND MORSEFRAMES_BOOST_INCLUDE_DIR
+   AND EXISTS "${MORSEFRAMES_BOOST_INCLUDE_DIR}/boost/core/empty_value.hpp")
+    add_executable(morseframes_gudhi_simplex_tree_view_tests
+        tests/test_gudhi_simplex_tree_view.cpp
+    )
+    target_link_libraries(morseframes_gudhi_simplex_tree_view_tests PRIVATE morseframes)
+    target_include_directories(morseframes_gudhi_simplex_tree_view_tests PRIVATE
+        "${MORSEFRAMES_GUDHI_INCLUDE_DIR}"
+        "${MORSEFRAMES_BOOST_INCLUDE_DIR}"
+    )
+
+    add_executable(morseframes_benchmark_gudhi_view
+        benchmarks/benchmark_gudhi_view.cpp
+    )
+    target_link_libraries(morseframes_benchmark_gudhi_view PRIVATE morseframes)
+    target_include_directories(morseframes_benchmark_gudhi_view PRIVATE
+        "${MORSEFRAMES_GUDHI_INCLUDE_DIR}"
+        "${MORSEFRAMES_BOOST_INCLUDE_DIR}"
+    )
+
+    add_executable(morseframes_gudhi_simplex_tree_example
+        examples/gudhi_simplex_tree_morse.cpp
+    )
+    target_link_libraries(morseframes_gudhi_simplex_tree_example PRIVATE morseframes)
+    target_include_directories(morseframes_gudhi_simplex_tree_example PRIVATE
+        "${MORSEFRAMES_GUDHI_INCLUDE_DIR}"
+        "${MORSEFRAMES_BOOST_INCLUDE_DIR}"
+    )
+
+    add_executable(morseframes_gudhi_style_simplex_tree_example
+        examples/example_morse_persistence_from_simplex_tree.cpp
+    )
+    target_link_libraries(morseframes_gudhi_style_simplex_tree_example PRIVATE morseframes)
+    target_include_directories(morseframes_gudhi_style_simplex_tree_example PRIVATE
+        "${MORSEFRAMES_GUDHI_INCLUDE_DIR}"
+        "${MORSEFRAMES_BOOST_INCLUDE_DIR}"
+    )
+elseif(MORSEFRAMES_BUILD_GUDHI_TOOLS
+       AND MORSEFRAMES_GUDHI_INCLUDE_DIR
+       AND EXISTS "${MORSEFRAMES_GUDHI_INCLUDE_DIR}/gudhi/Simplex_tree.h")
+    message(STATUS
+        "Skipping GUDHI Simplex_tree tools because Boost headers were not found. "
+        "Set MORSEFRAMES_BOOST_INCLUDE_DIR or BOOST_ROOT to enable them.")
+elseif(MORSEFRAMES_BUILD_GUDHI_TOOLS)
+    message(STATUS
+        "Skipping GUDHI Simplex_tree tools because GUDHI headers were not found. "
+        "Set MORSEFRAMES_GUDHI_INCLUDE_DIR or GUDHI_ROOT to enable them.")
+endif()
+
+if(MORSEFRAMES_BUILD_PYTHON)
+    find_package(Python COMPONENTS Interpreter Development.Module REQUIRED)
+    execute_process(
+        COMMAND "${Python_EXECUTABLE}" -m nanobind --cmake_dir
+        OUTPUT_STRIP_TRAILING_WHITESPACE
+        OUTPUT_VARIABLE nanobind_ROOT
+    )
+    find_package(nanobind CONFIG REQUIRED)
+
+    nanobind_add_module(_morse_core
+        python/morseframes/_core_bindings.cpp
+    )
+    target_link_libraries(_morse_core PRIVATE morseframes)
+    set_target_properties(_morse_core PROPERTIES
+        LIBRARY_OUTPUT_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/python/morseframes"
+    )
+    if(DEFINED SKBUILD)
+        install(TARGETS _morse_core
+            LIBRARY DESTINATION morseframes
+            RUNTIME DESTINATION morseframes
+        )
+    endif()
+endif()
+
+enable_testing()
+if(TARGET morseframes_tests)
+    add_test(NAME morseframes_tests COMMAND morseframes_tests)
+endif()
+if(TARGET morseframes_gudhi_simplex_tree_view_tests)
+    add_test(NAME morseframes_gudhi_simplex_tree_view_tests
+        COMMAND morseframes_gudhi_simplex_tree_view_tests)
+endif()

morseframes-0.1.0a1/CONTRIBUTING.md

@@ -0,0 +1,81 @@
+# Contributing
+
+MorseFrames is research software. Contributions are welcome, especially small
+tests, documentation fixes, reproducibility improvements, and focused bug
+reports.
+
+## Development Setup
+
+From the repository root, build and test the C++ core:
+
+```sh
+cmake -S . -B build -DMORSEFRAMES_BUILD_GUDHI_TOOLS=OFF
+cmake --build build --parallel
+ctest --test-dir build --output-on-failure
+```
+
+Install the Python package in editable mode:
+
+```sh
+python3 -m pip install -e ".[dev]"
+python3 -c "import morseframes as mf; print(mf.__version__, mf.cpp_backend_available())"
+```
+
+Run the pure-Python fallback tests:
+
+```sh
+MORSEFRAMES_DISABLE_CPP_BACKEND=1 python3 -m unittest discover -s python/tests -p "test_*.py"
+```
+
+Run the quickstart example:
+
+```sh
+python3 python/examples/quickstart.py
+```
+
+## Documentation
+
+Install the documentation dependencies and build the Sphinx site:
+
+```sh
+python3 -m pip install -r docs/requirements.txt
+MORSEFRAMES_DISABLE_CPP_BACKEND=1 python3 -m sphinx -W --keep-going -b html docs docs/_build/html
+```
+
+The public documentation is hosted at:
+
+<https://morseframes.readthedocs.io/>
+
+## Optional GUDHI Tools
+
+The GUDHI-facing examples, tests, and benchmarks are enabled when GUDHI and
+Boost headers are available:
+
+```sh
+cmake -S . -B build \
+  -DMORSEFRAMES_GUDHI_INCLUDE_DIR=/path/to/gudhi/include \
+  -DMORSEFRAMES_BOOST_INCLUDE_DIR=/path/to/boost/include
+```
+
+## Benchmarks
+
+Benchmark and table-generation scripts live in `tools/`. The public
+reproduction instructions are in:
+
+```text
+docs/benchmark_reproduction.md
+```
+
+Use benchmark results as comparative signals rather than absolute machine
+independent timings. When changing algorithms or reducers, prefer reporting
+ratios, dataset metadata, and repeated-run summaries.
+
+## Pull Request Checklist
+
+- Keep changes focused.
+- Add or update tests when behavior changes.
+- Run the C++ tests, Python fallback tests, and documentation build when
+  touching the corresponding surface.
+- Keep generated scratch files out of commits.
+- Do not commit private manuscript drafts or private discussion notes to this
+  public repository.

morseframes-0.1.0a1/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Laurent Najman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+