Introduction
Galore is a package which applies Gaussian and Lorentzian broadening to data from ab initio calculations. The two main intended applications are
Gaussian and Lorentzian broadening of electronic density-of-states, with orbital weighting to simulate UPS/XPS/HAXPES measurements.
Application of Lorentzian instrumental broadening to simulated Raman spectra from DFPT calculations.
Documentation
A brief overview is given in this README file. A full manual, including tutorials and API documentation, is available online at readthedocs.io. You can build a local version using Sphinx with make html from the docs directory of this project.
An brief formal overview of the background and purpose of this code has been published in The Journal of Open Source Software.
Usage
Broadening, weighting and plotting are accessed with the galore program. For full documentation of the command-line flags, please use the in-built help:
galore -h
Instrumental broadening
Data may be provided as a set of X,Y coordinates in a text file of comma-separated values (CSV). Whitespace-separated data is also readable, in which case a .txt file extension should be used.
To plot a CSV file to the screen with default Lorentzian broadening (2 cm-1), use the command:
galore MY_DATA.csv -l -p
and to plot to a file with more generous 10 cm-1 broadening:
galore MY_DATA.csv -l 10 -p MY_PLOT.png
will provide the additional data needed.
Other file formats are supported, including IR and Raman intensity simulation output. See the Tutorials for usage examples.
Photoelectron spectra
UPS, XPS or HAXPES spectra can be simulated using Galore. This requires several inputs:
Orbital-projected density of states data. - This may be provided as an output file from the VASP or GPAW codes. - Formatted text files may also be used.
Instrumental broadening parameters. The Lorentzian and Gaussian broadening widths are input by the user as before.
Photoionization cross section data, which is used to weight the contributions of different orbitals.
Galore includes data for valance band orbitals at Al k-α (XPS) and He II (UPS) energies, drawn from a more extensive table computed by Yeh and Lindau (1985). An alternative dataset may be provided as a JSON file; it is only necessary to include the elements and orbitals used in the DOS input files.
Cross-sections for high-energy (1-1500 keV) photons have been fitted from tabulated data computed by Scofield (1973).
See the Tutorials for a walkthrough using sample data.
The orbital data can also be accessed without working on a particular spectrum with the galore-get-cs program. For example:
galore-get-cs 4 Sn O
will print a set of valence orbital weightings for Sn and O corresponding to a 4 keV hard x-ray source. These values have been converted from atomic orbital data to per electron cross-sections.
The galore-plot-cs program is provided for plotting over a range of energies using the high-energy fitted data:
galore-plot-cs Pb S --emin 2 --emax 10 -o PbS.pdf
generates a publication-quality plot of cross-sections which may help in the selection of appropriate HAXPES energies for experiments with a given material.
Requirements
Galore is currently compatible with Python versions 3.8 and newer. Galore uses Numpy to apply convolution operations. Matplotlib is required for plotting.
Galore uses Pip and setuptools for installation. You probably already have this; if not, your GNU/Linux package manager will be able to oblige with a package named something like python-setuptools. On Max OSX, the Python distributed with Homebrew includes setuptools and Pip.
Installation
Windows user installation
Anaconda is recommended for managing the Python environment and dependencies on Windows. From the Anaconda shell:
pip3 install .
Linux/Mac developer installation
From the directory containing this README:
pip3 install --user -e .
which installs an editable (-e) version of galore in your userspace. The executable program galore goes to a user directory like ~/.local/bin (which may need to be added to your PATH) and the galore library should be available on your PYTHONPATH. These are links to the project source folder, which you can continue to edit and update using Git.
To import data from VASP calculations you will need the Pymatgen library. If you don’t have Pymatgen yet, the requirements can be added to the Galore installation with by adding [vasp] to the pip command e.g.:
pip3 install --user -e .[vasp]
Installation for documentation
If you need to build the documentation you can add [docs] to the pip command to ensure you have all the Sphinx requirements and extensions:
pip3 install --upgrade .[docs]
Support
If you’re having trouble with Galore or think you’ve found a bug, please report it using the Github issue tracker. Issues can also be used for questions and discussion about the Galore methodology/implementation.
Development
This code is developed by the Scanlon Materials Theory Group based at University College London. Suggestions and contributions are welcome; please read the CONTRIBUTING guidelines and use the Github issue tracker.
Testing
Galore uses the standard-library unittest package, and manages tests with tox. Install tox and the appropriate Python versions and run tox from the project directory.
How to cite Galore
If you use Galore in your research, please consider citing the following work:
Adam J. Jackson, Alex M. Ganose, Anna Regoutz, Russell G. Egdell, David O. Scanlon (2018). Galore: Broadening and weighting for simulation of photoelectron spectroscopy. Journal of Open Source Software, 3(26), 773, doi: 10.21105/joss.007733
Galore includes a machine-readable citation file in an emerging standard format with citation details for the actual code, but as conventions for software citation are still developing the JOSS paper is a more reliable method of giving credit.
License
Galore is made available under the GNU Public License, version 3.
Acknowledgements
Development work by Adam J. Jackson took place in the course of research into new transparent conducting materials, led by David O. Scanlon and funded by EPSRC (project code EP/N01572X/1). Work by Alex M. Ganose was supported by a studentship co-sponsored by the Diamond Light Source at the EPSRC Centre for Doctoral Training in Molecular Modelling and Materials Science (EP/L01582/1). Anna Ragoutz was our expert advisor on all things PES, guiding the feature-set and correcting the implementation of weighting, and was supported by an Imperial College Research Fellowship.
We acknowledge useful discussions with Alexey Sokol (who proposed that a code such as this would be useful), Katie Inzani, and Tim Veal. Feature requests and user testing came from Benjamin Williamsion, Christopher Savory and Winnie L. Leung.
This would have been much more painful if not for the excellent scientific Python ecosystem, and the Python Materials Genome project spared us the pain of writing Yet Another Vasp Parser.
2 maintainers
Metadata
2 maintainers
Release files for galore 0.10.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| galore-0.10.0.tar.gz | 601.8 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| galore-0.10.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 715.1 kB
Release files / galore-0.10.0.tar.gz
| Download URL | galore-0.10.0.tar.gz |
|---|---|
| Size | 601.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f970b28d421cf9ac9b80311c601314b21948c8c189e6d814922f628c8591d1bc
|
|
BLAKE2b-256 checksum How to use checksums |
6ec8412d647dbc40f0f855b08facd09e9fde7d0c20231c86bb42021c1fdbebc2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 13, 2026.
Transparency logRelease files / galore-0.10.0-py3-none-any.whl
| Download URL | galore-0.10.0-py3-none-any.whl |
|---|---|
| Size | 113.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d704419ee1b88590da9d314fac72cd1ab24924728490e5ea7af7f5ed6a0693b9
|
|
BLAKE2b-256 checksum How to use checksums |
c6108357435e94059dcd297cfb5cc226f843e81f83d2a051051baf8fa8347f80
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 13, 2026.
Transparency log
