PyELEGANT

Python Interface to the 6D Accelerator Program ELEGANT (ELEctron Generation ANd Tracking)

Overview

PyELEGANT provides a comprehensive Python interface to the ELEGANT accelerator physics simulation code, enabling advanced beam dynamics calculations, lattice optimization, and analysis workflows.

Installation

Prerequisites

• Python 3.12.* (for pixi setup)
• pixi (recommended) or conda/mamba

Using Pixi (Recommended)

Pixi is a fast, modern package manager that simplifies environment management. Install it following the official instructions.

Note for conda users: Unlike conda, pixi environments are project-specific and tied to the repository directory (where pixi.toml lives). You must be in the PyELEGANT directory to use pixi shell or pixi run commands. To use the environment from other directories, use pixi shell --manifest-path /path/to/PyELEGANT/pixi.toml.

Quick Start

1. Clone the repository:

   git clone https://github.com/NSLS2/PyELEGANT.git
   cd PyELEGANT

2. Configure for your facility (can skip if you don't plan to use a cluster):

   cp .env.example .env
   # Edit .env and set PYELEGANT_REMOTE to your facility (e.g., nsls2pluto)

3. Set up the environment and install PyELEGANT:

   pixi run install-editable

   This automatically creates the environment and installs PyELEGANT in editable/development mode.

4. Activate the environment:

   pixi shell

   The .env file will be automatically loaded, setting PYELEGANT_REMOTE for your facility.

5. Run commands in the environment:

   pixi run python your_script.py
   pixi run jupyter lab

   To open Jupyter notebooks in VS Code:

   code your_notebook.ipynb

Using the Environment from Other Directories

After the initial setup, you can activate the environment from anywhere using --manifest-path:

pixi shell --manifest-path /path/to/PyELEGANT/pixi.toml

This allows you to work with PyELEGANT while being in a different directory.

Note: The pixi configuration includes cluster compatibility requirements (Python 3.12.*, icu < 78) to prevent library version conflicts on compute clusters. Environment variables from .env are automatically loaded when importing pyelegant.

Available Environments

PyELEGANT provides multiple environments for different use cases. After running pixi install, use pixi run install-editable to install the package, or pixi run install-editable-all for all optional dependencies:

• default: Base installation with Jupyter support (Python 3.12.*)

  pixi install
  pixi run install-editable

• parallel: Includes MPI support for parallel computing (mpi4py)

  pixi install --environment parallel
  pixi shell --environment parallel
  pixi run install-editable

  NSLS-II cluster note: If mpi4py fails with libmpi.so.12: cannot open shared object file, run the following once after install (requires mpicc in PATH via module load mpich):

  pixi run fix-mpi4py-soname

  See Known Issues for details.

• genreport: Includes tools for report generation (PyLaTeX, XlsxWriter)

  pixi install --environment genreport
  pixi run install-editable

• all: All optional dependencies

  pixi install --environment all
  pixi run install-editable-all

• dev: Development environment with testing tools

  pixi install --environment dev
  pixi run install-editable-all
  pixi run test  # Run tests

Using Poetry (Alternative)

If you prefer poetry:

poetry install
poetry install --extras "all"  # Install all optional dependencies

Using pip (Basic Installation)

pip install -e .
pip install -e ".[all]"  # Install all optional dependencies

Features

Core Functionality

• Twiss Calculations: Linear optics and Twiss parameters
• Closed Orbit Analysis: On-momentum and off-momentum closed orbits
• Nonlinear Dynamics: Frequency map analysis, dynamic aperture
• Tune & Chromaticity Correction: Automated optimization routines
• Lattice Generation: Programmatic LTE file creation
• Parallel Computing: MPI-based parallel tracking and optimization

Optional Features

• Jupyter Integration (jupy): Interactive notebooks with plotting support
• Parallel Computing (parallel): MPI support for distributed calculations
• Report Generation (genreport): Automated LaTeX/Excel report creation
• All Features (all): Complete installation with all optional dependencies

Quick Start

Basic Twiss Calculation

import pyelegant as pe

# Calculate ring twiss parameters
LTE_filepath = 'your_lattice.lte'
E_MeV = 3000  # Beam energy in MeV
output_filepath = 'twiss_results.hdf5'

pe.calc_ring_twiss(output_filepath, LTE_filepath, E_MeV,
                   radiation_integrals=True)

# Plot results
pe.plot_twiss(output_filepath)

Using Jupyter Notebooks

Launch Jupyter Lab:

pixi run jupyter lab

Example notebooks are available in the demo/ directory.

Console Scripts

PyELEGANT provides several command-line utilities:

Common Scripts

• pyele_zip_lte: Compress LTE files
• pyele_unzip_lte: Decompress LTE files
• pyele_report: Generate analysis reports

SLURM Cluster Scripts (NSLS-II specific)

• pyele_slurm_print_queue: Display SLURM queue status
• pyele_slurm_print_load: Show cluster load
• pyele_scancel_regex_jobname: Cancel jobs by pattern
• pyele_slurm_nfree_change: Monitor available cores

GUI Applications

• pyele_gui_slurm: SLURM job management GUI
• pyele_gui_report_wiz: Report generation wizard

Development

Running Tests

pixi run test

Or with pytest directly:

pixi run pytest tests/

Pre-commit Hooks

Set up pre-commit hooks for code quality:

pixi run -e dev pre-commit install

Documentation

• Detailed examples in demo/ directory
• Jupyter notebooks demonstrating key features
• API documentation (coming soon)

Requirements

System Requirements

• Python: 3.12.* (pinned for cluster compatibility)
• icu: < 78 (required to avoid CXXABI version conflicts on compute clusters)

Core Dependencies

• numpy >= 2.3.2
• scipy >= 1.16.1
• matplotlib >= 3.10
• h5py >= 3.14.0
• pydantic >= 2.12
• ruamel.yaml 0.17.*

Optional Dependencies

• jupyter, ipympl (for Jupyter support)
• mpi4py, dill (for parallel computing)
• PyQt5, QtPy (for GUI applications)
• PyLaTeX, XlsxWriter (for report generation)

Known Issues

mpi4py on NSLS-II cluster with MPICH 4.3.0b1

The NSLS-II cluster (as of 2026-02) uses MPICH 4.3.0b1, which provides libmpi.so.0 instead of the libmpi.so.12 soname used by MPICH stable releases. The mpi4py 4.x pre-built wheel hardcodes libmpi.so.12, causing an ImportError when workers start on compute nodes.

Workaround: Run once after install (requires mpicc in PATH via module load mpich):

pixi run fix-mpi4py-soname

This creates a libmpi.so.12 → libmpi.so.0 symlink in ~/.local/lib. The pixi activation script (pixi_activation.sh) automatically prepends ~/.local/lib to LD_LIBRARY_PATH when you run pixi shell. SLURM propagates LD_LIBRARY_PATH from the submission shell to compute nodes, so no extra steps are needed after running the task.

This is a one-time setup per user. It is not needed once the cluster upgrades to a stable MPICH 4.x release (which will restore the libmpi.so.12 soname).

Quick test after the workaround:

pixi run python -c "from mpi4py import MPI; print(MPI.Get_version())"

License

BSD 3-Clause License. See LICENSE for details.

Authors

• Yoshiteru Hidaka - Maintainer - yhidaka@bnl.gov

Repository

GitHub: https://github.com/NSLS2/PyELEGANT

Acknowledgments

Developed at Brookhaven National Laboratory's National Synchrotron Light Source II (NSLS-II).