Skip to main content

Compute Wigner 3j and Clebsch-Gordan coefficients

Project description

Calculation of Wigner symbols and related constants

This package computes Wigner 3j coefficients and Clebsch-Gordan coefficients in pure Rust. The calculation is based on the prime factorization of the different factorials involved in the coefficients, keeping the values in a rational root form (sign * \sqrt{s / n}) for as long as possible. This idea for the algorithm is described in:

H. T. Johansson and C. Forssén, SIAM Journal on Scientific Compututing 38 (2016) 376-384

This implementation takes a lot of inspiration from the WignerSymbols Julia implementation (and even started as a direct translation of it), many thanks to them! This package is available under the same license as the Julia package.

Usage

From python

pip install wigners

And then call one of the exported function:

import wigners

w3j = wigners.wigner_3j(j1, j2, j3, m1, m2, m3)

cg = wigners.clebsch_gordan(j1, m1, j2, m1, j3, m3)

# full array of Clebsch-Gordan coefficients, computed in parallel
cg_array = wigners.clebsch_gordan_array(ji, j2, j3)

# we have an internal cache for recently computed CG coefficients, if you
# need to clean it up you can use this function
wigners.clear_wigner_3j_cache()

From rust

Add this crate to your Cargo.toml dependencies section:

wigners = "0.3"

And then call one of the exported function:

let w3j = wigners::wigner_3j(j1, j2, j3, m1, m2, m3);

let cg = wigners::clebsch_gordan(j1, m1, j2, m1, j3, m3);

wigners::clear_wigner_3j_cache();

Limitations

Only Wigner 3j symbols for full integers (no half-integers) are implemented, since that's the only part I need for my own work.

6j and 9j symbols can also be computed with this approach; and support for half-integers should be feasible as well. I'm open to pull-request implementing these!

Benchmarks

This benchmark measure the time to compute all possible Wigner 3j symbols up to a fixed maximal angular momentum; clearing up any cached values from previous angular momentum before starting the loop. In pseudo code, the benchmark looks like this:

if cached_wigner_3j:
    clear_wigner_3j_cache()

# only measure the time taken by the loop
start = time.now()
for j1 in range(max_angular):
    for j2 in range(max_angular):
        for j3 in range(max_angular):
            for m1 in range(-j1, j1 + 1):
                for m2 in range(-j2, j2 + 1):
                    for m3 in range(-j3, j3 + 1):
                        w3j = wigner_3j(j1, j2, j3, m1, m2, m3)

elapsed = start - time.now()

Here are the results on an Apple M1 Max (10 cores) CPU, against a handful of other libraries:

code & version max_angular=4 8 12 16 20
wigners (this) 0.190 ms 4.60 ms 36.5 ms 172 ms 572 ms
wigner-symbols v0.5 6.00 ms 181 ms 1.53 s 7.32 s /
WignerSymbols.jl v2.0 1.09 ms 21.1 ms 179 ms 902 ms 3.09 s
wigxjpf v1.11 0.237 ms 7.65 ms 68.3 ms 342 ms 1.24 s
0382/WignerSymbol vf8c8dce 0.070 ms 2.26 ms 19.3 ms 93.5 ms 320 ms
sympy v1.11 24.8 ms 1.15 s 20.8 s / /

A second set of benchmarks checks computing Wigner symbols for large j, with the corresponding m varying from -10 to 10, i.e. in pseudo code:

if cached_wigner_3j:
    clear_wigner_3j_cache()

# only measure the time taken by the loop
start = time.now()
for m1 in range(-10, 10 + 1):
    for m2 in range(-10, 10 + 1):
        for m3 in range(-10, 10 + 1):
            w3j = wigner_3j(j1, j2, j3, m1, m2, m3)

elapsed = start - time.now()
code & version j1=300, j2=100, j3=250
wigners (this) 29.2 ms
wigner-symbols v0.5 13.8 ms
WignerSymbols.jl v2.0 11.5 ms
wigxjpf v1.11 7.45 ms
0382/WignerSymbol vf8c8dce / (wrong result)
sympy v1.11 2.34 s

To run the benchmarks yourself on your own machine, execute the following commands:

cd benchmarks
cargo bench # this gives the results for wigners, wigner-symbols, wigxjpf and 0382/WignerSymbol

python sympy-bench.py # this gives the results for sympy

julia wigner-symbol.jl # this gives the results for WignerSymbols.jl

Comparison to wigner-symbols

