Developer API Reference

PyMAD-NG Low Level API (Able to be run independently of madp_object)

class pymadng.madp_pymad.BaseMadRef(name: str, mad_proc: MadProcess)

Bases: object

A reference to a variable in MAD-NG. This class allows for the retrieval of variables from MAD-NG without having to send them explicitly.

eval() → Any: Evaluate the reference and return the value.

class pymadng.madp_pymad.MadProcess(mad_path: str | Path, py_name: str = 'py', raise_on_madng_error: bool = True, debug: bool = False, stdout: str | Path | TextIO = None, redirect_stderr: bool = False)

Bases: object

close() → None

Terminate the MAD-NG process.

Closes all communication pipes and waits for the subprocess to finish.

protected_send(string: str) → MadProcess

Send a command string to MAD-NG with temporary error handling.

If error handling is enabled, any errors in MAD-NG will be reported back.

protected_variable_retrieval(name: str, shallow_copy: bool = False) → Any

Safely retrieve a variable from MAD-NG.

Enables temporary error handling while retrieving a variable. :param name: The MAD-NG variable name to retrieve. :type name: str :param shallow_copy: If True, retrieves a shallow copy of the variable. This has no effect for most types, but tables in MAD-NG are sent as references by default, so if you want to retrieve a copy of the table, set this to True. :type shallow_copy: bool

Returns:: The value of the variable.

recv(varname: str = None) → Any

Receive data from MAD-NG.

Reads 4 bytes to detect the data type and then extracts the corresponding value. Optional varname is used for reference purposes. :param varname: The variable name to use for reference in MAD-NG. :type varname: str

Returns:: The value received from MAD-NG, which can be of various types (str, int, float, ndarray, bool, list, dict).
Return type:: Any

recv_and_exec(env: dict = {}) → dict

Receive a command string from MAD-NG and execute it.

The execution context includes numpy as np and the mad process instance. Returns the updated execution environment. :param env: The environment dictionary to execute the received command in. :type env: dict

Returns:: The updated environment dictionary after executing the received command.
Return type:: dict

recv_vars(*names, shallow_copy: bool = False) → Any

Receive one or multiple variables from MAD-NG.

For a single variable (excluding internal names) a direct value is returned. For multiple variables, a tuple of values is returned. :param *names: Variable names to retrieve from MAD-NG. :param shallow_copy: If True, retrieves a shallow copy of the variable. This has no effect for most types, but tables in MAD-NG are sent as references by default, so if you want to retrieve a copy of the table, set this to True. :type shallow_copy: bool

Returns:: The value of the variable if a single name is provided, or a tuple of values if multiple names are provided.
Return type:: Any

Send data to the MAD-NG process.

Accepts several types (str, int, float, ndarray, bool, list, dict) and sends them using the appropriate serialization. Returns self to allow method chaining.

send_cpx_tpsa(monos: ndarray, coefficients: ndarray) → None

Transmit a complex TPSA to MAD-NG.

Sends complex monomials and coefficients to MAD-NG for table creation.

send_logrange(start: float, stop: float, size: int) → None

Send a logarithmic range (numpy array) to MAD-NG.

Builds an array equivalent to numpy.geomspace from start to stop with given size.

send_range(start: float, stop: float, size: int) → None

Send a linear range (numpy array) to MAD-NG.

Constructs a numpy.linspace array based on start, stop, and size and sends it over the MAD pipe.

send_tpsa(monos: ndarray, coefficients: ndarray) → None

Transmit TPSA data to MAD-NG.

Sends the monomials and their corresponding coefficients to construct a TPSA table.

send_vars(**variables) → MadProcess

Send multiple variables to MAD-NG.

Each keyword argument becomes a variable in the MAD-NG environment. If a variable is a MadRef, it is sent as its name; otherwise, the value is sent directly. :param **vars: Keyword arguments representing variable names and their values.

Returns:: Returns self to allow method chaining.
Return type:: MadProcess

set_error_handler(on_off: bool) → MadProcess

Toggle error handling in the MAD-NG process.

This determines whether errors are raised immediately. :param on_off: If True, errors will be raised immediately; if False, errors will not be raised. :type on_off: bool

Returns:: Returns self to allow method chaining.
Return type:: MadProcess

Determine the type string for the given input.

Parameters:: a – The data for which to determine the type.
Returns:: The corresponding type used for serialization.
Return type:: type

pymadng.madp_pymad.is_private(varname)

Check if the variable name is considered private.

Parameters:: varname (str) – The variable name to check.
Returns:: True if the variable name is private, False otherwise.
Return type:: bool

pymadng.madp_pymad.read_data_stream(self: MadProcess, dat_sz: int, dat_typ: dtype) → ndarray

Read data from the MAD-NG pipe in a specific format.

Parameters:

