🚀 Replace Julia/ROMEO backend with pure C++ port

[vanandrew]

Summary

Replaces the Julia-backed ROMEO phase-unwrapping path with a self-contained C++17 port (header-only under include/romeo/), then layers on the polish that fell out of the migration: modernized tooling, typed CLI, type stubs for the compiled extension, comprehensive tests, and docs/conventions.

Core change — Julia → C++

• ROMEO C++ port: unwrap_3d/unwrap_4d/voxelquality ported from ROMEO.jl v1.0.0. Self-contained, no runtime Julia dependency. Plan and provenance documented in notes/ROMEO_port_plan.md.
• Build/CI/Docker stripped of Julia: CMakeLists.txt, setup.py, Dockerfile, GitHub Actions workflow, cibuildwheel, conda recipe (the conda recipe was deleted entirely — it only existed to bootstrap Julia). macOS wheels re-enabled now that Julia isn't blocking.

Tooling modernization

• uv for deps, lockfile committed.
• ruff + pyright replace black/isort/pycodestyle. All naming made lowercase snake_case (no TEs, TE0, X, Y, W etc.) — ruff's N803/N806 selected with no per-file ignore.
• Python ≥ 3.11 baseline. Modern syntax (X | None, list[T], collections.abc imports).
• setuptools-scm for versioning.
• Pre-commit hooks: ruff check/format, pyright, plus a commit-msg gitmoji enforcer (scripts/check-gitmoji.sh). default_install_hook_types: [pre-commit, commit-msg] so pre-commit install wires both stages automatically.

Type stubs

• warpkit/warpkit_cpp.pyi generated by pybind11-stubgen, warpkit/py.typed marker shipped via MANIFEST.in + [tool.setuptools.package-data]. Downstream consumers see proper types for the compiled extension.
• scripts/regen-stub.sh wraps stubgen + the numpy.bool → numpy.bool_ rewrite + ruff fix-up so regenerations stay clean.
• All # type: ignore blanket suppressions on cpp imports dropped; pre-existing pyright debt cleaned up (no remaining reportArgumentType/reportAssignmentType/reportReturnType demotions).

CLI improvements

• medic: --out-prefix now required. Acquisition parameters can come from BIDS sidecars (--metadata) or be passed directly (--TEs, --total-readout-time, --phase-encoding-direction); the two are mutually exclusive. All long flags switched to dash form (--out-prefix, --total-readout-time, etc.) while keeping --TEs for MR convention.
• extract_field_from_maps: dash-form flags.
• Both expose --version.

CI / cibuildwheel

• Skip *musllinux* and free-threaded builds (cp313t-*, cp314t-*) — the latter was producing two cp314 wheels and breaking the test-wheel install step's glob.
• -march=x86-64-v2 baseline on x86_64 wheels (SSE3/SSE4.2/POPCNT — no v3 aggression, pre-Haswell CPUs would SIGILL).
• linux/aarch64 wheels built on the ubuntu-24.04-arm GHA runner alongside x86_64 and macOS universal2. Linux archs = ["auto"] so each runner builds its native arch — tests exercise the aarch64 wheel on real hardware (no QEMU).
• No gating dev-test job. The standalone test job that ran the dev install + pytest before the wheel matrix has been removed; the wheel matrix and sdist+coverage now run in parallel from the start of each push. Coverage instrumentation + Codecov upload moved into sdist-build (still ubuntu-latest, still editable install). Per-cell wheel test step continues to exercise the built artifact.

Docker

• Multi-arch image (linux/amd64 + linux/arm64) built via per-platform matrix on native runners (ubuntu-latest and ubuntu-24.04-arm) — no QEMU emulation. Distributed-build → digest-export → docker buildx imagetools create manifest-merge pattern.
• Build runs on every push (Dockerfile rot is now caught in PR CI). Only the push-by-digest + manifest publish to GHCR are gated on release.published. New docker-publish job handles the manifest merge under the release environment.

Tests

