Merlin logoThe Merlin++ accelerator simulation program library

Quickstart Guide

Some Tutorial Examples

We walk through a number of short tutorials to demonstrate some of the key features of the Merlin++ framework. Each section corresponds to a tutorial example provided with the Merlin++ package.

Note that the provided tutorials focus on simulating with a circular accelerator - linac tutorials will be added in future.

A basic knowledge of C++ is assumed, so includes, namespaces, defines and typedefs will not be discussed.

The tutorials are designed to done methodically in order, i.e. only new code will be discussed in each subsequent tutorial section.

Please don't take these examples as templates to be modified to match your own requirements. That's not their purpose. They're written to make things clear to a novice, which is not necessarily the 'best' code. If you understand the tutorials you should be in shape to write your own program rather than adapting someone else's

Tutorial 1 - LatticeConfig

The following snippet shows how to manually define a simple FODO lattice storage ring, made solely of quadrupole and dipole,. within Merlin++.

First, an instance of the AcceleratorModelConstructor class is opened, and a AcceleratorModelConstructor::NewModel() is defined. Subsequently, a loop appends individual components each with defined length, field and distance from the previous component. A final drift is appended at the end of the loop to complete the circle. Finally, an instance of AcceleratorModel is defined by the member function AcceleratorModelConstructor::GetModel().

AcceleratorModelConstructor latticeConstructor;
double rigidity = beamenergy/eV/SpeedOfLight;
double curv = (2*pi/(4*ncell));
//FODO lattice periodic
for (int n=1;n<(ncell+1);++n) {
  latticeConstructor.AppendComponent(new Quadrupole("QF",lquad,0.0098*rigidity), n==1 ? 0 : 0.15*lcell-ldipole);
  latticeConstructor.AppendComponent(new SectorBend("MB",ldipole,curv,rigidity*curv), 0.15*lcell-lquad);
  latticeConstructor.AppendComponent(new SectorBend("MB",ldipole,curv,rigidity*curv), 0.2*lcell-ldipole);
  latticeConstructor.AppendComponent(new Quadrupole("QD",lquad,-0.0098*rigidity), 0.15*lcell-ldipole);
  latticeConstructor.AppendComponent(new SectorBend("MB",ldipole,curv,rigidity*curv), 0.15*lcell-lquad);
  latticeConstructor.AppendComponent(new SectorBend("MB",ldipole,curv,rigidity*curv), 0.2*lcell-ldipole);
AcceleratorModel* lattice = latticeConstructor.GetModel();

To confirm the lattice is viable for tracking it we calculate the closed orbit of a single reference particle following:
ClosedOrbit theClosedOrbit(lattice,beamenergy);
Particle particle(0);

Tutorial 2 - LatticeConfigMAD

The provided LatticeConfigMAD tutorial demonstrates how to build an accelerator model by importing a MAD .tfs file with the Merlin++ API.

The script constructs a stable FODO lattice storage consisting of dipoles, quadrupoles and sextupole corrector magnets. Furthermore, this tutorial goes on to show how to calculate and plot commonly sought after lattice functions.

Beta and dispersion functions for imprted FODO lattice>

Tutorial 3 - LatticeManipulation

The LatticeManipulation tutorial shows how to alter individual component parameters within a user script directly to simulation alignment/field errors etc. This is done via the MagnetMover and MutipoleField classes.

Variations in beta functions as a result of magnet manipulation>

Tutorial 4 - ParticleTracking

The ParticleTracking tutorial shows how to create and track a ‘bunch’ of 2 particles at different starting real space coordinates using the Particle, ParticleBunch and ParticleTracker classes.

Tutorial 5 - ParticleBunchTracking

The ParticleTracking tutorial shows how to create and track a normally distributed particle bunch of 10,000 particles using the ParticleDistributionGenerator, rather than doing it 'by hand', as in the previous tutorial The tutorial continues to show a different method of recording the results, using beam position monitor (BPM) component buffers. This method records the bunch centroid in real space coordinates at every BPM component present in the constructed lattice.

Tutorial 6 - TheLHClattice

TheLHClattice tutorial shows how to import the LHC lattice, aperture and collimator information. A simple closed orbit calculation is performed to confirm stability and the lattice functions are subsequently calculated and recorded.

Tutorial 7 - CollimationAndScattering

The CollimationAndScattering tutorial shows how to initialize a simulation such that aperture checks are carried out and particles are lost where they exceed aperture limits. Moreover, if particles are lost in a collimator component, they follow a collimation process and are scattered following a defined scatter process. The scattering process used is defined by R. Appleby et al. in [ref]. Each scattered and subsequently lost particle has its loss location record in a histogram. The following simulation uses the LHC accelerator lattice and tracks 10,000 particles for 20 turns.