pyffag 0.1.0__tar.gz

pyffag-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eremey Valetov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyffag-0.1.0/PKG-INFO

@@ -0,0 +1,101 @@
+Metadata-Version: 2.4
+Name: pyffag
+Version: 0.1.0
+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
+
+# 150 MeV proton FFAG ring: 12 FDF-triplet cells
+DA.init(7, 2)  # DA order 7, 2 variables (x, px)
+Brho = kinetic_to_brho(150.0, M_PROTON)  # magnetic rigidity [T·m]
+
+# F magnet: B(x) = 1.2 + 3.0*x + 4.0*x² [T], 12° sector
+F = sector_map([1.2, 3.0, 4.0], Brho, angle=np.radians(12.0))
+
+# D magnet: B(x) = 1.2 − 5.0*x − 5.0*x² [T], 6° sector
+D = sector_map([1.2, -5.0, -5.0], Brho, angle=np.radians(6.0))
+
+# One cell = F + D + F, full ring = 12 cells
+cell = compose_sequence([F, D, F])
+ring = compose_n(cell, 12)
+
+print(f"Cell tune: {twiss(cell)['tune']:.4f}")
+print(f"Ring tune: {tune(ring):.4f}")
+```
+
+## Features
+
+- **Sector magnet tracking**: Exact midplane Hamiltonian integration
+  (no paraxial approximation) through sector magnets with polynomial
+  field profiles B(x) = B₀ + B₁x + B₂x² + ...
+- **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 equations of motion in Frenet-Serret
+(curvilinear) coordinates with arc length as the independent variable:
+
+```
+dx/ds  = (1 + hx) · px / √(1 − px²)
+dpx/ds = h · √(1 − px²) − (1 + hx) · By(x) / (Bρ)
+```
+
+where h = 1/ρ is the reference curvature.  Sector magnets have radial edge
+faces (no edge focusing).  The exact sqrt formulation captures kinematic
+nonlinearities that the paraxial approximation misses.
+
+## Integration with danf
+
+Use with [danf](https://pypi.org/project/danf/) for nonlinear normal form
+analysis (amplitude-dependent tune shifts, resonance driving terms):
+
+```python
+from danf import NormalForm
+
+nf = NormalForm(ring)
+nf.compute()
+print(f"ADTS: dν/dε = {nf.detuning['dnux_dJx'] / 2:.4f}")
+```
+
+## License
+
+MIT

pyffag-0.1.0/README.md

@@ -0,0 +1,81 @@
+# 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
+
+# 150 MeV proton FFAG ring: 12 FDF-triplet cells
+DA.init(7, 2)  # DA order 7, 2 variables (x, px)
+Brho = kinetic_to_brho(150.0, M_PROTON)  # magnetic rigidity [T·m]
+
+# F magnet: B(x) = 1.2 + 3.0*x + 4.0*x² [T], 12° sector
+F = sector_map([1.2, 3.0, 4.0], Brho, angle=np.radians(12.0))
+
+# D magnet: B(x) = 1.2 − 5.0*x − 5.0*x² [T], 6° sector
+D = sector_map([1.2, -5.0, -5.0], Brho, angle=np.radians(6.0))
+
+# One cell = F + D + F, full ring = 12 cells
+cell = compose_sequence([F, D, F])
+ring = compose_n(cell, 12)
+
+print(f"Cell tune: {twiss(cell)['tune']:.4f}")
+print(f"Ring tune: {tune(ring):.4f}")
+```
+
+## Features
+
+- **Sector magnet tracking**: Exact midplane Hamiltonian integration
+  (no paraxial approximation) through sector magnets with polynomial
+  field profiles B(x) = B₀ + B₁x + B₂x² + ...
+- **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 equations of motion in Frenet-Serret
+(curvilinear) coordinates with arc length as the independent variable:
+
+```
+dx/ds  = (1 + hx) · px / √(1 − px²)
+dpx/ds = h · √(1 − px²) − (1 + hx) · By(x) / (Bρ)
+```
+
+where h = 1/ρ is the reference curvature.  Sector magnets have radial edge
+faces (no edge focusing).  The exact sqrt formulation captures kinematic
+nonlinearities that the paraxial approximation misses.
+
+## Integration with danf
+
+Use with [danf](https://pypi.org/project/danf/) for nonlinear normal form
+analysis (amplitude-dependent tune shifts, resonance driving terms):
+
+```python
+from danf import NormalForm
+
+nf = NormalForm(ring)
+nf.compute()
+print(f"ADTS: dν/dε = {nf.detuning['dnux_dJx'] / 2:.4f}")
+```
+
+## License
+
+MIT

pyffag-0.1.0/pyffag/__init__.py

@@ -0,0 +1,51 @@
+"""pyffag — DA-based FFAG accelerator tracking.
+
+Built on daceypy for arbitrary-order differential algebra arithmetic,
+pyffag provides transfer map computation through FFAG sector magnets
+via integration of the exact midplane Hamiltonian.
+
+Example
+-------
+>>> from daceypy import DA
+>>> from pyffag import sector_map, compose_n, tune
+>>> from pyffag.constants import kinetic_to_brho, M_PROTON
+>>>
+>>> DA.init(5, 2)
+>>> Brho = kinetic_to_brho(150.0, M_PROTON)
+>>> cell = sector_map([1.0], Brho, angle=0.5236)  # 30-degree uniform dipole
+>>> ring = compose_n(cell, 12)
+>>> print(f"Tune: {tune(ring):.4f}")
+"""
+
+from pyffag.sector import sector_map
+from pyffag.elements import (
+    drift_map,
+    drift_map_paraxial,
+    edge_kick,
+    thin_quad,
+    thin_sext,
+    thin_oct,
+)
+from pyffag.ring import compose, compose_sequence, compose_n, find_closed_orbit
+from pyffag.optics import transfer_matrix, tune, is_stable, twiss, symplecticity_error
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "sector_map",
+    "drift_map",
+    "drift_map_paraxial",
+    "edge_kick",
+    "thin_quad",
+    "thin_sext",
+    "thin_oct",
+    "compose",
+    "compose_sequence",
+    "compose_n",
+    "find_closed_orbit",
+    "transfer_matrix",
+    "tune",
+    "is_stable",
+    "twiss",
+    "symplecticity_error",
+]

