.. SPDX-FileCopyrightText: 2022 Dominik Vilsmeier

   SPDX-License-Identifier: GPL-3.0-or-later


Accelerator models
==================

The `Madx`_ class uses MADX via `cpymad`_. Thus, it allows for usage
of the full spectrum of MADX features. Each model offers a few methods
for computing relevant quantities, such as `compute_orm`_. In addition,
the ``Madx`` model also offers a method for computing Twiss data via
`compute_twiss`_.
Each of these methods computes the quantities for the current lattice
configuration but it is possible to specify temporary updates (for the
duration of the computation) to each of these methods; please refer to
the documentation of the different methods for details.

In general, each model offers a context manager `temporary_update`_ which allows
to temporarily upate the model's parameters until the context manager exits.
For example:

.. code-block:: python

   with model.temporary_update(quadrupoles={'quad01': 0.1}):
       orm = model.compute_orm()

This example uses the shorthand function parameter ``quadrupoles`` to directly specify
quadrupoles names and the desired k1-values. Since each of the ``compute_*`` methods
only expects a general ``configuration`` object, the usage of the shorthand ``quadrupoles``
is possible with the helper function `build_configuration_from_parameter_values`_.
The following example is equivalent to the one above:

.. code-block:: python

   config = model.build_configuration_from_parameter_values(quadrupoles={'quad01': 0.1})
   orm = model.compute_orm(config)


.. _cpymad: https://pypi.org/project/cpymad/
.. _Madx: ../../api/accinv.model.html#accinv.model.Madx
.. _compute_orm: ../../api/accinv.model.html#accinv.model.Model.compute_orm
.. _compute_twiss: ../../api/accinv.model.html#accinv.model.OpticsModel.compute_twiss
.. _temporary_update: ../../api/accinv.model.html#accinv.model.Model.temporary_update
.. _build_configuration_from_parameter_values: ../../api/accinv.model.html#accinv.model.Model.build_configuration_from_parameter_values