arpes-viewer 1.2.1__tar.gz

arpes_viewer-1.2.1/LICENSE.md

@@ -0,0 +1,75 @@
+Required Notice: Copyright (c) 2026 Ding Pei (https://github.com/DingPei1995/ARPES-data-browser)
+
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose.  However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to distribute copies of the software.  Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution is use for a permitted purpose regardless of the source of funding or obligations resulting from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else.  These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice.  Otherwise, all your licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization.  **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.

arpes_viewer-1.2.1/NOTICE

@@ -0,0 +1,43 @@
+ARPES viewer
+Copyright (c) 2026 Ding Pei
+https://github.com/DingPei1995/ARPES-data-browser
+
+Licensed under the PolyForm Noncommercial License 1.0.0 (see LICENSE.md):
+free for any noncommercial purpose -- research, teaching, personal use --
+and not for commercial use.
+
+Authorship
+----------
+ARPES viewer is the work of Ding Pei. It began as Ding Pei's own earlier
+code for ARPES data and was developed from it independently: it is not a
+work made for hire, and no institution funded or commissioned it.
+
+The requirements, the design decisions and their trade-offs, the choice of
+what to build and what not to, the physics, the testing on real
+experimental data and the feedback from it, and the review and acceptance
+of every change are Ding Pei's. The real-data tests drew on the
+measurements and calculations of these papers:
+  - Phys. Rev. B 103, 245121 (2021), https://doi.org/10.1103/PhysRevB.103.245121
+  - Phys. Rev. B 95, 125126 (2017), https://doi.org/10.1103/PhysRevB.95.125126
+
+The implementation was carried out with the assistance of Claude, an AI
+model by Anthropic, as a coding assistant working under Ding Pei's
+direction; the commits it helped write name it as a
+co-author ("Co-Authored-By: Claude").
+
+Third-party data
+----------------
+The X-ray line energies in the synthetic demo data, and the core-level
+binding energies of the core-level check, are standard tabulated values
+(the X-ray Data Booklet, Lawrence Berkeley National Laboratory; core levels
+from its Table 1-1, J. A. Bearden & A. F. Burr).
+
+The space-group tables (arpes_viewer/tools/crystal/spacegroups.py) were
+generated once from the database of spglib (devtools/gen_spacegroups.py),
+Copyright (c) Atsushi Togo, distributed under the BSD 3-Clause licence.
+
+The colour tables (arpes_viewer/tools/output/colormaps.py) were converted
+from a laboratory file, Colormap.mat, together with re-creations of
+MATLAB's gray, jet, hsv, hot and copper (devtools/gen_colormaps.py). Several
+of them carry the names of Igor Pro's colour tables; where they reproduce
+those, they remain WaveMetrics' and are not covered by the licence above.

arpes_viewer-1.2.1/PKG-INFO

@@ -0,0 +1,246 @@
+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`).

arpes_viewer-1.2.1/README.md

@@ -0,0 +1,218 @@
+# 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`).

arpes_viewer-1.2.1/arpes_viewer/__init__.py

@@ -0,0 +1,11 @@
+"""ARPES viewer: browse, convert, analyse and lay out ARPES data as
+publication figures. ``arpes-viewer`` (or ``python -m arpes_viewer``)
+starts the program; :mod:`arpes_viewer.tools` holds the computations, free
+of any user interface, for scripts.
+
+Copyright (c) 2026 Ding Pei. Licensed under the PolyForm Noncommercial
+License 1.0.0 (LICENSE.md).
+"""
+from arpes_viewer.version import VERSION as __version__
+
+__all__ = ["__version__"]

arpes_viewer-1.2.1/arpes_viewer/__main__.py

@@ -0,0 +1,6 @@
+"""``python -m arpes_viewer``: start the program."""
+import sys
+
+from arpes_viewer.app import main
+
+sys.exit(main())