pyffag-0.1.0/pyffag/constants.py

@@ -0,0 +1,73 @@
+"""Physical constants for accelerator physics (SI + natural units)."""
+
+# Speed of light [m/s]
+C_LIGHT = 299792458.0
+
+# Proton mass [MeV/c^2]
+M_PROTON = 938.27208816
+
+# Electron mass [MeV/c^2]
+M_ELECTRON = 0.51099895069
+
+# Muon mass [MeV/c^2]
+M_MUON = 105.6583755
+
+# Elementary charge [C]
+E_CHARGE = 1.602176634e-19
+
+# Conversion: momentum [MeV/c] to magnetic rigidity [T·m]
+# Brho = p / (q * c) = p [eV/c] / (e * c) = p [MeV/c] * 1e6 / (c)
+# In convenient units: Brho [T·m] = p [MeV/c] / 299.792458
+BRHO_FACTOR = 1e6 / C_LIGHT  # multiply by p [MeV/c] to get Brho [T·m]
+
+
+def kinetic_to_momentum(T, mass):
+    """Convert kinetic energy to momentum.
+
+    Parameters
+    ----------
+    T : float
+        Kinetic energy [MeV].
+    mass : float
+        Rest mass [MeV/c^2].
+
+    Returns
+    -------
+    float
+        Momentum [MeV/c].
+    """
+    return (T * (T + 2 * mass)) ** 0.5
+
+
+def momentum_to_brho(p):
+    """Convert momentum to magnetic rigidity.
+
+    Parameters
+    ----------
+    p : float
+        Momentum [MeV/c].
+
+    Returns
+    -------
+    float
+        Magnetic rigidity Bρ [T·m].
+    """
+    return p * BRHO_FACTOR
+
+
+def kinetic_to_brho(T, mass):
+    """Convert kinetic energy to magnetic rigidity.
+
+    Parameters
+    ----------
+    T : float
+        Kinetic energy [MeV].
+    mass : float
+        Rest mass [MeV/c^2].
+
+    Returns
+    -------
+    float
+        Magnetic rigidity Bρ [T·m].
+    """
+    return momentum_to_brho(kinetic_to_momentum(T, mass))

pyffag-0.1.0/pyffag/elements.py

@@ -0,0 +1,116 @@
+"""Standard beam-line elements as DA maps (midplane, 1 DOF)."""
+
+import numpy as np
+from daceypy import DA
+
+
+def drift_map(length):
+    """Exact drift-space map (no paraxial approximation).
+
+    Uses the exact expression x' = x + L * px / sqrt(1 - px^2).
+
+    Parameters
+    ----------
+    length : float
+        Drift length [m].
+
+    Returns
+    -------
+    list of DA
+        [x_out, px_out].
+    """
+    x, px = DA(1), DA(2)
+    ps = DA.sqrt(1.0 - px * px)
+    return [x + length * px / ps, px]
+
+
+def drift_map_paraxial(length):
+    """Paraxial drift-space map: x' = x + L*px.
+
+    Parameters
+    ----------
+    length : float
+        Drift length [m].
+
+    Returns
+    -------
+    list of DA
+        [x_out, px_out].
+    """
+    x, px = DA(1), DA(2)
+    return [x + length * px, px]
+
+
+def edge_kick(h, e1):
+    """Thin edge-focusing kick for a rectangular (non-sector) magnet.
+
+    At an edge tilted by angle e1 from the radial direction, the
+    horizontal kick is dpx = +h * tan(e1) * x.
+
+    For a sector magnet (radial edges), e1 = 0 and there is no kick.
+
+    Parameters
+    ----------
+    h : float
+        Reference curvature 1/rho [1/m].
+    e1 : float
+        Edge angle [rad].  Positive = edge rotated toward the magnet body.
+
+    Returns
+    -------
+    list of DA
+        [x_out, px_out].
+    """
+    x, px = DA(1), DA(2)
+    return [x, px + h * np.tan(e1) * x]
+
+
+def thin_quad(k1L):
+    """Thin quadrupole kick: dpx = -k1L * x.
+
+    Parameters
+    ----------
+    k1L : float
+        Integrated quadrupole strength [1/m].
+
+    Returns
+    -------
+    list of DA
+        [x_out, px_out].
+    """
+    x, px = DA(1), DA(2)
+    return [x, px - k1L * x]
+
+
+def thin_sext(k2L):
+    """Thin sextupole kick: dpx = -(k2L/2) * x^2.
+
+    Parameters
+    ----------
+    k2L : float
+        Integrated sextupole strength [1/m^2].
+
+    Returns
+    -------
+    list of DA
+        [x_out, px_out].
+    """
+    x, px = DA(1), DA(2)
+    return [x, px - (k2L / 2) * x ** 2]
+
+
+def thin_oct(k3L):
+    """Thin octupole kick: dpx = -(k3L/6) * x^3.
+
+    Parameters
+    ----------
+    k3L : float
+        Integrated octupole strength [1/m^3].
+
+    Returns
+    -------
+    list of DA
+        [x_out, px_out].
+    """
+    x, px = DA(1), DA(2)
+    return [x, px - (k3L / 6) * x ** 3]

