Metadata-Version: 2.4
Name: pyffag
Version: 0.2.2
Summary: DA-based FFAG accelerator tracking using differential algebra
Author-email: Eremey Valetov <evv@msu.edu>
License: MIT
Project-URL: Repository, https://github.com/evvaletov/pyffag
Keywords: FFAG,accelerator,beam physics,differential algebra,transfer map
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: daceypy>=1.3.0
Requires-Dist: numpy>=1.24
Dynamic: license-file

# pyffag

DA-based FFAG accelerator tracking using differential algebra.

Built on [daceypy](https://pypi.org/project/daceypy/) for arbitrary-order
transfer map computation through FFAG sector magnets via integration of the
exact midplane Hamiltonian.

## Installation

```bash
pip install pyffag
```

## Quick start

```python
import numpy as np
from daceypy import DA
from pyffag import sector_map, compose_sequence, compose_n, tune, twiss
from pyffag.constants import kinetic_to_brho, M_PROTON

# 250 MeV proton FFAG ring: 8 FD doublet cells
DA.init(5, 2)  # DA order 5, 2 variables (x, px)
Brho = kinetic_to_brho(250.0, M_PROTON)

# F magnet: horizontally focusing sector, 25 degrees
F = sector_map([0.9, 2.0], Brho, angle=np.radians(25.0))

# D magnet: horizontally defocusing sector, 20 degrees
D = sector_map([0.9, -3.0], Brho, angle=np.radians(20.0))

# One cell = F + D, full ring = 8 cells
cell = compose_sequence([F, D])
ring = compose_n(cell, 8)

print(f"Cell tune: {twiss(cell)['tune']:.4f}")
print(f"Ring tune: {tune(ring):.4f}")
```

## Features

- **Sector magnet tracking**: Hamiltonian integration through sector
  magnets with polynomial field profiles. Midplane (`sector_map`, 2 DOF)
  and full 4D (`sector_map_4d`, with Maxwell-consistent off-midplane
  field expansion)
- **Element maps**: Drift (exact), thin quadrupole, sextupole, octupole,
  edge kicks for rectangular magnets
- **Ring operations**: Map composition, N-fold composition, closed orbit
  finding via Newton's method with DA Jacobian
- **Optics**: Tune, Twiss parameters, stability check, symplecticity error

## Physics

The core `sector_map()` integrates the midplane equations of motion
in Frenet-Serret (curvilinear) coordinates with arc length as the
independent variable.  Sector magnets have radial edge faces
(no edge focusing).

## Integration with danf

Use with [danf](https://pypi.org/project/danf/) for nonlinear normal form
analysis (amplitude-dependent tune shifts):

```python
from danf import NormalForm

nf = NormalForm(ring)
nf.compute()
print(nf.tunes)
print(nf.detuning)
```

## License

MIT
