Quick Start Guide

User Manual:

Open the PDF directly: View PDF .
Page Count: 29

Merlin++

A Quick Start Guide

R. Barlow, S. Rowan, S. Tygier

on behalf of the

Merlin Collaboration

Updated: March 2019

Welcome to Merlin++!

Merlin++ is a particle accelerator simulation software package. Its functional-

ity is similar to that of Methodical Accelerator Design (MAD), but with many

additional features. Merlin++ is written in C++ and comprises a library of

ﬂexible and modular C++ classes, taking full advantage of the beneﬁts of

object orientated techniques and methodologies in the process. To run Mer-

lin++, a user therefore constructs their own script or simulation program and

compiles it against the class library.

The following document provides information on how to get up and running

with Merlin++, going over the basics as well as walking-through a few choice

use-case examples.

Contents

1 A Brief History 3

2 Getting Started 4

2.1 Information and Support ....................... 4

2.2 Downloading and Installation ..................... 4

2.3 Doxygen Class Documentation .................... 7

2.4 Running Merlin++ in Eclipse CDT ................. 8

3 Code Base & Design Philosophy 11

3.1 Merlin++ Design Philosophy ..................... 11

3.2 Understand the Design Fundamentals ................ 11

3.2.1 Accelerator Model ........................... 12

3.2.2 Particle Tracking ............................ 13

3.2.3 The ‘Process’ Concept ......................... 14

4 Writing A User Script 15

4.1 Merlin++ user script fundamentals .................. 15

5 Tutorials 17

5.1 Tutorial 1 - LatticeConﬁguration ................... 17

5.2 Tutorial 2 - LatticeConﬁgurationMAD ................ 19

5.3 Tutorial 3 - LatticeManipulation ................... 20

5.4 Tutorial 4 - ParticleTracking ..................... 22

5.5 Tutorial 5 - ParticleBunchTracking .................. 23

5.6 Tutorial 6 - LHClattice ........................ 25

5.7 Tutorial 7 - CollimationAndScattering ................ 26

Chapter 1

A Brief History

Merlin++, formerly just Merlin, is a C++ accelerator simulation and parti-

cle tracking software package, originally developed by Nick Walker et al. at

DESY/LBNL in the late 1990’s for International Linear Collider (ILC) simu-

lations, i.e. electron linac beamlines. In the mid 2000’s, Merlin was further

adapted to allow for proton tracking as well as circular accelerator simula-

tions and has been used in High Luminosity Large Hadron Collider (HL-LHC)

studies ever since. In recent years, Merlin++ has been optimized for high-

throughput tracking and loss simulations through the addition of conventional

and Hollow-Electron Lens (HEL) collimation capabilities as well as the ap-

propriate pomeron scattering physics processes. Furthermore, recent develop-

ments have also focused on updating the code base to adhere to modern open

source and software sustainability practices. In this regard, we ﬁnd Merlin++

to be one of the most powerful, versatile and accessible software packages

available in particle accelerator design.

Chapter 2

Getting Started

2.1 Information and Support

Information on Merlin++, including general documentation, class library and

developers guide can be found either in the ‘MerlinDocumentation’ folder in-

cluded with the software package or via our website:

url: http://www.accelerators.manchester.ac.uk/merlin/

Support for both users and developers can be sought by contacting any of the

current developers through github at:

url: https://github.com/Merlin-Collaboration

2.2 Downloading and Installation

Prior to downloading Merlin++, it is important that you have all the required

prerequisites.

Below is a step-by-step guide to properly downloading, conﬁguring and in-

stalling all prerequisites as well as Merlin++ itself. The following only provides

install command examples speciﬁc to Ubuntu, for other linux distros, please

use as close to the equivalent commands as possible.

NOTE: If necessary, Merlin++ can be downloaded and run without the fol-

lowing prerequisites. However, it is advised that user/developer installs Mer-

lin+ in accordance with the following to prevent compatibility issues.

Prerequisites

•Update system

sudo apt install update

•C++ compiler, such as g++

sudo apt install build-essential

•CMake, including CCMake

sudo apt install cmake cmake-curses-gui

•Python, including numpy & scipy

sudo apt install python python-numpy python-scipy

•Git version control system

sudo apt install git

