graphot 0.0.2__tar.gz

graphot-0.0.2/.github/workflows/publish.yml

@@ -0,0 +1,207 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+    inputs:
+      target:
+        description: "Package index to publish to"
+        required: true
+        default: testpypi
+        type: choice
+        options:
+          - testpypi
+          - pypi
+      skip_tests:
+        description: "Skip pytest in validate job (manual runs only)"
+        required: false
+        default: false
+        type: boolean
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --group dev
+
+      - name: Lint
+        if: ${{ matrix.python-version == '3.13' }}
+        run: uv run ruff check .
+
+      - name: Test
+        if: ${{ github.event_name != 'workflow_dispatch' || inputs.skip_tests != true }}
+        run: uv run pytest -q
+
+  build_wheels:
+    needs: validate
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            artifact_name: wheels-linux
+            cibw_archs_linux: x86_64
+            cibw_archs_windows: auto
+            cibw_archs_macos: auto
+          - os: windows-latest
+            artifact_name: wheels-windows
+            cibw_archs_linux: auto
+            cibw_archs_windows: AMD64
+            cibw_archs_macos: auto
+          - os: macos-14
+            artifact_name: wheels-macos-arm64
+            cibw_archs_linux: auto
+            cibw_archs_windows: auto
+            cibw_archs_macos: arm64
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Verify tag matches package version
+        if: github.event_name == 'push'
+        shell: bash
+        run: |
+          python - <<'PY'
+          import tomllib
+          from pathlib import Path
+
+          tag = "${{ github.ref_name }}"
+          version = tomllib.loads(Path("pyproject.toml").read_text())["project"]["version"]
+          expected = f"v{version}"
+          if tag != expected:
+              raise SystemExit(
+                  f"Tag/version mismatch: pushed tag {tag!r} does not match pyproject version {version!r}."
+              )
+          print(f"Tag/version check passed: {tag}")
+          PY
+
+      - name: Build wheels
+        uses: pypa/cibuildwheel@v2.21.3
+        env:
+          CIBW_BUILD_FRONTEND: "build[uv]"
+          CIBW_BUILD: "cp311-* cp312-* cp313-*"
+          CIBW_SKIP: "pp* *-musllinux*"
+          CIBW_MANYLINUX_X86_64_IMAGE: "manylinux_2_28"
+          CIBW_ARCHS_LINUX: ${{ matrix.cibw_archs_linux }}
+          CIBW_ARCHS_WINDOWS: ${{ matrix.cibw_archs_windows }}
+          CIBW_ARCHS_MACOS: ${{ matrix.cibw_archs_macos }}
+          CIBW_BUILD_VERBOSITY: "1"
+          CIBW_TEST_COMMAND: "python {project}/tests/smoke_solve.py"
+
+      - name: Validate wheel metadata
+        run: |
+          python -m pip install --upgrade pip twine
+          python -m twine check wheelhouse/*.whl
+
+      - name: Upload wheel artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: ${{ matrix.artifact_name }}
+          path: wheelhouse/*.whl
+          if-no-files-found: error
+
+  build_sdist:
+    runs-on: ubuntu-latest
+    needs: validate
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --group dev
+
+      - name: Build source distribution
+        run: uv build --sdist
+
+      - name: Validate source distribution
+        run: uv run python -m twine check dist/*.tar.gz
+
+      - name: Upload source distribution
+        uses: actions/upload-artifact@v4
+        with:
+          name: sdist
+          path: dist/*.tar.gz
+          if-no-files-found: error
+
+  publish:
+    runs-on: ubuntu-latest
+    needs:
+      - build_wheels
+      - build_sdist
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Download release artifacts
+        uses: actions/download-artifact@v4
+        with:
+          pattern: "*"
+          path: dist
+          merge-multiple: true
+
+      - name: Publish to TestPyPI
+        if: github.event_name == 'workflow_dispatch' && inputs.target == 'testpypi'
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          packages-dir: dist
+
+      - name: Publish to PyPI (manual)
+        if: github.event_name == 'workflow_dispatch' && inputs.target == 'pypi'
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist
+
+      - name: Publish to PyPI (tag)
+        if: github.event_name == 'push'
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist

graphot-0.0.2/.gitignore

@@ -0,0 +1,41 @@
+# macOS
+.DS_Store
+
+# Python bytecode and caches
+__pycache__/
+*.py[cod]
+
+# Test and lint caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# Virtual environments
+.venv/
+
+# Coverage artifacts
+.coverage
+.coverage.*
+htmlcov/
+
+# Build and packaging artifacts
+build/
+build-*/
+dist/
+*.egg-info/
+.conan/
+.conan2/
+.cache/
+src/graphot/_core*.so
+src/graphot/_core*.pyd
+
+# Notebook artifacts
+.ipynb_checkpoints/
+
+# Example-generated outputs
+examples/output/
+examples/*/output/
+
+reference/
+
+.vscode

graphot-0.0.2/CMakeLists.txt

@@ -0,0 +1,65 @@
+cmake_minimum_required(VERSION 3.22)
+
+project(graphot_core LANGUAGES CXX)
+
+option(GRAPHOT_USE_CONAN "Install C++ dependencies via Conan during CMake configure" ON)
+
+set(CMAKE_CXX_STANDARD 20)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_CXX_EXTENSIONS OFF)
+set(CMAKE_POSITION_INDEPENDENT_CODE ON)
+
+find_package(Python REQUIRED COMPONENTS Interpreter Development.Module)
+
+if(GRAPHOT_USE_CONAN)
+  find_program(GRAPHOT_CONAN_EXECUTABLE conan)
+  if(NOT GRAPHOT_CONAN_EXECUTABLE)
+    message(FATAL_ERROR "GRAPHOT_USE_CONAN=ON but 'conan' was not found on PATH")
+  endif()
+
+  set(GRAPHOT_CONAN_HOME "${CMAKE_BINARY_DIR}/conan-home")
+  set(GRAPHOT_CONAN_OUTPUT "${CMAKE_BINARY_DIR}/conan")
+  set(GRAPHOT_BUILD_TYPE "${CMAKE_BUILD_TYPE}")
+  if(NOT GRAPHOT_BUILD_TYPE)
+    set(GRAPHOT_BUILD_TYPE "Release")
+  endif()
+  file(MAKE_DIRECTORY "${GRAPHOT_CONAN_HOME}")
+  file(MAKE_DIRECTORY "${GRAPHOT_CONAN_OUTPUT}")
+
+  if(NOT EXISTS "${GRAPHOT_CONAN_HOME}/profiles/default")
+    execute_process(
+      COMMAND "${CMAKE_COMMAND}" -E env "CONAN_HOME=${GRAPHOT_CONAN_HOME}" "${GRAPHOT_CONAN_EXECUTABLE}" profile detect --force
+      RESULT_VARIABLE graphot_conan_profile_result
+      COMMAND_ECHO STDOUT
+    )
+    if(NOT graphot_conan_profile_result EQUAL 0)
+      message(FATAL_ERROR "Conan profile detection failed with exit code ${graphot_conan_profile_result}")
+    endif()
+  endif()
+
+  if(NOT EXISTS "${GRAPHOT_CONAN_OUTPUT}/pybind11-config.cmake")
+    execute_process(
+      COMMAND "${CMAKE_COMMAND}" -E env "CONAN_HOME=${GRAPHOT_CONAN_HOME}" "${GRAPHOT_CONAN_EXECUTABLE}" install "${CMAKE_SOURCE_DIR}" -of "${GRAPHOT_CONAN_OUTPUT}" --build=missing -s "build_type=${GRAPHOT_BUILD_TYPE}"
+      RESULT_VARIABLE graphot_conan_result
+      COMMAND_ECHO STDOUT
+    )
+    if(NOT graphot_conan_result EQUAL 0)
+      message(FATAL_ERROR "Conan dependency resolution failed with exit code ${graphot_conan_result}")
+    endif()
+  endif()
+
+  list(PREPEND CMAKE_PREFIX_PATH "${GRAPHOT_CONAN_OUTPUT}")
+endif()
+
+find_package(pybind11 CONFIG REQUIRED)
+
+pybind11_add_module(_core MODULE cpp/graphot_core.cpp)
+target_compile_features(_core PRIVATE cxx_std_20)
+target_compile_definitions(_core PRIVATE PYBIND11_DETAILED_ERROR_MESSAGES=1)
+target_include_directories(_core PRIVATE "${CMAKE_SOURCE_DIR}/cpp")
+
+if(CMAKE_CXX_COMPILER_ID MATCHES "GNU|Clang")
+  target_compile_options(_core PRIVATE -O3 -Wall -Wextra -Wpedantic)
+endif()
+
+install(TARGETS _core LIBRARY DESTINATION graphot)

graphot-0.0.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LvDAO
+
+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.

graphot-0.0.2/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: graphot
+Version: 0.0.2
+Summary: Graph optimal transport on sparse reversible graphs
+Keywords: optimal transport,c++,numpy,scipy,graphs,wasserstein,numerical optimization
+Author: LvDAO
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Project-URL: Homepage, https://github.com/LvDAO/Graph-Optimal-Transport
+Project-URL: Repository, https://github.com/LvDAO/Graph-Optimal-Transport
+Project-URL: Issues, https://github.com/LvDAO/Graph-Optimal-Transport/issues
+Project-URL: Documentation, https://github.com/LvDAO/Graph-Optimal-Transport/tree/main/docs
+Requires-Python: >=3.11
+Requires-Dist: numpy>=2.1
+Requires-Dist: scipy>=1.14
+Provides-Extra: examples
+Requires-Dist: matplotlib>=3.10; extra == "examples"
+Description-Content-Type: text/markdown
+
+# graphot
+
+`graphot` solves dynamic optimal transport on sparse reversible graphs.
+
+Use it when you want:
+- a transport path between two endpoint distributions on a graph,
+- node densities over time,
+- edge fluxes over time,
+- a solver that runs from Python and returns NumPy arrays.
+
+## Install
+
+Install from PyPI:
+
+```bash
+pip install graphot
+```
+
+If you want to run the plotting examples:
+
+```bash
+pip install "graphot[examples]"
+```
+
+If you are working from a local checkout instead, run `pip install .` or
+`pip install ".[examples]"` from the repository root.
+
+These docs use the public import path `graphot`:
+
+```python
+from graphot import solve_ot
+```
+
+## Quick Start
+
+```python
+import numpy as np
+
+from graphot import (
+    GraphSpec,
+    LogMeanOps,
+    OTConfig,
+    OTProblem,
+    TimeDiscretization,
+    solve_ot,
+)
+
+graph = GraphSpec.from_undirected_weights(
+    num_nodes=2,
+    edge_u=[0],
+    edge_v=[1],
+    weight=[1.0],
+)
+
+mass_a = np.array([1.0, 0.0], dtype=np.float64)
+mass_b = np.array([0.0, 1.0], dtype=np.float64)
+
+rho_a = mass_a / graph.pi
+rho_b = mass_b / graph.pi
+
+problem = OTProblem(
+    graph=graph,
+    time=TimeDiscretization(num_steps=64),
+    rho_a=rho_a,
+    rho_b=rho_b,
+    mean_ops=LogMeanOps(),
+)
+
+solution = solve_ot(problem, OTConfig())
+
+print("distance:", float(solution.distance))
+print("converged:", solution.converged)
+print("iterations:", solution.iterations_used)
+```
+
+## Three Things To Remember
+
+- `graphot` expects endpoint densities with respect to `graph.pi`, not raw masses.
+- Convert ordinary masses with `rho = mass / graph.pi`.
+- Check `solution.converged` on harder problems before treating the result as final.
+
+## What You Get Back
+
+The most useful outputs are:
+- `solution.distance`
+- `solution.state.rho`
+- `solution.state.m`
+- `solution.diagnostics`
+
+## Start Here
+
+- [Getting Started](docs/getting-started.md)
+- [Graph Model](docs/graph-model.md)
+- [API Reference](docs/api-reference.md)
+- [Examples Guide](docs/examples-guide.md)
+- [Debugging and Diagnostics](docs/debugging-and-diagnostics.md)
+- [Numerical Limitations](docs/numerical-limitations.md)
+
+## Examples
+
+The repository includes ready-to-run scripts for:
+- two-node transport,
+- cycle transport,
+- line transport,
+- directed reversible transport,
+- large-grid transport.
+
+See [examples/README.md](examples/README.md) for the example index.

graphot-0.0.2/README.md

@@ -0,0 +1,108 @@
+# graphot
+
+`graphot` solves dynamic optimal transport on sparse reversible graphs.
+
+Use it when you want:
+- a transport path between two endpoint distributions on a graph,
+- node densities over time,
+- edge fluxes over time,
+- a solver that runs from Python and returns NumPy arrays.
+
+## Install
+
+Install from PyPI:
+
+```bash
+pip install graphot
+```
+
+If you want to run the plotting examples:
+
+```bash
+pip install "graphot[examples]"
+```
+
+If you are working from a local checkout instead, run `pip install .` or
+`pip install ".[examples]"` from the repository root.
+
+These docs use the public import path `graphot`:
+
+```python
+from graphot import solve_ot
+```
+
+## Quick Start
+
+```python
+import numpy as np
+
+from graphot import (
+    GraphSpec,
+    LogMeanOps,
+    OTConfig,
+    OTProblem,
+    TimeDiscretization,
+    solve_ot,
+)
+
+graph = GraphSpec.from_undirected_weights(
+    num_nodes=2,
+    edge_u=[0],
+    edge_v=[1],
+    weight=[1.0],
+)
+
+mass_a = np.array([1.0, 0.0], dtype=np.float64)
+mass_b = np.array([0.0, 1.0], dtype=np.float64)
+
+rho_a = mass_a / graph.pi
+rho_b = mass_b / graph.pi
+
+problem = OTProblem(
+    graph=graph,
+    time=TimeDiscretization(num_steps=64),
+    rho_a=rho_a,
+    rho_b=rho_b,
+    mean_ops=LogMeanOps(),
+)
+
+solution = solve_ot(problem, OTConfig())
+
+print("distance:", float(solution.distance))
+print("converged:", solution.converged)
+print("iterations:", solution.iterations_used)
+```
+
+## Three Things To Remember
+
+- `graphot` expects endpoint densities with respect to `graph.pi`, not raw masses.
+- Convert ordinary masses with `rho = mass / graph.pi`.
+- Check `solution.converged` on harder problems before treating the result as final.
+
+## What You Get Back
+
+The most useful outputs are:
+- `solution.distance`
+- `solution.state.rho`
+- `solution.state.m`
+- `solution.diagnostics`
+
+## Start Here
+
+- [Getting Started](docs/getting-started.md)
+- [Graph Model](docs/graph-model.md)
+- [API Reference](docs/api-reference.md)
+- [Examples Guide](docs/examples-guide.md)
+- [Debugging and Diagnostics](docs/debugging-and-diagnostics.md)
+- [Numerical Limitations](docs/numerical-limitations.md)
+
+## Examples
+
+The repository includes ready-to-run scripts for:
+- two-node transport,
+- cycle transport,
+- line transport,
+- directed reversible transport,
+- large-grid transport.
+
+See [examples/README.md](examples/README.md) for the example index.

graphot-0.0.2/conanfile.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from conan import ConanFile
+
+
+class GraphOTConan(ConanFile):
+    name = "graphot-core"
+    version = "0.0.2"
+    package_type = "application"
+
+    settings = "os", "arch", "build_type"
+    generators = "CMakeDeps"
+
+    requires = (
+        "pybind11/2.13.6",
+    )
+
+    def configure(self) -> None:
+        self.options["pybind11/*"].shared = False