2. Quantum metrology software platform/ecosystem overview#

In recent years, a unified Python codebase/ecosystem/platform has been in development to tackle various aspects of photoionization problems, including ab initio computations and experimental data handling, and (generalised) matrix element retrieval methods. The eponymous Quantum Metrology with Photoelectrons platform is introduced here, and is used for the analysis herein. The main aim of the platform is to provide a unifying data layer, and analysis routines, for photoelectron metrology, including new methods and tools, as well as a unifying bridge between these and existing tools. Fig. 2.1 provides a general overview of some of the main tools and tasks/layers.

As of late 2022, the new parts of the platform - primarily the Photoelectron Metrology Toolkit [5] library - implement general data handling for theory and experimental datasets (although not a full experimental analysis toolchain), along with matrix element handling and retrieval, which will be the main topic of this volume. In the future, it is hoped that the platform will be extended to other theoretical and experimental methods, including full experimental data handling.

2.1. Analysis components#

The two main components of the platform for analysis tasks, as used herein, are:

  • The Photoelectron Metrology Toolkit [5] (PEMtk) codebase aims to provide various general data handling routines for photoionization problems. At the time of writing, simulation of observables and fitting routines are implemented, along with some basic utility functions. Much of this is detailed herein, and more technical details and ongoing documentation case be found in the PEMtk documentation [20].

  • The ePSproc codebase [33, 34, 35] aims to provide methods for post-processing with ab initio radial dipole matrix elements from ePolyScat (ePS) [36, 37, 38, 39], or equivalent matrix elements from other sources (dedicated support for R-matrix results from the RMT suite [40, 41] is in development, for an overview of ab initio methods/packages see Ref. [42]). The core functionality includes the computation of AF and MF observables. Manual computation without known matrix elements is also possible, e.g. for investigating limiting cases, or data analysis and fitting - hence these routines also provide the backend functionality for PEMtk fitting routines. Again more technical details can be found in the ePSproc documentation [35].

../_images/QM_unified_schema_wrapped_280820_gv.png

Fig. 2.1 Quantum metrology with photoelectrons ecosystem overview.#

2.2. Additional tools#

Other tools listed in Fig. 2.1 include:

2.3. Python ecosystem (backends, libraries and packages)#