pyffag-0.1.0/pyffag/optics.py

@@ -0,0 +1,118 @@
+"""Linear optics extraction from DA transfer maps."""
+
+import numpy as np
+
+
+def transfer_matrix(da_map):
+    """Extract the 2x2 transfer matrix from a DA map.
+
+    Parameters
+    ----------
+    da_map : list of DA
+        [x', px'] map components.
+
+    Returns
+    -------
+    ndarray, shape (2, 2)
+        Transfer matrix M.
+    """
+    M = np.zeros((2, 2))
+    M[0, 0] = da_map[0].getCoefficient([1, 0])
+    M[0, 1] = da_map[0].getCoefficient([0, 1])
+    M[1, 0] = da_map[1].getCoefficient([1, 0])
+    M[1, 1] = da_map[1].getCoefficient([0, 1])
+    return M
+
+
+def tune(da_map):
+    """Extract the fractional tune from a DA map.
+
+    Parameters
+    ----------
+    da_map : list of DA
+        One-turn (or one-cell) [x', px'] map.
+
+    Returns
+    -------
+    float
+        Fractional tune nu in [0, 0.5].
+    """
+    M = transfer_matrix(da_map)
+    cos_mu = (M[0, 0] + M[1, 1]) / 2.0
+    cos_mu = np.clip(cos_mu, -1.0, 1.0)
+    return np.arccos(cos_mu) / (2.0 * np.pi)
+
+
+def is_stable(da_map):
+    """Check if the linear map is stable (|Tr M| < 2).
+
+    Parameters
+    ----------
+    da_map : list of DA
+        [x', px'] map.
+
+    Returns
+    -------
+    bool
+    """
+    M = transfer_matrix(da_map)
+    return abs(M[0, 0] + M[1, 1]) < 2.0
+
+
+def twiss(da_map):
+    """Extract Courant-Snyder (Twiss) parameters from a periodic map.
+
+    Assumes the map is one full period (cell or ring) and is stable.
+
+    Parameters
+    ----------
+    da_map : list of DA
+        One-period [x', px'] map.
+
+    Returns
+    -------
+    dict
+        {'beta': float, 'alpha': float, 'gamma': float, 'tune': float}
+        beta in [m], alpha dimensionless, gamma in [1/m].
+    """
+    M = transfer_matrix(da_map)
+    cos_mu = (M[0, 0] + M[1, 1]) / 2.0
+
+    if abs(cos_mu) >= 1.0:
+        raise ValueError(f"Unstable map: Tr/2 = {cos_mu:.6f}")
+
+    mu = np.arccos(np.clip(cos_mu, -1.0, 1.0))
+    sin_mu = np.sin(mu)
+
+    # Sign of sin(mu): from M12
+    if M[0, 1] < 0:
+        sin_mu = -sin_mu
+        mu = 2 * np.pi - mu
+
+    beta = M[0, 1] / sin_mu
+    alpha = (M[0, 0] - M[1, 1]) / (2.0 * sin_mu)
+    gamma = -M[1, 0] / sin_mu
+
+    return {
+        'beta': beta,
+        'alpha': alpha,
+        'gamma': gamma,
+        'tune': mu / (2.0 * np.pi),
+    }
+
+
+def symplecticity_error(da_map):
+    """Check how far the linear map is from symplectic (det M - 1).
+
+    Parameters
+    ----------
+    da_map : list of DA
+        [x', px'] map.
+
+    Returns
+    -------
+    float
+        |det(M) - 1|.
+    """
+    M = transfer_matrix(da_map)
+    return abs(np.linalg.det(M) - 1.0)