• 14 → 71 passing. Coverage 71% → 84%.
• New: tests/test_romeo.py (port-validation goldens + property tests against ROMEO.jl's vendored Phase.nii/Mag.nii, MIT-attributed under tests/data/romeo/). tests/test_unwrap.py (reject_outliers, compute_offset with known 2π shift recovery). tests/test_scripts.py (CLI argparse paths for both scripts).
• Extended: test_utilities.py covers normalize, rescale_phase, mask helpers, orientation transforms, fmap↔dmap round trips parameterized over all 6 PE directions, displacement field inversion, Hausdorff identity/symmetry, convert_warp validation. test_distortion.py covers affine/shape mismatch + None-affine paths. test_concurrency.py covers DummyExecutor + all three executor backends.

Repo conventions

• CLAUDE.md documents layout, dev workflow, conventions (lowercase naming, no Julia, modern Python, no blanket type-ignore), gitmoji commit/PR style with shortcode table, and CI specifics.

Test plan

• uv sync --group dev --config-setting editable_mode=strict succeeds on a machine with no Julia installed
• uv run pytest -q → 71 passed
• uv run --with ruff ruff check → clean
• uv run --with ruff ruff format --check → clean
• uv run --with pyright pyright → 0 errors
• uv run pre-commit run --all-files → all hooks pass (ruff check, ruff format, pyright)
• commit-msg hook rejects non-gitmoji subjects, allows merge/revert/fixup, accepts gitmoji shortcodes
• docker build . succeeds without fetching Julia
• medic --help against the installed entrypoint shows the new dash-form flags + either-or acquisition arg structure
• grep -ri julia --exclude-dir=.venv --exclude-dir=tests/data returns only algorithm-provenance references in C++ headers (documentation, not a runtime dep)
• CI green on Linux x86_64 + macOS universal2 wheel matrix for Python 3.11–3.14 (Copilot-flagged review comments addressed in d759c1e)
• CI green on linux/aarch64 wheel matrix (ubuntu-24.04-arm) for Python 3.11–3.14 — added in 4651f99, first run pending
• CI green after dropping the dev-test gate — wheel matrix + sdist/coverage run in parallel from push (2e2c9b7), Codecov upload still succeeds from sdist-build
• CI green on the multi-arch Docker matrix (d1cdfb2) — both linux/amd64 and linux/arm64 build on every PR push; manifest publish only fires on release.published

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR removes the Julia-based ROMEO dependency and replaces it with a header-only C++17 ROMEO port (unwrap + voxelquality) exposed via pybind11, while also modernizing packaging/tooling (uv, ruff, pyright, Python ≥3.11) and updating CLI/test infrastructure accordingly.

Changes:

• Replace Julia ROMEO backend with a pure C++ ROMEO port under include/romeo/, and update pybind11 bindings/types.
• Remove Julia from build/packaging/CI/Docker and migrate Python tooling to uv + ruff + pyright with Python 3.11+.
• Add ROMEO parity/behavior tests and refresh MEDIC test fixtures and CLI metadata handling.

Reviewed changes

Copilot reviewed 54 out of 65 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
warpkit/warpkit_cpp.pyi	Adds/updates type stubs for the compiled extension, including new ROMEO APIs.
warpkit/utilities.py	Typing + formatting updates; minor refactors around orientation transforms and ITK-backed helpers.
warpkit/unwrap.py	Switches unwrapping backend from JuliaContext to C++ Romeo bindings; updates naming/types and iterator plumbing.
warpkit/scripts/medic.py	CLI updated to support either BIDS sidecars or direct acquisition args; adds --version and renames flags.
warpkit/scripts/extract_field_from_maps.py	CLI polish: --version, renamed flags to kebab-case, small typing improvements.
warpkit/py.typed	Marks package as typed for downstream type checkers.
warpkit/model.py	Modernizes typing and variable naming (x/y/w) for weighted regression.
warpkit/julia.py	Removes JuliaContext shim (Julia dependency eliminated).
warpkit/distortion.py	Updates typing and echo-time naming; small formatting and cast narrowings.
warpkit/concurrency.py	Updates typing imports and refines DummyExecutor shutdown signature.
warpkit/init.py	Removes Julia auto-install preflight; uses setuptools-scm versioning; keeps WARPKIT_DEV behavior.
tests/test_utilities.py	Updates variable names to match new style.
tests/test_romeo.py	Adds comprehensive ROMEO port validation tests (goldens + properties + behavior).
tests/test_model.py	Updates variable names to match new style.
tests/test_julia.py	Removes JuliaContext test (Julia removed).
tests/test_distortion.py	Switches MEDIC pipeline test to use new fixture name/source.
tests/test_concurrency.py	Removes unused pytest import.
tests/data/test_data/sub-a01_task-rest_acq-tr1800_echo-3_part-phase_bold.json	Adds local test sidecar for echo 3 phase.
tests/data/test_data/sub-a01_task-rest_acq-tr1800_echo-3_part-mag_bold.json	Adds local test sidecar for echo 3 magnitude.
tests/data/test_data/sub-a01_task-rest_acq-tr1800_echo-2_part-phase_bold.json	Adds local test sidecar for echo 2 phase.
tests/data/test_data/sub-a01_task-rest_acq-tr1800_echo-2_part-mag_bold.json	Adds local test sidecar for echo 2 magnitude.
tests/data/test_data/sub-a01_task-rest_acq-tr1800_echo-1_part-phase_bold.json	Adds local test sidecar for echo 1 phase.
tests/data/test_data/sub-a01_task-rest_acq-tr1800_echo-1_part-mag_bold.json	Adds local test sidecar for echo 1 magnitude.
tests/data/download_bids_testdata.sh	Removes dead download script for old BIDS dataset.
tests/conftest.py	Introduces a new local test-data fixture loader for MEDIC tests.
tests/init.py	Removes old pybids-based fixture wiring.
src/warpkit.cpp	Replaces JuliaContext bindings with C++ ROMEO facade + new method names.
setup.py	Removes Julia preflight and adjusts build config for new toolchain expectations.
setup.cfg	Removes pycodestyle config (ruff now used).
scripts/check-gitmoji.sh	Adds commit-msg hook enforcing gitmoji shortcode convention.
pyproject.toml	Migrates to Python ≥3.11, uv dependency groups, ruff/pyright config, setuptools-scm versioning, updated cibuildwheel config.
notes/ROMEO_port_plan.md	Adds detailed plan/provenance for the ROMEO C++ port and rollout phases.
include/romeo/weights.h	Implements ROMEO :romeo weight computation and rescaling logic in C++.
include/romeo/voxel_quality.h	Implements voxel quality calculation and aggregation logic.
include/romeo/volume_view.h	Adds minimal column-major volume view declarations.
include/romeo/utility.h	Adds ROMEO utility helpers (gamma_fold, rem2pi_nearest, NBINS).
include/romeo/unwrap.h	Implements 3D/4D unwrap orchestration and global correction logic.
include/romeo/seed.h	Implements single-echo and multi-echo seed correction.
include/romeo/romeo.h	Provides Python-facing C++ Romeo facade implementing pybind-callable entry points.
include/romeo/priority_queue.h	Implements bucket priority queue matching ROMEO.jl dequeue semantics.
include/romeo/algorithm.h	Implements MST region-growing and unwrap edge logic.
include/romeo/README.md	Documents ROMEO port scope and provenance.
include/romeo/LICENSE	Includes upstream ROMEO MIT license.
include/romeo.h	Removes old Julia-based ROMEO bridge header.
conda/warpkit-conda-install.sh	Removes conda installer script.
conda/meta.yaml	Removes conda recipe (Julia-based).
cmake_aux/FindJulia.cmake	Removes Julia CMake discovery module.
README.md	Updates installation/build/docs to reflect Julia removal and new CLI behavior.
MANIFEST.in	Ensures py.typed and .pyi ship in sdists.
Dockerfile	Removes Julia stages and switches to uv-managed Python + deps.
CMakeLists.txt	Removes Julia linkage, updates pybind11/ITK pins, and adjusts compile flags.
CLAUDE.md	Adds repository conventions and workflow notes (tooling, naming, CI expectations).
.python-version	Pins Python 3.11 for local dev (uv-managed).
.pre-commit-config.yaml	Replaces black/isort with ruff + adds pyright + commit-msg hook.
.gitignore	Adjusts ignores (keep .python-version tracked; ignore generated _version.py; scratch dir tweak).
.github/workflows/build.yml	Removes Julia from CI, moves to uv, updates wheel matrix and actions versions.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[codecov]

Codecov Report

❌ Patch coverage is 86.76471% with 27 lines in your changes missing coverage. Please review.
✅ Project coverage is 83.54%. Comparing base (ca12028) to head (e6a64ae).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
warpkit/unwrap.py	88.63%	10 Missing ⚠️
warpkit/__init__.py	25.00%	6 Missing ⚠️
warpkit/scripts/medic.py	89.18%	4 Missing ⚠️
warpkit/scripts/extract_field_from_maps.py	50.00%	3 Missing ⚠️
warpkit/utilities.py	91.89%	3 Missing ⚠️
warpkit/distortion.py	94.11%	1 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##             main      #16       +/-   ##
===========================================
+ Coverage   70.05%   83.54%   +13.48%     
===========================================
  Files           7        9        +2     
  Lines         551      632       +81     
===========================================
+ Hits          386      528      +142     
+ Misses        165      104       -61     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.