JMad

JMad is a Java API for the MadX software, which is used at CERN and in many other accelerator labs to simulate particle accelerators. JMad plays a key role in CERNs accelerator control system as it is bridges numerical simulations with the control system of the real CERN accelerators.

Getting Started

In order to use JMad in your java projects add the following to your build files:

Maven:

<dependency>
    <groupId>io.jmad</groupId>
    <artifactId>jmad-core</artifactId>
    <version>X.Y.Z</version>
</dependency>

Gradle:

compile 'io.jmad:jmad-core:X.Y.Z'

IMPORTANT NOTE

As of version 0.5.0, the groupId of JMad has changed fromjmad to io.jmad!

Using a model

JMad comes with a concept called 'Model Definitions'. A model definition specifies which madx files have to be loaded for a certain accelerator and certain optics (for madx users: sequence files, strength files, etc...). Model definitions can be created programmatically or be loaded from different sources: zip files, git repos or jars in the classpath. For this example, we will use the latter one.

jmad-core comes with one model definition built in in its jar itself. To get a new instance of a model using this model definition we have to do the following:

/* create a new JMad service */
JMadService jmadService = JMadServiceFactory.createJMadService();

/* then find a model definition */
JMadModelDefinition modelDefinition = jmadService.getModelDefinitionManager()
                                                 .getModelDefinition("example");

/* create the model and initialize it */
JMadModel model = jmadService.createModel(modelDefinition);
model.init();

After this we can use the model. For example we can retrieve all the elements the sequence range:

/* get all the elements */
List<Element> elements = model.getActiveRange().getElements();

/* print name and type of each element */
for (Element element : elements) {
    System.out.println("name: " + element.getName() + "; type: " + JMadElementType.fromElement(element));
}

... we can retrieve the actual optics, change some quadrupole and recalculate the optics:

Range activeRange = model.getActiveRange();

/* retrieve an element by name (MONITOR) */
Monitor monitor = (Monitor) activeRange.getElement("BPMIH.22604");

/* retrieve the actual optics */
Optic optic = model.getOptics();

/* retrieve some optics values */
List<Double> betaxValues = optic.getValues(MadxTwissVariable.BETX, activeRange.getElements());

/* retrieve optics values for one element */
OpticPoint opticPoint = optic.getPoint(monitor);
double monX = opticPoint.getX();

/* change a quad strength by 10 percent */
Quadrupole aQuad = (Quadrupole) activeRange.getElement("MQIF.20400");
aQuad.setK1(aQuad.getK1() * 1.1);

/* IMPORTANT: refetch the optic since it has changed! */
optic = model.getOptics();

... or we can perform a custom twiss:

TfsResultRequestImpl request = new TfsResultRequestImpl();

/* a regexp for the elements we want to retrieve */
request.addElementFilter("BPM.*");

/* and the variables, which we want to get */
request.addVariable(MadxTwissVariable.NAME);
request.addVariable(MadxTwissVariable.X);
request.addVariable(MadxTwissVariable.Y);

/* run the twiss and get the results */
TfsResult result = model.twiss(request);

List<String> elementNames = result.getStringData(MadxTwissVariable.NAME);
List<Double> xValues = result.getDoubleData(MadxTwissVariable.X);
List<Double> yValues = result.getDoubleData(MadxTwissVariable.Y);

/* print the values */
for (String name : elementNames) {
    int index = result.getElementIndex(name);
    System.out.println(name + ": X=" + xValues.get(index) + "; Y=" + yValues.get(index) + ";");
}

To close a model we have to call:

model.cleanup();

Additional Components

• There is also a Swing GUI available, which runs on top of jmad and allows to interactively change model parameters, plot optics functions and can be embedded easily in other GUIs.
• To Retrieve model definitions from git repositories, the project jmad-modelpack-service can be used (works currently only with gitlab repos)
• pyjmad is a wrapper around jmad with which all the features of jmad (including model definitions, GUI and retrieval from git repos) can be used as library in python.

Further Reading

• An overview of jmad was given in a paper at IPAC 2010.
• A summary - including the GUI parts - can also be found in the Phd Thesis of K. Fuchsberger (see page 61).

Build Artifacts of the Latest Version

• dependency license report
• junit test report
• jacoco test report
• javadoc