From 390fb28cd6df27eccb788cadf5789a5193120248 Mon Sep 17 00:00:00 2001 From: jgray-19 Date: Sat, 27 Jan 2024 21:03:49 +0000 Subject: [PATCH] Add basic documentation on the high level of pymadng --- docs/source/highlevel.rst | 76 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 76 insertions(+) create mode 100644 docs/source/highlevel.rst diff --git a/docs/source/highlevel.rst b/docs/source/highlevel.rst new file mode 100644 index 0000000..178b4ce --- /dev/null +++ b/docs/source/highlevel.rst @@ -0,0 +1,76 @@ +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 :class:`API Reference `. + +When a user initialises a :class:`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. + +.. code-block:: python + + 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 +---------------- + +- :class:`io` - A lua library for reading and writing files. +- :class:`os` - A lua library for interacting with the operating system. +- :class:`math` - A lua library for mathematical functions. +- :class:`table` - A lua library for manipulating tables. +- :class:`string` - A lua library for manipulating strings. +- :class:`MAD` - The main library for accessing all the modules and functions of MAD-NG. +- :class:`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 +---------------- + +- :func:`assert` - A lua function for asserting a condition. +- :func:`print` - A lua function for printing to the console. +- :func:`error` - A lua function for throwing an error. +- :func:`ipairs` - A lua function for iterating over the indexed part of a table (the array part). +- :func:`pairs` - A lua function for iterating over the whole table, including indices and keys (the array and hash parts). +- :func:`tonumber` - A lua function for converting a string to a number. +- :func:`tostring` - A lua function for converting a number to a string. +- :func:`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 :class:`MAD` library, a few of the more important ones are immediately exposed to the user, only in PyMAD-NG, and are listed below: + +- :class:`beam` - See `Beams `_ +- :class:`beta0` - See `Beta0 `_ +- :class:`element` - See `Elements `_ +- :class:`match` - See `Match `_ +- :class:`mtable` - See `MTables `_ +- :class:`object` - See `Objects `_ +- :class:`sequence` - See `Sequences `_ +- :class:`survey` - See `Survey `_ +- :class:`track` - See `Track `_ +- :class:`twiss` - See `Twiss `_ + +Accessing the Global Environment +-------------------------------- + +To access anything in the global environment, we can use the :class:`MAD ` object, for example, to access the :class:`math` library, we can use the following: + +.. code-block:: python + + 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 :func:`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 :doc:`/ex-managing-refs` 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: + +.. code-block:: python + + 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 :class:`MAD ` object, several of libraries and functions are listed above, most of the other necessary functions required can be accessed through the :class:`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. \ No newline at end of file