Prepare for release 2024.2

.gitignore

@@ -13,3 +13,4 @@ docs/jupyter_execute
 twiss.tfs
 .vscode/
 dist/
+issues/

README.md

@@ -3,7 +3,7 @@
 [![ci](https://github.com/ULB-Metronu/georges/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/ULB-Metronu/georges/actions/workflows/master.yml)
 [![documentation](https://github.com/ULB-Metronu/georges/actions/workflows/documentation.yml/badge.svg?branch=master)](https://github.com/ULB-Metronu/georges/actions/workflows/documentation.yml)
 ![Python](docs/_static/python_versions.svg)
-![version](https://img.shields.io/badge/version-2024.1-blue)
+![version](https://img.shields.io/badge/version-2024.2-blue)
 
 [![Bugs](https://sonarcloud.io/api/project_badges/measure?project=ULB-Metronu_georges&metric=bugs)](https://sonarcloud.io/summary/overall?id=ULB-Metronu_georges)
 [![Coverage](https://sonarcloud.io/api/project_badges/measure?project=ULB-Metronu_georges&metric=coverage)](https://sonarcloud.io/summary/overall?id=ULB-Metronu_georges)

docs/authors.rst

@@ -17,17 +17,21 @@ Alphabetical list of past and present authors:
 Citation
 ########
 
-Authors of papers including reference to or results obtained with Georges are encouraged to cite as follow::
-
-@article{Georges,
-	author = {Robin Tesse and C{\'e}dric Hernalsteens and Eustache Gnacadja and Nicolas Pauly and Eliott Ramoisiaux and Marion Vanwelde},
-	doi = {https://doi.org/10.1016/j.softx.2023.101579},
-	journal = {SoftwareX},
-	pages = {101579},
-	title = {Georges: A modular Python library for seamless beam dynamics simulations and optimization},
-	volume = {24},
-	year = {2023}
-   }
+Authors of papers including reference to or results obtained with Georges are encouraged to cite as follows:
+
+.. code-block:: bibtex
+
+    @article{Georges,
+        author  = {Robin Tesse and C{\'e}dric Hernalsteens and Eustache Gnacadja and Nicolas Pauly and Eliott Ramoisiaux and Marion Vanwelde},
+        doi     = {https://doi.org/10.1016/j.softx.2023.101579},
+        journal = {SoftwareX},
+        pages   = {101579},
+        title   = {Georges: A modular Python library for seamless beam dynamics simulations and optimization},
+        volume  = {24},
+        year    = {2023}
+    }
+
+
 
 List of publications
 ####################

docs/changelog.rst

@@ -2,6 +2,15 @@
 Changelog
 *********
 
+* 2024-2
+
+    * Add documentation for integrators
+    * Fix a bug when creating the Manzoni Input
+    * Add some tests
+
+.. todolist::
+
+
 * 2024-1
 
     * Add doctest
@@ -11,8 +20,6 @@ Changelog
     * Add the paper published in Software-X
     * Update librairies
 
-.. todolist::
-
 * 2023-1
 
     * Add documentation of the PTW module

docs/index.rst

@@ -66,7 +66,7 @@ Indices and tables
 
 .. |Python version| image:: _static/python_versions.svg
 
-.. |version| image:: https://img.shields.io/badge/version-2023.1-blue
+.. |version| image:: https://img.shields.io/badge/version-2024.2-blue
 
 .. |Bugs| image:: https://sonarcloud.io/api/project_badges/measure?project=ULB-Metronu_georges&metric=bugs
    :target: https://sonarcloud.io/summary/overall?id=ULB-Metronu_georges

docs/installation.rst

@@ -13,7 +13,7 @@ For development purposes you can copy the source code on your computer. georges
 You can  stay on the bleeding-edge master branch or you can checkout
 a release tag::
 
-    git checkout tags/2023.1
+    git checkout tags/2024.2
 
 The installation process to get George’s running is relatively simple: the whole library is ready to
 be installed with `Poetry <https://python-poetry.org/>`_. However, depending your configuration,

docs/modules/manzoni.rst

@@ -31,6 +31,15 @@ The module is structured as depicted in figure below and described in the next s
 
     manzoni/structure
 
+Integrators
+===========
+
+..  toctree::
+    :hidden:
+    :maxdepth: 1
+
+    manzoni/manzoni_integrators
+
 
 Examples
 ========

docs/modules/manzoni/manzoni_integrators.rst

@@ -0,0 +1,27 @@
+Particle tracking with Manzoni
+##############################
+
+The transport of charged particles in a magnetic element can be described using the following matrix formalism:
+
+.. math::
+    X_i = \sum_j X_j R_{ij} + \sum_{jk} X_{ij} T_{ijk},
+
+where ``X`` is a vector containing the particle's properties, and ``R`` and ``T`` are the propagation matrices and tensors,
+respectively. This matrix formalism is notably employed in the particle accelerator field due to its effectiveness in
+mathematically describing the dynamics of charged particles moving through electromagnetic fields. It simplifies the
+analysis of particle behavior, facilitates beam optimization and component design, and enables accurate particle
+accelerator simulations.
+
+For each element, a first (``𝑅``) and second-order (``𝑇``) type propagation is implemented, allowing the user to select
+the proper tracking order for his specific application. Three different integrator types are implemented in Manzoni:
+
+    * MadX
+    * Transport
+    * MAD-8
+
+The user should be aware that the canonical variables of the particles are not the same for the three different integrator
+types, so the definition of the beam must be done accordingly to be consistent. The integrators ``Mad8-type`` and
+``Transport`` add higher-order terms (``𝑇``) to the matrix formalism, as the output coordinate does not depend linearly
+on the coordinate of the incoming particle. On the other hand, the ``MadX`` integrator is linear in the spatial coordinates
+and angles but exact in the momentum deviation, making it much more precise when we are interested in beams with a large
+energy spread.

georges/manzoni/beam.py

@@ -60,6 +60,10 @@ def distribution(self, dist: np.ndarray):
 
 
 class MadXBeam(Beam):
+    """
+    Beam distribution for MADX Integrator (x, x', y, y', dpp, pt)
+    """
+
     def __init__(self, kinematics: _Kinematics, distribution: np.ndarray, first_order: bool = False):
         super().__init__(kinematics=kinematics, distribution=distribution)
         pt = Beam.compute_pt(
@@ -73,5 +77,13 @@ def __init__(self, kinematics: _Kinematics, distribution: np.ndarray, first_orde
 
 
 class TransportBeam(Beam):
+    """
+    Beam distribution for Transport Integrator (x, x', y, y', l, dpp)
+    """
+
     def __init__(self, kinematics: _Kinematics, distribution: np.ndarray):
         super().__init__(kinematics=kinematics, distribution=distribution)
+        self._distribution = np.zeros((len(distribution), 6))
+        self._distribution[:, :-1] = distribution
+        self._distribution[:, -1] = 0
+        self._distribution[:, [-2, -1]] = self._distribution[:, [-1, -2]]

georges/manzoni/elements/magnets.py

@@ -436,7 +436,7 @@ class Fringeout(Bend):
         PARAMETERS (dict): Dictionary containing the parameters of the Fringeout with their default values.
 
     Examples:
-        >>> f2 = Fringeout('F2', L=1*_ureg.mm, ANGLE=30*_ureg.degrees, E1=5*_ureg.degrees,
+        >>> f2 = Fringeout('F2', L=1*_ureg.mm, ANGLE=30*_ureg.degrees, E2=5*_ureg.degrees,
         ...                 HGAP=2*_ureg.cm, K1=3*_ureg.m**-2, R2=1*_ureg.cm)
         >>> f2 #doctest: +NORMALIZE_WHITESPACE
             Fringeout: {'NAME': 'F2',
@@ -450,8 +450,8 @@ class Fringeout(Bend):
                        'K1': <Quantity(3, '1 / meter ** 2')>,
                        'K2': <Quantity(0.0, '1 / meter ** 3')>,
                        'L': <Quantity(1, 'millimeter')>,
-                       'E1': <Quantity(5, 'degree')>,
-                       'E2': <Quantity(0.0, 'radian')>,
+                       'E1': <Quantity(0.0, 'radian')>,
+                       'E2': <Quantity(5, 'degree')>,
                        'TILT': <Quantity(0.0, 'radian')>,
                        'HGAP': <Quantity(2, 'centimeter')>,
                        'FINT': 0.0, 'FINTX': 0.0,

georges/manzoni/input.py

@@ -163,10 +163,14 @@ def set_parameters(self, element: str, parameters: Dict):
             self.sequence[self.mapper[element]].__setattr__(param, parameters[param])
         self.sequence[self.mapper[element]].freeze()
 
-    def get_parameters(self, element: str, parameters: Optional[List] = None):
+    def get_parameters(self, element: str, parameters: Optional[Union[List, str]] = None):
         if parameters is None:
             parameters = self.sequence[self.mapper[element]].attributes
-        return dict(zip(parameters, list(map(self.sequence[self.mapper[element]].__getattr__, parameters))))
+            return dict(zip(parameters, list(map(self.sequence[self.mapper[element]].__getattr__, parameters))))
+        if isinstance(parameters, List):
+            return dict(zip(parameters, list(map(self.sequence[self.mapper[element]].__getattr__, parameters))))
+        if parameters is not None and isinstance(parameters, str):
+            return self.sequence[self.mapper[element]].__getattr__(parameters)
 
     @classmethod
     def insert_thin_element(
@@ -222,8 +226,9 @@ def from_sequence(
             element = element.replace({_np.nan: None})
             element_class = getattr(elements, MANZONI_FLAVOR.get(element["CLASS"], element["CLASS"]))
             parameters = list(set(list(element.index.values)).intersection(element_class.PARAMETERS.keys()))
+            params = element[parameters].dropna()  # Remove the None from the parameters.
             input_sequence.append(
-                element_class(name, **element[parameters]),
+                element_class(name, **params),
             )
         element_mapper = {k: v for v, k in enumerate(list(df_sequence.index.values))}
         return cls(sequence=input_sequence, mapper=element_mapper)

georges/manzoni/kernels.py

@@ -9,7 +9,7 @@
 
 
 @njit(nogil=True)  # no parallel jit found
-def batched_vector_matrix(b1: _np.ndarray, b2: _np.ndarray, matrix: _np.ndarray):  # pragma: no cover
+def batched_vector_matrix(b1: _np.ndarray, b2: _np.ndarray, matrix: _np.ndarray):
     """
 
     Args:
@@ -24,7 +24,7 @@ def batched_vector_matrix(b1: _np.ndarray, b2: _np.ndarray, matrix: _np.ndarray)
 
 
 @njit(parallel=True, nogil=True)
-def batched_vector_tensor(b1: _np.ndarray, b2: _np.ndarray, tensor: _np.ndarray):  # pragma: no cover
+def batched_vector_tensor(b1: _np.ndarray, b2: _np.ndarray, tensor: _np.ndarray):
     """
 
     Args:
@@ -51,7 +51,7 @@ def batched_vector_matrix_tensor(
     b2: _np.ndarray,
     matrix: _np.ndarray,
     tensor: _np.ndarray,
-):  # pragma: no cover
+):
     """
 
     Args:
@@ -75,5 +75,5 @@ def batched_vector_matrix_tensor(
 
 
 @njit
-def matrix_matrix(m1, m2):  # pragma: no cover
+def matrix_matrix(m1, m2):
     return _np.matmul(m1, m2)