•Java Runtime Environment (Only required for Eclipse CDT IDE)

sudo apt install openjdk-8-jre

•OPTIONAL: Doxygen

sudo apt install doxygen graphviz -y

•OPTIONAL: ROOT

Download from url: root.cern.ch

Downloading and Installing

For the purposes of this quick start guide, we only discuss how to download

and install Merlin++ for a Linux OS via git.

NOTE: It is, otherwise, also possible to download the Merlin++ source code

directly via either our online public github repository:

url: https://github.com/Merlin-Collaboration/Merlin

•Firstly, call your desired directory, we will assume home as default

cd ∼

•Subsequently, create and enter a suitable git repository directory

mkdir git

cd git

•Initialize this directory as an empty git repository

git init

•Download the latest release of Merlin++ from our public github reposi-

tory (check github link for most recent release version)

git clone -b Release-X.XX \

https://github.com/MERLIN-Collaboration/Merlin ./Merlin

•Now that you have a clone of the source code, you are ready to install

and run Merlin++! First, enter the cloned directory

cd Merlin

•Create and enter a suitable build directory

NOTE: Merlin++ does not allow in-source builds

mkdir build

cd build

•Create the release version makeﬁle with the cmake command

NOTE: Interactive conﬁguration is available using ccmake instead

cmake -DCMAKE\_BUILD\_TYPE=Release ..

// OR

ccmake ..

•Start building Merlin++!

make -jN // where N is the number of available CPUs, e.g. -j8

•To conﬁrm the installation has been successful, run the make test suite

make test

•Pending successful installation you should see something similar to the

following (more tests may have been developed):

Figure 1: Successful installation test results.

2.3 Doxygen Class Documentation

Doxygen is a common tool for generating class documentation from annotated

C++ source. Merlin++ has descriptive class comments in the header ﬁles

of all major classes formatted such that they are picked-up by doxygen. To

generate the class library for Merlin++, simply enter the following command

following successful installation. If using Eclipse CDT, use Build Targets in a

similar manner to how ‘make test’ is run.

•Generate class documentation via doxygen

make doxygen

The above command generates a ‘Doxygen’ folder and a full interactive .html

site in the build directory. To load, simply open the index.html ﬁle.

Within the html site, one can ﬁnd class and class member function descrip-

tions as well as inheritence information, namespace list and information and

ﬁle structure. Furthermore, developers have begun using this location to doc-

ument information on any recent API changes. A screenshot of the interactive

html class library is shown.

Figure 2: Interactive html Merlin++ class library procduced by doxygen.

2.4 Running Merlin++ in Eclipse CDT

As many developers and script writers alike prefer using an IDE, the following

details how to get Merlin++ up and running within the Eclipse CDT IDE. If

you are happy running Merlin++ from a command window, feel free to skip

this section.

NOTE: The following assumes you have followed through the guide thus far,

i.e. have installed all prerequisites and have conﬁgured Merlin++ successfully.

•Download the latest .tar.gz Eclipse IDE for C/C++ Developers

https://www.eclipse.org/downloads/packages/

•Uncompress then remove the .tar.gz ﬁle

sudo tar -xvf eclipse.cpp...tar.gz

sudo rm eclipse.cpp...tar.gz

•Move the eclipse ﬁle to your prefered install location, e.g. /opt/

sudo mv -r ./eclipse /opt

•Conﬁgure the eclipse launch command

sudo cd /usr/local/bin

sudo ln -s /opt/eclipse/eclipse

•Launch eclipse and provide an appropriate workspace name

eclipse

•Install cmake4eclipse plugin through the Eclipse Marketplace

> Help > Eclipse Marketplace

- search for and install cmake4eclipse

- agree to licence and select ’Install Anyway’ if an error appears

•Conﬁgure Eclipse Console

- While on ‘Console’ tab, click on the drop down menu at far right

and select ‘1 C\C++ Build Console’ to display all make outputs

•Conﬁgure the Merlin++ Project

NOTE: At this stage it is advised that you delete any build directory

created thus far (assuming you followed the command line instructions).

Within Eclipse CDT:

> File > New > C/C++ project

- Select ‘All’ > ‘C++ Managed Build’

- Enter a suitable Project name, such as ‘Merlin++’

