Metadata-Version: 2.1
Name: pysofft
Version: 0.9.5
Summary: Complete rewrite of the C library SOFT 2.0, that computes fourier transforms on the rotation group SO(3)
Keywords: SO(3),FFT,fourier transform,SOFT
Author-Email: Tim Berberich <tim.berberich@xfel.eu>
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python :: 3 :: Only
Project-URL: Homepage, https://github.com/TimBerberich/pysofft
Requires-Python: >=3.11
Requires-Dist: numpy<3.0.0,>=2.2.0
Provides-Extra: stats
Requires-Dist: scipy>=1.13; extra == "stats"
Description-Content-Type: text/markdown

[![Lates Release](https://img.shields.io/github/v/release/European-XFEL/xframe)](https://github.com/TimBerberich/pysofft/releases)
![License](https://img.shields.io/github/license/TimBerberich/pysofft)
[![Documentation](https://img.shields.io/readthedocs/pysofft)](https://pysofft.readthedocs.io/en/latest/)
[![Documentation](https://img.shields.io/badge/documentation-online-blue)](https://pysofft.readthedocs.io/en/latest/)
![Language](https://img.shields.io/badge/language-python-blue)
![Language](https://img.shields.io/badge/language-fortran-blue)

# Fast Fourier transforms on the 3D rotation group $\mathrm{SO}(3)$
PySOFFT provides high performance routines for harmonic analysis on the 3D rotation group written in Fortran and wrapped in Python.  

$$
f:\mathrm{SO}(3) \rightarrow \mathbb{C} \quad \overset{\mathrm{PySOFFT}}{\longleftrightarrow} \quad f^l_{m,n} \text{ with } |m|,|n|\leq l<\infty
$$

## Some applications:
* Rotational alignment of datasets given by their spherical harmonic coefficients.
* Statistical analysis over SO(3).
* X-ray scattering simulations of randomly oriented particles.

## Main features:
* [__Fast__](https://pysofft.readthedocs.io/en/latest/speed/)
* __OpenMP__ routines to speed up single transforms or compute many in parallel. 
* Dedicated faster transforms for real data.
* Compute __rotational cross-correlations__.
* Built in Python wrapper.
* On-the-fly computation of Wigner matrices: saving memory.
* Documentation at [https://pysofft.readthedocs.io](https://pysofft.readthedocs.io)

## Origin
PySOFFT started as a partial python port of soft-2.0 released by Peter Kostelec and Daniel Rockmore.
Now it is an entire rewrite in Fortran featuring several improvements, e.g higher precission computation of Wigner-D matrices, OpenMP routines and convenient python wrappers.

For details on soft-2.0 see:  
FFTs on the Rotation Group  
J Fourier Anal Appl (2008) 14: 145–179  
DOI [10.1007/s00041-008-9013-5](https://doi.org/10.1007/s00041-008-9013-5) ([pdf](https://www.cs.jhu.edu/~misha/ReadingSeminar/Papers/Kostelec08.pdf))

PySOFT is made available with consent of the original soft-2.0 authors and under the same GPL3 license.

## Installation

See the [documentation](https://pysofft.readthedocs.io) for more details:

You can install PySOFT via 

`pip install pysofft`
	
The only python dependency is [__numpy__](https://numpy.org/).  
Non-python dependencies are:  [__fftw__](https://fftw.org/), [__openmp__](https://www.openmp.org/), [__meson__](https://mesonbuild.com/) and [__gcc__/__gfortran__](https://gcc.gnu.org/).  
__Note:__ If you don't have some of the non-python dependencies installed the install will fail!

### Pixi
 If you use [pixi](https://pixi.prefix.dev/latest/) you can use the following pixi.toml for installation.  
 Here you don't have to install the non-python dependencies separately.
 
  ``` toml
 [workspace]
 channels = ["conda-forge"]
 description = "Workspace for pysofft"
 name = "temp"
 platforms = ["linux-64"]
 version = "0.1.0"
 
 [system-requirements]
 libc = { family = "glibc", version = "2.34" }
 
 [dependencies]
 gfortran = ">=15.2,<15.5.0"
 gcc = ">=15.2,<15.5.0"
 cpython = ">=3.13.11,<4"
 python = ">=3.13.11,<3.14"
 pip = ">=26.0.1,<27"
 numpy = ">=2.2.6,<2.2.7"
 meson = ">=1.8.1,<1.9.0"
 meson-python = ">=0.19.0,<0.20"
 fftw = ">=3.3.10,<4"
 openmp = ">=8.0.1,<9"
 
 [pypi-dependencies]
 pysofft = ">=0.9.0, <2.0.0"
 ```
 
## Basic Usage Python
	
Forward and inverse transforms

```Python
from pysofft import Soft
bw = 64
s = Soft(bw)

# complex case: inverse then forward 
f_lmn = s.get_coeff(random=True)
f = s.isoft(f_lmn)
f_lmn2 = s.soft(f)

# real case: inverse then forward
g_lmn = s.get_coeff(real=True,random=True)
g = s.irsoft(g_lmn)
g_lmn2 = s.rsoft(g)
```
Accessing individual harmonic coefficients

```Python
from pysofft import Soft
bw = 64
s = Soft(bw)

f_lmn = s.get_coeff(random=True)

l=4
m=-1
n=2

# access single coefficient
print(f_lmn.lmn[l,m,n])

# slicing is also possible
print(f_lmn.lmn[l,m,:])

# as well as value asignment
f_lmn.lmn[l,m,:] = 1 + 1.j
```
