# soprano
Soprano - a Python library to crack crystals!
[](https://github.com/CCP-NC/soprano/actions/workflows/python-test.yml)
[](https://badge.fury.io/py/Soprano)
## Introduction
Soprano is a Python library developed and maintained by the CCP for NMR Crystallography as a tool to help scientists
working with crystallography and simulations to generate, manipulate, run calculations on and analyse large data sets of
crystal structures, with a particular attention to the output of ab-initio random structure searching, or [AIRSS](https://www.mtg.msm.cam.ac.uk/Codes/AIRSS). It provides a number of functionalities to help automate many common tasks in computational crystallography.
## How to install
Soprano is now available on the Python Package Index. You can install the latest stable release by using `pip`:
pip install soprano
This will install Soprano with the latest available versions of ASE and NumPy.
### Installation Options
#### Installing with the latest ASE from git (recommended for magres files with CIF-style labels)
ASE versions 3.23 to 3.25 cannot read magres files with CIF-style labels due to a regression. This will be fixed in ASE 3.26 when it is released. Until then, you can install Soprano together with the latest development version of ASE from git:
pip install soprano git+https://gitlab.com/ase/ase.git@master
This will ensure full compatibility with magres files using CIF-style labels.
#### For Legacy Systems
If you need compatibility with older systems, you can use the legacy installation which pins ASE to version < 3.23 and NumPy to <2.0:
pip install soprano[legacy]
**Note:** This is useful for environments where you need more controlled dependency versions.
### Development Installation
To get the latest development version (not guaranteed to be stable) from GitHub:
git clone https://github.com/CCP-NC/soprano.git
cd soprano
pip install -e .
For development purposes, install additional tools:
pip install -e ".[dev]"
This installs Soprano in development mode, where changes to the code take effect immediately without reinstallation. The `dev` option includes tools for code formatting, linting, and testing. It also includes the latest development version of ASE from git, which is necessary for reading MAGRES files with CIF-style labels.
You can also combine installation options. For example, to install the development version with the docs dependencies:
pip install -e ".[dev,docs]"
This installs Soprano in development mode with additional dependencies for building documentation.
These approaches should work even on machines without admin privileges (such as HPC clusters), as long as Python and `pip` are present. You can also use the `--user` flag with `pip` to install packages for your user account only.
## Requirements
Soprano's dependencies are automatically handled by `pip` during installation. The core requirements include:
* [NumPy](http://www.numpy.org/)
* [SciPy](https://www.scipy.org/)
* [ASE](https://wiki.fysik.dtu.dk/ase/) (Atomic Simulation Environment)
* [Pandas](https://pandas.pydata.org/) (≥2.0)
* [Matplotlib](https://matplotlib.org/)
* [Spglib](https://spglib.github.io/spglib/) (≥2.4)
* [Pydantic](https://docs.pydantic.dev/) (≥2.0)
* [Click](https://click.palletsprojects.com/) (for CLI functionality)
* [Bottleneck](https://pypi.org/project/Bottleneck/) (≥1.3.6)
* [adjustText](https://github.com/Phlya/adjustText)
Additional, optional dependencies are available through feature sets:
* **docs**: Dependencies for building documentation (`jupyter-book`, `sphinx-click`, etc.)
* **dev**: Dependencies for development (`black`, `flake8`, `pytest`, etc.)
* **legacy**: Pinned versions of ASE and NumPy for compatibility with older systems
## Testing
Soprano uses `pytest` for testing and `hatch` for environment management. To run the test suite:
```bash
# Install hatch first if you don't have it
pip install hatch
# Run tests with the default dev environment
hatch run test:test
# Run tests with legacy dependencies
hatch run legacy:test
# For more verbose output
hatch run test:test -v
# To run tests without the latest ASE (if you have issues with it)
hatch run test:test-no-git
```
For contributors running tests locally with GitHub Actions, consider using [Act](https://github.com/nektos/act).
## Getting started
Soprano ships with several Jupyter notebooks that illustrate its core functionality and how to use it. Being familiar with the use of `ase` - the Atomic Simulation Environment - is a good starting point. To use Jupyter notebooks you only need to have Jupyter installed, then launch the notebook server in the tutorials folder:
pip install jupyter
cd tutorials
jupyter notebook
Additional information is available in the auto-generated documentation in the docs folder, and the same information can be retrieved by using the Python `help` function.
## Functionality
Here we show a basic rundown - not by any means exhaustive - of Soprano functionality and features.
### Mass manipulation of structure datasets with AtomsCollection
The AtomsCollection class generalises ASE's Atoms class by treating groups of structures together and making it easier to retrieve information about all of them at once. Combined with the large number of AtomProperties, which extract chemical and structural information and more, it provides a simple, powerful tool to look quickly at the results of an AIRSS search.
### Accurate treatment of periodic boundaries
Many functions in Soprano require to compute interatomic distances, such as when computing bonds, or estimating NMR dipolar couplings. Soprano always takes the utmost care in dealing with periodic boundaries, using algorithms that ensure that the closest periodic copies are always properly accounted for in a fast and efficient way. This approach can also be used in custom functions as the algorithm can be found in the function `soprano.utils.minimum_periodic`.
### Easy processing of NMR parameters and spectral simulations
ASE can read NMR parameters in the `.magres` file format, but Soprano can turn them to more meaningful physical quantities such as isotropies, anisotropies and asymmetries. In addition, with a full database of NMR active nuclei, Soprano can compute quadrupolar and dipolar couplings for specific isotopes. Finally, Soprano can produce a fast approximation of a powder spectrum - both MAS and static - in the diluted atoms approximation, or if that is not enough for your needs, provide an interface to NMR simulation software [Simpson](https://inano.au.dk/about/research-centers-and-projects/nmr/software/simpson).
### Machine learning and phylogenetic analysis
The `soprano.analyse.phylogen` module contains functionality to classify collections of structures based on relevant parameters of choice and identify similarities and patterns using Scipy's hierarchy and k-means clustering algorithms. This can be of great help when analysing collections of potential crystal structure looking for polymorphs, finding defect sites, or analysing disordered systems.
### HPC Submitters
Soprano provides a Submitter class, which can be inherited from by people with some experience in Python coding to create their own scripts running as background processes and able to process large amounts of calculations automatically. Files can be copied, sent to remote HPC machines, submitted for calculations to any of the major queue managing systems, and then downloaded back to the local machine - all or just the significant results, if space is an issue. While not the most user-friendly functionality provided by Soprano, Submitters have the potential to be extremely powerful tools that can save a lot of time when working with large batches of computations.
Raw data
{
"_id": null,
"home_page": null,
"name": "Soprano",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "ccpnc, computational chemistry, crystallography",
"author": null,
"author_email": "Simone Sturniolo <simone.sturniolo@stfc.ac.uk>, \"J. Kane Shenton\" <kane.shenton@stfc.ac.uk>",
"download_url": "https://files.pythonhosted.org/packages/63/0d/2564b72f3dfc65f06a278aebcc5921ec4e7cb0948b4a5a855fb6f924c1d3/soprano-0.10.1.tar.gz",
"platform": null,
"description": "# soprano\nSoprano - a Python library to crack crystals!\n\n[](https://github.com/CCP-NC/soprano/actions/workflows/python-test.yml)\n[](https://badge.fury.io/py/Soprano)\n\n## Introduction\nSoprano is a Python library developed and maintained by the CCP for NMR Crystallography as a tool to help scientists\nworking with crystallography and simulations to generate, manipulate, run calculations on and analyse large data sets of\ncrystal structures, with a particular attention to the output of ab-initio random structure searching, or [AIRSS](https://www.mtg.msm.cam.ac.uk/Codes/AIRSS). It provides a number of functionalities to help automate many common tasks in computational crystallography.\n\n## How to install\nSoprano is now available on the Python Package Index. You can install the latest stable release by using `pip`:\n\n pip install soprano\n\nThis will install Soprano with the latest available versions of ASE and NumPy.\n\n### Installation Options\n\n#### Installing with the latest ASE from git (recommended for magres files with CIF-style labels)\nASE versions 3.23 to 3.25 cannot read magres files with CIF-style labels due to a regression. This will be fixed in ASE 3.26 when it is released. Until then, you can install Soprano together with the latest development version of ASE from git:\n\n pip install soprano git+https://gitlab.com/ase/ase.git@master\n\nThis will ensure full compatibility with magres files using CIF-style labels.\n\n\n#### For Legacy Systems\nIf you need compatibility with older systems, you can use the legacy installation which pins ASE to version < 3.23 and NumPy to <2.0:\n\n pip install soprano[legacy]\n\n**Note:** This is useful for environments where you need more controlled dependency versions.\n\n\n\n### Development Installation\nTo get the latest development version (not guaranteed to be stable) from GitHub:\n\n git clone https://github.com/CCP-NC/soprano.git\n cd soprano\n pip install -e .\n\nFor development purposes, install additional tools:\n\n pip install -e \".[dev]\"\n\nThis installs Soprano in development mode, where changes to the code take effect immediately without reinstallation. The `dev` option includes tools for code formatting, linting, and testing. It also includes the latest development version of ASE from git, which is necessary for reading MAGRES files with CIF-style labels. \n\nYou can also combine installation options. For example, to install the development version with the docs dependencies:\n\n pip install -e \".[dev,docs]\"\nThis installs Soprano in development mode with additional dependencies for building documentation.\n\nThese approaches should work even on machines without admin privileges (such as HPC clusters), as long as Python and `pip` are present. You can also use the `--user` flag with `pip` to install packages for your user account only.\n\n## Requirements\nSoprano's dependencies are automatically handled by `pip` during installation. The core requirements include:\n\n* [NumPy](http://www.numpy.org/)\n* [SciPy](https://www.scipy.org/)\n* [ASE](https://wiki.fysik.dtu.dk/ase/) (Atomic Simulation Environment)\n* [Pandas](https://pandas.pydata.org/) (\u22652.0)\n* [Matplotlib](https://matplotlib.org/)\n* [Spglib](https://spglib.github.io/spglib/) (\u22652.4)\n* [Pydantic](https://docs.pydantic.dev/) (\u22652.0)\n* [Click](https://click.palletsprojects.com/) (for CLI functionality)\n* [Bottleneck](https://pypi.org/project/Bottleneck/) (\u22651.3.6)\n* [adjustText](https://github.com/Phlya/adjustText)\n\nAdditional, optional dependencies are available through feature sets:\n\n* **docs**: Dependencies for building documentation (`jupyter-book`, `sphinx-click`, etc.)\n* **dev**: Dependencies for development (`black`, `flake8`, `pytest`, etc.)\n* **legacy**: Pinned versions of ASE and NumPy for compatibility with older systems\n\n## Testing\n\nSoprano uses `pytest` for testing and `hatch` for environment management. To run the test suite:\n\n```bash\n# Install hatch first if you don't have it\npip install hatch\n\n# Run tests with the default dev environment\nhatch run test:test\n\n# Run tests with legacy dependencies\nhatch run legacy:test\n\n# For more verbose output\nhatch run test:test -v\n# To run tests without the latest ASE (if you have issues with it)\nhatch run test:test-no-git\n```\n\n\nFor contributors running tests locally with GitHub Actions, consider using [Act](https://github.com/nektos/act).\n\n## Getting started\nSoprano ships with several Jupyter notebooks that illustrate its core functionality and how to use it. Being familiar with the use of `ase` - the Atomic Simulation Environment - is a good starting point. To use Jupyter notebooks you only need to have Jupyter installed, then launch the notebook server in the tutorials folder:\n\n pip install jupyter\n cd tutorials\n jupyter notebook\n \nAdditional information is available in the auto-generated documentation in the docs folder, and the same information can be retrieved by using the Python `help` function.\n\n## Functionality\n\nHere we show a basic rundown - not by any means exhaustive - of Soprano functionality and features.\n\n### Mass manipulation of structure datasets with AtomsCollection\nThe AtomsCollection class generalises ASE's Atoms class by treating groups of structures together and making it easier to retrieve information about all of them at once. Combined with the large number of AtomProperties, which extract chemical and structural information and more, it provides a simple, powerful tool to look quickly at the results of an AIRSS search.\n\n### Accurate treatment of periodic boundaries\nMany functions in Soprano require to compute interatomic distances, such as when computing bonds, or estimating NMR dipolar couplings. Soprano always takes the utmost care in dealing with periodic boundaries, using algorithms that ensure that the closest periodic copies are always properly accounted for in a fast and efficient way. This approach can also be used in custom functions as the algorithm can be found in the function `soprano.utils.minimum_periodic`.\n\n### Easy processing of NMR parameters and spectral simulations\nASE can read NMR parameters in the `.magres` file format, but Soprano can turn them to more meaningful physical quantities such as isotropies, anisotropies and asymmetries. In addition, with a full database of NMR active nuclei, Soprano can compute quadrupolar and dipolar couplings for specific isotopes. Finally, Soprano can produce a fast approximation of a powder spectrum - both MAS and static - in the diluted atoms approximation, or if that is not enough for your needs, provide an interface to NMR simulation software [Simpson](https://inano.au.dk/about/research-centers-and-projects/nmr/software/simpson).\n\n### Machine learning and phylogenetic analysis\nThe `soprano.analyse.phylogen` module contains functionality to classify collections of structures based on relevant parameters of choice and identify similarities and patterns using Scipy's hierarchy and k-means clustering algorithms. This can be of great help when analysing collections of potential crystal structure looking for polymorphs, finding defect sites, or analysing disordered systems.\n\n### HPC Submitters\nSoprano provides a Submitter class, which can be inherited from by people with some experience in Python coding to create their own scripts running as background processes and able to process large amounts of calculations automatically. Files can be copied, sent to remote HPC machines, submitted for calculations to any of the major queue managing systems, and then downloaded back to the local machine - all or just the significant results, if space is an issue. While not the most user-friendly functionality provided by Soprano, Submitters have the potential to be extremely powerful tools that can save a lot of time when working with large batches of computations.\n",
"bugtrack_url": null,
"license": null,
"summary": "A Python library to crack crystals",
"version": "0.10.1",
"project_urls": {
"Homepage": "https://ccp-nc.github.io/soprano/"
},
"split_keywords": [
"ccpnc",
" computational chemistry",
" crystallography"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "cf3e55a43bc045bc3fe74241c0b6520f507963a125610eb3d4bf0bbdad30ab04",
"md5": "fd3b3f64a409e320a1e418aa6d472c4d",
"sha256": "86f3d8b59aaac82bfca79e9e35c24bada3d0e5c5c0b5fb75a3cdcac7cc0193a0"
},
"downloads": -1,
"filename": "soprano-0.10.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fd3b3f64a409e320a1e418aa6d472c4d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 290270,
"upload_time": "2025-07-28T15:47:40",
"upload_time_iso_8601": "2025-07-28T15:47:40.939483Z",
"url": "https://files.pythonhosted.org/packages/cf/3e/55a43bc045bc3fe74241c0b6520f507963a125610eb3d4bf0bbdad30ab04/soprano-0.10.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "630d2564b72f3dfc65f06a278aebcc5921ec4e7cb0948b4a5a855fb6f924c1d3",
"md5": "0bfc0bc95731feddb7558e54232621d7",
"sha256": "713a3b55f7bc9bd740db9c46e08aeed0643afea5f5ad9c41b0823faa786ab02e"
},
"downloads": -1,
"filename": "soprano-0.10.1.tar.gz",
"has_sig": false,
"md5_digest": "0bfc0bc95731feddb7558e54232621d7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 216502,
"upload_time": "2025-07-28T15:47:42",
"upload_time_iso_8601": "2025-07-28T15:47:42.670718Z",
"url": "https://files.pythonhosted.org/packages/63/0d/2564b72f3dfc65f06a278aebcc5921ec4e7cb0948b4a5a855fb6f924c1d3/soprano-0.10.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-28 15:47:42",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "soprano"
}
JSON