The core analysis tools, which constitute the Photoelectron Metrology Toolkit [5] platform, are themselves built with the aid of a range of open-source python packages/libraries which handle various backend functionality. Notably, they make use of the following key packages:

  • General functionality makes use of the usual “Scientific Python” stack, in particular:

    • Numpy [50] for general numerical methods and data types.

    • pandas [51] for statistical methods, and various tabulation and sorting tasks.

    • Scipy [52] for some special functions and computational routines, particularly spherical harmonics and fitting routines (see below).

  • General ND-array and tensor handling and manipulation makes use of the Xarray library [53, 54].

  • Angular momentum functions

    • Wigner D and 3js are currently implemented directly, or via the Spherical Functions library [55, 56], and have been tested for consistency with the definitions in Zare (for details see the ePSproc docs [35]). The Spherical Functions library also uses quaternion [57, 58] which implements a quaternion datatype in Numpy.

    • Spherical harmonics are defined with the usual physics conventions: orthonormalised, and including the Condon-Shortley phase. Numerically they are implemented directly or via SciPy’s sph_harm function (see the SciPy docs for details [59]. Further manipulation and conversion between different normalisations can be readily implemented with the pySHtools library [60, 61, 62, 63]. See Sect. 3.6.1 for examples.

    • Symmetry functionality, specifically computing symmetrized harmonics \(X_{hl}^{\Gamma\mu*}(\theta,\phi)\) (see Eq. (3.37)), makes use of libmsym [64, 65] (symmetry coefficients) and pySHtools [60, 61, 62, 63] (general spherical harmonic handling and conversion). See Sect. 3.6.2 for examples.

  • Non-linear optimization (fitting), as used for the bootstrap retrieval protocol (to determine radial matrix elements):

    • Fitting is handled via the lmfit library [66, 67], which implements and/or wraps a range of non-linear fitting routines in Python, including classes for handling fitting parameters and outputs. In this work only the Levenberg-Marquardt least-squares minimization method has been used, which wraps Scipy’s least_squares functionality [59], hence this is the core numerical minimization routine for the demonstration cases herein. (See Chapter 4 for further discussion of fitting methods.)

    • Basic parallelization for fitting routines is implemented using the xyzpy library [68], see Chapter 7 for further details.

  • For plotting a range of tools can be used, some of which are implemented/wrapped in the Photoelectron Metrology Toolkit [5], or can be used directly with Xarray data structures, including:

  • Some specialist (optional) tools also make use of additional libraries, although these are not required for basic use; in particular:

    • For 3D orbital visualizations with ePSproc [34]: pyvista for 3D plotting (which itself is built on VTK), cclib for electronic structure file handling and conversion, and methods based on Chemlab for molecule wavefunction (orbital) computation from electronic structure files are all used on the backend.

    • Numba [76] is used for numerical acceleration in some routines, although remains mainly experimental in ePSproc at the time of writing (an exception to this is the Spherical Functions library, which does make full use of Numba acceleration).

Code examples and further comments can be found as and when numerical examples are introduced in the text, particularly in Chapter 3 and Chapter 4.

2.4. Installation and environment set-up#

2.4.1. Quick-start installation#

For a basic installation, up-to-date version of Photoelectron Metrology Toolkit [5] and ePSproc codebase [33, 34, 35] can be installed directly from Github source using pip:

pip install git+https://github.com/phockett/ePSproc.git
pip install git+https://github.com/phockett/PEMtk.git

This should also install the required dependencies, although not all of the optional packages. (Note that pip install ePSproc will also work, and install the latest release from the Pypi repository, but this may not be fully up-to-date compared to the Github source; PEMtk is not yet available via Pypi.)

For more details and other installation options, see the ePSproc extended installation notes online, which includes directions for virtual environments (Anaconda, Venv).

To obtain the book source, including all example notebooks, simply use Git:

git clone https://github.com/phockett/Quantum-Metrology-with-Photoelectrons-Vol3.git

Alternatively, the files can be browsed and download via the web from the Quantum Metrology Vol. 3 (Github repo), which also includes additional setup notes.

2.4.2. Docker deployments#

Docker [77] provides a useful mechanism for distribution of software as stand-alone containers (essentially minimal virtual machines), including definitions and versioning for everything from the operating system layer and up. Docker containers are both portable and reproducible, hence excellent tools for open science (see Sect. 1.2.3).

A Docker-based distribution of various codes for tackling photoionization problems is available from the Open Photoionization Docker Stacks [19] project, which aims to make a range of these tools more accessible to interested researchers, and fully cross-platform/portable. The project currently includes Docker builds for ePSproc and PEMtk (as well as ePS and other useful tools). These are based on the Jupyter Docker Stacks project [78], which includes Jupyter Lab, and also add all the required tools for the work illustrated herein.

A Docker container for this book is also available from the Docker Hub (and source Dockerfiles via Quantum Metrology Vol. 3 (Github repo)). This container builds on the ePSproc and PEMtk container, and additionally includes the source notebooks and build tools (specifically Jupyter Book [15, 16] and related tools) as discussed in Sect. 1.2.2. It is suggested that readers interested in making use of this work start here as the easiest - and most comprehensive - methodology for getting the tools up and running. Docker uses simply need to run docker pull epsproc/quantum-met-vol3 to obtain a copy, and docker run epsproc/quantum-met-vol3 to run - for further details and notes see the Docker section of Quantum Metrology Vol. 3 (Github repo).

2.4.3. Running examples#

Any of the source notebooks can be run individually in a correctly configured Python/Jupyter environment (readers unfamiliar with Jupyter can find introductory materials online at jupyter.org [13]). Note that the majority of the imports are handled by a setup script, executed at the top of each notebook, for brevity and to ensure a standardized build:

%run '../scripts/setup_notebook.py'

For additional customization this script can be modified as desired. Depending on the build environment the full path to the script may also need to be set (the current code assumes the script will be located in the qm3-repo/doc-source/scripts directory, and notebooks run from their source dirs, e.g. qm3-repo/doc-source/part1).

2.5. General platform discussion#

Note that, at the time of writing:

Nonetheless, although both the codebase and methodologies are still under development, a range of numerical methods have been successfully trialled (as illustrated in Part II herein), and are now available to other researchers to make use of and build on.