- Uncheck ‘Use default location’ and enter Merlin++ source directory

> /home/username/git/Merlin

- Select ‘Executable > Empty Project’ and ‘Linux GCC’

- Click ‘Finish’

- Your should now have a project ‘Merlin [Merlin Release-X.XX] within

the ‘Project Explorer’ window’

- Right-click project, select Properties

IMPORTANT: For all of the following you must do for both Debug and

Release configurations seperately (drop down menu at the top) -

the ‘All configurations’ option is not supported by Merlin++.

- Go to ‘C/C++ Build’ and click on the ‘Behaviour’ tab. Check ‘Enable

parallel build’

- Go to ‘C/C++ Build > CMake’ and click on the ‘General’ tab. Check

‘Force cmake to run with each build’ under ‘Build Behavior’

- Go to ‘C/C++ Build > Tool Chain Editor’ and set ‘Current builder:’

to ‘CMake Builder (portable)’ via the drop down menu

- Click ‘Apply’

- Once you have done each of the above for both Debug and Release

Configurations, click ‘Apply and Close’

- Build Merlin++ using the hammer icon on the main workspace toolbar

•Conﬁrm conﬁguration with the Merlin++ test suite within Eclipse CDT

- Go back to the ‘Project Explorer’ window

- Within the newly created ‘build’ directory, right-click ‘Debug’ or

‘Release’ folders and select ‘Build Targets > Create...’

- Enter the ‘Target Name:’ ‘test’ and click OK

- A ‘Build Targets’ directory should have appeared within your build

sub-directory

- To launch the test suite simply double-click ‘Build Targets > test’

NOTE: This is same as running ‘make test’ from the command line.

Similarly, to run ‘make doxygen’ or equivalent, simply create a

new build target with the corresponding name. Eclipse can provide

some additional benefits in this regard as it provides a built-in

browser, useful for navigating the Merlin++ doxygen class library

- If configuration was successful, all tests should pass as before

•Launching Merlin++ UserSim or other individual applications

- With the ‘Project Explorer’, navigate to ‘build > Debug/Release >

UserSim > UserSim

- Right-click and select ‘Run As > (2) Local C++ Application’

- You should now be greeted with the Merlin++ welcome message

•Congratulations! Merlin++ is successfully conﬁgured in Eclipse CDT and

you are now ready to start constructing your own user script.

Chapter 3

Code Base & Design Philosophy

3.1 Merlin++ Design Philosophy

Merlin++ is a result of the requirement for object-orientated design (OOD)

methodologies in particle accelerator design software. This is mostly due to the

extensive lifetime accelerator design software packages tend to have (decades),

giving rise to a need for code maintainability and sustainability. C++ was

chosen as it excels in this regard, while also allowing for low-level processes to

written where necessary to maintain optimal performance. There are two key

design philosophies behind Merlin++ (not mutually exclusive):

1. To be able to do the job required in the simplest, but most ﬂexible form

2. To produce a set of loosely coupled software components which are easily

maintainable, extendible, and re-usable

The Merlin++ developers encourage that all users and future developers ad-

here to this design philosophy, too.

3.2 Understand the Design Fundamentals

Merlin++ is a C++ class library for performing charged particle tracking and

particle accelerator simulations. The library can be loosely divided into two

parts:

1. Accelerator Model construction

2. Beam dynamics and tracking simulation

The model of the accelerator system being studied contains only a descrip-

tion of the physical components e.g. magnets, diagnostics, vacuum chambers,

cavities, power supplies, support structures. The classes responsible for per-

forming the required beam dynamics simulations use this information to con-

struct the more abstract algorithm related representation of the model (e.g.

construction of a map for particle tracking.) In this respect, the accelerator

model can be thought of as a form of database.

This separation allows (in principle) the same accelerator model to be used

repeatedly for diﬀerent forms of beam dynamics simulations, without the need

to modify the accelerator model code directly. Currently, the only beam dy-

namics package supported is particle tracking (i.e. ray tracing.)

3.2.1 Accelerator Model

The accelerator model (class AcceleratorModel) is constructed from model

elements (class ModelElement). All accelerator components types have a com-

mon base class, AcceleratorComponent, and have speciﬁc list of associated

