High-Level PyMAD-NG

This page describes how the pythonic interface to MAD-NG works. This way of using PyMAD-NG is far more limited than the low-level interface, and everything that can be done with the high-level interface can also be done with the low-level interface, usually with more flexibility and better performance. However, the high-level interface is much easier to use for people used to python.

The “high-level” describes essentially every function, method, class, variable, etc. accessible from the top-level namespace of the pymadng module not listed in the API Reference.

When a user initialises a MAD object, as follows, we say that the user has created a “MAD object”, which creates a new instance of the MAD-NG program, and from this object we can interact with the MAD-NG program.

import pymadng
mad = pymadng.MAD()

The MAD object is used to access the global environment of the MAD instance, there does not exist a significant amount within the global environment, the full list of variables can be found on the MAD-NG GitHub, but a few of the more important ones are listed below, for a better understanding and examples see the MAD-NG manual.

Global Libraries

  • io - A lua library for reading and writing files.

  • os - A lua library for interacting with the operating system.

  • math - A lua library for mathematical functions.

  • table - A lua library for manipulating tables.

  • string - A lua library for manipulating strings.

  • MAD - The main library for accessing all the modules and functions of MAD-NG.

  • MADX - The MAD-X environment in MAD-NG - explicitly not MAD-X and so cannot be used to run MAD-X code, used for importing MAD-X sequences and adjusting variables and knobs.

Global Functions

  • assert() - A lua function for asserting a condition.

  • print() - A lua function for printing to the console.

  • error() - A lua function for throwing an error.

  • ipairs() - A lua function for iterating over the indexed part of a table (the array part).

  • pairs() - A lua function for iterating over the whole table, including indices and keys (the array and hash parts).

  • tonumber() - A lua function for converting a string to a number.

  • tostring() - A lua function for converting a number to a string.

  • type() - A lua function for getting the type of a variable.

Other Global Variables - Specific to PyMAD-NG

The functions that are required for physics are all contained within the MAD library, a few of the more important ones are immediately exposed to the user, only in PyMAD-NG, and are listed below:

Accessing the Global Environment

To access anything in the global environment, we can use the MAD object, for example, to access the math library, we can use the following:

import pymadng
mad = pymadng.MAD()
print(mad.math.sin(1).eval(), mad.math.cos(1).eval()) # 0.8414709848078965 0.5403023058681398

The reason we have to use the eval() function is because when a function is called from python and executed in MAD-NG, it will always return a reference, allowing us to continue to use the returned value in MAD-NG and it is not automatically converted to a python object. See Managing References for more information on these references and how to use/deal with them. This evaulation can also be done using the low level interface, as follows:

import pymadng
mad = pymadng.MAD()
mad.send("py:send(math.sin(1)):send(math.cos(1))")
print(mad.recv(), mad.recv()) # 0.8414709848078965 0.5403023058681398

To conclude, the global environment is accessed through the MAD object, several of libraries and functions are listed above, most of the other necessary functions required can be accessed through the MAD library in MAD-NG, by doing mad.MAD. With knowledge of MAD-NG, the user can access and interact with almost everything in MAD-NG through the high-level interface, however, the low-level interface is much more flexible and powerful, so it is recommended to use for more complex tasks.