perm-rs 0.1.3

Rust-accelerated permanent computation library.

perm-rs

This library contains a Rust re-implementation of the permanent calculation function from the thewalrus module, using maturin and PyO3 to then make this callable from Python. This is then extended to support calculation across multiple processes, which offers signifcant performance improvements at large matrix sizes.

The library is mainly intended for testing how rust-enhanced modules can be developed for Python and then distributed via pypi to different platforms.

License

This software is distributed under the terms of both MIT and Apache-2.0 licenses. The permanent implementation in src/permanent.py is derrived from Apache-2.0 licensed code. See Notice for more information.

Install

Rust must first be installed if not already, the instructions for which can be found here.

Maturin is then utilised for building the rust code and generating Python bindings, this requires a virtual or conda environment. All requirements, including maturin, may be installed using the below command. This requires pip 25.1 - use pip install pip --upgrade to update to this.

(venv) pip install --group dev

Once installed, the library is built using:

(venv) maturin develop

For optimal performance, it should be built with the release profile:

(venv) maturin develop --release

UV

uv can alternatively be utilised to simplify the above process. The command uv sync will install all requirements into a virtual environment and build the library in release mode.

Benchmarking

The performance of the library can be benchmarked against thewalrus implementation using the following command:

pytest benchmark

Alternatively, a more comprehensive set of matrix sizes can be compared using the script in benchmark/generate_figure.py, also comparing the single and multi-threaded approaches. The following is the output comparison between the two libraries when run using a AMD Ryzen 9 9950x3D CPU:

There are two current trends to observe from this:

• The single-threaded case is faster than thewalrus for small matrix sizes, but trends towards similar runtimes for large n.
• The multi-threaded case is much slower at large n, due to the overhead from this which sets the minimum time to be ~1ms, but after passing a threshold at n ~ 17 becomes much faster than both thewalrus and single-threaded implementations. The optimised case shown here, is using the permanent function, which automatically selects between single & multi-threaded, based on the size of the provided unitary. This will likely not be optimal for all CPUs, but should be close enough that performance degredation is not too significant. If required, the value for which the function switches between single and multi-threading can be modified using perm_rs.settings.multi_threading_threshold.

Plotting the relative performance of the library against thewarlus makes the above performance trends even clearer: