Getting Started¶

ERLabPy provides two main workflows for ARPES analysis: a notebook-based Python workflow and a GUI-centered workflow using ImageTool Manager. Install ERLabPy first, verify the installation, and then choose the learning path that matches your work.

Installing¶

Use Conda with Miniforge if you are new to Python package management. Select an installation method below. The additional packages in each command enable the Qt applications and notebook widgets used in the tutorials.

Conda

Create or activate a Conda environment, then run:

conda install -c conda-forge erlab pyqt6 ipywidgets

Miniforge is the recommended Conda distribution. The Scikit-HEP Conda guide explains how to create and use environments.

Tip

On macOS, the default BLAS and LAPACK libraries can reduce numerical performance. On an Apple Silicon Mac, use Accelerate:

conda install "libblas=*=*_newaccelerate"

On an Intel Mac, use MKL:

conda install "libblas=*=*mkl"

See the conda-forge BLAS documentation to keep this selection when you update the environment.

Pip

Create and activate a virtual environment, then run:

python -m pip install "erlab[complete]" pyqt6

See the Python Packaging User Guide if you need help creating a virtual environment.

Create a project and add ERLabPy:

uv init my-project
cd my-project
uv add "erlab[complete]" pyqt6

See the uv installation guide if uv is not installed.

Pixi

Create a workspace and add ERLabPy:

pixi init my-project
cd my-project
pixi add erlab pyqt6 ipywidgets

See the Pixi installation guide if pixi is not installed.

Standalone application

Download ImageTool Manager from GitHub Releases if you want to use the GUI without installing Python. Follow the platform instructions after downloading it.

Important

Install PyQt6 or PySide6 in the same environment as ERLabPy to use ImageTool and the other interactive tools. The commands above install PyQt6. Replace pyqt6 with pyside6 if you prefer PySide6. Qt5 bindings are not supported.

For optional dependency groups, compatibility details, and platform notes, see Dependencies and compatibility. To install a development checkout, see Creating a development environment.

Verifying the installation¶

Print the installed ERLabPy version:

python -c "import erlab; print(erlab.__version__)"

Confirm that Qt is available:

python -c "from qtpy import API_NAME; print(API_NAME)"

Launch ImageTool Manager:

itool-manager

Before the tutorial¶

The Python tutorial assumes that you can run notebook cells, import packages, call functions, and read basic Python errors. The tutorial introduces the xarray structure and ERLabPy data conventions that it uses.

Use these resources if you need a review:

Tip

For notebook work, use Visual Studio Code with the Jupyter extension and the ERLab extension.

Choosing a workflow¶

First notebook is the recommended learning path. It uses one generated dataset to introduce inspection, coordinate selection, plotting, and momentum conversion. It also shows how to open the data in ImageTool from Python.

To understand how GUI and Python work together, see Python and GUI workflows. To learn the current Manager workflow without a notebook, start the ImageTool Manager tutorial.

The two workflows can exchange data and reproducible code. See Python and GUI workflows for the relationship between them.

AI assistance¶

The ARPES Analysis Assistant provides ChatGPT-based help. It can give code examples, explain functions and parameters, and give general guidance about installing and using ERLabPy.
The arpes-analysis agent skill helps coding agents answer questions about ERLabPy and perform basic analysis tasks. With the GitHub CLI installed, run:
```
gh skill install kmnhan/erlabpy arpes-analysis
```
This skill is still a work in progress.

Warning

Large language models are not a source of truth. Verify API details in the Reference section. Generated code can contain errors. Review and test it, and validate its analysis on your data.