pals2cosy

Convert PALS lattice files to COSY INFINITY input code.

Supports the official PALS format (PALS: root with facility:/line: composition) with auto-detection from the root key. Also accepts a flat beamline: format with positioned elements.

Installation

pip install pals2cosy

Or for development:

pip install -e .

Requires Python 3.9+ and PyYAML (for YAML input).

Usage

# PALS FODO cell (auto-detected from PALS: root key)
pals2cosy examples/fodo.pals.yaml --ke 1000 --particle proton

# Write to file with fringe fields
pals2cosy beamline.pals.yaml -o output.fox --ke 40 --fr 1

# Select a specific BeamLine from the facility
pals2cosy lattice.pals.yaml --beamline fodo_cell --ke 1000

# Compute Twiss parameters (periodic lattices only)
pals2cosy lattice.pals.yaml --ke 1000 --particle proton --twiss

Options

Input format

PALS:
  version: null
  facility:
    - q1:
        kind: Quadrupole
        length: 1.0
        MagneticMultipoleP:
          Bn1: 1.0           # Pole-tip field (Tesla)
    - b1:
        kind: SBend
        length: 2.0
        BendP:
          g_ref: 0.5         # Bend strength (1/m)
          e1: 0.1            # Entrance edge angle (radians)
          e2: 0.2            # Exit edge angle (radians)
    - my_line:
        kind: BeamLine
        line:
          - q1
          - b1

See examples/fodo.pals.yaml for a complete FODO cell with inherit: and repeat:.

Element mapping

Supported particles

Known limitations

• Drift fallback: All active elements fall back to drifts when their field parameters are absent.
• Enge coefficients: Maximum 6 coefficients per fringe field (COSY INFINITY FC command limit). Longer coefficient lists are truncated with a warning.
• Quad sign convention: The current-based quadrupole path (±G·I·r) uses an electron-specific sign convention (QPF→negative B, QPD→positive B). Proton beamlines should use Bn1 (pole-tip field) instead, which bypasses the sign logic.

Roadmap

pals2cosy implements provisional support for element types and parameters that are present in COSY INFINITY but not yet part of the official PALS specification, such as MagneticMultipoleP.Bn2–Bn5, SolenoidP.Bz, and RFCavityP. As a documented PALS use case, these extensions may inform future PALS standardization. If PALS adopts a different parameterization, pals2cosy can be adjusted accordingly.

Planned extensions:

• Combined-function magnets (dipole + multipole fields → COSY MC/MS)
• Electrostatic deflectors (EC, ECL, ES)
• Skew multipoles (MMS, EMS)
• Particle tracking (SR + TR + PRAY/WRAY)
• FIT optimization blocks

Acknowledgments

This work was supported in part by DOE EPSCoR Award DE-SC0025583. The converter is based in part on research performed on the University of Hawaiʻi free electron laser by the author.

Tests

pip install pytest
pytest tests/ -v