feral-solver

Python bindings for feral, a pure-Rust sparse symmetric indefinite direct solver with certified inertia counts. Aimed at interior-point methods (the IPM in discopt is the primary consumer), but usable for any application that factors symmetric KKT-shaped systems.

Install

pip install feral-solver           # plain
pip install 'feral-solver[scipy]'  # with scipy.sparse adapters
uv add feral-solver                # via uv

Wheels are published for CPython 3.10+ on Linux x86_64/aarch64, macOS universal2, and Windows x86_64. abi3 means one wheel per platform/arch covers all supported Python minor versions.

Quickstart

import numpy as np
import feral

A = feral.CscMatrix.from_dense(np.array([
    [4.0, 1.0, 0.0],
    [1.0, 3.0, 2.0],
    [0.0, 2.0, 5.0],
]))

solver = feral.Solver()
status, inertia = solver.factor(A)
assert status == feral.FactorStatus.SUCCESS
print(inertia)                       # Inertia(n_pos=3, n_neg=0, n_zero=0)

b = np.array([1.0, 2.0, 3.0])
x = solver.solve(b)
print(np.allclose(A.symv(x), b))     # True

IPM use

The feral.ipm.KktSolver class wraps Solver with the Wächter–Biegler 2006 §3.1 perturbation-escalation loop. Symbolic analysis is cached; across an entire Newton run solver.symbolic_call_count stays at 1.

import feral
import feral.ipm

kkt_pattern = feral.CscMatrix.from_scipy(my_kkt)   # see scipy adapter
kkt = feral.ipm.KktSolver(
    kkt_pattern,
    expected_inertia=feral.Inertia(n_vars, n_equality_constraints),
)
for newton_iter in range(max_iter):
    report = kkt.factor(values_this_iter)          # auto-perturbs if needed
    if report.status != feral.FactorStatus.SUCCESS:
        break
    dx_aff, dx_corr = kkt.solve_pair(b_aff, b_corr)
    ...

See examples/discopt_ipm_kkt.py for an end-to-end Newton step against a small NLP.

Unsymmetric LU basis engine

LuFactor factors a general square matrix and solves A x = b (ftran) / Aᵀ y = c (btran), with simplex-style product-form updates. It auto-routes to a dense or sparse engine via the same should_use_dense_lu heuristic the Rust core uses; pass force_dense=True/False to override.

import numpy as np
import feral

A = np.array([[2.0, 1.0, 0.0], [0.0, 3.0, 1.0], [1.0, 0.0, 4.0]])
lu = feral.LuFactor(feral.LuMatrix.from_dense(A))
x = lu.ftran(np.array([1.0, 2.0, 3.0]))     # solve A x = b
y = lu.btran(np.array([1.0, 0.0, 0.0]))     # solve Aᵀ y = c
lu.update(1, np.array([0.0, 5.0, 1.0]))     # replace basis column 1
# P A Q = L U :  A[perm][:, qcol] == l_array() @ u_array()

A singular basis raises SingularBasisError (a FactorError); an exhausted update budget raises NeedsRefactorError — call lu.refactor(new_matrix).

Factor access and introspection

After Solver.factor, the assembled factor and its statistics are available without re-solving:

s = feral.Solver(ordering="amd", profiling=True)
s.factor(A_csc)

fac = s.factors()                  # Factors snapshot
indptr, indices, data = fac.l_csc()   # unit-lower L as CSC (factorization order)
d_diag, d_subdiag = fac.d_blocks()    # block-diagonal D (2×2 where d_subdiag != 0)
L_scipy = fac.to_scipy_l()            # optional scipy.sparse.csc_matrix

# Reconstruction identity (factorization order):
#   L @ D @ L.T  ==  P (S A S) Pᵀ
# with fac.perm and the per-row fac.scaling vector.

stats = s.last_factor_stats()      # nnz, fill_ratio, inertia, pivot range, ...
print(s.min_pivot_magnitude, s.max_pivot_magnitude)
print(s.scaling_info.kind)         # "applied" | "mc64_fallback_to_infnorm" | ...
print(s.profile_report())          # populated when profiling=True

Solver.symbolic() (and the standalone feral.analyze(A_csc, ordering=...), which runs no numeric factorization) return a SymbolicAnalysis with the resolved ordering, perm/perm_inv, num_supernodes, factor_nnz_estimate, col_counts, and the elimination-tree etree_parent array (roots marked -1).

New Solver(...) keyword arguments — all optional, defaulting to the prior behavior — expose the tuning knobs: ordering ("amd", "amf", "metis", "scotch", "kahip", "auto", "auto_race"), mc64_cache, profiling, partial_singular_warning, and auto_cascade_break.

Conversion conveniences

CscMatrix.to_dense() returns the full symmetric matrix as a 2-D numpy array; CscMatrix.from_dense(a, triangle="lower"|"upper"|"full") ingests either triangle; CscMatrix.symmetric_pattern() returns the full (indptr, indices) structural pattern.

Example notebooks

