Soprano comes with a number of tutorials in the form of Jupyter Notebooks
. If you don't have Jupyter installed on your computer, all you need to do is use pip:
Once you have Jupyter, download Soprano's tutorials. You can either download the entire repository from Github and find the folder in the parent directory or use
svn export https://github.com/CCP-NC/soprano/trunk/tutorials
After navigating to the tutorials folder, launch the notebook:
and you're good to go!
So what is it about?
Soprano has a lot of functionality meant to make working with crystallographic sets simple. Here, following the tutorials, we will outline some of it.
- Tutorial 1 covers the very basics; how to load multiple structures into a single collection, how to access them individually or in groups, assign data arrays to them, and sort them;
- Tutorial 2 covers Generators, Properties and Calculators. In Soprano, Generators are iterators that help you to construct many structures quickly - for example, by interpolating linearly between two extreme configurations in a number of steps, or by generating structures in which a random defect has been injected. If you use AIRSS, there are also bindings to its random structure generator, buildcell. Properties are classes that help extracting information from collections of structures, ranging from the simple (their lattice parameters) to the very complex (NMR dipolar couplings, Steinhardt bond order parameters, and so on). Finally, Calculators are the same as the ones from ASE and provide interfaces to commonly used software packages. Here we see how they can be used within Soprano;
- Tutorial 3 covers the subject of Selections and Transforms. Selections are instances of a special class that allows one to pick a subset of atoms within a structure, based for example on their species, or distance from a given point. They can also be operated with using Boolean logic to create complex choices (did you ever want to be able to pick all carbon atoms within 2 Angstroms of an oxygen atom in your sample in a couple of lines of code? Now you can!). Transforms are special properties that use Selections to modify a structure. The chosen selection can be rotated, translated, reflected and so on, creating new structures;
- Tutorial 4 is about one of the core functionalities of Soprano - the "phylogenetic" clustering approach. This is an analysis method meant to help one to find similar structures among a large number of candidates - for example, grouping the output structures of an AIRSS run based on which polymorph or phase they ended up converging to. The PhylogenCluster class allows to do this by providing a vast number of "genes" that embody various properties. These properties can be calculated on a set of structures and used to classify them based on similarity thanks to Scipy's implementation of hierarchical and k-means clustering. In addition, the user can create custom "genes" depending on the need. The reason why this analysis is called "phylogenetic" is that it draws inspiration from biology - chemical structures are grouped in trees of similarity using a string of information that describes them just like animals can be grouped in species, families and so on based on the resemblance of their DNA.
- Tutorial 5 focuses on NMR. ASE can read the .magres file format, the output format of choice for CASTEP and Quantum Espresso, and here we explore the ways in which Soprano can make use of this data. These include processing the tensors into more commonly used parameters following the Haeberlen or Herzfeld Berger conventions, computing quantities that require isotope-specific data like quadrupolar couplings, and finally produce powder spectra in the dilute (=non-interacting nuclear spins) limit.
- Tutorial 6 is about defect calculations. A series of new tools has been developed recently, dedicated to the specific task of creating defect structures, such as interstitials, substitutions, or localised additions of one specific atom. This tutorial illustrates some examples of how to use these tools and manipulate the resulting structures. Combination of these tools has the potential to be a very powerful way of creating complex defect structures, such as one can need when studying zeolites.
The tutorials only cover the essentials of how to use Soprano - for detailed information about the various functions and classes and how they work, refer to the documentation