Add fastpidc: standalone Python port of FastPIDC.jl

.github/workflows/python-CI.yml

@@ -0,0 +1,55 @@
+name: Python CI
+
+on:
+  push:
+    branches:
+      - master
+    tags:
+      - "v*"
+    paths:
+      - "python/**"
+      - ".github/workflows/python-CI.yml"
+  pull_request:
+    paths:
+      - "python/**"
+      - ".github/workflows/python-CI.yml"
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ startsWith(github.ref, 'refs/pull/') }}
+
+defaults:
+  run:
+    working-directory: python
+
+jobs:
+  test:
+    name: Python ${{ matrix.python-version }} - ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.13"]
+        os:
+          - ubuntu-latest
+          - macos-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: julia-actions/setup-julia@v2
+        with:
+          version: "1"
+      - uses: julia-actions/cache@v2
+      - uses: julia-actions/julia-buildpkg@v1
+        with:
+          project: "."
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync
+      - run: uv run ruff check .
+      - run: uv run pytest -q
+        # Julia-cross-validation and CUDA-backend tests skip themselves when
+        # julia / a GPU aren't available; the FastPIDC.jl project above is
+        # instantiated so those tests actually run (rather than erroring)
+        # on runners that ship a preinstalled julia, e.g. ubuntu-latest.

.gitignore

@@ -12,4 +12,14 @@
 
 # Documenter build output
 /docs/build/
-/docs/Manifest.toml
+/docs/Manifest.toml
+
+# Python (python/)
+python/.venv/
+**/__pycache__/
+*.py[cod]
+*.egg-info/
+python/.pytest_cache/
+python/.ruff_cache/
+python/.coverage
+python/htmlcov/

Project.toml

@@ -26,7 +26,8 @@ julia = "≥ 1.0.0"
 
 [extras]
 DelimitedFiles = "8bb1440f-4735-579b-a4ab-409b98df4dab"
+LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 
 [targets]
-test = ["DelimitedFiles", "Test"]
+test = ["DelimitedFiles", "LinearAlgebra", "Test"]

README.md

@@ -2,6 +2,41 @@
 
 Documentation: https://meyer-lab.github.io/FastPIDC.jl/
 
+## Repository layout
+
+This repository holds two independent implementations of the same
+algorithms, released and versioned separately, kept in one place so they're
+easy to keep in sync:
+
+* **Julia** (`Project.toml`, `src/`, `ext/`, `test/`, `CLI_fastpidc.jl` at
+  the repository root) - the original package, `FastPIDC.jl`, registered
+  and installed the normal Julia way (`Pkg.add("FastPIDC")`). Its CI is
+  `.github/workflows/CI.yml`.
+* **Python** (`python/`) - `fastpidc`, a standalone NumPy/SciPy port (it
+  does not call out to Julia at runtime), managed with
+  [uv](https://docs.astral.sh/uv/). See `python/README.md` for
+  installation and usage. Its CI is `.github/workflows/python-CI.yml`,
+  scoped to only run on changes under `python/`.
+
+Each package has its own dependency manifest, test suite and CI workflow,
+so a change to one cannot break the other's build. `python/tests/` also
+cross-validates its results against a freshly run `FastPIDC.jl` (skipped
+automatically when `julia` isn't on `PATH`, e.g. in most CI runs) using the
+shared fixtures under `test/data/` and `test/baseline_outputs/` - these are
+Julia-agnostic edge lists, so both packages can use them without conflict.
+
+The two packages' GPU acceleration shares one implementation: the CUDA
+kernels live in
+[`python/src/fastpidc/kernels/pidc_kernels.cu`](python/src/fastpidc/kernels/pidc_kernels.cu),
+written in plain CUDA C so they can be compiled from either language.
+Python's `cuda` backend loads it via `cupy` (nvrtc); the Julia extension
+(`ext/FastPIDCCUDAExt`) compiles it with `nvcc` and drives it with
+`CUDA.jl`'s `cudacall` - see that file's header comment for both.
+
+When changing the algorithm, update both `src/`/`ext/` (Julia) and
+`python/src/fastpidc/` (Python and the shared kernel) together, and re-run
+`python/tests` with `julia` on `PATH` to confirm they still agree.
+
 ## Description
 
 NetworkInference is a package for inferring (undirected) networks, given a set of measurements for each node. The main output is the `InferredNetwork` type, which represents a fully connected, weighted network, where an edge's weight indicates the relative confidence of that edge existing in the true network. See also [Scope](#scope).

docs/src/api.md

@@ -143,8 +143,16 @@ Loaded automatically when `using CUDA` alongside `FastPIDC`.
 
 ```@docs
 FastPIDCCUDAExt
-FastPIDCCUDAExt.joint_counts_kernel_chunked!
-FastPIDCCUDAExt.mi_si_kernel_chunked!
-FastPIDCCUDAExt.puc_accumulation_kernel_chunked!
-FastPIDCCUDAExt.bayesian_blocks_dp_kernel!
+FastPIDCCUDAExt._kernel_source_path
+FastPIDCCUDAExt._compile_ptx
+FastPIDCCUDAExt._get_module
+FastPIDCCUDAExt._bb_kernel_name
+FastPIDC.bayesian_blocks_cuda_available
+FastPIDC.solve_bayesian_blocks_cuda
 ```
+
+The GPU kernels themselves (`joint_counts_kernel`, `mi_si_kernel`,
+`puc_accumulation_kernel`) are plain CUDA C, not Julia, so they aren't
+Julia docstrings; see the header comments in
+`python/src/fastpidc/kernels/pidc_kernels.cu`, the canonical source shared
+with the Python package.