Interface Summary
Interface	Description
IAlgorithm	The defining interface of all probe tracking algorithms
IComponent	Base interface for any structural modeling object.
IComposite	Represents a composite modeling structure.
IElement	The defining interface for atomic accelerator modeling components.
IProbe	The root interface of physical objects and mathematical abstractions used in UAL applications (for example: Bunch, Particle, Twiss, Taylor map, and others).

Class Summary
Class	Description
CompositeGlobalIterator	Implementation of an iterator class for `IComposite` objects.
Lattice	High-level container representing a machine model.
LineModel	Represents a model lattice for a linear accelerating structure.
RingModel
Sector	Represents a logical sector of beamline.

Exception Summary
Exception	Description
ModelException	Base exception class for exceptions thrown by the XAL online model.
PropagationException	Model exceptions specific to propagation a probe object down an element lattice.

Package xal.model Description

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.