From 9fd95b75e461f75294e1ac14160b6ae1fac2c4a7 Mon Sep 17 00:00:00 2001 From: Max Lapin <4691364+mlapin@users.noreply.github.com> Date: Mon, 16 Nov 2026 12:30:39 +0100 Subject: [PATCH 1/6] libsdca 0.3.1: shared CPU and CUDA kernels for PyTorch and JAX, float32 work by default See CHANGELOG.md for the changes since 0.3.0. The numerics and performance write-ups under docs/ are replaced by the known limits in docs/API.md, the benchmarks in python/TORCH.md and the technical report. --- .github/workflows/ci.yml | 8 +- .github/workflows/packages.yml | 62 +- .gitignore | 1 + AGENTS.md | 34 +- CHANGELOG.md | 62 +- CITATION.cff | 44 +- CMakeLists.txt | 14 +- CONTRIBUTING.md | 154 +- DEPENDENCIES.md | 124 +- MANIFEST.in | 7 +- README.md | 375 +- VERSION | 1 + docs/API.md | 156 +- docs/C.md | 10 +- docs/CPP.md | 12 +- docs/MATLAB.md | 7 +- docs/README.md | 32 +- docs/figures/aspect-frontier.png | Bin 246793 -> 0 bytes docs/figures/pytorch-softmax-collapse.png | Bin 157583 -> 0 bytes docs/figures/softmax-cancellation.png | Bin 148735 -> 0 bytes docs/numerics.md | 160 - docs/performance.md | 190 - docs/softmax-collapse.md | 122 - examples/python/README.md | 21 +- examples/python/numpy_fit.py | 4 +- include/sdca/c_api.h | 41 +- include/sdca/loss.h | 120 +- include/sdca/math/compensated.h | 15 + include/sdca/math/distillation.h | 5 +- include/sdca/math/distillation_rows.h | 322 ++ include/sdca/math/entropy.h | 17 +- include/sdca/math/prox_rows.h | 63 +- include/sdca/math/storage.h | 117 + include/sdca/math/tensor_float.h | 56 + include/sdca/prox/entropy_norm.h | 2 +- include/sdca/prox/knapsack_eq.h | 4 +- include/sdca/solver.h | 9 +- include/sdca/solver/eval.h | 7 +- include/sdca/solver/objective.h | 20 +- matlab/make.m | 2 +- pyproject.toml | 25 +- python/JAX.md | 73 +- python/README.md | 50 +- python/TORCH.md | 92 +- python/build.py | 4 +- python/libsdca/_core.py | 48 +- python/libsdca/_cpu_distill.h | 950 +++++ python/libsdca/_cpu_lanes.h | 701 ++++ python/libsdca/_cpu_prox.h | 833 +++++ python/libsdca/_cpu_prox_distill.h | 257 ++ python/libsdca/_cross_entropy.py | 26 +- python/libsdca/_cuda_launch.py | 22 +- python/libsdca/_entropy.py | 5 + python/libsdca/_extensions.py | 89 +- python/libsdca/_hinge.py | 25 +- python/libsdca/_jax_compat.py | 97 + python/libsdca/_jax_cpu.py | 261 ++ python/libsdca/_jax_cuda.cpp | 374 ++ python/libsdca/_jax_cuda.py | 1455 ++++++++ python/libsdca/_jax_ffi.cpp | 488 ++- python/libsdca/_jax_ffi.py | 247 +- python/libsdca/_jax_fusion.py | 320 ++ python/libsdca/_jax_losses.py | 92 +- python/libsdca/_linear_cross_entropy.py | 1 + python/libsdca/_multilabel.py | 6 +- python/libsdca/_ops.py | 20 +- python/libsdca/_tensor_losses.py | 3 +- python/libsdca/_torch_cuda.h | 23 +- python/libsdca/_torch_distill.h | 1221 +------ python/libsdca/_torch_lanes.h | 633 +--- python/libsdca/_torch_prox.h | 810 +---- python/libsdca/_torch_topk_hinge.h | 23 +- python/libsdca/_triton_build.py | 84 + python/libsdca/_triton_distillation.py | 821 ++++- python/libsdca/_triton_distillation_fast.py | 112 + python/libsdca/_triton_entropy.py | 10 +- python/libsdca/_triton_hinge.py | 288 +- python/libsdca/_triton_multilabel.py | 83 +- python/libsdca/_triton_prox.py | 7 +- python/libsdca/_triton_reduce.py | 8 +- python/libsdca/_triton_topk.py | 10 +- python/libsdca/jax.py | 591 +++- python/libsdca/torch.py | 152 +- requirements-dev.txt | 3 +- rust/README.md | 13 +- rust/consumer/src/main.rs | 4 +- rust/src/lib.rs | 2 +- rust/src/names.rs | 3 +- rust/src/options.rs | 5 +- rust/src/real.rs | 6 +- rust/tests/api.rs | 31 +- sdca_build.py | 6 + setup.py | 80 +- src/CMakeLists.txt | 1 + src/README.md | 8 - src/c_api.cpp | 22 + src/tensor_losses.h | 439 +-- tests/cpp/c_api_threads.cpp | 24 + tests/cpp/c_api_validation.c | 74 +- tests/cpp/regression.cpp | 148 +- tests/cpp/solver/context.cpp | 4 +- tests/cpp/solver/objective.cpp | 20 +- tests/cpp/solver/solver.cpp | 2 +- tests/cpp/solver/validation.cpp | 34 + tests/cpp/test_util.h | 2 +- tests/matlab/run_octave_tests.sh | 23 +- tests/matlab/test_numerics.m | 8 +- tests/python/common_inputs.py | 2 +- tests/python/conformance/__init__.py | 9 + tests/python/conformance/backends.py | 303 ++ tests/python/conformance/cells.py | 580 ++++ tests/python/conformance/contract.py | 298 ++ tests/python/conformance/inputs.py | 345 ++ tests/python/conformance/known.py | 71 + .../known_failures/Darwin-arm64.json | 2488 ++++++++++++++ .../known_failures/Linux-x86_64.json | 3062 +++++++++++++++++ tests/python/conformance/references.py | 445 +++ tests/python/conftest.py | 16 +- tests/python/hinge_order_cases.py | 20 + tests/python/release_numerics.py | 566 +++ tests/python/test_accuracy_claims.py | 2 +- tests/python/test_api_contracts.py | 8 + tests/python/test_backend_routing.py | 48 +- tests/python/test_build_config.py | 27 +- tests/python/test_conformance_jax.py | 122 + tests/python/test_conformance_native.py | 17 + tests/python/test_conformance_references.py | 147 + tests/python/test_conformance_torch.py | 18 + tests/python/test_conformance_tracking.py | 66 + tests/python/test_cross_entropy.py | 18 + tests/python/test_cuda_launch.py | 59 +- tests/python/test_cuda_memory.py | 48 + tests/python/test_distillation_adaptive.py | 71 + tests/python/test_distillation_far_tail.py | 203 ++ tests/python/test_distillation_references.py | 10 +- tests/python/test_examples.py | 39 + tests/python/test_float32_zero_gaps.py | 11 +- tests/python/test_float64_zero_gaps.py | 4 +- tests/python/test_half_gradient_rounding.py | 6 +- tests/python/test_half_precision.py | 2 +- tests/python/test_half_zero_gaps.py | 4 +- tests/python/test_hinge_order_jax.py | 39 + tests/python/test_hinge_order_native.py | 26 + tests/python/test_hinge_order_torch.py | 31 + tests/python/test_hinge_precision_gpu.py | 104 + tests/python/test_jax_backend.py | 282 +- tests/python/test_jax_compat.py | 38 + tests/python/test_jax_cuda.py | 1304 +++++++ .../test_jax_distillation_references.py | 110 +- tests/python/test_jax_far_tail.py | 283 ++ tests/python/test_jax_ffi.py | 125 +- tests/python/test_jax_half_precision.py | 10 +- tests/python/test_jax_hinge_precision_gpu.py | 61 + tests/python/test_jax_memory.py | 53 + tests/python/test_jax_precision_policy.py | 133 + tests/python/test_jax_prox_default.py | 92 + tests/python/test_jax_proximal_cpu.py | 120 + tests/python/test_jax_shared_cpu.py | 152 + tests/python/test_kernel_limits.py | 9 - tests/python/test_multilabel_kernels.py | 124 +- tests/python/test_precision_policy.py | 180 + tests/python/test_precision_ranges.py | 3 + tests/python/test_proximal_extremes.py | 4 + tests/python/test_shrinking.py | 4 +- tests/python/test_sklearn.py | 8 +- tests/python/test_softmax_limits.py | 4 +- tests/python/test_stress.py | 5 +- tests/python/test_threads.py | 2 +- tests/python/test_topk_kernels.py | 3 +- tests/python/test_topk_references.py | 4 +- tests/python/test_topk_subnormal_mass.py | 2 +- tests/python/test_torch_compile.py | 3 +- tests/python/test_torch_func.py | 28 + tests/python/test_triton_build.py | 48 + tests/python/test_work_counts.py | 70 + tools/README.md | 25 +- tools/bump_version.py | 62 + tools/check_install_archives.py | 101 + tools/complexity_baseline.txt | 2 +- tools/perf_gate.py | 182 + tools/quality.py | 51 +- tools/readme_contract_smoke.py | 204 ++ tools/readme_cpu_smoke.py | 235 ++ tools/readme_cuda_smoke.py | 78 + tools/readme_precision_smoke.py | 142 + tools/readme_smoke.py | 371 ++ tools/run_cpp_tests.sh | 8 +- tools/typings/triton/backends/__init__.pyi | 4 + tools/typings/triton/backends/compiler.pyi | 4 + tools/typings/triton/runtime/__init__.pyi | 4 + tools/typings/triton/runtime/driver.pyi | 4 + tools/typings/triton/runtime/jit.pyi | 4 + 192 files changed, 23887 insertions(+), 4995 deletions(-) create mode 100644 VERSION delete mode 100644 docs/figures/aspect-frontier.png delete mode 100644 docs/figures/pytorch-softmax-collapse.png delete mode 100644 docs/figures/softmax-cancellation.png delete mode 100644 docs/numerics.md delete mode 100644 docs/performance.md delete mode 100644 docs/softmax-collapse.md create mode 100644 include/sdca/math/distillation_rows.h create mode 100644 include/sdca/math/storage.h create mode 100644 include/sdca/math/tensor_float.h create mode 100644 python/libsdca/_cpu_distill.h create mode 100644 python/libsdca/_cpu_lanes.h create mode 100644 python/libsdca/_cpu_prox.h create mode 100644 python/libsdca/_cpu_prox_distill.h create mode 100644 python/libsdca/_jax_compat.py create mode 100644 python/libsdca/_jax_cpu.py create mode 100644 python/libsdca/_jax_cuda.cpp create mode 100644 python/libsdca/_jax_cuda.py create mode 100644 python/libsdca/_jax_fusion.py create mode 100644 python/libsdca/_triton_build.py create mode 100644 python/libsdca/_triton_distillation_fast.py delete mode 100644 src/README.md create mode 100644 tests/python/conformance/__init__.py create mode 100644 tests/python/conformance/backends.py create mode 100644 tests/python/conformance/cells.py create mode 100644 tests/python/conformance/contract.py create mode 100644 tests/python/conformance/inputs.py create mode 100644 tests/python/conformance/known.py create mode 100644 tests/python/conformance/known_failures/Darwin-arm64.json create mode 100644 tests/python/conformance/known_failures/Linux-x86_64.json create mode 100644 tests/python/conformance/references.py create mode 100644 tests/python/hinge_order_cases.py create mode 100644 tests/python/release_numerics.py create mode 100644 tests/python/test_conformance_jax.py create mode 100644 tests/python/test_conformance_native.py create mode 100644 tests/python/test_conformance_references.py create mode 100644 tests/python/test_conformance_torch.py create mode 100644 tests/python/test_conformance_tracking.py create mode 100644 tests/python/test_cuda_memory.py create mode 100644 tests/python/test_distillation_adaptive.py create mode 100644 tests/python/test_distillation_far_tail.py create mode 100644 tests/python/test_examples.py create mode 100644 tests/python/test_hinge_order_jax.py create mode 100644 tests/python/test_hinge_order_native.py create mode 100644 tests/python/test_hinge_order_torch.py create mode 100644 tests/python/test_hinge_precision_gpu.py create mode 100644 tests/python/test_jax_compat.py create mode 100644 tests/python/test_jax_cuda.py create mode 100644 tests/python/test_jax_far_tail.py create mode 100644 tests/python/test_jax_hinge_precision_gpu.py create mode 100644 tests/python/test_jax_memory.py create mode 100644 tests/python/test_jax_precision_policy.py create mode 100644 tests/python/test_jax_prox_default.py create mode 100644 tests/python/test_jax_proximal_cpu.py create mode 100644 tests/python/test_jax_shared_cpu.py create mode 100644 tests/python/test_precision_policy.py create mode 100644 tests/python/test_triton_build.py create mode 100644 tests/python/test_work_counts.py create mode 100644 tools/bump_version.py create mode 100644 tools/check_install_archives.py create mode 100644 tools/perf_gate.py create mode 100644 tools/readme_contract_smoke.py create mode 100644 tools/readme_cpu_smoke.py create mode 100644 tools/readme_cuda_smoke.py create mode 100644 tools/readme_precision_smoke.py create mode 100644 tools/readme_smoke.py mode change 100644 => 100755 tools/run_cpp_tests.sh create mode 100644 tools/typings/triton/backends/__init__.pyi create mode 100644 tools/typings/triton/backends/compiler.pyi create mode 100644 tools/typings/triton/runtime/__init__.pyi create mode 100644 tools/typings/triton/runtime/driver.pyi create mode 100644 tools/typings/triton/runtime/jit.pyi diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index eb874366..3b30179e 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -1,8 +1,8 @@ name: CI on: - # Pushes to main or master and pull requests, each run once. + # Pushes to the main branches and pull requests, each run once. push: - branches: [main, master] + branches: [main, master, integration] pull_request: workflow_dispatch: permissions: @@ -23,7 +23,7 @@ jobs: with: python-version: '3.10' # Install pinned linters/formatters (ruff, clang-format, clang-tidy, basedpyright, lizard) and scientific stubs. - - run: python -m pip install -r requirements-dev.txt numpy scipy mpmath scikit-learn jax + - run: python -m pip install -r requirements-dev.txt numpy scipy mpmath matplotlib scikit-learn jax # Install CPU PyTorch so basedpyright can resolve torch types across the package and tests. - run: python -m pip install torch --index-url https://download.pytorch.org/whl/cpu # Run ruff, clang-format, basedpyright, version consistency, complexity ceiling, and clang-tidy. @@ -193,8 +193,6 @@ jobs: - run: CXX=c++ python python/build.py --blas-backend EXTERNAL # Run the core NumPy and scikit-learn test suite in parallel across workers. - run: PYTHONPATH=python python -m pytest -p no:cacheprovider -n auto --dist worksteal tests/python --group core - # Run the serial thread-scaling tests on macOS arm64. - - run: PYTHONPATH=python python -m pytest -p no:cacheprovider tests/python --group core -m serial # Run the PyTorch CPU test suite (including the Apple Clang CPU extension) in parallel. - run: PYTHONPATH=python python -m pytest -p no:cacheprovider -n auto --dist worksteal tests/python --group torch -m 'not long' diff --git a/.github/workflows/packages.yml b/.github/workflows/packages.yml index 306d8458..aed4b142 100644 --- a/.github/workflows/packages.yml +++ b/.github/workflows/packages.yml @@ -2,9 +2,8 @@ name: Packages # Builds the sdist, the wheels and the crate archive. A manual run can upload # the sdist and wheels to TestPyPI; a v* tag uploads them to PyPI, then the # crate to crates.io. Uploads use Trusted Publishing in the GitHub environments -# testpypi, pypi and crates-io; the one-time setup is in CONTRIBUTING.md -# (Releases). Pull requests only build and test the artifacts: every upload -# job skips them. +# testpypi, pypi and crates-io. Pull requests only build and test the +# artifacts: every upload job skips them. on: pull_request: workflow_dispatch: @@ -27,24 +26,25 @@ jobs: runs-on: ubuntu-24.04 steps: # Check out repository sources to build and validate the release source distribution. - - uses: actions/checkout@v7.0.1 + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 # Set up Python 3.12 for building and testing the sdist. - uses: actions/setup-python@v7.1.0 with: python-version: '3.12' - # On tag pushes, verify that the git tag v matches the version in pyproject.toml. + # On tag pushes, verify that the git tag is v and that every version copy agrees. - if: github.ref_type == 'tag' - name: Check that the tag is v + name: Check that the tag is v env: TAG: ${{ github.ref_name }} - run: >- - python -c "import os, sys, tomllib; - v = 'v' + tomllib.load(open('pyproject.toml', 'rb'))['project']['version']; - sys.exit(None if os.environ['TAG'] == v else 'tag ' + os.environ['TAG'] + ' is not ' + v)" + run: | + test "$TAG" = "v$(cat VERSION)" || { echo "tag $TAG is not v$(cat VERSION)"; exit 1; } + python -c "import runpy; runpy.run_path('tools/quality.py')['check_versions']()" # Install pinned PEP 517 build frontend and Twine metadata checker. - run: python -m pip install build==1.6.1 twine==7.0.0 # Build the source distribution archive in dist/. - run: python -m build --sdist + - name: Check shared CPU sources in the sdist + run: python tools/check_install_archives.py --source . dist/*.tar.gz # Verify sdist metadata and long_description rendering for PyPI. - run: python -m twine check --strict dist/* # Install the sdist into an isolated venv outside the repo and run the core test suite. @@ -78,9 +78,33 @@ jobs: runs-on: ${{ matrix.os }} steps: # Check out repository sources to build and test portable binary wheels. - - uses: actions/checkout@v7.0.1 + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - uses: actions/setup-python@v7.1.0 + with: + python-version: '3.12' # Build py3-none platform wheels with built-in BLAS, repair with auditwheel/delocate, and run core tests. - uses: pypa/cibuildwheel@v4.3.5 + - name: Check shared CPU headers in the wheels + run: python tools/check_install_archives.py --source . wheelhouse/*.whl + # Install only each documented extra into a fresh environment and run README examples. + - name: Fresh wheel installs and literal README examples + run: | + python -m pip install uv + python tools/readme_smoke.py --wheel wheelhouse/libsdca-*.whl --output "$RUNNER_TEMP/readme-smoke" --cleanup + - name: Save fresh-install records + if: always() + uses: actions/upload-artifact@v7.0.2 + with: + name: readme-smoke-${{ matrix.os }} + path: | + ${{ runner.temp }}/readme-smoke/results.json + ${{ runner.temp }}/readme-smoke/*/commands.log + ${{ runner.temp }}/readme-smoke/*/packages.txt + ${{ runner.temp }}/readme-smoke/*/example.py + ${{ runner.temp }}/readme-smoke/*/precision.py + ${{ runner.temp }}/readme-smoke/*/precision.json + ${{ runner.temp }}/readme-smoke/*/cpu-dispatch.py + ${{ runner.temp }}/readme-smoke/*/cpu-dispatch.json # Validate wheel metadata and README formatting with Twine. - run: pipx run --spec twine==7.0.0 twine check --strict wheelhouse/* # Upload the platform wheel artifact for the TestPyPI / PyPI publish jobs. @@ -94,7 +118,7 @@ jobs: runs-on: ubuntu-24.04 steps: # Check out repository sources to package and test the standalone Rust crate archive. - - uses: actions/checkout@v7.0.1 + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 # Install stable Rust toolchain to package and test the crate. - run: rustup toolchain install stable --profile minimal && rustup default stable # Vendor the C++ headers and C ABI sources into rust/native/ and build the .crate archive. @@ -123,13 +147,13 @@ jobs: id-token: write steps: # Download the verified sdist and platform wheels built by earlier jobs. - - uses: actions/download-artifact@v8.0.2 + - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2 with: pattern: dist-* path: dist merge-multiple: true # Publish sdist and wheels to TestPyPI via OIDC Trusted Publishing. - - uses: pypa/gh-action-pypi-publish@v1.14.3 + - uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3 with: repository-url: https://test.pypi.org/legacy/ @@ -145,13 +169,13 @@ jobs: id-token: write steps: # Download the verified sdist and platform wheels built by earlier jobs. - - uses: actions/download-artifact@v8.0.2 + - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2 with: pattern: dist-* path: dist merge-multiple: true # Publish sdist and wheels to PyPI via OIDC Trusted Publishing. - - uses: pypa/gh-action-pypi-publish@v1.14.3 + - uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3 crates-io: name: Upload (crates.io) @@ -165,18 +189,18 @@ jobs: id-token: write steps: # Check out the tagged sources the verified crate archive was built from. - - uses: actions/checkout@v7.0.1 + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 # Install stable Rust to package and publish the crate. - run: rustup toolchain install stable --profile minimal && rustup default stable # Download the crate archive that the crate job tested outside the checkout. - - uses: actions/download-artifact@v8.0.2 + - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2 with: name: crate path: verified # Repackage and check that the archive to publish is byte-identical to the tested one. - run: rust/package.sh --no-verify && cmp verified/*.crate rust/target/package/libsdca-*.crate # Exchange the GitHub OIDC token for a short-lived crates.io token, revoked after the job. - - uses: rust-lang/crates-io-auth-action@v1.0.6 + - uses: rust-lang/crates-io-auth-action@3268eb413133e2960fa4ae0e963ca76380c54cd9 # v1.0.6 id: auth # Publish the crate to crates.io via Trusted Publishing. - run: cargo publish --allow-dirty diff --git a/.gitignore b/.gitignore index bf4cb589..c037730f 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,5 @@ build* +!build_*.py !python/build.py !rust/build.rs matlab/*.mex* diff --git a/AGENTS.md b/AGENTS.md index 2ad03f64..b995987d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -7,8 +7,9 @@ examples are in the [README](README.md#quick-start) and the linked guides. ```bash pip install libsdca # NumPy solver and losses (numpy>=1.23) -pip install 'libsdca[torch]' # PyTorch losses (torch>=2.1, installs ninja) -pip install 'libsdca[jax]' # JAX losses (jax>=0.4.35) +pip install 'libsdca[torch]' # PyTorch losses (torch>=2.1) +pip install 'libsdca[jax]' # JAX CPU losses (jax>=0.4.35) +pip install 'libsdca[jax-cuda]' # JAX CUDA losses (Linux, NVIDIA driver 580+) pip install 'libsdca[sklearn]' # SDCAClassifier (scikit-learn>=1.6) cargo add libsdca # Rust crate (Rust>=1.74 and a C++11 compiler) ``` @@ -17,6 +18,8 @@ cargo add libsdca # Rust crate (Rust>=1.74 and a C++11 compiler) - PyTorch and JAX compile small C++ extensions on first use when a compiler and Python headers are present; otherwise they fall back with a one-time warning ([TORCH.md](python/TORCH.md#build-tools)). +- Check the selected path: `libsdca.torch.explain_backend(logits, target, "cross_entropy")` + returns `(backend, reason)`. ## Which API to use @@ -29,8 +32,12 @@ cargo add libsdca # Rust crate (Rust>=1.74 and a C++11 compiler) | Losses in JAX (`jit`, `grad`, `vmap`) | `libsdca.jax` | [JAX.md](python/JAX.md) | | Linear or kernel SVM / softmax classifier (scikit-learn) | `libsdca.SDCAClassifier` | [python/README.md](python/README.md#classifier) | | Same, with duality-gap history and warm starts | `libsdca.fit` | [python/README.md](python/README.md#training) | +| Losses and gradients on NumPy arrays | `libsdca.loss_and_grad` | [python/README.md](python/README.md#losses-and-gradients) | | Rust, C++, C, MATLAB | crate `libsdca`, headers, `libsdca_c`, `matsdca_*` | [Rust](rust/README.md), [C++](docs/CPP.md), [C](docs/C.md), [MATLAB](docs/MATLAB.md) | +Loss names, options, defaults and errors are shared across languages: +[docs/API.md](docs/API.md). + ## Pitfalls - **Class axis:** `CrossEntropyLoss` takes classes on `dim=1` like PyTorch; every other @@ -48,9 +55,24 @@ cargo add libsdca # Rust crate (Rust>=1.74 and a C++11 compiler) [API.md](docs/API.md#options)). - **Convergence:** only `status == "solved"` certifies the duality gap ([API.md](docs/API.md#results)). +- **Precision:** `precision=None` follows the storage dtype (16-bit inputs use `float32` + work); pass `precision="float64"` for double work ([API.md](docs/API.md#precision), + [known limits](docs/API.md#known-limits)). + +## Working in this repository + +| Path | Contents | +| --- | --- | +| `include/sdca/` | Header-only C++11 core (`solver.h`, `loss.h`, `prox.h`, `c_api.h`) | +| `src/c_api.cpp` | C ABI used by Python and Rust | +| `python/libsdca/` | Python package (NumPy, scikit-learn, PyTorch, JAX) | +| `rust/`, `matlab/`, `src/matlab/` | Rust crate and MATLAB/Octave gateways | +| `tests/`, `examples/` | Test suites and runnable examples | -## Further documentation +```bash +pip install -e '.[test-torch,test-jax]' +python -m pytest -n auto tests/python --group core # core, torch, jax or all +python tools/quality.py --skip-tidy +``` -- Loss formulas, options and environment variables: [docs/API.md](docs/API.md) -- Numerics and known limits: [docs/numerics.md](docs/numerics.md) -- Performance: [docs/performance.md](docs/performance.md) +[CONTRIBUTING.md](CONTRIBUTING.md) lists the full checks; `VERSION` holds the version. diff --git a/CHANGELOG.md b/CHANGELOG.md index 49230f5d..06354d4e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,22 +1,43 @@ # Changelog -## 0.3.1 (2026-11-12) +## 0.3.1 (2026-11-16) -- **CUDA hinges:** For `C <= 128`, the fused multiclass, smooth and top-*k* hinge kernels pack - several rows per CTA, as the top-*k* cross-entropy kernels already do. Forward plus backward - on an A100 (`bfloat16`): `multiclass_hinge` at `262144 × 10` takes `0.20` ms (was `0.52`), - the smooth hinge `0.27` ms (was `2.21`), and `topk_hinge_alpha` ($k = 5$) `0.17` ms (was - `2.76`). Values and gradients are unchanged, and wider rows keep the existing kernels. -- **Name and description:** The project is described everywhere by the technical report's - title, *libsdca: Accurate and Fast Classification Losses for SDCA and Neural Networks* - (README, PyPI, crates.io, module docs), and report links go to - . -- **Citation:** `CITATION.cff` and the README cite the technical report and the TPAMI 2018 - paper; softmax collapse is credited to Prieto et al. (2025). -- **Docs:** Fixed GitHub math rendering, wide tables and line wrapping. -- **Packaging:** The crate is published through crates.io Trusted Publishing, and - `tools/quality.py` checks the `CITATION.cff` version and date and the release-pinned links - of the PyPI and crates.io pages. +- **JAX on CUDA:** `libsdca.jax` runs the same fused Triton kernels as PyTorch for every + loss (Linux wheels include the handler), falling back to `jax.numpy` with a warning. +- **Shared CPU distillation:** PyTorch and JAX use the same fused CPU row kernels for + distillation in all four dtypes; JAX proximal distillation uses the shared native solver. + An overflowing native proximal-distillation loss now returns `+inf` with a finite + gradient instead of `nan`. +- **`float32` work by default:** NumPy, scikit-learn, Rust and the C++ loss helpers default + to `float32` work for `float32` inputs; `precision="float64"` keeps double work. Proximal + cross-entropy and CUDA top-1 hinges use `float32` work for 16- and 32-bit inputs, promoting + rows that need double ([API.md](docs/API.md#precision)). +- **Hinge ties:** Nonsmooth top-1 hinges select the largest represented score before forming + the margin, so tiny score gaps no longer round to ties. +- **Aggregate tails:** CUDA distillation, proximal distillation and multilabel + cross-entropy, and the JAX array losses, keep sums of individually underflowing + exponentials. +- **Faster CUDA paths:** Adaptive distillation kernels and packed short hinge rows. +- **JAX CPU fusion:** `SDCA_JAX_CPU_FUSION=auto` times fused and fenced array programs once + per machine and caches the choice ([JAX.md](python/JAX.md#cpu-pass-fusion)). +- **Packaging:** JAX-only installs no longer need PyTorch; the `torch` extra works with + PyTorch 2.1; transient build failures no longer suppress retries for 24 hours. The + version is read from one `VERSION` file. +- **Clearer errors:** PyTorch losses other than `cross_entropy` raise `ValueError` inside + `torch.func` transforms, and all losses raise `ValueError` for tensors other than CPU or + CUDA (MPS failed with a `TypeError`). `gamma` and `alpha` reject booleans. Fallback + warnings point at the calling line. +- **Fixes:** `cross_entropy(..., backend="torch")` accepts nonfinite logits in ignored rows, + as the other backends do. A solve whose final evaluation throws ends as `failed` instead + of raising. The JAX CPU build falls back to portable flags when the native-ISA probe fails. + `float64` proximal cross-entropy compensates its row sums: on 4,097–32,768 classes, values + and gradients were up to `95×` the error bound and are now within it. +- **Docs and citation:** The README starts with the installation and shows the same two losses + in every interface; [TORCH.md](python/TORCH.md#benchmarks) lists CUDA benchmarks; + `CITATION.cff` prefers the TPAMI 2018 paper. +- **Known limits:** [API.md](docs/API.md#known-limits) lists the recorded `float64` + cancellation errors (below `5e-17` absolute) and the behavior of finite rows at + `±finfo.max`. ## 0.3.0 (2026-11-09) @@ -28,11 +49,10 @@ gateways sharing one set of objective, option and status names ([API.md](docs/API.md)). - **Numerical stability:** Losses and gradients preserve tiny probability tails down to the subnormal limit (avoiding softmax collapse), and distillation gradients are exact zero at - equal logits ([numerics](docs/numerics.md), - [known limits](docs/numerics.md#aggregate-tail-limitations)). + equal logits ([known limits](docs/API.md#known-limits)). - **Fused CUDA and CPU kernels:** On an A100 (`8192 × 32000` and `8192 × 128256`), cross-entropy takes `0.93–0.98×` `torch.compile` time (`0.33–0.41×` eager), top-5 - cross-entropy `0.23–0.26×`, and distillation `0.62–0.81×` ([performance](docs/performance.md)). + cross-entropy `0.23–0.26×`, and distillation `0.62–0.81×`. - **Certified convergence:** `status == "solved"` requires the duality gap of the returned weights and the feasible projection of the returned duals, evaluated in `double` with a first-order rounding estimate, to meet @@ -78,11 +98,11 @@ - **Single rounding:** 16-bit gradients are scaled by the upstream cotangent and reduction factor in working precision before a single rounding to the output dtype, and hinge / top-*k* target gradients are formed from the unrounded competitor sum. -- **Double iterate for `float32` fits (`precision="float64"` default):** Keeps internal +- **Optional double iterate for `float32` fits (`precision="float64"`):** Keeps internal solver weights and duals in `double` (`8(d + n)m` bytes) and rounds once at each evaluation so `float32` fits reach `float64` gap tolerances down to `float32` output rounding (`3.5e-7` on `digits`; pass `precision="float32"` for pure `float32` speed and - memory; [numerics.md](docs/numerics.md#what-each-precision-guarantees)). + memory). - **Compensated reductions & hardened projections:** Compensated sums in multilabel cross-entropy and distillation, warm-start residual preservation at large score offsets, and checked `float64` / extended-precision `multilabel_hinge` projections diff --git a/CITATION.cff b/CITATION.cff index 6a4cd83c..62bd1a20 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -1,7 +1,7 @@ cff-version: 1.2.0 message: >- - If libsdca is useful in your research, please cite the paper for the losses you use - and the technical report for the library. + If libsdca is useful in your research, please cite the TPAMI paper; the earlier papers + introduce the top-k losses, and the technical report describes the library. type: software title: "libsdca: Accurate and Fast Classification Losses for SDCA and Neural Networks" abstract: >- @@ -11,7 +11,7 @@ authors: - family-names: Lapin given-names: Max version: 0.3.1 -date-released: 2026-11-12 +date-released: 2026-11-16 license: MIT url: https://mlapin.github.io/libsdca/ repository-code: https://github.com/mlapin/libsdca @@ -25,14 +25,21 @@ keywords: - pytorch - jax preferred-citation: - type: report - title: "libsdca: Accurate and Fast Classification Losses for SDCA and Neural Networks" + type: article + title: Analysis and Optimization of Loss Functions for Multiclass, Top-k, and Multilabel Classification authors: - family-names: Lapin - given-names: Max - year: 2026 - month: 11 - url: https://mlapin.github.io/libsdca/report/ + given-names: Maksim + - family-names: Hein + given-names: Matthias + - family-names: Schiele + given-names: Bernt + journal: IEEE Transactions on Pattern Analysis and Machine Intelligence (TPAMI) + volume: 40 + issue: 7 + start: 1533 + end: 1554 + year: 2018 references: - type: conference-paper title: Top-k Multiclass SVM @@ -56,18 +63,11 @@ references: given-names: Bernt collection-title: IEEE Conference on Computer Vision and Pattern Recognition (CVPR) year: 2016 - - type: article - title: Analysis and Optimization of Loss Functions for Multiclass, Top-k, and Multilabel Classification + - type: report + title: "libsdca: Accurate and Fast Classification Losses for SDCA and Neural Networks" authors: - family-names: Lapin - given-names: Maksim - - family-names: Hein - given-names: Matthias - - family-names: Schiele - given-names: Bernt - journal: IEEE Transactions on Pattern Analysis and Machine Intelligence - volume: 40 - issue: 7 - start: 1533 - end: 1554 - year: 2018 + given-names: Max + year: 2026 + month: 11 + url: https://mlapin.github.io/libsdca/report/ diff --git a/CMakeLists.txt b/CMakeLists.txt index 8dbb7cd1..139fcc1b 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -1,12 +1,7 @@ cmake_minimum_required(VERSION 3.12) -project(libsdca) - -set(libsdca_MAJOR_VERSION 0) -set(libsdca_MINOR_VERSION 3) -set(libsdca_PATCH_VERSION 1) -set(libsdca_VERSION - ${libsdca_MAJOR_VERSION}.${libsdca_MINOR_VERSION}.${libsdca_PATCH_VERSION} - ) +file(STRINGS "${CMAKE_CURRENT_SOURCE_DIR}/VERSION" libsdca_VERSION LIMIT_COUNT 1) +project(libsdca VERSION ${libsdca_VERSION}) +set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS VERSION) add_definitions(-DSDCA_VERSION="${libsdca_VERSION}") # Whether to use @@ -300,8 +295,7 @@ target_compile_features(libsdca INTERFACE cxx_std_11) target_include_directories(libsdca INTERFACE $ $ ${SDCA_BLAS_INCLUDE_DIRS}) -target_compile_definitions(libsdca INTERFACE ${SDCA_BLAS_DEFINITIONS} - SDCA_VERSION="${libsdca_VERSION}") +target_compile_definitions(libsdca INTERFACE ${SDCA_BLAS_DEFINITIONS}) if(USE_CHRONO) target_compile_definitions(libsdca INTERFACE SDCA_USE_CHRONO) else() diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 76f327dd..727ba795 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,117 +1,99 @@ # Contributing -`libsdca` is a header-only C++11 library with a C ABI and Python (NumPy, -scikit-learn, PyTorch, JAX), Rust and MATLAB/Octave interfaces. This guide lists -the development workflow, repository layout, quality gates and coding rules. +`libsdca` is a header-only C++11 library with a C ABI and Python (NumPy, scikit-learn, +PyTorch, JAX), Rust and MATLAB/Octave interfaces. ## Development setup +On Debian/Ubuntu: + ```bash +sudo apt-get install -y build-essential python3-dev python3-venv cmake ninja-build clang \ + libomp-dev libblas-dev pkg-config python3 -m venv build/dev && source build/dev/bin/activate pip install -r requirements-dev.txt numpy scipy mpmath scikit-learn jax ninja pip install torch --index-url https://download.pytorch.org/whl/cpu pip install -e . # rerun after changing include/ or src/ +``` + +## Tests and checks + +```bash python -m pytest -n auto --dist worksteal tests/python --group all # or core, torch, jax -python -m pytest tests/python --group all -m serial +python -m pytest tests/python --group all -m serial # timing-sensitive, unloaded host cmake -S . -B build/cpp -DBUILD_TESTING=ON -DSDCA_BUILD_C_API=ON -DSDCA_WARNINGS_AS_ERRORS=ON -cmake --build build/cpp -j4 -ctest --test-dir build/cpp --output-on-failure --parallel 4 -python tools/quality.py +cmake --build build/cpp -j4 && ctest --test-dir build/cpp --output-on-failure --parallel 4 +python tools/quality.py # --fix formats first; --skip-tidy skips clang-tidy python tools/coverage.py --cpp-only cargo fmt --check --manifest-path rust/Cargo.toml cargo clippy --manifest-path rust/Cargo.toml --all-targets -- -D warnings cargo test --manifest-path rust/Cargo.toml +OCTAVE_HOME= tests/matlab/run_octave_tests.sh ``` -- `tools/quality.py --fix` formats C++ and Python sources before running the checks. -- If you run `python/build.py`, delete `build/python` (or set `SDCA_LIBRARY_DIR`) when - switching back to `pip install -e .`, as `build/python/libsdca_c.so` takes precedence. -- Pytest markers (`tests/python/conftest.py`): `slow` and `long` tests are scheduled first - under `-n auto --dist worksteal` (CI deselects `long` with `-m "not long"`); `serial` - tests require an unloaded machine and run via `-m serial` without `-n`. -- For repeated local JAX test runs, set `JAX_COMPILATION_CACHE_DIR=` and +- **Markers:** `slow` and `long` tests are scheduled first under `--dist worksteal` (CI + deselects `long`); `serial` tests run without `-n` on an unloaded machine. +- **CUDA:** On a machine with an NVIDIA GPU, install a CUDA build of PyTorch (and + of JAX); the same pytest command then runs the CUDA tests, which skip otherwise. + `python tests/python/release_numerics.py --device cuda --output ` also checks the + CUDA entropy and distillation losses against `mpmath` references and exits 1 on a failure. +- **Runtime:** `tests/python/test_work_counts.py` bounds the solver's epochs on seeded + problems, so convergence regressions fail without a timer. On a CUDA machine, + `python tools/perf_gate.py --output ` times the losses against `torch.compile` on + 32,000- and 128,256-class rows and exits 1 when a speedup falls below its floor or libsdca + needs more peak memory. +- **Installed package:** `python -m pytest tests/python --installed` tests the installed + `libsdca` instead of the source tree. +- **`python/build.py`** builds `build/python/libsdca_c.so`, which takes precedence over an + editable install; delete it (or set `SDCA_LIBRARY_DIR`) when switching back. +- **JAX:** For repeated runs, set `JAX_COMPILATION_CACHE_DIR=` and `JAX_PERSISTENT_CACHE_MIN_COMPILE_TIME_SECS=0`. +| Tool | Rule | +| --- | --- | +| `clang-format`, `clang-tidy` (v18) | `.clang-format` (Google style, C++11, 100 columns) and `.clang-tidy`, warnings as errors | +| `ruff`, `basedpyright` | `pyproject.toml`: `E`, `F`, `I`, `B`, `UP`, `C90`; standard mode, warnings as errors | +| `lizard` | Cyclomatic complexity $\le 20$, length $\le 100$ lines (`tools/complexity_baseline.txt` may only shrink) | +| `gcovr`, `coverage.py` | $\ge 90\%$ line coverage of `include/sdca`, `src/c_api.cpp` and `python/libsdca` | +| `rustfmt`, `clippy` | `-D warnings`, all public items documented | +| C++ compilers | `-pedantic -Werror -W -Wall -Wextra` under GCC and Clang | + ## Layout | Location | Contents | | --- | --- | -| `include/sdca/math/`, `include/sdca/prox/` | Compensated math, entropy roots, BLAS, projections and proximal operators | -| `include/sdca/solver/`, `include/sdca/loss.h` | Data views, contexts, objectives, dual updates, stopping criteria, evaluation and loss dispatch | +| `include/sdca/math/`, `include/sdca/prox/` | Compensated math, BLAS, projections and proximal operators | +| `include/sdca/solver/`, `include/sdca/loss.h` | Data views, objectives, dual updates, stopping criteria and losses | | `include/sdca/c_api.h`, `src/c_api.cpp` | Exception-safe C ABI used by Python and Rust | | `python/libsdca/_core.py`, `sklearn.py` | NumPy API and `SDCAClassifier` | -| `python/libsdca/torch.py`, `_cpu.py`, `_torch_*` | PyTorch autograd layers, tensor losses, and ATen/OpenMP CPU extension | -| `python/libsdca/_triton_*.py`, `_cuda_launch.py` | Fused Triton CUDA kernels and C++ `cuLaunchKernel` launcher | -| `python/libsdca/jax.py`, `_jax_*` | JAX losses and XLA FFI custom-call handler | -| `rust/`, `matlab/`, `src/matlab/` | Rust crate (`rust/consumer` tests BLAS links) and MATLAB/Octave gateways | -| `tests/`, `examples/`, `docs/`, `tools/` | C++/Python/MATLAB test suites, runnable examples, docs, and quality/coverage scripts | - -## Checks - -| Tool | Scope | Rule | -| --- | --- | --- | -| `clang-format` | `include/sdca`, `src`, `tests`, `tools`, `python/libsdca` | `.clang-format` (v18): Google style, C++11, 100 columns | -| `clang-tidy` | `src/c_api.cpp`, `tests/cpp/regression.cpp` (both BLAS backends) | `.clang-tidy` (v18): correctness and performance checks, warnings as errors | -| `lizard` | `include/sdca`, `src`, `python/libsdca` | Cyclomatic complexity $\le 20$, length $\le 100$ lines (`tools/complexity_baseline.txt` may only shrink) | -| `ruff` | `python`, `tests/python`, `examples/python`, `tools`, build scripts | `pyproject.toml`: `E`, `F`, `I`, `B`, `UP`, `C90` (complexity $\le 15$) | -| `basedpyright` | Python package, tests, examples, build scripts, tools | `pyproject.toml`: standard mode, warnings as errors, rule-scoped `# pyright: ignore[rule]` | -| `gcovr`, `coverage.py` | `include/sdca`, `src/c_api.cpp`, `python/libsdca/` | $\ge 90\%$ line coverage across C++ and Python host code (only `@triton.jit` device bodies excluded) | -| `rustfmt`, `clippy` | `rust/` | Standard style, `-D warnings`, all public items documented | -| C++ compilers | All C++ targets | `-pedantic -Werror -W -Wall -Wextra` under GCC and Clang | - -To combine GPU and CPU Python host coverage from the same source checkout: - -```bash -python tools/coverage.py --write-python-manifest build/gpu.coverage -PYTHONPATH=python COVERAGE_FILE=build/gpu.coverage SDCA_CUDA_LAUNCHER=on \ - python -m coverage run --source=libsdca -m pytest tests/python --group torch -PYTHONPATH=python COVERAGE_FILE=build/gpu.coverage SDCA_CUDA_LAUNCHER=off \ - python -m coverage run --append --source=libsdca -m pytest tests/python --group torch -python tools/coverage.py --python-data build/gpu.coverage -``` - -## Coding guidelines - -- **C++:** C++11, header-only, strict IEEE semantics (`-fno-fast-math -ffp-contract=off`), - no `new` (use `std::vector` or `detail::entropy_buffer`). Public functions validate inputs - and throw `std::invalid_argument` or `std::runtime_error`; `detail` helpers document their - preconditions. -- **Python:** Annotate all functions; keep `import libsdca` free of `torch`, `jax`, - `sklearn` and native-library loads; raise `ValueError` or `TypeError` at the API boundary - and never copy tensors across devices implicitly. +| `python/libsdca/torch.py`, `_cpu.py`, `_torch_*` | PyTorch layers, tensor losses and the CPU extension | +| `python/libsdca/_triton_*.py`, `_cuda_launch.py` | Triton CUDA kernels and the C++ launcher | +| `python/libsdca/jax.py`, `_jax_*` | JAX losses and XLA FFI handlers | +| `rust/`, `matlab/`, `src/matlab/` | Rust crate and MATLAB/Octave gateways | +| `tests/`, `examples/`, `docs/`, `tools/` | Test suites, examples, guides and developer scripts | + +## Guidelines + +- **C++:** C++11, header-only, IEEE semantics (`-fno-fast-math -ffp-contract=off`), no `new`. + Public functions validate inputs and throw `std::invalid_argument` or `std::runtime_error`. +- **Python:** Annotate all functions; keep `import libsdca` free of `torch`, `jax`, `sklearn` + and native-library loads; raise `ValueError` or `TypeError` at the API boundary; never copy + tensors across devices implicitly. - **Rust:** No `unsafe` outside FFI calls, each with a `// SAFETY:` comment. -- **Cross-language vocabulary:** Every new objective, option or status uses the same name - across C++, the C ABI, Python, Rust and MATLAB ([docs/API.md](docs/API.md)), pinned by - `tests/python/test_api_contracts.py` and `rust/tests/api.rs`. -- **Numerical changes:** Every fix includes a regression test against an independent - analytic, `mpmath`, or KKT reference. Refactorings of `include/sdca` must leave results - bitwise unchanged, and performance-sensitive changes must report before/after timings - ([docs/performance.md](docs/performance.md#where-libsdca-is-slower)). +- **Names:** A new objective, option or status uses the same name in every interface + ([docs/API.md](docs/API.md)), pinned by `tests/python/test_api_contracts.py` and + `rust/tests/api.rs`. +- **Numerical changes:** Every fix comes with a regression test against an independent + analytic, `mpmath` or KKT reference. Do not loosen a tolerance to make a test pass. ## Releases -The version string is checked across 11 files by `tools/quality.py`: `CMakeLists.txt`, -`pyproject.toml`, `setup.py`, `python/build.py`, `python/libsdca/__init__.py`, -`matlab/make.m`, `rust/Cargo.toml`, `include/sdca/c_api.h`, `docs/C.md`, `CITATION.cff` -(whose `date-released` must match the changelog date), and `CHANGELOG.md`. The release-pinned -GitHub links (`blob/v`, `--tag v`) in `pyproject.toml`, `python/README.md` -and `rust/README.md` must name the same version. - -The project is described everywhere by the technical report's title, *libsdca: Accurate and -Fast Classification Losses for SDCA and Neural Networks*. The PyPI summary, the crates.io -description, `CITATION.cff` and the README openings start from it and then name the losses by -their search terms (cross-entropy, SVM, softmax, distillation). - -`.github/workflows/packages.yml` builds and tests the sdist, `manylinux_2_28` `x86_64` and -macOS 11+ `arm64` wheels (`cibuildwheel`), and the `.crate` archive (`rust/package.sh`), -publishing to TestPyPI (manual dispatch) or, on `v*` tags, to PyPI and then crates.io via OIDC -Trusted Publishing: +```bash +python tools/bump_version.py 0.3.2 # VERSION and its copies; "## Unreleased" gets the date +python tools/quality.py --skip-tidy # checks that every copy agrees +git tag v0.3.2 && git push origin v0.3.2 +``` -1. In GitHub *Settings → Environments*, create `testpypi`, `pypi` and `crates-io` (restrict - `pypi` and `crates-io` to `v*` tags, and `pypi` to required reviewers: approving it releases - both, since the crates.io job waits for the PyPI upload). -2. On [TestPyPI](https://test.pypi.org/manage/account/publishing/) and - [PyPI](https://pypi.org/manage/account/publishing/), register `mlapin/libsdca`, workflow - `packages.yml`, and environment `testpypi` / `pypi` as a trusted publisher. -3. In the [crates.io](https://crates.io/crates/libsdca) crate settings, add a GitHub trusted - publisher for `mlapin/libsdca`, workflow `packages.yml`, and environment `crates-io`. +`VERSION` is read by CMake, `setup.py`, `pyproject.toml`, `python/build.py` and +`matlab/make.m`. On a `v*` tag, `.github/workflows/packages.yml` builds the sdist, the wheels +and the crate and publishes them to PyPI and crates.io with trusted publishing. diff --git a/DEPENDENCIES.md b/DEPENDENCIES.md index 269e66db..517b2ef9 100644 --- a/DEPENDENCIES.md +++ b/DEPENDENCIES.md @@ -1,46 +1,62 @@ -# Dependencies and optional builds +# Dependencies and builds -`libsdca` requires a C++11 compiler. An external BLAS library is optional: a built-in -backend lets the solver and loss functions run with no third-party runtime dependencies. -CMake 3.12+ is required only for the CMake packages (`libsdca::libsdca` and -`libsdca::sdca_c`). +`libsdca` needs only a C++11 compiler. An external CBLAS is optional (a built-in backend is +included), and CMake 3.12+ is needed only for the CMake packages `libsdca::libsdca` and +`libsdca::sdca_c`. ## Tested configurations -| Component | Validated environments | +| Component | Environments | | --- | --- | -| C++ & C ABI | Ubuntu 22.04 / 24.04 (`x86_64`) with GCC 11.4 / 13 and Clang 18 (`BUILTIN` and `EXTERNAL` BLAS, C and C++ consumers, GCC ASan/UBSan, Clang TSan); macOS (`arm64`) with Apple Clang 21 (`BUILTIN` and Accelerate) | -| Python (CPU) | Python 3.10–3.14, NumPy 1.23–2.5, SciPy 1.10–1.18, scikit-learn 1.6–1.9, PyTorch 2.1–2.15 (CPU extension across AVX-512, AVX2 and generic/arm64), JAX 0.4.35–0.12 (with and without XLA FFI) | -| CUDA | NVIDIA A100-SXM4-80GB and H100 (PyTorch 2.14–2.15, Triton 3.8–3.9, both C++ launcher and Triton launch paths; JAX 0.12 with CUDA plugin) | -| Packaging | Portable `py3-none` wheels (`SDCA_BLAS_BACKEND=BUILTIN`) via `cibuildwheel` on `manylinux_2_28` `x86_64` and macOS 11+ `arm64`, sdist builds, and standalone `.crate` archives | -| Rust | Rust 1.74 (MSRV) and stable on Linux `x86_64` (`BUILTIN`, reference BLAS, OpenBLAS and BLIS, shared and static) | -| Octave | GNU Octave 10.3 (`mkoctfile` MEX gateways) | +| C++ and C ABI | Ubuntu 22.04 / 24.04 `x86_64` with GCC 11 and 13 and Clang 18 (built-in and external BLAS, ASan/UBSan, TSan); macOS `arm64` with Apple Clang (built-in BLAS and Accelerate) | +| Python | Python 3.10–3.13, NumPy 1.26–2.5, SciPy 1.15–1.18, scikit-learn 1.7–1.9, PyTorch 2.1–2.15, JAX 0.4.35–0.12 | +| CUDA | NVIDIA A100 with PyTorch 2.14–2.15, Triton 3.8–3.9 and JAX 0.12 (hosted CI has no GPU) | +| Packaging | `py3-none` wheels via `cibuildwheel` on `manylinux_2_28` `x86_64` and macOS 11+ `arm64`, sdist, `.crate` | +| Rust | Rust 1.74 (MSRV) and stable on Linux `x86_64` (built-in BLAS, reference BLAS, OpenBLAS, BLIS) | +| Octave | GNU Octave 10 (`mkoctfile`) | -- **PyTorch & JAX version floors:** Requires `python >= 3.10`, `numpy >= 1.23`, - `torch >= 2.1` (use `numpy < 2` with PyTorch 2.1 wheels), `jax >= 0.4.35`, and - `scikit-learn >= 1.6`. -- **CUDA fused kernels:** Require `torch >= 2.7` and `triton >= 3.3` (older versions fall - back to composed PyTorch tensor ops). The C++ `cuLaunchKernel` launcher supports Triton - 3.3–3.9 (`SDCA_CUDA_LAUNCHER` overrides selection; `libsdca.torch.explain_backend` - reports the active backend). +## Python -## C++ configuration +| Extra | Packages | Purpose | +| --- | --- | --- | +| *(default)* | `numpy>=1.23` | NumPy solver and losses | +| `sklearn` | `scikit-learn>=1.6` | `SDCAClassifier` | +| `torch` | `torch>=2.1`, `ninja`, `setuptools>=77,<81`, `ziglang>=0.13,<0.18` (Linux) | PyTorch losses and their C++ extensions | +| `jax` | `jax>=0.4.35` | JAX losses (`libsdca.jax`) | +| `jax-cuda` | `jax[cuda13]>=0.7.2`, `triton>=3.3` (Linux) | JAX losses on CUDA | +| `test`, `test-torch`, `test-jax` | `pytest`, `pytest-xdist`, `scipy`, `mpmath`, ... | Test suites (`--group core\|torch\|jax\|all`) | + +- **Versions:** PyTorch 2.1 wheels need `numpy<2`. The fused CUDA kernels need `triton>=3.3`, + which PyTorch 2.7 and later install (older versions use composed PyTorch operations); the C++ + launcher supports Triton 3.3–3.9. `libsdca.torch.explain_backend` reports the active path. +- **Runtime extensions:** The PyTorch CPU extension and CUDA launcher compile on first use + with `torch.utils.cpp_extension` (a C++17 compiler with OpenMP, Python headers, and CUDA + headers for the launcher). JAX compiles a small XLA FFI handler against + `jax.ffi.include_dir()`. Without build tools both fall back with a one-time warning. + +```bash +python -m pip install . # system CBLAS if found, else built-in +SDCA_BLAS_BACKEND=BUILTIN python -m pip install . # no external BLAS +SDCA_BLAS_BACKEND=EXTERNAL python -m pip install . # require an external CBLAS +SDCA_BLAS="-L/opt/blas/lib -lopenblas" python -m pip install . # explicit linker flags +SDCA_BUILD_NATIVE=OFF python -m pip install '.[torch]' # tensor losses only, no compiler +``` + +## C++ and CMake | CMake option | Default | Description | | --- | --- | --- | -| `SDCA_BLAS_BACKEND` | `AUTO` | `AUTO` (prefer external CBLAS, else built-in), `BUILTIN` (no external BLAS/OpenMP), or `EXTERNAL` (require external CBLAS) | -| `SDCA_BUILD_C_API` | `OFF` | Build and install the C ABI library `libsdca::sdca_c` (links `Threads`) | -| `SDCA_WARNINGS_AS_ERRORS` | `OFF` | Treat compiler warnings as errors (`-Werror`) | -| `BUILD_TESTING` | `OFF` | Build bundled GoogleTest and C++ test suites | -| `SDCA_BUILD_MATLAB` | `OFF` | Build MATLAB MEX gateways | -| `USE_CHRONO` | `ON` | Use `` wall clock (`OFF` selects POSIX `gettimeofday`) | -| `USE_SEQUENTIAL`, `USE_ILP64`, `USE_THREADING_SUFFIX` | `ON`, `ON`, `OFF` | Intel MKL threading layer, 64-bit integer ABI, and MEX binary suffix | - -Minimal installation and CMake usage: +| `SDCA_BLAS_BACKEND` | `AUTO` | `AUTO` (external CBLAS if found, else built-in), `BUILTIN`, or `EXTERNAL` | +| `SDCA_BUILD_C_API` | `OFF` | Build and install the C ABI library `libsdca::sdca_c` | +| `SDCA_BUILD_MATLAB` | `OFF` | Build the MATLAB MEX gateways | +| `BUILD_TESTING` | `OFF` | Build the bundled GoogleTest suites | +| `SDCA_WARNINGS_AS_ERRORS` | `OFF` | Add `-Werror` | +| `USE_CHRONO` | `ON` | `` wall clock (`OFF`: POSIX `gettimeofday`) | +| `USE_SEQUENTIAL`, `USE_ILP64`, `USE_THREADING_SUFFIX` | `ON`, `ON`, `OFF` | Intel MKL threading layer, 64-bit integers, MEX suffix | ```bash -cmake -S . -B build/minimal -DSDCA_BLAS_BACKEND=BUILTIN -DCMAKE_INSTALL_PREFIX=/your/prefix -cmake --build build/minimal --target install +cmake -S . -B build -DSDCA_BLAS_BACKEND=BUILTIN -DCMAKE_INSTALL_PREFIX="$PWD/build/install" +cmake --build build --target install ``` ```cmake @@ -48,44 +64,12 @@ find_package(libsdca CONFIG REQUIRED) target_link_libraries(my_program PRIVATE libsdca::libsdca) ``` -Include `sdca/utility/logging.cpp` in exactly one translation unit. Direct header users -without CMake default to `BLAS_BUILTIN` and `` (or define `BLAS_DEFAULT`, -`BLAS_DEFAULT_LOCAL_HEADER`, `BLAS_MKL`, `BLAS_ACCELERATE`, or `BLAS_MATLAB` and link the -corresponding CBLAS library). - -## Python configuration - -The PyTorch CPU extension and CUDA launcher compile on first use via -`torch.utils.cpp_extension` (requiring `ninja`, a C++17/C++20 compiler with OpenMP, Python -headers, and CUDA headers for the launcher); native JAX CPU losses likewise compile a small -XLA FFI handler against `jax.ffi.include_dir()` ([environment variables](docs/API.md#environment-variables)). -Without build tools, both fall back automatically with a one-time warning. - -```bash -# Default source install (uses system CBLAS if found, else built-in): -python -m pip install . - -# Force built-in BLAS (no external BLAS dependency): -SDCA_BLAS_BACKEND=BUILTIN python -m pip install . - -# Require external BLAS: -SDCA_BLAS_BACKEND=EXTERNAL python -m pip install . - -# Pure-Python wheel for PyTorch/JAX tensor losses only (no C++ compiler needed): -SDCA_BUILD_NATIVE=OFF python -m pip install '.[torch]' -``` - -| Optional extra | Packages | Purpose | -| --- | --- | --- | -| *(default)* | `numpy>=1.23` | NumPy solver and loss interface | -| `torch` | `torch>=2.1`, `ninja` | PyTorch loss layers and JIT extensions | -| `jax` | `jax>=0.4.35` | JAX loss functions (`libsdca.jax`) | -| `sklearn` | `scikit-learn>=1.6` | `SDCAClassifier` estimator | -| `test`, `test-torch`, `test-jax` | `pytest>=9`, `pytest-xdist>=3.6`, `scipy`, `mpmath`, ... | Test suites (`--group core\|torch\|jax\|all`) | -| `coverage` | `coverage[toml]>=7` | Python line-coverage instrumentation | +Without CMake, define one of `BLAS_BUILTIN` (default), `BLAS_DEFAULT`, +`BLAS_DEFAULT_LOCAL_HEADER`, `BLAS_MKL`, `BLAS_ACCELERATE` or `BLAS_MATLAB`, link the matching +CBLAS, and compile `sdca/utility/logging.cpp` in exactly one translation unit. -## Rust configuration +## Rust -The `libsdca` crate has zero Rust dependencies and requires Rust 1.74+. Its `build.rs` -compiles `src/c_api.cpp` with `CXX` (default `c++`) and the built-in BLAS, or links an -external CBLAS via `SDCA_BLAS` ([rust/README.md](rust/README.md#building)). +The crate has no Rust dependencies and needs Rust 1.74+. `build.rs` compiles `src/c_api.cpp` +with `CXX` (default `c++`) and the built-in BLAS, or links an external CBLAS given by +`SDCA_BLAS` ([rust/README.md](rust/README.md#building)). diff --git a/MANIFEST.in b/MANIFEST.in index 08a4ba3c..7367d94e 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -1,9 +1,10 @@ recursive-include include *.h include src/c_api.cpp src/tensor_losses.h -include sdca_build.py +include sdca_build.py VERSION include python/README.md include python/TORCH.md python/JAX.md -include python/libsdca/_torch_entropy.cpp python/libsdca/_torch_*.h python/libsdca/_jax_ffi.cpp +include python/libsdca/_cpu_*.h +include python/libsdca/_torch_entropy.cpp python/libsdca/_torch_*.h python/libsdca/_jax_ffi.cpp python/libsdca/_jax_cuda.cpp include include/sdca/utility/logging.cpp include CHANGELOG.md DEPENDENCIES.md AGENTS.md CITATION.cff -include tests/python/*.py +recursive-include tests/python *.py *.json diff --git a/README.md b/README.md index 8188b1e1..1df71efc 100644 --- a/README.md +++ b/README.md @@ -6,90 +6,97 @@ [![Crates.io](https://img.shields.io/crates/v/libsdca.svg)](https://crates.io/crates/libsdca) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) -**libsdca** provides accurate and fast classification losses for SDCA and neural -networks. It implements multiclass, top-*k*, multilabel, and soft-target -classification losses in two forms: fused CPU and CUDA loss layers for PyTorch and -JAX (and NumPy functions), and stochastic dual coordinate ascent (SDCA) solvers for -linear and kernel models. It covers cross-entropy, the multiclass hinge, knowledge -distillation, the multilabel losses, and the top-*k* hinge and entropy losses of -[Lapin et al.](#citation). - -Every loss and gradient is accurate to the limit of its floating-point format: -confident predictions keep nonzero losses and target gradients down to subnormal -underflow instead of collapsing to zero (softmax collapse [7], fixed in [6]), and -distillation gradients are exact zero at equal student and teacher logits (softmax -cancellation [6]), across `float16`, `bfloat16`, `float32` and `float64` on CPU -and CUDA ([known limits](docs/numerics.md#known-limits)). +**libsdca** is a fast and accurate implementation of classification losses: cross-entropy, +multiclass and multilabel SVM hinges, top-*k* losses and knowledge distillation. The losses +are available as PyTorch and JAX layers on CPU and CUDA and as NumPy, Rust, C++, C and MATLAB +functions, and a stochastic dual coordinate ascent (SDCA) solver trains linear and kernel +classifiers with them. + +- **Fast:** The losses are fused CPU and CUDA kernels, not chains of tensor operations. On an + A100 with 32k–128k classes, cross-entropy matches `torch.compile` and is 2.4–3× faster than + eager PyTorch, and the multiclass hinge is 4–8× faster than compiled and 8–14× faster than + eager PyTorch implementations ([benchmarks](python/TORCH.md#benchmarks)). +- **Accurate:** Losses and gradients of confident predictions are kept down to the subnormal + range of the output dtype: a naive `float32` cross-entropy rounds to zero from a margin of + about 17 (softmax collapse [7]), and `libsdca` stays accurate up to about 104. Distillation + gradients are exactly zero at equal student and teacher logits [6]. The entropy and + distillation losses are tested on CPU and CUDA against 100-digit `mpmath` references + ([known limits](docs/API.md#known-limits)). +- **Many losses:** Cross-entropy, the multiclass hinge (Crammer–Singer SVM [1]), the top-*k* + hinge and entropy losses [4, 5], the multilabel hinge [2] and cross-entropy, logit + distillation and proximal variants, with nonsmooth or smoothed hinges, and + `linear_cross_entropy` for a language-model head without its `(N, V)` logits + ([losses](#losses)). +- **Many interfaces:** PyTorch modules and functions (with `torch.compile` support), JAX + functions for `jit`, `grad` and `vmap`, NumPy, a scikit-learn estimator, Rust, header-only + C++, C and MATLAB/Octave, with the same loss and option names in each + ([API reference](docs/API.md)). +- **SDCA solver with a duality-gap guarantee:** SDCA trains linear and kernel classifiers + (multiclass, top-*k* and multilabel SVMs, softmax regression). The duality gap bounds the + distance to the optimum, so `status == "solved"` guarantees that the objective of the + returned model is within the relative tolerance `tol` of the optimal value + ([results](docs/API.md#results)). Its steps use efficient projections onto the simplex and + the top-*k* cone [3, 4], which C++ and MATLAB also provide directly. -```python -from libsdca import CrossEntropyLoss +## Installation + +Create a fresh environment with [uv](https://docs.astral.sh/uv/) and install `libsdca` with +PyTorch support: -criterion = CrossEntropyLoss() # drop-in for torch.nn.CrossEntropyLoss(), except integer - # class labels only and no label smoothing -loss = criterion(logits, targets) -loss.backward() + +```bash +uv venv --seed --managed-python --python 3.12 .venv +source .venv/bin/activate +pip install 'libsdca[torch]' ``` -- **Accurate to the limit of the format:** Every loss value and gradient entry is - verified within `64` output-dtype eps against 100-digit `mpmath` references across - `2` to `32,769` classes, subnormal tails, cancellation offsets and `±finfo.max` - ([verification](docs/numerics.md#how-it-is-verified)). -- **Fast fused loss kernels:** On an A100 at `8192 × 32000` and `8192 × 128256` - (`bfloat16` / `float32`), `CrossEntropyLoss` runs in `0.33–0.41×` eager - `F.cross_entropy` time (`0.93–0.98×` `torch.compile`) and saves a few scalars - per row instead of an `(N, C)` tensor ([performance](docs/performance.md)). -- **Certified SDCA:** Training evaluates the duality gap of the returned - weights and the feasible projection of the returned duals in `double`, with a - first-order rounding estimate $e$; - `status == "solved"` certifies $P(W) - D(A) + e \le \text{tol} \cdot \max(|P|, |D|)$ - ([numerics](docs/numerics.md#the-solved-certificate)). -- **Decoupled storage and compute precision:** `precision="float32"` or `"float64"` - selects working arithmetic independently of array/tensor storage - ([support matrix](docs/API.md#precision)). -- **Zero-overhead imports & optional BLAS:** `import libsdca` loads neither - PyTorch, JAX nor scikit-learn until used, and the C++ core includes a built-in - BLAS fallback when no external CBLAS is installed. - -## Objectives +Then use the losses in place of the PyTorch ones: -| Name | Loss | Targets | -| --- | --- | --- | -| `cross_entropy` | Softmax cross-entropy | single class index | -| `topk_cross_entropy` | Top-*k* entropy [5] | single class index | -| `multiclass_hinge` | Multiclass hinge (Crammer–Singer SVM) [1] | single class index | -| `topk_hinge_alpha`, `topk_hinge_beta` | Top-*k* hinge $\alpha$ [4] and $\beta$ [5] | single class index | -| `multilabel_hinge` | Multilabel hinge (multilabel SVM) [2] | label sets / boolean mask | -| `multilabel_cross_entropy` | Multilabel cross-entropy | label sets / boolean mask | + +```python +import torch +from libsdca import CrossEntropyLoss, TopKHingeLoss -Hinge losses accept `gamma >= 0` (`0` = nonsmooth hinge, `> 0` = Moreau-smoothed -hinge [5]). The loss layers additionally provide `proximal_cross_entropy`, -`distillation_loss` ([TORCH.md](python/TORCH.md#teacher-logits-and-distillation)), -`proximal_distillation_loss`, and `linear_cross_entropy`, which evaluates a -language-model linear head + cross-entropy in chunks without materializing `(N, V)` -logits ([TORCH.md](python/TORCH.md#linear-layer-and-cross-entropy-without-the-logits)). +device = "cuda" if torch.cuda.is_available() else "cpu" +logits = torch.randn(32, 5, device=device, requires_grad=True) +targets = torch.randint(5, (32,), device=device) -## Installation +ce = CrossEntropyLoss()(logits, targets) # replaces torch.nn.CrossEntropyLoss() +hinge = TopKHingeLoss(k=2)(logits, targets) # top-2 SVM loss +(ce + hinge).backward() +``` + +### Other interfaces + +Every interface installs with one command or CMake target, and its guide documents all +options: | Interface | Install | Guide | | --- | --- | --- | | Python (NumPy) | `pip install libsdca` | [python/README.md](python/README.md) | | scikit-learn estimator | `pip install 'libsdca[sklearn]'` | [python/README.md](python/README.md#classifier) | | PyTorch losses | `pip install 'libsdca[torch]'` | [python/TORCH.md](python/TORCH.md) | -| JAX losses | `pip install 'libsdca[jax]'` | [python/JAX.md](python/JAX.md) | +| JAX losses (CPU) | `pip install 'libsdca[jax]'` | [python/JAX.md](python/JAX.md) | +| JAX losses (Linux NVIDIA GPU) | `pip install 'libsdca[jax-cuda]'` | [python/JAX.md](python/JAX.md) | | Rust | `cargo add libsdca` | [rust/README.md](rust/README.md) | | C++ (header-only) | CMake target `libsdca::libsdca` | [docs/CPP.md](docs/CPP.md) | | C | CMake target `libsdca::sdca_c` (`-DSDCA_BUILD_C_API=ON`) | [docs/C.md](docs/C.md) | | MATLAB / Octave | `run matlab/make.m` / `tests/matlab/run_octave_tests.sh` | [docs/MATLAB.md](docs/MATLAB.md) | -- **Python wheels:** Prebuilt wheels for Linux `x86_64` (`manylinux_2_28`) and - macOS 11+ (`arm64`) are self-contained; other platforms build from the sdist with - a C++11 compiler. -- **Runtime C++ extensions:** PyTorch and JAX compile small C++ extensions on first - use when a C++17/C++20 compiler and Python headers are installed (`build-essential` - and `python3-dev` on Debian/Ubuntu; `xcode-select --install` on macOS). Without a - compiler, losses fall back automatically with a one-time warning - ([build tools](python/TORCH.md#build-tools), [environment variables](docs/API.md#environment-variables)). -- **CMake and BLAS:** See [DEPENDENCIES.md](DEPENDENCIES.md) for CMake and BLAS options. +
+conda environment + + +```bash +conda create --yes --override-channels --channel conda-forge --prefix .venv python=3.12 pip +conda activate ./.venv +pip install 'libsdca[torch]' +``` + +
+ +
+C++ and C from source ```bash git clone https://github.com/mlapin/libsdca && cd libsdca @@ -97,10 +104,54 @@ cmake -S . -B build -DCMAKE_INSTALL_PREFIX=/usr/local # add -DSDCA_BUILD_C_API cmake --build build --target install ``` +CMake and BLAS options are in [DEPENDENCIES.md](DEPENDENCIES.md). + +
+ +
+Wheels, GPU and compiler requirements + +- **Wheels:** Prebuilt for Linux `x86_64` (`manylinux_2_28`) and macOS 11+ `arm64`; other + platforms build from the sdist with a C++11 compiler. +- **GPU:** CUDA needs Linux, an NVIDIA GPU and a compatible driver. The PyTorch examples + use CUDA when available; `jax-cuda` installs the CUDA 13 runtime and Triton (Python 3.11+, + driver 580+). NumPy, scikit-learn, Rust, C, C++ and MATLAB run on CPU. +- **Compilers:** PyTorch and JAX compile small C++ extensions on first use when a C++17 + compiler and Python headers are present (`build-essential python3-dev` on Debian/Ubuntu, + `xcode-select --install` on macOS); otherwise they fall back with a one-time warning + ([build tools](python/TORCH.md#build-tools)). uv-managed and conda Pythons include headers. + +
+ ## Quick start -### Python (scikit-learn and NumPy) +Each example uses cross-entropy and the top-2 hinge (top-2 SVM) loss with the default +options; the PyTorch example is [above](#installation). The [API reference](docs/API.md) and +the interface guides document every parameter and option. + +### JAX + +The losses are plain functions that compose with `jax.grad`, `jit` and `vmap`: + +```python +import jax +import jax.numpy as jnp +from libsdca.jax import cross_entropy, topk_hinge_loss + +logits = jnp.array([[1.0, 2.0, 0.5], [0.0, 1.0, 3.0]]) +targets = jnp.array([0, 2]) + +value, gradient = jax.value_and_grad(cross_entropy)(logits, targets) +value, gradient = jax.value_and_grad(topk_hinge_loss)(logits, targets, k=2) +``` + +### Python (NumPy) + +`fit` trains a linear classifier with the SDCA solver and returns the model with its +convergence status: + + ```python import numpy as np import libsdca @@ -109,91 +160,173 @@ rng = np.random.default_rng(0) X = rng.normal(size=(200, 10)) y = (X @ rng.normal(size=(10, 3))).argmax(axis=1) -clf = libsdca.SDCAClassifier("topk_cross_entropy", k=2, C=1.0).fit(X, y) -model = libsdca.fit(X, y, "topk_cross_entropy", k=2, C=1.0) -values, gradients = libsdca.loss_and_grad(X @ model.weights, y, "topk_hinge_alpha", k=2, gamma=1.0) +model = libsdca.fit(X, y) # cross-entropy (softmax regression) +model = libsdca.fit(X, y, "topk_hinge_beta", k=2) # top-2 SVM +print(model.status, (model.predict(X) == y).mean()) ``` -### PyTorch - -```python -import torch -from libsdca import CrossEntropyLoss, TopKHingeLoss +### Python (scikit-learn) -net = torch.nn.Linear(10, 5) -criterion = CrossEntropyLoss() # or TopKHingeLoss(k=2, variant="beta", gamma=0.5) -loss = criterion(net(torch.randn(32, 10)), torch.randint(0, 5, (32,))) -loss.backward() -``` - -### JAX +`SDCAClassifier` wraps the solver as a scikit-learn estimator: + ```python -import jax -import libsdca.jax as sjax +import numpy as np +from libsdca import SDCAClassifier + +rng = np.random.default_rng(0) +X = rng.normal(size=(200, 10)) +y = (X @ rng.normal(size=(10, 3))).argmax(axis=1) -loss_and_grad = jax.jit(jax.value_and_grad( - lambda w, x, y: sjax.sdca_loss(x @ w, y, "topk_hinge_beta", k=3, gamma=0.5) -)) +clf = SDCAClassifier().fit(X, y) # cross-entropy +clf = SDCAClassifier("topk_hinge_beta", k=2).fit(X, y) # top-2 SVM +print(clf.status_, clf.score(X, y)) ``` ### Rust +In a Cargo project (Rust 1.74+ and a C++11 compiler), run `cargo add libsdca`, save this as +`src/main.rs`, and run `cargo run`: + + ```rust -use libsdca::{fit, loss_and_grad, FitOptions, Loss, LossOptions, Matrix, Objective}; - -let x = Matrix::new(&[1.0, 0.0, 0.0, 1.0, -1.0, -1.0], 3, 2)?; -let fit_opts = FitOptions { c: 10.0, objective: Objective::CrossEntropy, ..Default::default() }; -let model = fit(x, &[0, 1, 2], &fit_opts)?; -let scores = Matrix::new(&[0.3, -0.8, 1.2], 1, 3)?; -let loss_opts = LossOptions { loss: Loss::TopKHingeBeta, k: 2, gamma: 1.0, ..Default::default() }; -let (values, gradients) = loss_and_grad(scores, &[0], &loss_opts)?; +use libsdca::{fit, FitOptions, Matrix, Objective}; + +fn main() -> libsdca::Result<()> { + let x = Matrix::new(&[1.0, 0.0, 0.0, 1.0, -1.0, -1.0], 3, 2)?; // 3 examples, 2 features + let y = [0, 1, 2]; + + let model = fit(x, &y, &FitOptions::default())?; // cross-entropy + println!("{} {:?}", model.status(), model.predict(x)?); + + let options = FitOptions { objective: Objective::TopKHingeBeta, k: 2, ..Default::default() }; + let model = fit(x, &y, &options)?; // top-2 SVM + println!("{} {:?}", model.status(), model.predict(x)?); + Ok(()) +} ``` ### C++ +After the [CMake installation](#other-interfaces) (*C++ and C from source*), compile this as +a C++11 program with the installed include directory and +`-DBLAS_BUILTIN -pthread -fno-fast-math -ffp-contract=off` (a CMake consumer is in +[examples/cpp](examples/cpp)): + + ```cpp +#include +#include #include "sdca/solver.h" #include "sdca/utility/logging.cpp" // in exactly one translation unit -auto context = sdca::make_context( - sdca::make_input_feature(d, n, features), sdca::multiclass_output(m, labels), - sdca::l2_entropy(/* C */ 1.0), dual, weights); -sdca::make_solver(context).solve(); +template +bool train(Objective objective) { + double features[] = {1, 0, 0, 1, -1, -1}; // 3 examples, 2 features + double weights[6] = {}, dual[9] = {}; + std::vector labels = {0, 1, 2}; + auto context = sdca::make_context( + sdca::make_input_feature(2, 3, features), sdca::multiclass_output(3, labels), + std::move(objective), dual, weights); + sdca::make_solver(context).solve(); + return context.status == sdca::solver_status::solved; +} + +int main() { + bool solved = train(sdca::l2_entropy(1.0)) // cross-entropy + && train(sdca::l2_topk_hinge(1.0, 2)); // top-2 SVM + return solved ? 0 : 1; +} ``` -### MATLAB +### C + +Build with `-DSDCA_BUILD_C_API=ON` as for C++ and link `libsdca_c` (a CMake consumer is in +[examples/c](examples/c)); this program evaluates both losses and their gradients: + + +```c +#include +#include "sdca/c_api.h" + +int main(void) { + const double scores[] = {0.3, -0.8, 1.2}; + const uint8_t positive[] = {1, 0, 0}; + double values[1], gradients[3]; + struct sdca_options options = SDCA_OPTIONS_DEFAULT; /* cross-entropy */ + int status = sdca_loss_gradient(&options, 1, 3, scores, positive, values, gradients); + options.loss = SDCA_TOPK_HINGE_BETA; /* top-2 SVM loss */ + options.k = 2; + status |= sdca_loss_gradient(&options, 1, 3, scores, positive, values, gradients); + return status != SDCA_OK; +} +``` + +### MATLAB / Octave +In MATLAB, `run matlab/make.m; addpath matlab` builds the gateways (with a configured MEX +C++ compiler). In Octave, run `tests/matlab/run_octave_tests.sh`, then `addpath build/octave`. + + ```matlab -model = matsdca_fit(X, Y, struct('objective', 'cross_entropy', 'C', 1)); % X: d-by-n -[~, predicted] = max(model.W' * Xtest); +X = [1 0 -1; 0 1 -1]; % 2 features, 3 examples +Y = [1 2 3]; +model = matsdca_fit(X, Y); % cross-entropy +model = matsdca_fit(X, Y, struct('objective', 'topk_hinge_beta', 'k', 2)); % top-2 SVM +[~, predicted] = max(model.W' * X); ``` -Runnable examples are in [examples/](examples), [rust/examples](rust/examples) and +More examples: [examples/](examples), [rust/examples](rust/examples) and [matlab/demo.m](matlab/demo.m). +## Losses + +All interfaces share these loss names: + +| Name | Loss | Targets | +| --- | --- | --- | +| `cross_entropy` | Softmax cross-entropy | class index | +| `topk_cross_entropy` | Top-*k* entropy [5] | class index | +| `multiclass_hinge` | Multiclass hinge (Crammer–Singer SVM) [1] | class index | +| `topk_hinge_alpha`, `topk_hinge_beta` | Top-*k* hinge $\alpha$ [4] and $\beta$ [5] | class index | +| `multilabel_hinge` | Multilabel hinge (multilabel SVM) [2] | label sets / boolean mask | +| `multilabel_cross_entropy` | Multilabel cross-entropy | label sets / boolean mask | +| `distillation`, `proximal_distillation` | Teacher-logit distillation and its Moreau envelope | teacher logits | +| `proximal_cross_entropy` | Moreau envelope of cross-entropy | class index | + +Hinge losses take `gamma >= 0` (`0`: nonsmooth, `> 0`: smoothed [5]). PyTorch also provides +`linear_cross_entropy` (linear head + cross-entropy in chunks). Formulas: +[API.md](docs/API.md#loss-definitions). + ## Documentation -- [API reference](docs/API.md): loss formulas, cross-language names, options, - precision, results and environment variables +An index of the guides is in [docs/](docs/README.md). + +- [API reference](docs/API.md): loss formulas, names across languages, options, precision, + results, threads, environment variables and known limits - Interface guides: [Python](python/README.md), [PyTorch](python/TORCH.md), [JAX](python/JAX.md), [Rust](rust/README.md), [C++](docs/CPP.md), [C](docs/C.md), [MATLAB](docs/MATLAB.md) -- [Numerical notes](docs/numerics.md): precision guarantees, verification and known limits -- [Performance](docs/performance.md): CUDA, CPU and solver benchmarks -- [Softmax collapse and cancellation](docs/softmax-collapse.md): formulations and - reproduction of Barron et al. [6] - [Dependencies](DEPENDENCIES.md), [contributing](CONTRIBUTING.md), - [AI coding assistant guide](AGENTS.md) and [changelog](CHANGELOG.md) -- [Project page](https://mlapin.github.io/libsdca/) and technical report, - [*libsdca: Accurate and Fast Classification Losses for SDCA and Neural Networks*](https://mlapin.github.io/libsdca/report/) + [guide for AI coding assistants](AGENTS.md) and [changelog](CHANGELOG.md) +- [Project page](https://mlapin.github.io/libsdca/) and technical report ## Citation -If `libsdca` is useful in your research, please cite the paper for the losses you use -and the technical report for the library: +If `libsdca` is useful in your research, please cite the TPAMI paper; the earlier papers +introduce the top-*k* losses, and the technical report describes the library: ```bibtex +@article{lapin2018analysis, + title = {Analysis and Optimization of Loss Functions for Multiclass, Top-k, and Multilabel Classification}, + author = {Lapin, Maksim and Hein, Matthias and Schiele, Bernt}, + journal = {IEEE Transactions on Pattern Analysis and Machine Intelligence (TPAMI)}, + volume = {40}, + number = {7}, + pages = {1533--1554}, + year = {2018} +} + @inproceedings{lapin2015topk, title = {Top-k Multiclass {SVM}}, author = {Lapin, Maksim and Hein, Matthias and Schiele, Bernt}, @@ -208,16 +341,6 @@ and the technical report for the library: year = {2016} } -@article{lapin2018analysis, - title = {Analysis and Optimization of Loss Functions for Multiclass, Top-k, and Multilabel Classification}, - author = {Lapin, Maksim and Hein, Matthias and Schiele, Bernt}, - journal = {IEEE Transactions on Pattern Analysis and Machine Intelligence (TPAMI)}, - volume = {40}, - number = {7}, - pages = {1533--1554}, - year = {2018} -} - @misc{lapin2026libsdca, title = {libsdca: Accurate and Fast Classification Losses for {SDCA} and Neural Networks}, author = {Lapin, Max}, @@ -230,6 +353,8 @@ GitHub's *Cite this repository* button uses [CITATION.cff](CITATION.cff). ## References +The numbered citations above refer to: + 1. K. Crammer and Y. Singer. On the algorithmic implementation of multiclass kernel-based vector machines. *JMLR*, 2001. 2. K. Crammer and Y. Singer. A family of additive online algorithms for @@ -240,7 +365,7 @@ GitHub's *Cite this repository* button uses [CITATION.cff](CITATION.cff). 5. M. Lapin, M. Hein and B. Schiele. Loss functions for top-k error: analysis and insights. *CVPR*, 2016. 6. J. T. Barron, D. Gnanapragasam and M. Tschannen. A fix for softmax and - cross-entropy. arXiv:2610.31642, 2026 ([reproduction](docs/softmax-collapse.md#reproduction)). + cross-entropy. arXiv:2610.31642, 2026. 7. L. Prieto, M. Barsbey, P. A. M. Mediano and T. Birdal. Grokking at the edge of numerical stability. *ICLR*, 2025. diff --git a/VERSION b/VERSION new file mode 100644 index 00000000..9e11b32f --- /dev/null +++ b/VERSION @@ -0,0 +1 @@ +0.3.1 diff --git a/docs/API.md b/docs/API.md index c6adba42..4d84bf97 100644 --- a/docs/API.md +++ b/docs/API.md @@ -1,9 +1,8 @@ # API reference -`libsdca` shares one set of loss names, option names, status codes and defaults -across C++, the C ABI (`include/sdca/c_api.h`), Python, PyTorch, JAX, Rust and -MATLAB. Interface guides: [Python](../python/README.md), -[PyTorch](../python/TORCH.md), [JAX](../python/JAX.md), +One set of loss names, option names, status codes and defaults is shared by C++, the C ABI +(`include/sdca/c_api.h`), Python, PyTorch, JAX, Rust and MATLAB. Interface guides: +[Python](../python/README.md), [PyTorch](../python/TORCH.md), [JAX](../python/JAX.md), [Rust](../rust/README.md), [C++](CPP.md), [C](C.md) and [MATLAB](MATLAB.md). ## Loss definitions @@ -36,7 +35,7 @@ $h_j = 1 + z_j - z_y$ ($j \neq y$) sorted as $h_{[1]} \ge h_{[2]} \ge \dots$ `gamma > 0` is its Moreau envelope $\max_{p \in S} \langle h, p \rangle - \frac{\gamma}{2}\Vert p \Vert_2^2$, which is within $\gamma / 2$ of the nonsmooth loss and has a $(1/\gamma)$-Lipschitz gradient [4]. - **Top-*k* exclusion:** Top-*k* hinges exclude the target class $y$ when selecting the $k$ - largest competitor margins $h_{[1]}, \dots, h_{[k]}$ [4, Prop. 11]. At $k = 1$, + largest competitor margins $h_{[1]}, \dots, h_{[k]}$ [4]. At $k = 1$, `topk_hinge_alpha` and `topk_hinge_beta` coincide with `multiclass_hinge`. ## Objectives and losses @@ -84,7 +83,7 @@ Public C++ headers: `sdca/solver.h`, `sdca/prox.h` and `sdca/loss.h` ## Options -Python, MATLAB and Rust share the option names below (`c` in Rust and C): +Python, MATLAB and Rust share the option names below: | Option | C++ | Default | Meaning | | --- | --- | --- | --- | @@ -101,15 +100,16 @@ Python, MATLAB and Rust share the option names below (`c` in Rust and C): | `kernel` | `make_input_kernel` | `false` | Input $X$ is a symmetric PSD $(n, n)$ Gram matrix | | `center` | `context.primal_initial` | `None` | Regularize $0.5\Vert W - W_0 \Vert_2^2$ instead of $0.5\Vert W \Vert_2^2$ | | `initial_dual` | dual buffer | `None` | Initial dual variables $A$ for warm starts | -| `num_threads` | `criteria.num_threads` | `auto` | Worker threads for losses, steps and evaluations | -| `precision` | `` | `"float64"` | Working and iterate precision ([below](#precision)) | +| `num_threads` | `criteria.num_threads` | `auto` | Worker threads for `loss_and_grad`, `coordinate_update` and C `sdca_options` (`SDCA_NUM_THREADS` for `fit`) | +| `precision` | `` | storage dtype | Working and iterate precision ([below](#precision)) | - **Evaluations (`eval_epoch`, `recompute_primal`):** Besides checking every `eval_epoch` epochs, a fit with `tol > 0` schedules up to two interpolated evaluations when the gap trend projects crossing `tol` early. With `recompute_primal=True` (default), feature fits rebuild $W = W_0 + X^\top A$ before evaluating the primal objective so incremental update drift does not - pollute the certificate. + enter the gap (not for `float32` data with `precision="float64"`, whose `double` $W$ is + evaluated as stored). - **Kernel validation (`kernel=True`):** Every interface verifies a nonnegative diagonal, symmetry within $10^{-5}\sqrt{K_{ii}K_{jj}}$, and $\lvert K_{ij} \rvert \le (1 + 10^{-3})\sqrt{K_{ii}K_{jj}}$. @@ -126,14 +126,15 @@ bounds (entropy objectives have strictly positive probabilities and ignore the o shrinking [7]. Epochs between full passes skip examples whose dual block did not change and restrict single-label updates to the target and nonzero-dual classes; full passes and evaluations run after `eval_epoch` full-pass equivalents of work (at most 50 epochs). -- `"safe"` (`Shrinking::Safe`, `SDCA_SHRINKING_SAFE`): Gap-safe screening [8] on feature - inputs. Uses strong convexity $\Vert W - W^\star \Vert_2 \le \sqrt{2\text{ gap}}$ to permanently - prune dual variables proven to be zero at the optimum. +- `"safe"` (`Shrinking::Safe`, `SDCA_SHRINKING_SAFE`): Gap-safe screening [8] for the + single-label hinges on feature inputs (no effect for `multilabel_hinge` or kernels). Uses + strong convexity $\Vert W - W^\star \Vert_2 \le \sqrt{2\text{ gap}}$ to permanently prune + dual variables proven to be zero at the optimum. - `"both"` / `"auto"` (default): Combines `"heuristic"` and `"safe"`. - `"off"`: Updates every class of every example on every epoch. -All modes evaluate the duality gap across all examples and classes (`solved` -carries the same certificate; see [performance](performance.md#solver)). +All modes evaluate the duality gap across all examples and classes, so `solved` carries the +same certificate. ### Projection precision @@ -143,62 +144,67 @@ carries the same certificate; see [performance](performance.md#solver)). in `double` and verifies that every entry lies clear of its threshold error bound, falling back to the extended-precision solver only when a near-tie or extreme scale fails the check. - `"extended"` (`ProjectionPrecision::Extended`, `SDCA_PROJECTION_EXTENDED`): Always runs - the hardened `long double` solver (`0–12%` slower at 1,000 classes, bitwise reproducible - on extreme spreads; see [numerics.md](numerics.md#projection-precision)). + the `long double` solver (slightly slower; reproducible on extreme spreads). ## Precision -Storage and working arithmetic are decoupled across all interfaces: - -| Storage dtype | `precision` | Native (NumPy, Rust, C) | PyTorch | JAX | -| --- | --- | --- | --- | --- | -| `float16`, `bfloat16` | `None` (default), `"float32"` | unsupported (cast to `float32`) | `float32` (`float64` CE stats) | `float32` work | -| `float16`, `bfloat16` | `"float64"` | unsupported | `float64` work | `float64` (needs `jax_enable_x64`) | -| `float32` | `None` (default), `"float64"` | `float64` work & `double` iterate | `float32` in CE (`float64` in hinges or `"float64"`) | `float32` in CE (`float64` with `"float64"`, x64) | -| `float32` | `"float32"` | `float32` work & `float` iterate | `float32` work | `float32` work | -| `float64` | `None` (default), `"float64"` | `float64` (`"float32"` invalid) | `float64` (`"float32"` invalid) | `float64` (`"float32"` invalid) | - -- **Outputs:** Returned weights, duals and gradients keep the input storage dtype. Loss - values are `double` in the native APIs and `promote(logits.dtype, float32)` in PyTorch - and JAX (`float32` for 16-/32-bit, `float64` for `float64`, as in `torch.autocast`). -- **Default `precision="float64"` for `float32` fits:** Keeping `W` and the duals in - `float32` loses updates below $\frac{1}{2}\mathrm{ulp}$ near the optimum (`4.7e-6` gap on - `digits`). The default `"float64"` (`` in C++) keeps `double` iterates - (`8(d + n)m` extra bytes) and certifies the rounded `float32` arrays (`3.5e-7` gap; - [numerics.md](numerics.md#what-each-precision-guarantees)). Pass `"float32"` for - `1.6–1.9×` faster cross-entropy fits. -- **Compiler flags:** Build `libsdca` with IEEE semantics (`-fno-fast-math -ffp-contract=off`); - `-ffast-math` or `-Ofast` breaks nonfinite-input checks and compensated reductions. +Storage and working precision are separate. `precision=None` (default) follows the storage +dtype, with 16-bit storage computed in `float32`; `"float32"` or `"float64"` selects the +working precision explicitly: + +| Storage dtype | `None` (default), `"float32"` | `"float64"` | +| --- | --- | --- | +| `float16`, `bfloat16` | `float32` work (the NumPy and C APIs reject 16-bit storage: cast to `float32` first) | `float64` work (JAX: see [backends](../python/JAX.md#backends)) | +| `float32` | `float32` work | `float64` work | +| `float64` | `float64` work (`"float32"` raises) | `float64` work | + +MATLAB differs: `precision` defaults to `'double'` for every input class +([MATLAB.md](MATLAB.md#training)). + +- **Accuracy contract:** `float32` work bounds the accuracy of the results; individual + operations may run in `float64`. Row statistics of the entropy losses are accumulated in + `float64`, and kernels promote rows or parameters that `float32` cannot represent. Some paths + (single-label cross-entropy and smoothed hinges in the native library, proximal distillation + on CPU) keep `float64` arithmetic throughout. +- **Outputs:** Weights, duals and gradients keep the storage dtype. Loss values are `double` + in the native APIs and `promote(logits.dtype, float32)` in PyTorch and JAX. +- **`float32` fits:** Keeping $W$ and the duals in `float32` can stall near the optimum + (updates below half an ulp are lost). `precision="float64"` (`` in C++) keeps + `double` iterates for tighter convergence at `8(d + n)m` extra bytes. Both modes certify the + returned arrays. +- **Compiler flags:** Build with IEEE semantics (`-fno-fast-math -ffp-contract=off`); + `-ffast-math` or `-Ofast` breaks the nonfinite-input checks and compensated sums. ### Parameter domains and numerical limits All loss and training entry points require `classes >= 2`, integer `1 <= k < classes`, finite scores/features, and valid targets (0-based class indices, or 1-based in MATLAB; boolean masks require at least one positive label, plus one negative label for -`multilabel_hinge` and `proximal_cross_entropy`). +`multilabel_hinge` and `proximal_cross_entropy`; label sets in `fit` and `coordinate_update` +require a negative label for every objective). | Parameter | Valid domain | Notes | | --- | --- | --- | -| `C`, `alpha`, `temperature` | finite, strictly positive | `C` and `C * norm2` must be normal in working precision; `alpha` or `temperature` outside normal `float32` promotes to `float64` | +| `C`, `alpha`, `temperature` | finite, strictly positive | `C`, `norm2` and `C * norm2` must be normal in the storage dtype, and `C` in working precision; `alpha` or `temperature` outside normal `float32` promotes to `float64` | | `gamma` | finite, `>= 0` | `0` selects the nonsmooth hinge; positive values follow the rules of `alpha` | -| `tol` | finite, `>= 0` | `0` runs until `max_epoch` (or time limits in MATLAB); tolerances below ~`1e-12` in `float64` cannot be certified | +| `tol` | finite, `>= 0` | `0` disables the `solved` stop: the fit ends with `max_epoch`, `no_progress` or `failed` (or a time limit in MATLAB) | | `ignore_index` (PyTorch) | 64-bit integer | Matching targets are excluded from the loss and gradient | | `weight` (PyTorch CE) | finite, `>= 0`, shape `(C,)` | Matches logits device and dtype (`float32` accepted for 16-bit logits under autocast) | -Tested accuracy bounds and representation limits are documented in -[numerics.md](numerics.md#known-limits). +See [known limits](#known-limits) for accuracy bounds. ## Results Training returns a status (`none`, `solving`, `solved`, `no_progress`, `max_epoch`, `max_cpu_time`, `max_wall_time`, `failed`) and an evaluation `history` (`epoch`, `primal`, `dual`, `primal_loss`, `dual_loss`, `regularizer`, `relative_gap`, -`accuracy` / `rank_loss`, `cpu_time`, `wall_time`). +`accuracy` / `rank_loss`, `cpu_time`, `wall_time`; MATLAB's `model.train` has its own field +names). Only `status == "solved"` certifies convergence: $$P(W) - D(A) + e \le \text{tol} \cdot \max(|P(W)|, |D(A)|),$$ where $P(W)$ is evaluated in `double` at the returned weights, $D(A)$ at the feasible -projection of the returned duals, and $e$ is a first-order estimate of evaluation rounding ([numerics.md](numerics.md#the-solved-certificate)). +projection of the returned duals, and $e$ is a first-order estimate of evaluation rounding. If a numerical step fails or the evaluated gap falls below $-e$, training stops with `failed` at the last consistent iterate. With a regularizer center $W_0$, $P(W)$ and $D(A)$ evaluate the full centered objective directly from $W - W_0$ without cancelling @@ -215,8 +221,7 @@ same shape and dtype; the teacher receives no gradient. With $p = \mathrm{softma $q = \mathrm{softmax}(z/T)$, the student gradient is $(q - p)/T$ (or $(\pi - p)/T$ at the Moreau-envelope optimum $\pi = \mathrm{softmax}(u^\star)$ for `proximal_distillation_loss`), with no $T^2$ multiplier. Because each entry is formed from a centered log-ratio via `expm1`, -identical student and teacher logits produce an **exact zero gradient** in every dtype -([softmax cancellation](softmax-collapse.md#softmax-cancellation)). +identical student and teacher logits produce an **exact zero gradient** in every dtype. ```python import torch @@ -230,8 +235,12 @@ prox = ProximalDistillationLoss(temperature=4.0, alpha=0.5)(student, teacher) ``` In PyTorch, both run on fused Triton kernels on CUDA and the C++ extension on CPU -(first-order derivatives only). In JAX (`libsdca.jax`), both run in `jax.numpy` on any -device (`jvp`/`jacfwd` raise, while reverse-over-reverse and `jax.hessian` are supported). +(first-order derivatives only). In JAX (`libsdca.jax`), both run on the same Triton +kernels on CUDA and use the shared CPU kernels where available, with array +fallbacks. Direct `jvp`/`jacfwd` of these custom-VJP losses raise. Ordinary +distillation supports reverse-over-reverse and `jax.hessian`; proximal distillation +supports `jax.hessian` (forward-over-reverse), but reverse-over-reverse is unsupported +because the array reference solve's dynamic loop cannot be transposed. ## Threads @@ -244,19 +253,20 @@ worker threads with **bitwise-identical results** for every thread count: `OMP_NUM_THREADS` and divided across concurrent calls. Passing `1` runs on the calling thread. - **Work threshold:** A call times its first rows on the calling thread and spawns workers only when remaining work is estimated at $\ge 1\text{ ms}$ ($\ge 0.2\text{ ms}$ on an OpenMP team). -- **Training (`fit`):** Coordinate-ascent epochs are sequential; only duality-gap evaluations - and kernel validation run in parallel. +- **Training (`fit`):** Coordinate-ascent epochs are sequential; only duality-gap evaluations, + gap-safe screening passes and kernel validation run in parallel. - **Floating-point environment:** Every C ABI call executes with IEEE subnormals enabled and round-to-nearest (even if the caller set flush-to-zero, as XLA:CPU does) and restores the caller's environment on return. ## Environment variables -For the runtime-compiled extension switches (`SDCA_CPU_EXTENSION`, `SDCA_CUDA_LAUNCHER`, -`SDCA_JAX_FFI`), `auto` (default) compiles and caches the extension on first use when build -tools are available, or falls back with a one-time warning (`*.build-failed.txt` suppresses -retries across processes for 24 h); `on` (`1`) requires the extension and raises -`RuntimeError` on failure; `off` (`0`) disables it silently. +The runtime-compiled extension switches (`SDCA_CPU_EXTENSION`, `SDCA_CUDA_LAUNCHER`, +`SDCA_JAX_FFI`, `SDCA_JAX_CUDA`) take `auto` (default: compile and cache on first use, or +fall back with a one-time warning), `on` (`1`: raise `RuntimeError` if unavailable) or `off` +(`0`). A compiler error leaves `*.build-failed.txt` in the cache, which suppresses +retries for 24 hours (transient failures are not recorded); delete it to retry. The CUDA +switches fall back without a warning when Triton is newer than the verified range. | Variable | Default | Purpose | | --- | --- | --- | @@ -264,11 +274,13 @@ retries across processes for 24 h); `on` (`1`) requires the extension and raises | `SDCA_CPU_EXTENSION` | `auto` | `auto \| on \| off`: JIT-compiled PyTorch CPU C++ extension (`libsdca.torch.explain_backend` reports status) | | `SDCA_CUDA_LAUNCHER` | `auto` | `auto \| on \| off`: C++ `cuLaunchKernel` launcher for CUDA kernels (Triton 3.3–3.9) | | `SDCA_JAX_FFI` | `auto` | `auto \| on \| off`: XLA FFI custom-call handler for native JAX CPU losses | -| `SDCA_CACHE_DIR` | `~/.cache/libsdca` | Cache directory for compiled JAX FFI handlers | +| `SDCA_JAX_CUDA` | `auto` | `auto \| on \| off`: fused Triton kernels of JAX losses on CUDA GPUs (Triton 3.3–3.9; `off` keeps `jax.numpy`) | +| `SDCA_JAX_CPU_FUSION` | `auto` | `auto \| fenced \| unfenced`: fusion of the JAX entropy and distillation CPU passes, read when a loss is traced; `auto` times both once per machine ([JAX.md](../python/JAX.md#cpu-pass-fusion)) | +| `SDCA_CACHE_DIR` | `$XDG_CACHE_HOME/libsdca` (`~/.cache/libsdca`) | Cache directory for compiled JAX FFI handlers and `SDCA_JAX_CPU_FUSION=auto` decisions | | `TORCH_EXTENSIONS_DIR` | PyTorch cache | Cache directory for compiled PyTorch CPU and CUDA extensions | | `OMP_NUM_THREADS` | unset | Caps automatic threads when no OpenMP runtime is loaded | | `SDCA_LIBRARY_DIR` | unset | Override directory from which Python loads `libsdca_c.so` | -| `SDCA_BLAS_BACKEND` | `AUTO` | Build-time BLAS selection (`AUTO`, `EXTERNAL`, `BUILTIN`) for `pip install`, `python/build.py`, `rust/build.rs`, and CMake | +| `SDCA_BLAS_BACKEND` | `AUTO` | Build-time BLAS selection (`AUTO`, `EXTERNAL`, `BUILTIN`) for `pip install`, `python/build.py` and `rust/build.rs` (CMake: `-DSDCA_BLAS_BACKEND`) | | `SDCA_BLAS` | unset | Explicit external BLAS linker flags (e.g. `-lopenblas` or `-L/opt/blas/lib -lblas`) | | `SDCA_BUILD_NATIVE` | `ON` | Set to `OFF` during `pip install` to build a pure-Python wheel for tensor losses only | | `CXX`, `AR`, `CUDA_HOME` | system default | Compiler, archiver, and CUDA toolkit path for native and extension builds | @@ -282,12 +294,40 @@ CMake options (`cmake -D