130 lines
5.3 KiB
Markdown
130 lines
5.3 KiB
Markdown
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)](https://www.psi.ch/)
|
|
by the team of the [PEARL beamline](https://www.psi.ch/en/sls/pearl).
|
|
|
|
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](http://garciadeabajos-group.icfo.es/widgets/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](https://msspec.cnrs.fr/index.html) 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](http://www.apache.org/licenses/LICENSE-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](http://www.psi.ch)
|
|
|
|
|
|
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.
|
|
|