Package xal.model


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 element
  • Tracker.UPDATE_EXIT · the probe is propagated through the element then its state saved to the trajectory
  • Tracker.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() to Tracker.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 to Trajectory#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 the xal.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 are TODO comments marking the necessary changes. Look for the local variables DELTA_PHASE_CORRECTION and theEnergyGain.

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.

  • Class
    Description
    Implementation of an iterator class for IComposite objects.
    The defining interface of all probe tracking algorithms
    Base 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 used
    Base 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 used
    Represents a logical sector of beamline.