attributes, see Table 1. The majority of these model elements represent the

more tradition beamline components found in other optics codes, see Table 2.

Table 1: Accelerator component attributes and their corresponding classes.

Component Attribute Merlin++ class

Aperture class Aperture

Electro-Magnetic Field class EMField

Geometry class AcceleratorGeometry

Table 2: Accelerator component types and their corresponding classes.

Component Type Merlin++ class

Drift Section class Drift

Sector Bend class SectorBend

Quadrupole class Quadrupole

Sextupole class Sextupole

Octupole class Octupole

Skew-Quadrupole class SkewQuadrupole

Skew-Sextupole class SkewSextupole

Standing-wave RF Cavity class SWRFStructure

Traveling-wave RF Cavity class TWRFStructure

Horizontal Correctors (xcor) class XCor

Vertical Correctors (ycor) class YCor

Beam Position Monitors (BPM) class BPM

Proﬁle Monitors class RMSProﬁleMonitor

An Aperture deﬁnes the physical aperture of the component. An EMField

represents the electro-magnetic ﬁeld of a component; it can be time-dependent.

Both the Aperture and EMField are deﬁned in the local coordinate frame of

the component, which is a property of its AcceleratorGeometry. In Merlin,

an AcceleratorGeometry is an important concept and serves several functions.

Primarily it is responsible for calculating coordinate transformations to and

from the local component coordinate frame during tracking operations.

3.2.2 Particle Tracking

By ‘tracking’, we generally mean either tracking some representation of the

beam through the accelerator beamline, or propagating some map. The Merlin

class library has been designed to allow addition of diﬀerent forms of tracking

without the need to modify existing code (in particular the accelerator model

classes.) Currently, the Merlin library only supports particle tracking (i.e. ray

tracing.)

Merlin separates the responsibilities for tracking (iterating) over a beamline

and performing the necessary coordinate transformations between component

(frames), and actually tracking, or integrating through a component (e.g. a

quadrupole.) The latter is the job of the ComponentTracker class, which

supplies the primary tracking interface to the accelerator components.

A ComponentTracker contains a set of Integrators which perform the physi-

cal tracking through a component. Typically, there is one integrator object per

component class in the accelerator model, although there are often less inte-

grators than component types, e.g. the particle tracker uses a single integrator

to deal with all rectangular multipoles magnets. The job of the Component-

Tracker class, therefore is to simple select the correct integrator for the current

component.

To add a new tracking module, we must perform the following to steps:

•Derive a new class from ComponentTracker

•Construct a set of integrators speciﬁc to that tracker for each relevant

component in the accelerator model.

Once the ComponentTracker object has been initialised with an accelerator

component, it can be told to track either the entire component in one go, or

take a speciﬁc step through the component. The integration step is therefore

under the control of the application, avoiding having to split magnets in the

model description (input deck), which is so often necessary in existing optics

codes.

3.2.3 The ‘Process’ Concept

The ComponentTracker concept dealt with in the last section is responsible for

performing some concrete tracking algorithm though individual components.

Generally, we perform such tracking on a sequence of such components that

represents some lattice or beamline. The applications programmer could sim-

ple write a do-loop that iterated over the components, but Merlin supplies a

much higher-level concept to do this, under the control of one or more so-called

Processes.

The TrackingSimulation class is a top-level abstraction for performing some

accelerator simulation. Exactly what form that simulation takes is deﬁned by

one or more processes (class BunchProcess). Generally, processes fall into two

categories:

•A process which increments the independent variable (usual s), i.e. ac-

tually tracks through a step ds; these processes are know as Transport

Processes

•A process that does not actual increment s, but applies some impulse to

the bunch; these are know as Impulse Processes

Processes normally represent some physics process (e.g. particle scattering,

space charge, synchrotron radiation), but one could easily have a process that

formed part of the application (e.g. output at certain point during tracking

could be under control of a process.) A TrackingSimulation generally has at

least one Transport Process that does the ‘tracking. As an example, the class

ParticleTracker provides the primary interface to the particle tracking module.

ParticleTracker inherits from TrackingSimulation, and on construction, auto-

matically adds a ParticleTransportProcess to its list of processes. Additional

processes (e.g. SynchRadParticleProcess) can be added if required. Particle-

