Classes | |
| struct | MapTraceEntry |
| struct | NonlinearLensInvariants |
Enumerations | |
| enum class | OnMissingLinearMap { IdentityWithWarning , IdentitySilent , Throw } |
Enumeration Type Documentation
◆ OnMissingLinearMap
|
strong |
Policy for how map_trace and linear_map handle elements whose transport_map evaluation throws, i.e. elements that do not provide an analytic linear transport map (for example NonlinearLens or Programmable).
The distinction between the two identity-substituting policies is deliberate: IdentityWithWarning is appropriate when the user has not asked for a fallback (e.g. from the Twiss diagnostic) and should be made aware that part of the lattice was ignored; IdentitySilent is appropriate when the user has explicitly opted in to the fallback (e.g. through transfer_map's fallback_identity_map=True kwarg) and does not want repeated warnings.
Function Documentation
◆ CubicRootsAlg()
| std::tuple< amrex::ParticleReal, amrex::ParticleReal, amrex::ParticleReal > impactx::diagnostics::CubicRootsAlg | ( | amrex::ParticleReal | a, |
| amrex::ParticleReal | b, | ||
| amrex::ParticleReal | c, | ||
| amrex::ParticleReal | d ) |
Function to return the roots of a cubic polynomial ax^3 + bx^2 + cx + d. The algebraic form of Cardano's formula is used. This implementation expects three real roots, which is verified by checking the sign of the discriminant.
- Parameters
-
[in] a coefficient of cubic term [in] b coefficient of quadratic term [in] c coefficient of linear term [in] d coefficient of constant term
- Returns
- tuple of three real roots
◆ CubicRootsTrig()
| std::tuple< amrex::ParticleReal, amrex::ParticleReal, amrex::ParticleReal > impactx::diagnostics::CubicRootsTrig | ( | amrex::ParticleReal | a, |
| amrex::ParticleReal | b, | ||
| amrex::ParticleReal | c, | ||
| amrex::ParticleReal | d ) |
Function to return the roots of a cubic polynomial ax^3 + bx^2 + cx + d. The trigonometric form of Cardano's formula is used. This implementation expects three real roots, which is verified by checking the sign of the discriminant.
- Parameters
-
[in] a coefficient of cubic term [in] b coefficient of quadratic term [in] c coefficient of linear term [in] d coefficient of constant term
- Returns
- tuple of three real roots
◆ DiagnosticOutput() [1/3]
| void impactx::diagnostics::DiagnosticOutput | ( | ImpactXParticleContainer const & | pc, |
| std::string | file_name, | ||
| int | step = 0, | ||
| bool | append = false ) |
ASCII output diagnostics associated with the beam particles.
This prints reduced beam characteristics derived from particles in ASCII.
- Parameters
-
pc container of the particles use for diagnostics file_name the file name to write to step the global step append open a new file with a fresh header (false) or append data to an existing file (true)
◆ DiagnosticOutput() [2/3]
| void impactx::diagnostics::DiagnosticOutput | ( | Map6x6 const & | cm, |
| RefPart const & | ref_part, | ||
| std::string | file_name, | ||
| int | step = 0, | ||
| bool | append = false ) |
ASCII output diagnostics associated with the covariance matrix.
This prints reduced beam characteristics derived from the envelope description in ASCII.
- Parameters
-
cm covariance matrix ref_part reference particle file_name the file name to write to step the global step append open a new file with a fresh header (false) or append data to an existing file (true)
◆ DiagnosticOutput() [3/3]
| void impactx::diagnostics::DiagnosticOutput | ( | RefPart const & | ref_part, |
| std::string | file_name, | ||
| int | step = 0, | ||
| bool | append = false ) |
ASCII output diagnostics associated with the reference particle.
This prints reference particle properties in ASCII.
- Parameters
-
ref_part reference particle file_name the file name to write to step the global step append open a new file with a fresh header (false) or append data to an existing file (true)
◆ Eigenemittances()
| std::tuple< amrex::ParticleReal, amrex::ParticleReal, amrex::ParticleReal > impactx::diagnostics::Eigenemittances | ( | amrex::SmallMatrix< amrex::ParticleReal, 6, 6, amrex::Order::F, 1 > const & | Sigma | ) |
This function returns the three eigenemittances denoted e1, e2, and e3 as constructed from the 6x6 beam covariance matrix. These three quantities are invariant under any linear symplectic transport map, and reduce to the projected normalized rms emittances in the limit of uncoupled transport.
input - Sigma symmetric 6x6 covariance matrix returns - tuple containing eigenemittances e1, e2, and e3
Returns the three eigenemittances denoted e1, e2, and e3 as constructed from the 6x6 beam covariance matrix. These three quantities are invariant under any linear symplectic transport map, and reduce to the projected normalized rms emittances in the limit of uncoupled transport. These quantities are described in:
G. Rangarajan, F. Neri, and A. Dragt, "Generalized Emittance Invariants," in Proc. 1989 IEEE Part. Accel. Conf., Chicago, IL, 1989, doi:10.1109/PAC.1989.73422. A. Dragt, F. Neri, and G. Rangarajan, "General Moment Invariants for Linear Hamiltonian Systems," Phys. Rev. A 45, 2572-2585 (1992), doi:10.1103/PhysRevA.45.2572.
- Parameters
-
[in] Sigma symmetric 6x6 covariance matrix
- Returns
- tuple containing eigenemittances e1, e2, and e3
◆ KineticInvariants()
| std::tuple< amrex::ParticleReal, amrex::ParticleReal, amrex::ParticleReal > impactx::diagnostics::KineticInvariants | ( | amrex::SmallMatrix< amrex::ParticleReal, 6, 6, amrex::Order::F, 1 > const & | Sigma | ) |
This function returns the three independent kinetic invariants denoted I2, I4, and I6 as constructed from the 6x6 beam covariance matrix. These three quantities are invariant under any linear symplectic transport map, and are used in the calculation of the three eigenemittances.
input - Sigma symmetric 6x6 covariance matrix returns - tuple containing invariants I2, I4, and I6
Returns the three independent kinematic moment invariants denoted I2, I4, and I6 as constructed from the 6x6 beam covariance matrix. These three quantities are invariant under any linear symplectic transport map, and are used in the calculation of the three eigenemittances, as described in:
G. Rangarajan, F. Neri, and A. Dragt, "Generalized Emittance Invariants," in Proc. 1989 IEEE Part. Accel. Conf., Chicago, IL, 1989, doi:10.1109/PAC.1989.73422. A. Dragt, F. Neri, and G. Rangarajan, "General Moment Invariants for Linear Hamiltonian Systems," Phys. Rev. A 45, 2572-2585 (1992), doi:10.1103/PhysRevA.45.2572.
- Parameters
-
[in] Sigma symmetric 6x6 covariance matrix
- Returns
- tuple containing invariants I2, I4, and I6
◆ linear_map()
| Map6x6 impactx::diagnostics::linear_map | ( | std::list< elements::KnownElements > const & | lattice, |
| RefPart const & | ref_part_init, | ||
| OnMissingLinearMap | on_missing = OnMissingLinearMap::IdentityWithWarning ) |
Return the end-to-end linear transport map of a lattice.
Convenience wrapper around map_trace that returns only the final cumulative map. For a ring, this is the one-turn map used as input to the Wolski eigendecomposition [Wolski, Phys. Rev. ST Accel. Beams 9, 024001 (2006); doi:10.1103/PhysRevSTAB.9.024001] of the periodic Twiss, tune, and dispersion diagnostics in impactx.twiss_lattice.compute_twiss (see the Python module for the full bibliography, including the Courant-Snyder [Ann. Phys. 3, 1 (1958)] and Mais-Ripken [DESY M-82-05, DESY 88-114] references that underlie the coupled parameterization).
- Parameters
-
[in] lattice list of lattice elements [in] ref_part_init reference particle at the starting s [in] on_missing policy for elements without a linear map; default is identity + warning
- Returns
- end-to-end 6x6 linear transport map
◆ map_trace()
| std::vector< MapTraceEntry > impactx::diagnostics::map_trace | ( | std::list< elements::KnownElements > const & | lattice, |
| RefPart const & | ref_part_init, | ||
| OnMissingLinearMap | on_missing = OnMissingLinearMap::IdentityWithWarning ) |
Compose the linear transport map element-by-element along a lattice.
Walks the lattice once, advancing a local copy of the reference particle through each element's non-linear reference-particle push and multiplying the cumulative 6x6 linear transport map by each element's per-slice transport_map. The caller's reference particle is not modified.
Slice ordering inside each element matches the envelope tracker in src/tracking/envelope.cpp : for each of nslice sub-steps, first advance the reference particle by one slice, then evaluate transport_map at the post-advance reference state. This keeps both code paths consistent for elements whose linear map depends on the reference momentum through the element (for example radio-frequency cavities).
Effects that are part of the non-linear tracker but not of the linear map are deliberately skipped here: space charge, Coherent Synchrotron Radiation (CSR), and Incoherent Synchrotron Radiation (ISR). The result is a purely element-by-element linear-optics trace appropriate for Twiss / tune / chromaticity / dispersion diagnostics.
Elements whose transport_map throws (for example NonlinearLens and Programmable explicitly reject a linear-map evaluation) are handled according to on_missing: either replaced by the identity (with a single warning per offending element type recorded via the ABLASTR warn manager) or re-raised as a std::runtime_error naming the offending element.
- Parameters
-
[in] lattice list of lattice elements to traverse [in] ref_part_init reference particle at the starting s [in] on_missing policy for elements without a linear map; default is identity + warning
- Returns
- vector of entries, size
lattice.size()+ 1 ; the first entry is the identity map at the starting s, each subsequent entry is the cumulative map at the exit of one element.
◆ reduced_beam_characteristics() [1/2]
| std::unordered_map< std::string, amrex::ParticleReal > impactx::diagnostics::reduced_beam_characteristics | ( | ImpactXParticleContainer const & | pc | ) |
Compute moments of the beam distribution from particle data
This uses an MPI Allreduce and returns a result on all ranks.
◆ reduced_beam_characteristics() [2/2]
| std::unordered_map< std::string, amrex::ParticleReal > impactx::diagnostics::reduced_beam_characteristics | ( | Map6x6 const & | cm, |
| RefPart const & | ref_part ) |
Compute moments of the beam distribution from covariance matrix
Generated by
1.13.2