Metadata-Version: 2.4
Name: sphericart
Version: 2.0.1
Summary: Fast calculation of spherical harmonics
Author: Filippo Bigi, Guillaume Fraux, Nicholas Browning, Michele Ceriotti
License-Expression: Apache-2.0 OR MIT
Project-URL: homepage, https://github.com/lab-cosmo/sphericart
Project-URL: documentation, https://sphericart.readthedocs.io/en/latest/
Project-URL: repository, https://github.com/lab-cosmo/sphericart
Keywords: spherical harmonics
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: POSIX
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE-APACHE
License-File: LICENSE-MIT
License-File: LICENSE.md
Requires-Dist: numpy
Provides-Extra: torch
Requires-Dist: sphericart-torch; extra == "torch"
Provides-Extra: jax
Requires-Dist: sphericart-jax; extra == "jax"
Dynamic: license-file
Dynamic: provides-extra

# sphericart

[![Test](https://github.com/lab-cosmo/sphericart/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/lab-cosmo/sphericart/actions/workflows/tests.yml)

This is sphericart, a multi-language library for the efficient calculation of real
spherical harmonics and their derivatives in Cartesian coordinates.

For instructions and examples on the usage of the library, please refer to our
[documentation](https://sphericart.readthedocs.io/en/latest/).

<p align="center">
  <img src="./docs/src/_static/sphericart_3-0.png" alt="A plot of the +-1 isosurfaces of the Y^0\_3 solid harmonic, including also gradients." width="50%">
</p>

If you are using sphericart for your academic work, you can cite it as

```
@article{sphericart,
    title={Fast evaluation of spherical harmonics with sphericart},
    author={Bigi, Filippo and Fraux, Guillaume and Browning, Nicholas J. and Ceriotti, Michele},
    journal={J. Chem. Phys.},
    year={2023},
    number={159},
    pages={064802},
}
```

This library is dual-licensed under the Apache License 2.0 and the MIT license. You can use to use it under either of the two licenses.

## Installation

### Python

Pre-built (https://pypi.org/project/sphericart/).

```bash
pip install sphericart             # numpy interface, CPU only
pip install sphericart[torch]      # Torch (and TorchScript) interface, CPU and GPU
pip install sphericart[jax]        # JAX interface, CPU and GPU
```

Note that the pre-built packages are compiled for a generic CPU, and might be
less performant than they could be on a specific processor. To generate
libraries that are optimized for the target system, you can build from source:

```bash
git clone https://github.com/lab-cosmo/sphericart
pip install .

# if you also want the torch bindings (CPU and GPU)
pip install .[torch]

# torch bindings, CPU-only version
pip install --extra-index-url https://download.pytorch.org/whl/cpu .[torch]
```

If you want to enable the CUDA version of the code when builing from source,
you'll need to set the `CUDA_HOME` environement variable. You can build a CUDA enabled `sphericart`, but the calculations though numpy will only run on CPU.

### Julia

A native Julia implementation of `sphericart` is provided, called `SpheriCart`.
Install the package by opening a REPL, switch to the package manager by
typing `]` and then `add SpheriCart`.
See [julia/README.md](julia/README.md) for usage.


### C and C++

From source

```bash
git clone https://github.com/lab-cosmo/sphericart
cd sphericart

mkdir build && cd build

cmake .. <cmake configuration options>
cmake --build . --target install
```

The following cmake configuration options are available:
- `-DSPHERICART_BUILD_TORCH=ON/OFF`: build the torch bindings in addition to the main library
- `-DSPHERICART_BUILD_TESTS=ON/OFF`: build C++ unit tests
- `-DSPHERICART_BUILD_EXAMPLES=ON/OFF`: build C++ examples and benchmarks
- `-DSPHERICART_OPENMP=ON/OFF`: enable OpenMP parallelism
- `-DCMAKE_INSTALL_PREFIX=<where/you/want/to/install>` set the root path for installation

### GPU Support

The support for GPU offload could be controled with the following CMake variables at configuration:

- `-DSPHERICART_ENABLE_CUDA=ON/OFF`: build with CUDA support also set `CUDA_HOME` environement variable.
- `-DSPHERICART_ENABLE_SYCL=ON/OFF`: build with SYCL support, configure tool will search for `sycl/sycl.h` header.
- `-DSPHERICART_SYCL_DEVICE=all/cpu/gpu`: target architecute for SYCL support, check which devices are available with `sycl-ls`, for `all` (default) is possible to control at execution with `export ONEAPI_DEVICE_SELECTOR=opencl:gpu` or `export ONEAPI_DEVICE_SELECTOR=opencl:cpu`.

The following flags have been tested with Intel OneAPI 2025.3 for enabling SYCL support:
- `-DCMAKE_CXX_COMPILER=icpx`
- `-DCMAKE_C_COMPILER=icx`
- `-DCMAKE_CXX_FLAGS=" -qopenmp --intel -fsycl  -fsycl-targets=spir64 -Wno-deprecated-declarations -Wno-macro-redefined -Wno-unused-parameter -w"`

**Note**: Only tested in C++, python/JAX/Torch support is in progress.

### Running tests and documentation

Tests and the local build of the documentation can be run with `tox`.
The default tests, which are also run on the CI, can be executed by simply running

```bash
tox
```

in the main folder of the repository.

To run tests in a CPU-only environment you can set the environment variable
`PIP_EXTRA_INDEX_URL` before calling tox, e.g.

```bash
PIP_EXTRA_INDEX_URL=https://download.pytorch.org/whl/cpu tox -e docs
```

will build the documentation in a CPU-only environment.


## Other flavors of spherical harmonics

Although sphericart natively calculates real solid and spherical harmonics from
Cartesian positions, it is easy to manipulate its output it to calculate complex
spherical harmonics and/or to accept spherical coordinates as inputs. You can see
examples [here](https://sphericart.readthedocs.io/en/latest/spherical-complex.html).


## Maintainers

This project is [maintained](https://github.com/lab-cosmo/.github/blob/main/Maintainers.md) by [@frostedoyster](https://github.com/frostedoyster) and [@Luthaf](https://github.com/Luthaf). The maintainers will reply to issues and pull requests opened on this repository as soon as possible. You can mention them directly if you have not received an answer after a couple of days.
