NonlinearNormalForm

Overview

This package can be used for doing perturbation theory with nonlinear, parametric Hamiltonian maps using Lie algebraic methods. Maps with large damping can be handled. Given a map expressed as a truncated power series in small deviations of the variables and parameters, this package can be used to calculate and analyze the canonical transformation to the normal form – coordinates where the motion lies on action-dependent circles in phase space or contains a single resonance. This allows for easy calculation of all important (parameter-dependent) properties of the map. Furthermore, by extending the Lie algebra to include a quaternion operator in the vector field, the spin normal form analysis can be performed in the same way as the orbital. This fully unifies spin and orbital one-resonance normal form calculations, without needing to learn two different theories, and allows for analysis of time-dependent Hamiltonians via Deprit-like algorithms. The package is used in the SciBmad accelerator physics ecosystem for all analysis, and may also be of interest in fields such as celestial mechanics, electronic circuits, electron microscopy, geometrical optics, and plasma physics.

Setup

To use this package, in the Julia REPL run:

import Pkg; Pkg.add(url="https://github.com/bmad-sim/NonlinearNormalForm.jl")

Basic Usage

This package includes real and complex differential algebraic (DA) maps with properly overloaded operators, map composition and inversion, parametric normal form calculation routines optionally including a "coasting" plane (including a constant "energy-like" canonical variable), factorization of the normalizing map, Lie operators including a quaternion for spin, calculations such as exp of Lie operators to construct Lie maps or the log of Lie maps to obtain the Lie operator, and one resonance normal form analysis tools.

After a DAMap is calculated via tracking of a truncated power series, the map can be analyzed using the routines here. Some example maps randomly generated by FPP are provided in the test directory.

julia> m = DAMap(v=v, q=q) # make a DA map from orbital ray (v) and optionally spin quaternion (q)

julia> m_lin = cutord(m, 2); # extract the linear part in orbital

julia> m_nonlinear = inv(m_lin) ∘ m; # remove the linear part

julia> F = log(m_nonlinear); # Get the Lie operator (including quaternion) generating nonlinear part

julia> m = m_lin ∘ exp(F);  # Reconstruct same map using Lie exponent and linear part separately

julia> a = normal(m);  # Calculate the nonlinear (parametric) normalizing canonical transformation

julia> R_z = inv(a) ∘ m ∘ a; # Nonlinear amplitude-dependent rotation in regular phase space (x, px, …)

julia> c = c_map(m);  # Get the transform to phasors basis √(J)*exp(±im*ϕ)

julia> R_J = inv(c) ∘ R_z ∘ c; # Nonlinear amplitude-dependent rotation in phasors basis

julia> a_spin, a0, a1, a2 = factorize(a); # Spin part, nonlinear parameter-dependent fixed point, a1, a2

julia> Σ = equilibrium_moments(m, a); # Calculate equilibrium sigma matrix when fluctuation-dissipation

julia> a = normal(m, m=[0; 1], m_spin=[-1]);  # Leaving in a Q_y - Q_spin resonance

History and Acknowledgement

This NonlinearNormalForm package is inspired by the Full Polymorphic Package (FPP) library written by Etienne Forest (AKA Patrice Nishikawa) in Fortran90. Much thanks must go to Etienne for his time and patience in teaching the normal form methods and guiding the implementation of the tools in this package.