Metadata-Version: 2.4
Name: arpes-viewer
Version: 1.2.1
Summary: Browse, convert, analyse and compare ARPES data with calculations, and lay the results out as publication figures.
Author: Ding Pei
License-Expression: PolyForm-Noncommercial-1.0.0
Project-URL: Homepage, https://github.com/DingPei1995/ARPES-data-browser
Project-URL: Documentation, https://github.com/DingPei1995/ARPES-data-browser/blob/main/docs/USER_GUIDE_en.md
Project-URL: Issues, https://github.com/DingPei1995/ARPES-data-browser/issues
Project-URL: Changelog, https://github.com/DingPei1995/ARPES-data-browser/blob/main/CHANGELOG.md
Keywords: ARPES,photoemission,synchrotron,band structure,Fermi surface
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: X11 Applications :: Qt
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE.md
License-File: NOTICE
Requires-Dist: PyQt5>=5.12
Requires-Dist: pyqtgraph>=0.12
Requires-Dist: numpy>=1.20
Requires-Dist: scipy>=1.6
Requires-Dist: h5py>=3.0
Dynamic: license-file

# ARPES viewer

**Version 1.2.1** (last modified 29 October 2026) — see
[CHANGELOG.md](https://github.com/DingPei1995/ARPES-data-browser/blob/v1.2.1/CHANGELOG.md) for what changed. The version is in
`arpes_viewer/version.py` and is shown in the main window's title bar and at its foot,
with a link to this repository for bug reports and the latest version
(<https://github.com/DingPei1995/ARPES-data-browser>). Please quote it when
reporting a bug, and upload the error log with the report ([below](#bug-reports)).

> **Terms of use.** This program is for **non-commercial use only**
> (academic research and teaching); any commercial use is not permitted.
> New and updated loaders cover data from **public large-scale facilities**
> (synchrotrons and similar user facilities) only -- formats of individual
> laboratories' own set-ups are not supported. If you use this program for
> a paper on ARPES experiments, please cite this repository in its
> references (<https://github.com/DingPei1995/ARPES-data-browser>). A paper
> related to AI that uses this program or its code **must** first be
> discussed with the author by e-mail. For collaborations, or
> questions about the details, contact
> [ding.pei@synchrotron-soleil.fr](mailto:ding.pei@synchrotron-soleil.fr).
>
> **Licence and authorship.** Copyright (c) 2026 Ding Pei. Licensed under
> the [PolyForm Noncommercial License 1.0.0](https://github.com/DingPei1995/ARPES-data-browser/blob/v1.2.1/LICENSE.md); see also
> [NOTICE](https://github.com/DingPei1995/ARPES-data-browser/blob/v1.2.1/NOTICE). This is the author's personal work, developed from the
> author's own earlier code; no institution funded it. The requirements, design
> decisions, trade-offs, physics, the testing on real experimental data
> and the feedback from it (drawing on
> [Phys. Rev. B 103, 245121 (2021)](https://doi.org/10.1103/PhysRevB.103.245121) and
> [Phys. Rev. B 95, 125126 (2017)](https://doi.org/10.1103/PhysRevB.95.125126)),
> and the review and acceptance of every change are Ding Pei's; the
> implementation was assisted by Claude (Anthropic), credited as co-author
> in the commits.

A Python/PyQt5 program for ARPES data: browse the measurements of a
beamtime, open them in their own windows, convert to momentum, cut, fit,
process, compare with a band-structure calculation, and lay the results out
as a publication figure.

---

## From raw data to a publication figure -- and an AI agent can drive it

![Example figure 1: a notched cube, measured and calculated constant-energy contours, stacked contours](https://raw.githubusercontent.com/DingPei1995/ARPES-data-browser/v1.2.1/docs/images/example_figure_1.png)

> **These are not real experimental data.** Every panel above is made from
> the program's **synthetic demo data** (`devtools/demo_data.py`): an
> invented tight-binding toy model -- a triangular lattice, a = 3.3 Å,
> stacked with c = 6 Å, a few bands with orbital labels and a k_z
> dispersion -- turned into spectra with a Fermi-Dirac cut-off, the
> analyser resolution and Poisson counting noise, and written as beamline
> files. The "calculation" in panel (b) is the same toy Hamiltonian made
> deliberately 1/0.8 times wider and 50 meV higher, so that comparing it
> with the "measurement" has something to find. **No published data or
> literature were used to generate them**: the model and its parameters are
> invented, and names such as "Se-pxy" or "1T-TiSe₂-like" are labels for the
> toy, not a description of a real material. (The only tabulated values in
> the demo set are the X-ray line energies of its synthetic EDS spectrum,
> standard emission energies as listed in the X-ray Data Booklet; that
> spectrum is not part of this figure.)

<p align="center">
  <img src="https://raw.githubusercontent.com/DingPei1995/ARPES-data-browser/v1.2.1/docs/images/composer_colour_bar.png" width="96%"
       alt="Example figure 1 in the figure composer, its colour bar being set">
</p>
<p align="center">
  <img src="https://raw.githubusercontent.com/DingPei1995/ARPES-data-browser/v1.2.1/docs/images/main_window_advanced.png" width="50%"
       alt="The main panel: the beamtime's datasets and the tools for the selected ones">
  <img src="https://raw.githubusercontent.com/DingPei1995/ARPES-data-browser/v1.2.1/docs/images/map_k_contour.png" width="47%"
       alt="A Fermi-surface map converted to momentum, in its viewer">
</p>
<p align="center"><sub>Example figure 1 in the figure composer (top); the
main panel and a Fermi-surface map in momentum, in its viewer (bottom) --
also on the synthetic demo data.</sub></p>

Every step from the files to the finished figure is the program's own,
and every step is plain Python that a script -- or an **AI agent** -- can
run, without a screen:

| Step | In the program | In code |
|---|---|---|
| 1. Raw data | the beamline files, as the main panel lists them | `arpes_viewer.loader.registry.load(path, entry)` |
| 2. To momentum | the Γ-plane Fermi-surface map → k-map | `arpes_viewer.tools.momentum.kspace.convert_map(...)` |
| 3. The calculation | **Calculated bands**: a Wannier Hamiltonian; Z and the shift fitted on a cut | `BandsDialog.open_file(...)`, `.fit_alignment()` |
| 4. Measured vs calculated | constant-energy maps over the calculated contours, coloured by orbital weight (b) | `BandsDialog.series_panels(...)` |
| 5. 3-D views | the notched cube (a), the stacked contours (c) | `VolumeWindow(...).figure_panel()` |
| 6. The figure | the **figure composer**: arranged, lettered, exported as PNG / PDF, saved as `.afig` with the data and the files it came from | `FigureWindow(...)`, `.arrange(...)`, `.write(...)` |

`devtools/figure_tests.py` is exactly this script -- it writes the demo
files, reads them back, and builds this figure (and its companion, example
figure 2) in under a minute:

```
python devtools/figure_tests.py out_png/ out_afig/
```

In the step 3 fit it recovers what was built into the demo calculation
(Z = 0.798 ± 0.001 and a shift of −49.8 ± 0.4 meV, against 0.8 and −50 meV).

**Why an AI agent can drive it.** The computations live in `arpes_viewer/tools/`,
free of any user interface; the windows can run off-screen
(`QT_QPA_PLATFORM=offscreen`) and be driven call by call as a user drives
them; each step is documented in the [user guide](https://github.com/DingPei1995/ARPES-data-browser/blob/v1.2.1/docs/USER_GUIDE_en.md)
and in the technical references beside the code; and a saved figure records
the data and the original files behind every panel. So a coding agent given
this repository and a folder of data can be asked in plain words -- *"convert
the Γ-plane map to momentum, compare it with the Wannier calculation in
`calc/`, and make a figure like example figure 1, with constant-energy maps
at E_F, −0.3, −0.6 and −0.9 eV"* -- write and run the script, look at the
PNG it made, and refine it, through to a figure ready for a manuscript. The
user guide's [worked example](https://github.com/DingPei1995/ARPES-data-browser/blob/v1.2.1/docs/USER_GUIDE_en.md#30-worked-example-two-figures-in-the-figure-composer)
does the same by hand, step by step. As with any analysis, check what an
agent produced before you publish it -- and see the terms of use above for
papers related to AI.

---

## What it does

- **Reads** SOLEIL ANTARES and CASSIOPEE (including whole folders and the
  spin end station), ALS MAESTRO, ALBA LOREA, Diamond I05 and I05-1, MAX IV
  Bloch, Elettra APE, BESSY One Cube / One Square, SOLARIS URANOS, ASTRID2
  SGM4, and its own saved format ([loading data](https://github.com/DingPei1995/ARPES-data-browser/blob/v1.2.1/docs/USER_GUIDE_en.md#4-loading-data)).
- **Shows** cuts, Fermi-surface maps, photon-energy scans, spatially resolved
  scans and spin-resolved curves, each in its own window with linked cursors
  ([the viewers](https://github.com/DingPei1995/ARPES-data-browser/blob/v1.2.1/docs/USER_GUIDE_en.md#5-what-the-viewers-have-in-common)).
- **Converts** maps and cuts to momentum, photon-energy scans to k_z, with the
  Brillouin zone drawn over them
  ([§13](https://github.com/DingPei1995/ARPES-data-browser/blob/v1.2.1/docs/USER_GUIDE_en.md#13-converting-a-map-to-momentum),
  [§14](https://github.com/DingPei1995/ARPES-data-browser/blob/v1.2.1/docs/USER_GUIDE_en.md#14-photon-energy-scans-kz),
  [§15](https://github.com/DingPei1995/ARPES-data-browser/blob/v1.2.1/docs/USER_GUIDE_en.md#15-brillouin-zone)).
- **Analyses**: Fermi-edge fits, Fermi-surface correction, MDC / EDC fits,
  ridge detection, curvature and second derivatives, dichroism, core levels,
  spin, de-gridding, detector corrections
  ([§7–§24](https://github.com/DingPei1995/ARPES-data-browser/blob/v1.2.1/docs/USER_GUIDE_en.md#7-arbitrary-cuts-and-fermi-surface-correction)).
- **Compares with theory**: crystal structures, tight-binding fits, and
  calculated bands from Wien2k, VASP, Quantum ESPRESSO, Wannier90 and the
  FPLO + Wannier tools -- along a path, as constant-energy contours on any
  (hkl) plane, or as a 3-D Fermi surface
  ([§25–§27](https://github.com/DingPei1995/ARPES-data-browser/blob/v1.2.1/docs/USER_GUIDE_en.md#27-calculated-bands)).
- **Makes figures**: the figure composer, laid out like a manuscript page,
  exported as PNG, PDF or SVG, and saved with its data
  ([§28–§30](https://github.com/DingPei1995/ARPES-data-browser/blob/v1.2.1/docs/USER_GUIDE_en.md#28-the-figure-composer)).
- **Loses nothing**: every derived dataset is autosaved, a crash is recovered
  from, and long steps show a progress bar
  ([§31](https://github.com/DingPei1995/ARPES-data-browser/blob/v1.2.1/docs/USER_GUIDE_en.md#31-autosave-memory-and-recovery)).

---

## Installing and starting

Needs Python 3.9+. With pip, which installs PyQt5, pyqtgraph, numpy,
h5py and scipy with it:

```
pip install arpes-viewer
arpes-viewer
```

(`python -m arpes_viewer` does the same; for the latest, unreleased
version: `pip install git+https://github.com/DingPei1995/ARPES-data-browser`.)
Installed this way, the error logs go to `~/.arpes_viewer/error_logs/`.

From a downloaded copy of this repository, with those packages installed:

```
python ARPES_viewer.py
```

- **Windows:** double-click **`ARPES viewer.pyw`** in this folder: no
  console window to close by mistake (the output goes to
  `~/.arpes_viewer/launcher.log`).
- **macOS:** double-click **`ARPES viewer.app`** in this folder. It finds a
  Python that has the packages (conda included), remembers it, and says what
  to install if none has. The first time, if macOS calls it an app from an
  unidentified developer: **System Settings → Privacy & Security → Open
  Anyway**.
- **No beamtime at hand?** `python devtools/demo_data.py` writes the
  synthetic demo data above to `demo_data/`
  ([trying it with demo data](https://github.com/DingPei1995/ARPES-data-browser/blob/v1.2.1/docs/USER_GUIDE_en.md#2-trying-it-with-demo-data)).

---

## Bug reports

The program saves what went wrong by itself, in
`error_logs/errors_<date>_<time>.txt` in its folder (in `~/.arpes_viewer/` when installed with pip), and keeps running. With
a bug report on [GitHub Issues](https://github.com/DingPei1995/ARPES-data-browser/issues),
**upload that file** (drag it into the text box) **or paste its text** -- the
main panel's foot has **Copy the newest error log** and **Open the error
logs** -- and give the version number.

---

## Documentation

- **User guide**, with screenshots: [English](https://github.com/DingPei1995/ARPES-data-browser/blob/v1.2.1/docs/USER_GUIDE_en.md) ·
  [中文](https://github.com/DingPei1995/ARPES-data-browser/blob/v1.2.1/docs/USER_GUIDE_zh.md) · [Français](https://github.com/DingPei1995/ARPES-data-browser/blob/v1.2.1/docs/USER_GUIDE_fr.md); as PDF:
  [English](https://github.com/DingPei1995/ARPES-data-browser/blob/v1.2.1/docs/pdf/ARPES_viewer_user_guide_en.pdf) ·
  [中文](https://github.com/DingPei1995/ARPES-data-browser/blob/v1.2.1/docs/pdf/ARPES_viewer_user_guide_zh.pdf) ·
  [Français](https://github.com/DingPei1995/ARPES-data-browser/blob/v1.2.1/docs/pdf/ARPES_viewer_user_guide_fr.pdf).
- **What changed, and why**: [CHANGELOG.md](https://github.com/DingPei1995/ARPES-data-browser/blob/v1.2.1/CHANGELOG.md).
- **Technical references**, beside the code they describe -- the formulas,
  the file layouts, the assumptions and the tests behind each step:
  - [Reading data](https://github.com/DingPei1995/ARPES-data-browser/blob/v1.2.1/arpes_viewer/loader/README.md) -- every facility's files, the data
    kinds, adding a beamline, the assumptions the formats force;
  - [The windows](https://github.com/DingPei1995/ARPES-data-browser/blob/v1.2.1/arpes_viewer/ui/README.md) -- the main panel, the viewers, autosave
    and recovery, long operations;
  - [Analysis](https://github.com/DingPei1995/ARPES-data-browser/blob/v1.2.1/arpes_viewer/tools/README.md) -- what each tool does and what it assumes;
    the tools ported from the MATLAB programs;
  - [Momentum conversion](https://github.com/DingPei1995/ARPES-data-browser/blob/v1.2.1/arpes_viewer/tools/momentum/README.md) -- k conversion, k_z
    maps;
  - [Spectra](https://github.com/DingPei1995/ARPES-data-browser/blob/v1.2.1/arpes_viewer/tools/spectra/README.md) -- core levels, curves, curve fits,
    spin;
  - [Processing](https://github.com/DingPei1995/ARPES-data-browser/blob/v1.2.1/arpes_viewer/tools/processing/README.md) -- de-gridding, cut
    arithmetic;
  - [Figures, export and the experiment log](https://github.com/DingPei1995/ARPES-data-browser/blob/v1.2.1/arpes_viewer/tools/output/README.md);
  - [For developers](https://github.com/DingPei1995/ARPES-data-browser/blob/v1.2.1/docs/DEVELOPER.md) -- the layout of the code, and the
    tests (`python -m pytest`).
