Skip to main content

Introduction to OCELOT Elements

In OCELOT, one beamline element is usually not implemented as a single class. The object that users put into a MagneticLattice is typically a public wrapper such as Drift, Quadrupole, Cavity, or TDCavity. That wrapper holds an internal physics object and builds the transformations used for optics and tracking.

The Basic Idea​

Most CPBD element families are organized into four layers:

  • OpticElement: public wrapper with the user-facing API, cached maps, and tracking-method selection.
  • Element or Magnet: atom layer that stores physics parameters and computes map parameters.
  • TMParams: typed parameter containers passed from atoms to transformations.
  • Transformation: map application layer such as TransferMap, SecondTM, or family-specific transformations.
Quadrupole wrapper
    -> QuadrupoleAtom
    -> FirstOrderParams / SecondOrderParams
    -> TransferMap / SecondTM / KickTM

This split allows OCELOT to keep a stable public API while still supporting several tracking methods for the same element family.

Why This Structure Matters​

  • The same element family can support several active tracking methods.
  • First-order optics remain available even when active tracking uses another transformation.
  • A lattice-wide transformation request is a broad default: families that do not support it keep their own default active transformation.
  • Edge-aware elements can build ENTRANCE -> MAIN -> EXIT map sequences.
  • Public element attributes such as quad.k1 remain convenient, while the actual physics state lives on the atom.

For a more detailed explanation, start with Element Architecture and then read the class pages for OpticElement, Element, and Magnet. If you want to extend CPBD itself, continue with How to Create a New Element or How to Create a New TM.

File Layout​

For most element families you will find at least two files in ocelot/cpbd/elements/:

Examples:

  • drift.py and drift_atom.py
  • quadrupole.py and quadrupole_atom.py
  • cavity.py and cavity_atom.py

The full implementation is available in the OCELOT GitHub repository.

Overview of Element Families​

Base classes​

  • OpticElement: public wrapper used by most beamline elements.
  • Element: minimal atom-layer base class.
  • Magnet: atom-layer base class for many magnetic families.

Passive and utility elements​

  • Drift: straight beam transport without fields.
  • Marker: zero-length reference point.
  • Monitor: diagnostic element with monitor-specific state.
  • Aperture: stores beam aperture limits.

Magnetic elements​

  • Quadrupole: linear focusing or defocusing.
  • Sextupole: chromatic correction.
  • Octupole: higher-order nonlinear correction.
  • Multipole: dedicated multipole family with its own active transformation.
  • Solenoid: focusing with a solenoidal field.
  • Bend, SBend, RBend: dipole bending elements.
  • Hcor, Vcor: horizontal and vertical correctors.

RF elements​

  • Cavity: standing-wave accelerating cavity.
  • TDCavity: transverse deflecting cavity.
  • TWCavity: traveling-wave cavity.

Specialized elements​

  • Undulator: periodic magnetic structure for radiation generation.
  • UnknownElement: placeholder for imported or legacy elements.
  • Pulse: helper object for time-dependent kicks; it is not part of the usual wrapper/atom stack.