# sphericart
[](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 version
pip install sphericart[torch] # including also the torch bindings
pip install sphericart[jax] # JAX bindings (CPU-only)
```
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]
```
Building from source is also necessary to use sphericart's PyTorch GPU
functionalities, and it requires a CUDA compiler.
### 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
### 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).
Raw data
{
"_id": null,
"home_page": null,
"name": "sphericart",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "spherical harmonics",
"author": "Filippo Bigi, Guillaume Fraux, Nicholas Browning, Michele Ceriotti",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/f6/c8/d1f01bb72558ce56c0d631f21069003fc1b228c9d4f753e0d9c33e93bcf4/sphericart-1.0.0.tar.gz",
"platform": null,
"description": "# sphericart\n\n[](https://github.com/lab-cosmo/sphericart/actions/workflows/tests.yml)\n\nThis is sphericart, a multi-language library for the efficient calculation of real\nspherical harmonics and their derivatives in Cartesian coordinates.\n\nFor instructions and examples on the usage of the library, please refer to our\n[documentation](https://sphericart.readthedocs.io/en/latest/).\n\n<p align=\"center\">\n <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%\">\n</p>\n\nIf you are using sphericart for your academic work, you can cite it as\n\n```\n@article{sphericart,\n title={Fast evaluation of spherical harmonics with sphericart},\n author={Bigi, Filippo and Fraux, Guillaume and Browning, Nicholas J. and Ceriotti, Michele},\n journal={J. Chem. Phys.},\n year={2023},\n number={159},\n pages={064802},\n}\n```\n\nThis 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.\n\n## Installation\n\n### Python\n\nPre-built (https://pypi.org/project/sphericart/).\n\n```bash\npip install sphericart # numpy version\npip install sphericart[torch] # including also the torch bindings\npip install sphericart[jax] # JAX bindings (CPU-only)\n```\n\nNote that the pre-built packages are compiled for a generic CPU, and might be\nless performant than they could be on a specific processor. To generate\nlibraries that are optimized for the target system, you can build from source:\n\n```bash\ngit clone https://github.com/lab-cosmo/sphericart\npip install .\n\n# if you also want the torch bindings (CPU and GPU)\npip install .[torch]\n\n# torch bindings, CPU-only version\npip install --extra-index-url https://download.pytorch.org/whl/cpu .[torch]\n```\n\nBuilding from source is also necessary to use sphericart's PyTorch GPU \nfunctionalities, and it requires a CUDA compiler.\n\n### Julia \n\nA native Julia implementation of `sphericart` is provided, called `SpheriCart`. \nInstall the package by opening a REPL, switch to the package manager by \ntyping `]` and then `add SpheriCart`. \nSee [julia/README.md](julia/README.md) for usage.\n\n\n### C and C++\n\nFrom source\n\n```bash\ngit clone https://github.com/lab-cosmo/sphericart\ncd sphericart\n\nmkdir build && cd build\n\ncmake .. <cmake configuration options>\ncmake --build . --target install\n```\n\nThe following cmake configuration options are available:\n- `-DSPHERICART_BUILD_TORCH=ON/OFF`: build the torch bindings in addition to the main library\n- `-DSPHERICART_BUILD_TESTS=ON/OFF`: build C++ unit tests\n- `-DSPHERICART_BUILD_EXAMPLES=ON/OFF`: build C++ examples and benchmarks\n- `-DSPHERICART_OPENMP=ON/OFF`: enable OpenMP parallelism\n- `-DCMAKE_INSTALL_PREFIX=<where/you/want/to/install>` set the root path for installation\n\n\n### Running tests and documentation\n\nTests and the local build of the documentation can be run with `tox`.\nThe default tests, which are also run on the CI, can be executed by simply running\n\n```bash\ntox\n```\n\nin the main folder of the repository.\n\nTo run tests in a CPU-only environment you can set the environment variable\n`PIP_EXTRA_INDEX_URL` before calling tox, e.g.\n\n```bash\nPIP_EXTRA_INDEX_URL=https://download.pytorch.org/whl/cpu tox -e docs\n```\n\nwill build the documentation in a CPU-only environment.\n\n\n## Other flavors of spherical harmonics\n\nAlthough sphericart natively calculates real solid and spherical harmonics from\nCartesian positions, it is easy to manipulate its output it to calculate complex \nspherical harmonics and/or to accept spherical coordinates as inputs. You can see\nexamples [here](https://sphericart.readthedocs.io/en/latest/spherical-complex.html).\n\n",
"bugtrack_url": null,
"license": "Apache-2.0 or MIT",
"summary": "Fast calculation of spherical harmonics",
"version": "1.0.0",
"project_urls": {
"documentation": "https://sphericart.readthedocs.io/en/latest/",
"homepage": "https://github.com/lab-cosmo/sphericart",
"repository": "https://github.com/lab-cosmo/sphericart"
},
"split_keywords": [
"spherical",
"harmonics"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "241fac69c5006b77b8492e2f55dad3c958a5b9fb1c7624e6e741d3c049c485a1",
"md5": "e273e10b9fd7879efeecce5396354410",
"sha256": "536ceb65e4a4281803b8aea6271dcc16454f8e733e9e30a42e0500faf8c0d96c"
},
"downloads": -1,
"filename": "sphericart-1.0.0-py3-none-macosx_11_0_arm64.whl",
"has_sig": false,
"md5_digest": "e273e10b9fd7879efeecce5396354410",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 155779,
"upload_time": "2025-01-27T13:08:57",
"upload_time_iso_8601": "2025-01-27T13:08:57.579429Z",
"url": "https://files.pythonhosted.org/packages/24/1f/ac69c5006b77b8492e2f55dad3c958a5b9fb1c7624e6e741d3c049c485a1/sphericart-1.0.0-py3-none-macosx_11_0_arm64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "fff516237cfa021d190e78092a1c2720a4cf144fd098121d0bfd483104a57362",
"md5": "2c742286a160a0adb707d55e91b51e0b",
"sha256": "cdddf114d2290b465221652eb7cd4283073b100616c70bc61e14df15703aca69"
},
"downloads": -1,
"filename": "sphericart-1.0.0-py3-none-macosx_11_0_x86_64.whl",
"has_sig": false,
"md5_digest": "2c742286a160a0adb707d55e91b51e0b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 175639,
"upload_time": "2025-01-27T13:08:59",
"upload_time_iso_8601": "2025-01-27T13:08:59.779132Z",
"url": "https://files.pythonhosted.org/packages/ff/f5/16237cfa021d190e78092a1c2720a4cf144fd098121d0bfd483104a57362/sphericart-1.0.0-py3-none-macosx_11_0_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "fc416ea06548cc8c362690f658e18d92bd733d1133dc4b4a8e534deb5354a810",
"md5": "4a7b1225c94c34f56decec5237c07085",
"sha256": "0263fd1e6d84f8d379791c80fd5d2070c93b6f25fc2ad0b7cd1e679ebda4fda8"
},
"downloads": -1,
"filename": "sphericart-1.0.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "4a7b1225c94c34f56decec5237c07085",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 374987,
"upload_time": "2025-01-27T13:09:01",
"upload_time_iso_8601": "2025-01-27T13:09:01.435934Z",
"url": "https://files.pythonhosted.org/packages/fc/41/6ea06548cc8c362690f658e18d92bd733d1133dc4b4a8e534deb5354a810/sphericart-1.0.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f6c8d1f01bb72558ce56c0d631f21069003fc1b228c9d4f753e0d9c33e93bcf4",
"md5": "7804ab6e8b37356694f916046418cd7e",
"sha256": "e5790e33c10460a84538ba3088b02fc5142a8af32a0c697bbad290f26f09093b"
},
"downloads": -1,
"filename": "sphericart-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "7804ab6e8b37356694f916046418cd7e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 61017,
"upload_time": "2025-01-27T13:09:26",
"upload_time_iso_8601": "2025-01-27T13:09:26.100318Z",
"url": "https://files.pythonhosted.org/packages/f6/c8/d1f01bb72558ce56c0d631f21069003fc1b228c9d4f753e0d9c33e93bcf4/sphericart-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-27 13:09:26",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "lab-cosmo",
"github_project": "sphericart",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "sphericart"
}
JSON