There is another Rust implementation of wigner symbols: the wigner-symbols crate. wigner-symbols also implements 6j and 9j symbols, but it was not usable for my case since it relies on rug for arbitrary precision integers and through it on the GMP library. The GMP library might be problematic for you for one of these reason:

  • it is relatively slow (see the benchmarks above)
  • it is distributed under LGPL (this crate is distributed under Apache/MIT);
  • it is written in C and C++; and as such is hard to cross-compile or compile to WASM;
  • it does not support the MSVC compiler on windows, only the GNU compilers

As you can see in the benchmarks above, this usage of GMP becomes an advantage for large j, where the algorithm used in this crate does not scale as well.

License

This crate is distributed under both the MIT license and the Apache 2.0 license.

Project details


Download files

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

Source Distribution

wigners-0.3.1.tar.gz (24.1 kB view details)

Uploaded Source

Built Distributions

wigners-0.3.1-py3-none-win_amd64.whl (164.9 kB view details)

Uploaded Python 3Windows x86-64

wigners-0.3.1-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (1.1 MB view details)

Uploaded Python 3manylinux: glibc 2.17+ x86-64

wigners-0.3.1-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (304.2 kB view details)

Uploaded Python 3manylinux: glibc 2.17+ ARM64

wigners-0.3.1-py3-none-macosx_11_0_x86_64.whl (272.1 kB view details)

Uploaded Python 3macOS 11.0+ x86-64

wigners-0.3.1-py3-none-macosx_11_0_arm64.whl (263.6 kB view details)

Uploaded Python 3macOS 11.0+ ARM64

File details

Details for the file wigners-0.3.1.tar.gz.

File metadata

  • Download URL: wigners-0.3.1.tar.gz
  • Upload date:
  • Size: 24.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.12.8

File hashes

Hashes for wigners-0.3.1.tar.gz
Algorithm Hash digest
SHA256 90882e69208a830140a244645e39d4c3a84b8db1a4feb926ba29d0cc374ac149
MD5 5c3d72e64fc6c189c5a506f5a8e10424
BLAKE2b-256 fd2334ab7e82cf19cfc7130e0a5de265bccadbb85fd73dd8bc853f8628d187fb

See more details on using hashes here.

File details

Details for the file wigners-0.3.1-py3-none-win_amd64.whl.

File metadata

  • Download URL: wigners-0.3.1-py3-none-win_amd64.whl
  • Upload date:
  • Size: 164.9 kB
  • Tags: Python 3, Windows x86-64
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.12.8

File hashes

Hashes for wigners-0.3.1-py3-none-win_amd64.whl
Algorithm Hash digest
SHA256 33339221391fabc187dbe74bdee78106852e3f002a5f910fc5d9ba564f4cceb8
MD5 1d3e38d4c9777f79ce1b0322b90033e0
BLAKE2b-256 756102d69ad90dfade6440f05dc92cddd4c8009db4d20b5114dc0db963ec0e94

See more details on using hashes here.

File details

Details for the file wigners-0.3.1-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for wigners-0.3.1-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 d19d81a7665cfea85f829ff1366330e7ca602e9330f03bf12b036021e290ce47
MD5 a3679ce4d9102c90cfbded158f041c2b
BLAKE2b-256 e73fd022d7dcd360eb0cd4cd15c07446539eea593e7c53bfc252e2c15ec297c8

See more details on using hashes here.

File details

Details for the file wigners-0.3.1-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for wigners-0.3.1-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 8fcf25cbbd3ad9fb0959d8311dcec53163da3f2b8fad35789a7c4d9deb0f8eea
MD5 4b383fba372efe646f81a0e05fba8815
BLAKE2b-256 55c4812f351bef5aff78bc103c10354a8e34f87294b037d4b799f9ed8538890d

See more details on using hashes here.

File details

Details for the file wigners-0.3.1-py3-none-macosx_11_0_x86_64.whl.

File metadata

File hashes

Hashes for wigners-0.3.1-py3-none-macosx_11_0_x86_64.whl
Algorithm Hash digest
SHA256 4d32371c14301cdd0886e1c513fffdcb15e5b6c79b2ff0f6735f1d9611007ce9
MD5 cc85042ce92f505828762824a9c57a71
BLAKE2b-256 3d77bae16eb22f7ec3bb2bbd397bc757d15861ae6ef264961a7de1c91f9c9074

See more details on using hashes here.

File details

Details for the file wigners-0.3.1-py3-none-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for wigners-0.3.1-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 ec1b7458f777faa5107a9832966091aa664373d62be551aad493927ba1e19d31
MD5 25929093b94627ad12274655b2590c57
BLAKE2b-256 6a2d81a167d21433816f8c422087fd1331fa654d568298131407d83929344d55

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page