# soprano
Soprano - a Python library to crack crystals!
## 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 --user
In addition, you can get the latest version (not guaranteed to be stable) from github:
git clone https://github.com/CCP-NC/soprano.git
pip install ./soprano --user
This approach should work even on machines on which one does not possess admin privileges (such as HPC clusters), as long as Python and `pip` are present.
## Requirements
Soprano has a few requirements that should be installed automatically by `pip` when used. Installing with `pip` is strongly advised. The core Soprano requirements are:
* [Numpy](http://www.numpy.org/)
* [Scipy](https://www.scipy.org/)
* The [Atomic Simulation Environment](https://wiki.fysik.dtu.dk/ase/)
Additional, optional requirements are `pyspglib` (used for spacegroup detection in `soprano.properties.symmetry` and `soprano.calculate.xrd`) and `paramiko` (used for remote SSH operation in `soprano.hpc.submitter`).
## Getting started
Soprano ships with five Jupyter notebooks that illustrate its core functionality and how to use it. Being accustomed already 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.9",
"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/f4/2b/d8960473deb4803119f27d7f218ccef85694bbf0732773fcc9fa4d486188/soprano-0.9.2.tar.gz",
"platform": null,
"description": "# soprano\nSoprano - a Python library to crack crystals!\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 --user\n\nIn addition, you can get the latest version (not guaranteed to be stable) from github:\n\n git clone https://github.com/CCP-NC/soprano.git\n pip install ./soprano --user\n \nThis approach should work even on machines on which one does not possess admin privileges (such as HPC clusters), as long as Python and `pip` are present.\n\n## Requirements\nSoprano has a few requirements that should be installed automatically by `pip` when used. Installing with `pip` is strongly advised. The core Soprano requirements are:\n\n* [Numpy](http://www.numpy.org/)\n* [Scipy](https://www.scipy.org/)\n* The [Atomic Simulation Environment](https://wiki.fysik.dtu.dk/ase/)\n\nAdditional, optional requirements are `pyspglib` (used for spacegroup detection in `soprano.properties.symmetry` and `soprano.calculate.xrd`) and `paramiko` (used for remote SSH operation in `soprano.hpc.submitter`).\n\n## Getting started\nSoprano ships with five Jupyter notebooks that illustrate its core functionality and how to use it. Being accustomed already 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.9.2",
"project_urls": {
"Homepage": "https://ccp-nc.github.io/soprano/"
},
"split_keywords": [
"ccpnc",
" computational chemistry",
" crystallography"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b087d4ce3269b133143f163c3b48258c97829702852de0b75cc3bacb1f00427a",
"md5": "2930043378791371035d43ddca9d8b13",
"sha256": "7d5dc74cb372ffab7854b6159e658af68ba9bc255852e3211fe51919aa1344d3"
},
"downloads": -1,
"filename": "soprano-0.9.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2930043378791371035d43ddca9d8b13",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 280410,
"upload_time": "2024-10-03T09:50:04",
"upload_time_iso_8601": "2024-10-03T09:50:04.411760Z",
"url": "https://files.pythonhosted.org/packages/b0/87/d4ce3269b133143f163c3b48258c97829702852de0b75cc3bacb1f00427a/soprano-0.9.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f42bd8960473deb4803119f27d7f218ccef85694bbf0732773fcc9fa4d486188",
"md5": "cdde3395c4c9efc7313aaae346d1936e",
"sha256": "207aa8f486f06668caa08e97436b767c8e0a1f1901980894a12ac5bba8271c7c"
},
"downloads": -1,
"filename": "soprano-0.9.2.tar.gz",
"has_sig": false,
"md5_digest": "cdde3395c4c9efc7313aaae346d1936e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 205606,
"upload_time": "2024-10-03T09:50:06",
"upload_time_iso_8601": "2024-10-03T09:50:06.148459Z",
"url": "https://files.pythonhosted.org/packages/f4/2b/d8960473deb4803119f27d7f218ccef85694bbf0732773fcc9fa4d486188/soprano-0.9.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-03 09:50:06",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "soprano"
}
JSON