Package xal.model
The Online Model
Introduction
Here we list some general notes and descriptions of the online model operation. The procedure for running simulations is well documented in many other sources, including the official Open XAL web site and the ESS Open XAL web site.
Running Simulations
Scenarios
To simulate a section of beamline, one first needs to create an online model object for
that beamline. This object is of type xal.sim.Scenario
. The scenario object
is instantiated for a particular AcceleratorSeq
object representing the
section of beamline to be simulated.
Probes
The type of simulation is determined by the type of probe object used in the
simulation; that is, provided to the scenario object. For example, to simulate a
single particle, or beam centroid, a probe of type
xal.model.probe.ParticleProbe
is used. For an envelope simulation an
xal.model.probe.EnvelopeProbe
object would be instantiated. To create
these probes a factory class exists, xal.sim.scenario.ProbeFactory
.
However, an algorithm object must first be created before a probe can be
instantiated with the factory (see below).
Synchronization
Once the algorithm, probe, and scenario are created, before the simulation can be run
a synchronization scheme must be chosen. This is done with the method
Scenario.setSynchronizationMode()
. Listed below are the possible arguments
for this method and their result.
SYNC_MODE_LIVE - synchronizes the beamline model parameters to the live machine values
SYNC_MODE_DESIGN - set the beamline model parameters to the machine design values
SYNC_MODE_RF_DESIGN - the RF parameters are set to design, all others are live values
There is one other option. The PVLogger
service can be used to retrieve historical
machine states and align all the model parameters to these values. The class that performs this
function is xal.service.pvlogger.sim
.
Simulation Process
Simulation results are saved as probe states in a trajectory object. That is,
depending upon the type of simulation (particle, envelope, transfer map, etc.), the results are
encapsulated by objects derived from the base class ProbeState
and aggregated
in the ordered Trajectory
object. Here we cover the way the online model saves
probe states.
The following is what happens when you run a scenario:
- If a starting element is specified the online model saves the initializing probe state as the first state in the trajectory.
- When the starting element is reached the next probe state to be saved depends
upon the values of the
probeUpdatePolicy
attribute of the algorithm object (see below). - The online model then transports the probe through the model lattice with the initial state intact until it reaches the starting element.
- Once the start element is reached the online model begins propagation the probe through the beamline until it reaches either the stopping element if one is specified, or the end of the sequence if no stopping element is specified.
- The dynamics of the probe propagation depend upon both the type of the probe (e.g., particle, envelope, transfer map, etc.) the algorithm provided to, and maintained by, the probe.
Note that a single probe type may have many different methods of propagation, for example,
an EnvelopeProbe
may have an EnvelopeTracker
,
EnvelopeBackTracker
, EnvTrackerAdapt
, etc.
Dynamics
The dynamics of the simulation are contained in the algorithm
component of the online model. Algorithms classes are derived from the base
class xal.model.alg.Tracker
, which contains the boiler plate functionality
for any algorithm. Algorithms understand how to propagate specific probe types
through the model beamline. They are implementations of specific dynamics. Since there
may be many different ways to model the dynamics of a beam aspect there can be many
different algorithms for the same probe type. Thus, it is necessary to provide
each probe a specific algorithm object. There is an algorithm factory,
xal.sim.scenario.AlgorithmFactory
, for creating algorithms.
Simulation Results
The results of an online model simulation are contained in a Trajectory
object maintained by the probe. The trajectory is an ordered aggregation of
ProbeState
-derived objects. They contain the state of the probe
at specified instances along the beamline (see below). The attributes of the
state are particular to the type of probe being simulated.
The Probe Update Policy
Each probe maintains an algorithm object, as mentioned above. The value of
theprobeUpdatePolicy
attribute in this algorithm object determines
the way the simulation results (i.e., "probe states") are stored in the trajectory.
Tracker.UPDATE_ENTRANCE
· the probe state is saved to the trajectory then the probe is propagated through the elementTracker.UPDATE_EXIT
· the probe is propagated through the element then its state saved to the trajectoryTracker.UPDATE_ALWAYS
· the probe state is saved every time the probe is moved (e.g., after a space charge kick), but only when moved.Tracker.UPDATE_ENTRANCEANDEXIT
· the probe state is saved to the the trajectory, the probe is propagated through the element, then again saved
The default value is Tracker.UPDATE_EXIT
.
The above behaviors are essentially the same when you do not have a starting element specified. Here there is usually a marker node at the beginning of any sequence and the state of a marker is the same irrelevant of exit or entrance. Choice of the probeUpdatePolicy depends upon where you need the probe states (see below).
There can be multiple modeling elements that map to the same hardware node.
Plus there can be multiple probe states that map to the same modeling element (especially so with space charge).
When you ask the trajectory object for the states of a hardware node you will
get all of them. The convenience method
Trajectory#statesForElement(String) : ProbeState[]. The method Trajectory#stateForElement(String) : ProbeState
just returns the first one.
Retrieving the First State
If you require that the initial state of the start element be in the trajectory the following are are a couple options:
- You can set the
Tracker#setProbeUpdatePolicy()
toTracker.UPDATE_ENTRANCEANDEXIT
. Then both the entrance and exit states of every element between the start element and the stop element will be in the trajectory. - You can set the
Probe#setCurrentElementId()
to the ID of the start element. Thus, when the propagation is initiated, the initial state of the probe is saved to the trajectory with the ID of the start element, and will be returned with a call toTrajectory#statesForElement(String)
.
Processing Simulation Results
There are a variety of tools for processing the simulation results of the online model. In particular there is a suite of tools in thexal.tools.beam.calc
package that
performs direct calculations on the Trajectory
objects produced in the simulation.
The calculations depend upon the type of the ProbeState
objects contained in
the trajectory. For example, the class CalculationsOnMachines
expects
TransferMapState
objects since such states are completely determined by the
beamline, and not any beam. The components of xal.tools.beam.calc
are
well documented and we refer the reader to the Javadoc for this package.
New Acceleration Model
Compatibility
Currently the acceleration model of the online model is being upgraded. This action
includes modification of the lattice generator, addition of nested modeling elements analogous
to the nested hardware objects of the SMF hierarchy, addition of longitudinal phase variables,
addition of a RF cavity, and a complete refactoring of the RF gap element. The old modeling
element IdealRfGap
was replaced with the new implementation
SpectralMapRfGap
. There are two
new and very important classes in the refactoring, AxialFieldSpectrum representing the
axial RF field spectrum and related quantities, and AcceleratingRfGap which handles all the
dynamics calculations of the RF gap. It was necessary to alter these two classes in order
to emulate the previous acceleration dynamics. These modifications are listed below and must
be converted back in order to utilize the full acceleration model.
As of November, 2015 the new RF acceleration model has been configured to emulate the previous acceleration model. To utilize all the features of the new model the following issues are identified:
AxialFieldSpectrum
- Private method
dkTzfromDkTz0(double)
used for backward compatibility must be switched to use magic number implementation. - Private method
dkTzfromDkTz0(double)
used for backward compatibility must be switched to use magic number implementation. - Private method
dkTqFromDkSq0(double>
used for backward compatibility must be switched to use magic number implementation. - Private method
dkSqFromDkSq0(double>
used for backward compatibility must be switched to use magic number implementation.
AcceleratingRfGap
-
No changes necessary at this time.
SpectrumMapRfGap
- Private method
compGapPhaseAndEnergyGainIndirect(IProbe)
has multiple issues. There are many type outs to be removed as necessary. The old method computes the "mid-gap wave number" then the phase and energy gains from that value. The new method computes the gap gains directly for the upstream (pre-gap) and downstream (post-gap) regions then sums them for the full values. There areTODO
comments marking the necessary changes. Look for the local variablesDELTA_PHASE_CORRECTION
andtheEnergyGain
.
New Spectral Quantities
The new acceleration model also requires new spectral quantities other than the conventional transit time factors T(k) and S(k). They are termed the quadrature transit time factors Tq(k) and Sq(k). The additional quantities can be provided using an "optics_extra" file if they are not available in the XDXF file. These quantities must be computed off line in a similar fashion as are the conventional transit time factors. For a complete set of RF cavity field spectral quantities the online model requires T(k), S(k), Tq(k), Sq(k), and their derivatives. Polynomial approximations are used for all.-
ClassDescriptionImplementation of an iterator class for
IComposite
objects.The defining interface of all probe tracking algorithmsBase interface for any structural modeling object.Represents a composite modeling structure.The defining interface for atomic accelerator modeling components.The root interface of physical objects and mathematical abstractions used in UAL applications (for example: Bunch, Particle, Twiss, Taylor map, and others).High-level container representing a machine model.Deprecated.This class is never usedBase exception class for exceptions thrown by the XAL online model.Model exceptions specific to propagation a probe object down an element lattice.Deprecated.This class is never usedRepresents a logical sector of beamline.