parx 0.1.0__tar.gz

parx-0.1.0/.envrc

@@ -0,0 +1,3 @@
+source ~/.config/direnv/functions.zsh
+source ~/.config/direnv/terminal_colours.zsh
+switch_terminal_bg "$TERM_COLOR_NAVY"

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

@@ -0,0 +1,55 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: Python ${{ matrix.python-version }} / Julia ${{ matrix.julia-version }}
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+        julia-version: ["1.10"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Julia
+        uses: julia-actions/setup-julia@v2
+        with:
+          version: ${{ matrix.julia-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Create virtual environment
+        run: uv venv --python ${{ matrix.python-version }}
+
+      - name: Install Python dependencies
+        run: uv pip install -e ".[dev]"
+
+      - name: Instantiate Julia environment
+        run: julia --project=src/parx/julia -e "using Pkg; Pkg.instantiate()"
+
+      - name: Lint with ruff
+        run: uv run ruff check src/ tests/
+
+      - name: Run tests
+        run: uv run pytest --cov=parx --cov-report=xml
+        env:
+          JULIA_NUM_THREADS: "2"
+
+      - name: Upload coverage
+        uses: codecov/codecov-action@v4
+        with:
+          file: coverage.xml
+        continue-on-error: true

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

@@ -0,0 +1,72 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - "src/**"
+      - ".github/workflows/docs.yml"
+  pull_request:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - "src/**"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build MkDocs site
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Configure GitHub Pages
+        if: github.event_name != 'pull_request'
+        uses: actions/configure-pages@v5
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Create virtual environment
+        run: uv venv --python 3.12
+
+      - name: Install docs dependencies
+        run: uv pip install "mkdocs>=1.6" "mkdocs-material>=9.5" "mkdocstrings[python]>=0.26"
+
+      - name: Build site
+        run: uv run mkdocs build --strict
+
+      - name: Upload Pages artifact
+        if: github.event_name != 'pull_request'
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: site
+
+  deploy:
+    name: Deploy to GitHub Pages
+    needs: build
+    if: github.event_name != 'pull_request'
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

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

@@ -0,0 +1,56 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # setuptools-scm needs full history + tags to compute the version;
+          # a shallow checkout would silently produce a 0.0.devN version.
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/parx/
+    permissions:
+      id-token: write # required for Trusted Publishing (OIDC) — no API token stored
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Publish to PyPI
+        run: uv publish --trusted-publishing always

parx-0.1.0/.gitignore

@@ -0,0 +1,61 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+venv/
+.env
+
+# uv
+.uv/
+uv.lock          # commit this if you want locked Python deps, otherwise ignore
+
+# Pytest / coverage
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Ruff / mypy
+.ruff_cache/
+.mypy_cache/
+
+# Julia
+# Do NOT ignore Manifest.toml — it should be committed for reproducibility
+*.jl.cov
+*.jl.mem
+/depot/
+
+# Local packaging/release working notes — not meant for the public repo
+/road2publish.md
+
+# Claude Code
+.claude/
+CLAUDE.md
+memory/
+
+# Examples output
+examples/output/
+
+# Editors
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Store
+
+# Jupyter (if you add notebooks later)
+.ipynb_checkpoints/
+*.ipynb
+
+# marimo
+__marimo__/
+.marimo_agent_state.json
+layouts/
+project_overview.py
+
+# MkDocs
+site/

parx-0.1.0/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
+once it reaches 1.0.
+
+## [Unreleased]
+
+### Fixed
+- `pyproject.toml` referenced a nonexistent `LICENSE` file while the tracked
+  `LICENCE` file was empty; replaced with a real MIT `LICENSE` and the modern
+  SPDX `license`/`license-files` metadata form.
+- The built sdist/wheel silently omitted all Julia source files
+  (`src/parx/julia/src/*.jl`) because `package-data`'s `julia/*` glob does not
+  recurse into the nested `julia/src/` directory. Anyone installing from a
+  built artifact (rather than an editable/source checkout) would have hit a
+  hard failure on first import. Fixed by adding `julia/src/*` to
+  `package-data`.
+- README referenced a `parx[analysis]` extra that did not exist in
+  `pyproject.toml`; added it (`scikit-learn`, used by `plot_partition_pca`).
+- Stale/placeholder content in `CONTRIBUTING.md` (clone URL, test file
+  listing) and a broken `LICENCE` link in `README.md`.
+
+### Added
+- `LICENSE` (MIT).
+- `CITATION.cff` for GitHub's citation button and future Zenodo archival.
+- CI/docs/license/Python-version badges in `README.md`.
+- `road2publish.md`, tracking the path to a PyPI release and Zenodo DOI.
+
+### Changed
+- Untracked marimo/layout tool artifacts (`.marimo_agent_state.json`,
+  `__marimo__/session/*.json`, `layouts/*.json`, `project_overview.py`) that
+  don't belong in the package; they remain on disk but are now gitignored.

parx-0.1.0/CITATION.cff

@@ -0,0 +1,31 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+title: "parx: Polyhedral Affine Region eXplorer"
+abstract: >-
+  Exact enumeration and analysis of the linear (polyhedral activation)
+  regions of ReLU neural networks. A Python API layered over a Julia
+  backend for the combinatorially intensive region-finding algorithms.
+type: software
+version: 0.1.0
+date-released: "2026-07-03"
+license: MIT
+repository-code: "https://github.com/Johanmkr/parx"
+url: "https://github.com/Johanmkr/parx"
+authors:
+  - family-names: Mylius-Kroken
+    given-names: Johan
+    email: johan.m.kroken@gmail.com
+    orcid: https://orcid.org/0009-0005-8580-372X
+keywords:
+  - neural networks
+  - linear regions
+  - polyhedral
+  - ReLU
+  - piecewise linear
+  - affine
+  - interpretability
+  - geometry
+# identifiers:
+#   - type: doi
+#     value: 10.5281/zenodo.XXXXXXX
+#     description: Zenodo archive of this repository (added once a DOI exists — see road2publish.md Phase 4)

parx-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,217 @@
+# Contributing to parx
+
+## Prerequisites
+
+- Python ≥ 3.10
+- Julia ≥ 1.10 (install via [juliaup](https://github.com/JuliaLang/juliaup))
+- [uv](https://github.com/astral-sh/uv) (recommended) or pip
+
+---
+
+## Setting Up the Development Environment
+
+### 1. Clone the repository
+
+```bash
+git clone https://github.com/Johanmkr/parx
+cd parx
+```
+
+### 2. Create a virtual environment and install dependencies
+
+**With uv (recommended):**
+```bash
+uv venv                         # creates .venv/
+source .venv/bin/activate       # Windows: .venv\Scripts\activate
+uv pip install -e ".[dev]"
+```
+
+**With pip:**
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+### 3. Verify the setup
+
+```bash
+pytest
+```
+
+All tests should pass.
+
+---
+
+## Project Structure
+
+```
+parx/
+├── pyproject.toml              # build config, dependencies, tool config
+├── README.md
+├── CONTRIBUTING.md
+├── LICENSE
+├── .github/
+│   └── workflows/
+│       ├── ci.yml               # GitHub Actions CI
+│       └── docs.yml             # builds & deploys the docs site to GitHub Pages
+├── mkdocs.yml                   # docs site config
+├── docs/                        # docs site content (see "Docs site" below)
+├── tests/
+│   ├── conftest.py
+│   ├── test_analysis.py
+│   ├── test_diagnostics.py
+│   ├── test_io.py
+│   ├── test_io_partition.py
+│   ├── test_julia_bridge.py
+│   ├── test_methods.py
+│   ├── test_mlp.py
+│   ├── test_network.py
+│   ├── test_partition.py
+│   ├── test_verify.py
+│   └── test_viz.py
+└── src/
+    └── parx/
+        ├── __init__.py         # public API surface
+        ├── _check.py           # startup checks (Julia on PATH, etc.)
+        ├── _julia_init.py      # Julia runtime initialization
+        ├── _lp.py              # Chebyshev center LP helper
+        ├── network.py          # network loading (.pth, .h5)
+        ├── region.py           # Region dataclass
+        ├── partition.py        # Partition object + halfspaces/route/filter
+        ├── methods/            # region-finding backends
+        │   ├── __init__.py
+        │   ├── sparse_julia.py
+        │   ├── exact_julia.py
+        │   ├── exact_julia_fast.py
+        │   ├── sparse_python.py
+        │   └── exact_python.py
+        ├── io.py               # iter_state_dicts helper
+        ├── verify.py           # overlap/coverage checks
+        ├── viz.py              # Plotly (default) / matplotlib visualizations
+        ├── juliapkg.json       # Julia runtime dependencies (for juliacall/juliapkg)
+        └── julia/
+            ├── LinearRegions.jl
+            ├── bridge.jl
+            ├── sparse.jl
+            ├── exact.jl
+            ├── lp.jl
+            ├── Project.toml    # standalone Julia environment (for direct Julia testing)
+            └── Manifest.toml   # locked deps for standalone environment
+```
+
+---
+
+## Development Workflow
+
+### Running tests
+```bash
+pytest                          # run all tests
+pytest tests/test_methods.py   # run a specific file
+pytest -x                      # stop on first failure
+pytest --cov=parx               # with coverage
+```
+
+### Linting and formatting
+```bash
+ruff check src/ tests/          # lint
+ruff format src/ tests/         # format
+```
+
+### Testing the Julia code independently
+
+You can test Julia code directly without going through Python:
+```bash
+cd src/parx/julia
+julia --project=. -e "using LinearRegions; LinearRegions.run_tests()"
+```
+
+---
+
+## Docs site
+
+The docs site (published at [johanmkr.github.io/parx](https://johanmkr.github.io/parx/)) is built with MkDocs from `docs/` and deployed by `.github/workflows/docs.yml` whenever `docs/` or `mkdocs.yml` changes on `main`.
+
+```bash
+uv pip install -e ".[docs]"
+mkdocs serve      # live preview at http://127.0.0.1:8000
+mkdocs build --strict   # what CI runs; fails on broken nav/links
+```
+
+The three demo notebooks are embedded on the Notebooks page as pre-exported static HTML (`docs/notebooks/demo_plt.html`, `docs/notebooks/demo_plotly.html`, `docs/notebooks/feature_embedding.html`) — the docs build itself has no Julia/PyTorch dependency, so this export step is manual. **After editing any of `notebooks/demo_plt.py`, `notebooks/demo_plotly.py`, or `notebooks/feature_embedding.py`, re-export before committing:**
+
+```bash
+marimo export html notebooks/demo_plt.py -o docs/notebooks/demo_plt.html
+marimo export html notebooks/demo_plotly.py -o docs/notebooks/demo_plotly.html
+marimo export html notebooks/feature_embedding.py -o docs/notebooks/feature_embedding.html
+```
+
+---
+
+## Adding Julia Dependencies
+
+parx uses two separate Julia environments:
+
+- **Runtime environment** — managed by juliacall/juliapkg, stored in `.venv/julia_env`.
+  Declare new packages in `src/parx/juliapkg.json`.  juliacall resolves and installs them
+  automatically on the next `import parx`.  No manual `Pkg.add` needed.
+
+- **Standalone testing environment** — `src/parx/julia/Project.toml`.  Used only for
+  running Julia code directly (see "Testing the Julia code independently" above).
+  Add packages here with:
+
+```bash
+cd src/parx/julia
+julia --project=.
+```
+```julia
+using Pkg
+Pkg.add("SomePackage")   # updates Project.toml and Manifest.toml
+```
+
+Commit both `Project.toml` and `Manifest.toml` when changing the standalone environment.
+
+For packages needed at runtime, edit `src/parx/juliapkg.json` and commit that file.
+
+---
+
+## Environment Variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `JULIA_NUM_THREADS` | `"auto"` | Number of Julia threads |
+| `PYTHON_JULIACALL_HANDLE_SIGNALS` | `"yes"` | Makes the harmless segfault at exit (when Julia threads are active) happen cleanly after results are already reported, instead of during teardown. It does not prevent the segfault itself — if you see one, check the run's actual output/exit status first; a `"N passed"` line means the run succeeded despite it. |
+| `PYTHON_JULIAPKG_EXE` | auto-detected on juliaup (see below) | Force juliacall to use a specific Julia binary instead of auto-resolving one. |
+
+---
+
+## Troubleshooting
+
+### `ERROR: could not load library ".../juliaup/bin/../lib/julia/sys.so": ... No such file or directory`
+
+This used to happen on the **first** call that touches Julia (`ensure_julia()`, any `*_julia`/`exact_julia*` method, or the `julia_session` pytest fixture) on a machine where Julia was installed via [juliaup](https://github.com/JuliaLang/juliaup) — i.e. exactly the install method this repo recommends. **`parx` now works around it automatically** (`_julia_init.py::_resolve_juliaup_shim`) — read on for what it does and what to do if you still hit this.
+
+**Cause:** `julia` on `PATH` is juliaup's launcher shim (`~/.juliaup/bin/julia`), not a real Julia install — juliaup keeps the actual per-version binaries elsewhere (`~/.julia/juliaup/julia-<version>+.../`). `juliapkg` tries to auto-upgrade to the newest Julia release on every resolve; when that opportunistic install fails (network hiccup, a not-yet-fully-available release, etc.) it silently falls back to the raw shim path instead of one of your already-installed, perfectly good Julia versions, and juliacall then derives the system-image path relative to the shim's directory — which never has a `lib/julia/sys.so` next to it. This is a `juliapkg` bug, not a `parx` one; it's invisible in CI because CI installs Julia directly (`julia-actions/setup-julia@v2`), never through juliaup.
+
+**The automatic fix:** before `juliacall` is ever imported, `ensure_julia()` checks whether `julia` on `PATH` resolves to a juliaup launcher shim (`os.path.realpath` ends in `julialauncher`). If so, it reads `~/.julia/juliaup/juliaup.json` directly to find the real binary behind juliaup's *default* channel, and sets `PYTHON_JULIAPKG_EXE` to that real path (via `os.environ.setdefault`, so it never overrides an explicit value you've already set) — juliapkg then uses that binary directly instead of falling back to the broken shim path. Confirmed end-to-end: a from-scratch clone + `uv venv` + `pip install -e ".[dev]"` + `pytest`, with **zero manual env vars**, now passes cleanly (`219 passed`).
+
+**If it still happens anyway** (e.g. juliaup's on-disk metadata format has changed since this was written, or you're using something other than juliaup — a container image with a hand-rolled Julia install, `asdf`, etc.), the detection silently no-ops and you're back to the original failure. Fall back to pointing juliacall at a known-good binary yourself:
+
+```bash
+juliaup list                                    # see what's installed, e.g. 1.10.11+0.x64.linux.gnu
+export PYTHON_JULIAPKG_EXE="$HOME/.julia/juliaup/julia-1.10.11+0.x64.linux.gnu/bin/julia"
+```
+
+(matching the Julia 1.10 that CI and `src/parx/julia/Manifest.toml` are pinned to is the safest bet — a newer version may work but isn't what's tested). Then delete any stale resolution and retry: `rm -rf .venv/julia_env`. If you had to do this, please open an issue — it means the auto-detection missed a case and should be taught about it.
+
+If you'd rather not hardcode a version path, `export PYTHON_JULIAPKG_OFFLINE=yes` also avoids the buggy auto-upgrade path (it makes juliapkg reuse the newest **already-installed** juliaup version instead of trying to fetch a new one) — simpler, but it may still land you on a newer, less-tested Julia than pinning to 1.10 would.
+
+---
+
+## Pull Request Checklist
+
+- [ ] Tests pass (`pytest`)
+- [ ] Code is formatted (`ruff format`)
+- [ ] No lint errors (`ruff check`)
+- [ ] New functionality has tests
+- [ ] `Manifest.toml` is committed if Julia deps changed

parx-0.1.0/LICENSE

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