TransportProcess uses a ComponentTracker to track through each component.

The real power behind a process is that taken together, the list of processes

deﬁnes the ﬁnite steps taken through each component. As an example, you

can tell the SynchRadParticleProcess to take twenty equidistant steps through

each magnet. TrackingSimulation is responsible for managing the step length.

It determines the next step to take (ds) after interrogating each of its processes

in turn, after which it tells each process to take that step.

Note that processes can be turned on or oﬀ, or made active for only certain

types of/speciﬁc components.

Chapter 4

Writing A User Script

4.1 Merlin++ user script fundamentals

Merlin++ follows a relatively simple overarching design in that a user script

can be thought of in just ﬁve parts.

1. Deﬁning the lattice

2. Deﬁning the beam

3. Deﬁning the tracker

4. Running the simulation

5. Post-processing & output of results

The following provides a code snippet corresponding to each part. Note that

this is simply an example of the most basic implementation and more advanced

methods exist as can be found in the tutorials.

1. Deﬁning the Lattice (A OR B)

A Deﬁne lattice apertures manually within Merlin++

AcceleratorModelConstructor newModel();

newModel.NewModel();

newModel.AppendComponent(new Quadrupole( QF ,1.0,5.5));

newModel.AppendComponent(new Drift( D1 ,12.55));

newModel.AppendComponent(new SectorBend( BFD ,5.0,0.0255,11.23));

newModel.AppendComponent(new Drift( D1 ,12.55));

newModel.AppendComponent(new Quadrupole( QD ,1.0,-5.5));

// etc..

AcceleratorModel* theModel = newModel.GetModel();

B Importing MAD optices/lattice apertures ﬁle

MADInterface madInterface("/path/to/lattice.tfs", beamenergy);

AcceleratorModel* theModel = madInterface.ConstructModel();

2. Deﬁning the Beam

ParticleBunch* theBunch = new ParticleBunch(beamenergy);

particleBunch->AddParticle(co);

3. Deﬁning the Tracker

ParticleTracker tracker(theModel->GetBeamline(), theBunch);

4. Running the Simulation

tracker.Run();

5. Processing & Output of Results

// Prior to running the tracker:

ofstream trackingLog("build/trackinginfo.out");

// Post running the tracker:

ParticleBunch& tracked = tracker.GetTrackedBunch();

tracked.Output(trackingLog);

// Tracking data can be imported and plotted in python/octave etc

For a more in-depth look at how to write user scripts for varying use-cases,

please continue on to the tutorials in Chapter 5.

Chapter 5

Tutorials

In the chapter, we walk-through a number of short tutorials to demonstrate

some of the key features of the Merlin++ framework. Each section corresponds

to an tutorial as provided with the Merlin++ source package as default. Note

that the provided tutorials focus on simulating with a circular accelerator -

linac tutorials will be added in future. Includes, namespaces, deﬁnes and

typedefs will not be discussed as basic C++ knowledge is assumed. Further-

more, the tutorials are designed to done methodically in order, i.e. only new

code will be discussed in each subsequent tutorial section.

5.1 Tutorial 1 - LatticeConﬁguration

The provided ManualConstruction tutorial demonstrates how to build an ac-

celerator model manually using the Merlin++ API. The script constructs a

FODO lattice storage ring made solely of quadrupole and dipoles.

LatticeConﬁguration

•The following snippet shows how to construct a manually deﬁned simple

FODO lattice within Merlin++. This tutorial goes on to show how to

calculate and plot the lattice horizontal beta function.

First, an instance of a AcceleratorModelConstructor is opened and a Ac-

celeratorModelConstructor::NewModel() is deﬁned. Subsequently, a loop

(only for periodic lattices) appends individual components with deﬁned

length, ﬁeld and distance from the previous component. A ﬁnal drift

is appended at the end of the loop to complete the circle. Finally, and

instance of AcceleratorModel is deﬁned by the member function Acceler-

atorModelConstructor::GetModel().

AcceleratorModelConstructor latticeConstructor;

latticeConstructor.NewModel();

double rigidity = beamenergy/eV/SpeedOfLight;

double curv = (2*pi/(4*ncell));

//FODO lattice periodic

for (int n=1;n<(ncell+1);++n) {