dat_sz (int) – The size of the data to read.
dat_typ (np.dtype) – The data type for numpy conversion.

Returns:

The data read from the MAD-NG input stream, converted to the specified numpy type.

Return type:

np.ndarray

pymadng.madp_pymad.recv_bool(self: MadProcess) → bool

Read a boolean value from the MAD-NG pipe.

Parameters:: self (MadProcess) – The MAD-NG process instance.
Returns:: The boolean value received from MAD-NG.
Return type:: bool

pymadng.madp_pymad.recv_cpx(self: MadProcess) → complex

Receive a complex number from the MAD-NG pipe.

Parameters:: self (MadProcess) – The MAD-NG process instance.
Returns:: The received complex number.
Return type:: complex

pymadng.madp_pymad.recv_cpx_matrix(self: MadProcess) → ndarray

Receive a matrix of complex numbers from the MAD-NG pipe.

Returns:: The received complex matrix.
Return type:: np.ndarray

pymadng.madp_pymad.recv_cpx_tpsa(self: MadProcess)

Receive a complex TPSA table from the MAD-NG pipe.

Returns:: A tuple containing the monomial list and coefficients.
Return type:: tuple

pymadng.madp_pymad.recv_dbl_tpsa(self: MadProcess)

Receive a double TPSA table from the MAD-NG pipe.

Returns:: A tuple containing the monomial list and coefficients.
Return type:: tuple

pymadng.madp_pymad.recv_dict(self: MadProcess) → dict

Receive a dictionary from the MAD-NG pipe.

Returns:: The received dictionary.
Return type:: dict

pymadng.madp_pymad.recv_err(self: MadProcess)

Receive an error message from MAD-NG and raise an exception.

Parameters:: self (MadProcess) – The MAD-NG process instance.
Raises:: RuntimeError – Always raised with the error message from MAD-NG.

pymadng.madp_pymad.recv_generic_matrix(self: MadProcess, dtype: dtype) → str

Receive a generic matrix from the MAD-NG pipe.

Parameters:

self (MadProcess) – The MAD-NG process instance.
dtype (np.dtype) – The numpy data type of the matrix.

Returns:

A string representation of the matrix (reshaped numpy array).

Return type:

str

pymadng.madp_pymad.recv_generic_tpsa(self: MadProcess, dtype: dtype) → ndarray

Receive a generic TPSA table from MAD-NG.

Parameters:

self (MadProcess) – The MAD-NG process instance.
dtype (np.dtype) – The numeric data type for coefficients.

Returns:

A tuple (monomial list, coefficients array).

Return type:

np.ndarray

pymadng.madp_pymad.recv_int(self: MadProcess) → int

Receive a 32-bit integer from the MAD-NG pipe.

Parameters:: self (MadProcess) – The MAD-NG process instance.
Returns:: The integer value received from MAD-NG.
Return type:: int

pymadng.madp_pymad.recv_int_matrix(self: MadProcess) → ndarray

Receive a matrix of 32-bit integers from the MAD-NG pipe.

Returns:: The received integer matrix.
Return type:: np.ndarray

pymadng.madp_pymad.recv_int_range(self: MadProcess) → range

Receive an inclusive integer range from the MAD-NG pipe.

Returns:: The received range, inclusive of both ends.
Return type:: range

pymadng.madp_pymad.recv_list(self: MadProcess) → list

Receive a list from the MAD-NG pipe.

Returns:: The received list.
Return type:: list

pymadng.madp_pymad.recv_logrange(self: MadProcess) → ndarray

Receive a logarithmic range from the MAD-NG pipe.

Returns:: The logarithmic range as a numpy array.
Return type:: np.ndarray

pymadng.madp_pymad.recv_matrix(self: MadProcess) → ndarray

Receive a matrix of 64-bit floats from the MAD-NG pipe.

Returns:: The received matrix.
Return type:: np.ndarray

pymadng.madp_pymad.recv_monomial(self: MadProcess) → ndarray

Receive a monomial from MAD-NG.

Returns:: The received monomial as an array of 8-bit unsigned integers.
Return type:: np.ndarray

pymadng.madp_pymad.recv_nil(self: MadProcess)

Receive a nil value from MAD-NG.

This is a placeholder function as nil is not sent down the pipe, but rather the receiving of the type is used to tell MAD-NG that the value is nil.

Parameters:: self (MadProcess) – The MAD-NG process instance.
Returns:: No value is received.
Return type:: None

pymadng.madp_pymad.recv_num(self: MadProcess) → float64

Receive a 64-bit float from the MAD-NG pipe.

Parameters:: self (MadProcess) – The MAD-NG process instance.
Returns:: The float value received from MAD-NG.
Return type:: np.float64

pymadng.madp_pymad.recv_range(self: MadProcess) → ndarray

Receive a linear range from the MAD-NG pipe.