Runnable notebooks live in examples/notebooks/. Regenerate them from the reviewable _build_notebooks.py generator: python _build_notebooks.py re-executes each notebook and commits its cell outputs (the embedded assertions double as a smoke test), or pass --no-execute for source-only .ipynb when feral is not installed in the running interpreter.

  • 01_basic_factor_solve — factor, certified inertia, solve, refine, reuse.
  • 02_multi_rhs_batched — batched multi-RHS solve, motivated by a steady-state heat-conduction sweep, with a correctness check and a looped-vs-batched timing showing the per-RHS speedup (issue #57).
  • 03_kkt_saddle_inertia — indefinite KKT system with certified inertia.
  • 04_scipy_numpy_interop — scipy.sparse round-trip vs spsolve.
  • 05_lu_and_introspection — the LU basis engine (ftran/btran, product-form updates, P A Q = L U), factor access (L/D reconstruction, feral.analyze), and introspection (knobs, factor stats, pivot range, scaling info) added in 0.11.0.

scipy.sparse interop

import scipy.sparse as sp
import feral

A_scipy = sp.csc_matrix(...)
A = feral.from_scipy(A_scipy, symmetric="full")    # reads lower triangle
# ... factor, solve ...
A_back = feral.to_scipy(A)                          # round-trips to scipy

Building from source

Requires a stable Rust toolchain (1.75+) and Python 3.10+.

git clone https://github.com/jkitchin/feral.git
cd feral/python
pip install maturin
maturin develop --release    # builds and installs into current venv
pytest tests/

License

MIT, same as the underlying Rust crate.

Project links

Data verified by PyPI on Aug 14, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.17.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for jkitchin from gravatar.com jkitchin

Credits

Author: John Kitchin

GitHub Statistics

Data verified by PyPI on Aug 14, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

MIT License (MIT)

Requires

Python >=3.10

Provides Extra

dev jax scipy test

Tags

sparse solver linear-algebra ldlt kkt interior-point

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

feral_solver-0.16.0.tar.gz (966.0 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

feral_solver-0.16.0-cp310-abi3-win_amd64.whl (875.4 kB view details)

Uploaded CPython 3.10+Windows x86-64

feral_solver-0.16.0-cp310-abi3-manylinux_2_28_aarch64.whl (882.6 kB view details)

Uploaded CPython 3.10+manylinux: glibc 2.28+ ARM64

feral_solver-0.16.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (968.7 kB view details)

Uploaded CPython 3.10+manylinux: glibc 2.17+ x86-64

feral_solver-0.16.0-cp310-abi3-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl (1.7 MB view details)

Uploaded CPython 3.10+macOS 10.12+ universal2 (ARM64, x86-64)macOS 10.12+ x86-64macOS 11.0+ ARM64

File details

Details for the file feral_solver-0.16.0.tar.gz.

File metadata

  • Download URL: feral_solver-0.16.0.tar.gz
  • Upload date:
  • Size: 966.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for feral_solver-0.16.0.tar.gz
Algorithm Hash digest
SHA256 751e7db27c690c6e0186a02ab1663eaf8667eae860136b6a6c17890ad56caa8c
MD5 c5d425b7fd36c143d684511aa216f83c
BLAKE2b-256 68e41e124a5d04f3b18c1916e0336f3dcce3ff7b5caeb347497ff4b2d6ad1b39

See more details on using hashes here.

Provenance

The following attestation bundles were made for feral_solver-0.16.0.tar.gz:

Publisher: python-wheels.yml on jkitchin/feral

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file feral_solver-0.16.0-cp310-abi3-win_amd64.whl.

File metadata

File hashes

Hashes for feral_solver-0.16.0-cp310-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 e1ba1ae45db672cfc4389491e8b0bbee885435b86f2c7141e78ab1445ee1084d
MD5 5dedc6c0ed5c4226bcab8442ff502a13
BLAKE2b-256 94a5bb8411927351c70bde25d2aceaeedd80d94c51f675240ee4725163f0d171

See more details on using hashes here.

Provenance

The following attestation bundles were made for feral_solver-0.16.0-cp310-abi3-win_amd64.whl:

Publisher: python-wheels.yml on jkitchin/feral

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file feral_solver-0.16.0-cp310-abi3-manylinux_2_28_aarch64.whl.

File metadata

File hashes

Hashes for feral_solver-0.16.0-cp310-abi3-manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 9c28d61af645da915d07ed9c9c8f9fd2c6e42f22f0ba02b80e37c372b8f70bf4
MD5 4352781b92888e2e9c63394ebb912736
BLAKE2b-256 f61bdb878b25a7b09e5ff4e525437e2204bb32786e2f51e129996ac14332e2d8

See more details on using hashes here.

Provenance

The following attestation bundles were made for feral_solver-0.16.0-cp310-abi3-manylinux_2_28_aarch64.whl:

Publisher: python-wheels.yml on jkitchin/feral

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file feral_solver-0.16.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for feral_solver-0.16.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 df0cfdbb6f9dadf75c78aa66a312296f9ef0330e995ff5eb94457bf052ce8db5
MD5 deec44d400a8d83a959cd29ee83e4b17
BLAKE2b-256 caa7e163494ebf6a9ccfb52cc7e736f5238533d8734c9a34a94ba94d3fe6cb1c

See more details on using hashes here.

Provenance

The following attestation bundles were made for feral_solver-0.16.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: python-wheels.yml on jkitchin/feral

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file feral_solver-0.16.0-cp310-abi3-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl.

File metadata

File hashes

Hashes for feral_solver-0.16.0-cp310-abi3-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl
Algorithm Hash digest
SHA256 d989f66662cd088f16597323c52d0a2f70cf7c6666948d3bdbd2427b9903d2bb
MD5 dd92953679f00f4472ba07874966966c
BLAKE2b-256 b9f9f6e1e59964c2c3bce74be210240165a19fe9ca4b067488854904e45bc634

See more details on using hashes here.

Provenance

The following attestation bundles were made for feral_solver-0.16.0-cp310-abi3-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl:

Publisher: python-wheels.yml on jkitchin/feral

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.17.0

5 files

This release

0.16.0 This release

5 files

0.15.1

5 files

0.15.0

5 files

0.14.0

5 files

0.13.0

5 files

0.12.0

5 files

0.11.3

5 files

0.11.2

5 files

0.11.1

5 files

0.11.0

5 files

0.10.0

5 files

0.9.0

5 files

0.8.0

5 files

0.7.0

5 files

0.6.0

5 files

0.5.0

5 files

0.4.0

5 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page