pmsco-public/README.md

Introduction

PMSCO (PSI multiple-scattering cluster calculations and structural optimization) is a Python-based workflow engine to calculate photoelectron diffraction patterns, and to optimize structural models based on measured data using machine learning techniques. PMSCO was developed at the Paul Scherrer Institut (PSI) by the team of the PEARL beamline.

The actual scattering calculation is done by code developed by other parties. PMSCO wraps around those programs and facilitates parameter handling, cluster building, structural optimization and parallel processing. In the current version, the EDAC code developed by F. J. García de Abajo, M. A. Van Hove, and C. S. Fadley (1999) is used for scattering calculations. Instead of EDAC built-in routines, alternatively, the PHAGEN program from MsSpec-1.0 can be used to calculate atomic scattering factors.

Highlights

• angle and energy scanned XPD.
• various scanning modes including energy, manipulator angle (polar/azimuthal), emission angle.
• averaging over multiple domains and emitters.
• global optimization of multiple scans.
• structural optimization algorithms: particle swarm optimization, genetic algorithm, grid scan, table scan.
• detailed reports and graphs of result files.
• calculation of the modulation function.
• calculation of the weighted R-factor.
• automatic parallel processing using OpenMPI.
• compatible with Slurm resource manager on Linux cluster machines.

Installation

PMSCO is written in Python. The recommended Python version is 3.12. Further requirements are the GNU compiler collection, BLAS/LAPACK libraries, OpenMPI and a package manager such as uv, pip or conda. For optimization jobs, a cluster machine with 20-50 available processor cores is recommended. Smaller jobs run on any recent Linux workstation. The code requires about 2 GB of RAM per process.

Detailed installation instructions and dependencies can be found in the documentation (docs/src/installation.dox).

License

The source code of PMSCO is licensed under the Apache License, Version 2.0. This does not include the calculation packages contained in the subprojects folder which are licensed separately.

• Please read and respect the respective license agreements.
• Please acknowledge the use of the code.
• Please consider sharing your developments with the original author.

Due to different copyright terms, the third-party calculation programs are not contained in the public software repository. These programs may not be used without an explicit agreement by the respective original authors.

Authors

• Matthias Muntwiler, mailto:matthias.muntwiler@psi.ch
• Frederik Schirdewahn, mailto:frederik.schirdewahn@psi.ch

Copyright

Copyright 2015-2025 by Paul Scherrer Institut

Release Notes

For a detailed list of changes, see the CHANGES.md file.

4.2.0 (2026-01-01)

• Recommended Python version 3.12 (compatibility 3.10-3.13)
• Build system and package environment
  • Switch to Astral-UV package manager
  • Meson build system for Fortran, C and C++ extension modules
  • Namespace package installation, support for editable installation
  • CI lint, build, test workflow in gitea
  • Automated documentation workflow in gitea
• User interface
  • Simplified command line, all configuration via runfile and/or project class
  • Select modulation and R-factor functions in runfile
  • Parametric holo scan generator
  • Configurable reports
  • Path resolution in runfile
  • Database interface for reports
  • Runfile based job scheduling
• Calculation features
  • Multipole expansion
  • Table optimization mode
  • Integrate phagen scattering amplitude calculator
  • Differential cross section in periodic table

3.0.0 (2021-02-08)

• Run file interface replaces command line arguments:
  • Specify all run-time parameters in a JSON-formatted text file.
  • Override any public attribute of the project class.
  • Only the name of the run file is needed on the command line.
• The command line interface is still available, some default values and the handling of directory paths have changed. Check your code for compatibility.
• Integrated job scheduling with the Slurm resource manager:
  • Declare all job arguments in the run file and have PMSCO submit the job.
• Graphics scripts for genetic chart and swarm population (experimental feature).
• Update for compatibility with recent Ubuntu (20.04), Anaconda (4.8) and Singularity (3.7).
• Drop compatibility with Python 2.7, minimum requirement is Python 3.6.

2.2.0 (2020-09-04)

This release breaks existing project code unless the listed refactorings are applied.

• Major refactoring: The 'symmetry' calculation level is renamed to 'domain'. The previous Domain class is renamed to ModelSpace, Params to CalculatorParams. The refactorings must be applied to project code as well.
• Included periodic table of elements with electron binding energies and scattering cross-sections.
• Various bug fixes in cluster routines, data file handling, and in the PHAGEN interface.
• Experimental sqlite3 database interface for optimization results.