Returns:: The range as a numpy array.
Return type:: np.ndarray

pymadng.madp_pymad.recv_reference(self: MadProcess)

Receive a reference to an object from MAD-NG.

Returns:: A reference object corresponding to the received variable.
Return type:: BaseMadRef

pymadng.madp_pymad.recv_str(self: MadProcess) → str

Receive a string from the MAD-NG pipe.

Parameters:: self (MadProcess) – The MAD-NG process instance.
Returns:: The string value received from MAD-NG.
Return type:: str

pymadng.madp_pymad.send_bool(self: MadProcess, value: bool) → int

Write a boolean value to the MAD-NG pipe.

Parameters:

self (MadProcess) – The MAD-NG process instance.
value (bool) – The boolean value to send.

Returns:

The number of bytes written to the MAD-NG input stream.

Return type:

int

pymadng.madp_pymad.send_cpx(self: MadProcess, value: complex) → int

Send a complex number to the MAD-NG pipe.

Parameters:

self (MadProcess) – The MAD-NG process instance.
value (complex) – The complex number to send.

Returns:

The number of bytes written to the MAD-NG input stream.

Return type:

int

pymadng.madp_pymad.send_dict(self: MadProcess, dct: dict)

Send a dictionary to the MAD-NG pipe.

Parameters:

self (MadProcess) – The MAD-NG process instance.
dct (dict) – The dictionary to send.

Returns:

The number of bytes written to the MAD-NG input stream.

Return type:

int

Raises:

ValueError – If a key in the dictionary is None, as nil keys are not allowed in Lua.

pymadng.madp_pymad.send_generic_matrix(self: MadProcess, mat: ndarray)

Send a 2D matrix to MAD-NG.

Parameters:

self (MadProcess) – The MAD-NG process instance.
mat (np.ndarray) – A 2-dimensional numpy array to send.

Returns:

None

pymadng.madp_pymad.send_generic_range(self, start: float, stop: float, size: int)

Send a generic range to MAD-NG.

Parameters:

self (MadProcess) – The MAD-NG process instance.
start (float) – The starting value of the range.
stop (float) – The ending value of the range.
size (int) – The number of points in the range.

Returns:

None

pymadng.madp_pymad.send_generic_tpsa(self: MadProcess, monos: np.ndarray, coefficients: np.ndarray, send_num: Callable[[MadProcess, float | complex], None])

Send a generic TPSA table to MAD-NG.

Parameters:

self (MadProcess) – The MAD-NG process instance.
monos (np.ndarray) – 2D array of monomials (must be uint8).
coefficients (np.ndarray) – Array of coefficients corresponding to the monomials.
send_num (Callable) – The function to send a numeric (float or complex) value.

Returns:

None

pymadng.madp_pymad.send_int(self: MadProcess, value: int) → int

Send a 32-bit integer to the MAD-NG pipe.

Parameters:

self (MadProcess) – The MAD-NG process instance.
value (int) – The integer value to send.

Returns:

The number of bytes written to the MAD-NG input stream.

Return type:

int

pymadng.madp_pymad.send_int_range(self: MadProcess, rng: range)

Send an integer range to the MAD-NG pipe.

Parameters:

self (MadProcess) – The MAD-NG process instance.
rng (range) – The range object to send.

Returns:

The number of bytes written.

Return type:

int

pymadng.madp_pymad.send_list(self: MadProcess, lst: list)

Send a list to the MAD-NG pipe.

Parameters:

self (MadProcess) – The MAD-NG process instance.
lst (list) – The list to send.

Returns:

None

pymadng.madp_pymad.send_monomial(self: MadProcess, mono: ndarray)

Send a monomial to MAD-NG.

Parameters:

self (MadProcess) – The MAD-NG process instance.
mono (np.ndarray) – A numpy array representing the monomial.

Returns:

None

pymadng.madp_pymad.send_nil(self: MadProcess, _)

Send a nil value to MAD-NG.

This is a placeholder function as nil is not sent down the pipe, but rather the sending of the type is used to tell MAD-NG that the value is nil. The function is included for consistency with the other send functions.

Parameters:

self (MadProcess) – The MAD-NG process instance.
input – The input value (not used).

Returns:

No value is sent, but the function is included for consistency.

Return type:

None

pymadng.madp_pymad.send_num(self: MadProcess, value: float) → int

Send a 64-bit float to the MAD-NG pipe.

Parameters:

self (MadProcess) – The MAD-NG process instance.
value (float) – The float value to send.

Returns:

The number of bytes written to the MAD-NG input stream.

Return type:

int

pymadng.madp_pymad.send_reference(self, obj: BaseMadRef)

Send a reference to an object in MAD-NG.

Parameters:

self (MadProcess) – The MAD-NG process instance.
obj (BaseMadRef) – The reference object to send.

Returns:

The number of bytes written to the MAD-NG input stream.

Return type:

int

pymadng.madp_pymad.send_str(self: MadProcess, value: str) → int

Send a string to the MAD-NG pipe.

Parameters:

self (MadProcess) – The MAD-NG process instance.
value (str) – The string value to send.

Returns:

The number of bytes written to the MAD-NG input stream.

Return type:

int

pymadng.madp_pymad.write_serial_data(self: MadProcess, dat_fmt: str, *dat: Any) → int

Write data to the MAD-NG pipe in a specific format.”

Parameters:

dat_fmt (str) – The format string for struct.pack.
*dat – The data to be packed and written.

Returns:

The number of bytes written to the MAD-NG input stream.

Return type:

int

PyMAD-NG Reference Layer for Object Communication

class pymadng.madp_classes.MadFunc(name: str, mad_proc: MadProcess)

Bases: MadRef

A high-level MAD function reference.

Enables calling MAD-NG functions with support for method and function invocation. Automatically passes instance or object context as needed.

class pymadng.madp_classes.MadLast(mad_proc: MadProcess)

Bases: object

Manage a temporary ‘_last’ variable in MAD-NG.

This class assigns a unique temporary name for storing return values from MAD-NG functions.

class pymadng.madp_classes.MadLastObject(mad_proc: MadProcess)

Bases: MadLast, MadObject

A high-level representation for ‘_last’ objects that are of object type.

Provides seamless integration of temporary MAD-NG objects with Python functionality.

class pymadng.madp_classes.MadLastRef(mad_proc: MadProcess)

Bases: MadLast, MadRef

A combined reference for ‘_last’ objects.

Inherits from both MadLast and MadRef to provide callable behavior on the last result.

class pymadng.madp_classes.MadObject(name: str, mad_proc: MadProcess)

Bases: MadRef

A high-level MAD object for complex data and table handling.

Inherits from MadRef and extends functionality for retrieving object keys, iteration, and conversion to Pandas dataframes.

convert_to_dataframe(columns: list = None, force_pandas: bool = False)

Converts the object to a pandas dataframe.

Parameters:

columns (list, optional) – List of columns to include in the dataframe. Defaults to None.
force_pandas (bool, optional) – If True, always use pandas.DataFrame. Defaults to False.

Returns:

The dataframe containing the object’s data.

Return type:

pandas.DataFrame or tfs.TfsDataFrame

to_df(columns: list = None, force_pandas: bool = False): See convert_to_dataframe

class pymadng.madp_classes.MadRef(name: str, mad_proc: MadProcess)

Bases: BaseMadRef

A high-level MAD reference.

Wraps a MAD-NG reference so that attribute and item access are transparent. Automatically handles indexing differences between Python and MAD-NG.

eval() → Any

Evaluate the reference and return the value.

Returns:: The evaluated value of the reference in MAD-NG.
Return type:: Any

Helper Functions for Communicating Strings to MAD-NG

pymadng.madp_strings.create_mad_string(py_name, var: Any)

Convert a list of objects into the required string for MAD-NG. Converting string instead of sending more data is up to 2x faster (therefore last resort). Slowdown is mainly due to sending lists of strings.

Convert a Python variable to its MAD-NG string representation.

Handles lists, dictionaries, strings, and MAD references. For non-string or non-primitive types, it falls back on using a receive call.

Parameters:

py_name (str) – The Python reference name in MAD-NG.
var (Any) – The variable to be converted.

Returns:

A tuple containing the formatted string and a list of associated variables.

Return type:

tuple

pymadng.madp_strings.format_args_to_string(py_name, *args)

Convert an argument input to a string used by MAD-NG

Convert positional arguments into a MAD-NG formatted string.

Each argument is processed to produce a string suitable for MAD-NG while collecting any additional variables that require separate sending.

Parameters:

py_name (str) – The Python reference name used in MAD-NG.
*args – Positional arguments to be formatted.

Returns:

A tuple containing the composed argument string and a list of variables to send.

Return type:

tuple

pymadng.madp_strings.format_kwargs_to_string(py_name, **kwargs)

Convert a keyword argument input to a string used by MAD-NG

The function produces a Lua table-like string representation of the arguments and gathers any non-string items in a list for separate sending.

Parameters:

py_name (str) – The name of the Python reference variable in MAD-NG.
**kwargs – Arbitrary keyword arguments to be converted.

Returns:

A tuple with the formatted string and a list of variables to send.

Return type:

tuple

Special Last Object Handler

class pymadng.madp_last.LastCounter(size: int)

Bases: object

Maintain a counter for anonymous ‘_last’ variables in MAD-NG.

The __last__ variable stores the most recent function result in MAD-NG. This helper class tracks available temporary variable indices.

Parameters:: size (int) – The maximum number of temporary ‘_last’ variables available.

get()

set(idx)