Skip to content

Home

Jump to bottom
elichad edited this page Jan 13, 2022 · 11 revisions

Intro

pymuon-suite is a suite of command line tools designed to help with doing computational science for muon spectroscopy, specifically when involving positively charged muons. In particular, pymuon-suite is designed to help answer questions such as:

  • what are the optimal stopping sites for a muon in a certain crystalline solid?
  • what are the effects of quantum delocalisation on the hyperfine coupling of the muon?

To this end, pymuon-suite has a number of scripts that will help you automate tasks that would otherwise be very long, difficult and/or error prone to carry out by hand. However it must be stressed that pymuon-suite is not:

  • a quantum chemistry software. pymuon-suite does not provide any internal way of computing the energies or forces between atoms; instead, it relies on external tools such as CASTEP or DFTB+ to do that;
  • a simulation tool for muon spin spectroscopy experiment. If that's what you're looking for, check out muspinsim or Mantid's QUANTUM instead;
  • a tool to compute the energy levels or X-ray emissions for negatively charged muons. If that's what you need, check out mudirac instead;
  • a Graphical User Interface tool (though one is in development).

Getting started

In order to get started using pymuon-suite, you will need a functional installation of Python 3.7+, a working connection to the internet, and either of the tools pip or conda to access Python package repositories. Installing Python and pip/conda tends to be more straightforward for Linux and Mac users, but it can easily be done in Windows too in various ways, for example by installing the Anaconda Python distribution, which can be launched with a few clicks. Once in a running Python environment, run the following command:

If using pip:

pip install pymuonsuite

If using conda (skip the first two lines if you have set up the conda-forge channel before):

conda config --add channels conda-forge
conda config --set channel_priority strict
conda install pymuonsuite

Once that's done, you will have access to all the pymuon-suite tools from the command line.

Installation from Source (not recommended)

If you can't or don't want to use the pip or conda install methods above, you can install pymuon-suite from source instead. Given a running Python environment:

  1. download the pymuon-suite source code, either as a ZIP file, choosing one of our Releases if there are any, or directly cloning the repository;

  2. after the source code is unzipped and accessible in a folder, enter your command line console and navigate to that folder;

  3. run the install command pip install ./ within that folder to install the suite as well as all its missing dependencies.

Once that's done, you will have access to all the pymuon-suite tools from the command line.

List of tools

Once the suite is installed, the following tools are available:

  • pm-muairss: allows to use Ab-Initio Random Structure Searching to find muon stopping sites. This tool will both generate random structures that can be optimised with use of DFT or other quantum chemistry software and analyse the results of these calculations to identify the most likely stopping sites;
  • pm-muairss-gen: a legacy alias for pm-muairss that will only take care of the generation step, but not the analysis;
  • pm-uep-opt: uses an electronic density output from a DFT calculation to compute an Unperturbed Electrostatic Potential, and given a certain muon starting position, relaxes it to the closest local minimum;
  • pm-uep-plot: uses an electronic density output from a DFT calculation to compute an Unperturbed Electrostatic Potential, and creates line or plane slice plots of it;
  • pm-symmetry: analyses the symmetry of a structure with spglib and identifies the Wyckoff points, which ones are occupied, and which ones can be ruled out as saddle points of the potential purely by geometric considerations, thus very quickly providing some candidates for muon stopping sites in crystals;
  • pm-asephonons: compute phonons for the given structure using the Atomic Simulation Environment and DFTB+;
  • pm-nq: generates input files for quantum effect evaluation using a phonon approximation or analyses the results (work in progress).

Installing pymuon-suite also means that its core library gets added to your Python environment; that means that it becomes possible to use import pymuonsuite in any Python script, and access its internal functions and classes. However, pymuon-suite is mainly designed as a set of tools, so this documentation is not focused on its inner workings. A Developer's Guide may be written eventually, but for now, the adventurous developer who wants to go into it will have to rely on documentation and navigating the source code! Of course, this software being fully Open Source, any contributions and pull requests from contributors are welcome.

Acknowledgments

pymuon-suite is written as part of the Muon Spectroscopy Computational Project, a collaboration between the Scientific Computing Department and the ISIS Muon Group within the Science and Technology Facilities Council. It uses heavily the Atomic Simulation Environment and Soprano libraries. It also contains data extracted from DFTB.org to help running Density Functional Tight Binding calculations.

How to cite pymuon-suite

If you use pymuon-suite for your research, you should cite all the relevant external software or their papers, and in addition, you should cite:

Clone this wiki locally