.. SPDX-FileCopyrightText: 2022 Dominik Vilsmeier

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


The Loco main class
===================

The main ``Loco`` class can be imported from ``accinv.loco``.
Details for its usage are available in the `API documentation <Loco_>`_.
The following aspects are worth pointing out.

The most general way for specifying fit parameters is via ``parameters``.
The argument should be a list of parameter groups. These are available
from the `parameters`_ module.
However, there are a few shorthand arguments for specifying quadrupole,
multipole and gain error parameters:

* ``quadrupoles``: expects the names of thick quadrupoles as specified in the model;
  this a shorthand for `Quadrupoles`_.
* ``multipoles``: expects the name of thin multipoles as specified in the model;
  this a shorthand for `Multipoles`_.
* ``fit_gain_errors``: expects a true or false value; if true, then it will automatically
  add those BPM/steerer gain errors which are not already present in ``parameters``.

With ``customize_residuals`` and ``customize_jacobian``, the user can supply two functions
which allow to modify the computed residuals and Jacobian before they are passed to the
optimizer.

The ``Loco.run`` method allows to specify the maximum number of Jacobian evaluations
via ``maxiter``. Typically, it is a good idea to limit these. Otherwise, the convergence
will be determined by the underlying optimizer.


.. _Loco: ../../api/accinv.loco.html#accinv.loco.Loco
.. _parameters: ../../api/accinv.parameters.html
.. _Quadrupoles: ../../api/accinv.parameters.html#accinv.parameters.Quadrupoles
.. _Multipoles: ../../api/accinv.parameters.html#accinv.parameters.Multipoles