Improve documentation

.gitignore

@@ -18,3 +18,4 @@ distributions
 docs/_build
 
 dev*
+*.glb

.vscode/ltex.dictionary.en-GB.txt

@@ -53,3 +53,6 @@ EuXFEL
 dtype
 DOOCS
 subclassing
+backpropagation
+autograd
+paraxial

CHANGELOG.md

@@ -21,6 +21,7 @@
 
 - Non-deterministic torch features now raise a warning in tests instead of a failure. This also fixes a test failure introduced by changes on the MPS backend in PyTorch 2.13. (see #655) (@Hespe, @jank324)
 - Add example notebook on implementing custom elements to documentation (see #522) (@jank324)
+- New _Getting Started_ guide in the documentation with a more comprehensive overview of Cheetah's features and capabilities etc. (see #651) (@jank324)
 
 ### 🌟 First Time Contributors
 

cheetah/accelerator/aperture.py

@@ -31,7 +31,7 @@ class Aperture(Element):
     :param metadata: Dictionary of arbitrary, serialisable annotations attached to the
         element (e.g. control-system addresses or PVs). This information is *not* used
         in simulation and may contain any extra data the user wants to store along with
-        the lattice. See :doc:`/examples/including_metadata` for more information.
+        the lattice. See :doc:`/getting_started/control_systems` for more information.
     :param device: Device on which to create the element's tensors.
     :param dtype: Data type of the element's tensors.
     """

cheetah/accelerator/bpm.py

@@ -24,7 +24,7 @@ class BPM(Element):
     :param metadata: Dictionary of arbitrary, serialisable annotations attached to the
         element (e.g. control-system addresses or PVs). This information is *not* used
         in simulation and may contain any extra data the user wants to store along with
-        the lattice. See :doc:`/examples/including_metadata` for more information.
+        the lattice. See :doc:`/getting_started/control_systems` for more information.
     :param device: Device on which to create the element's tensors.
     :param dtype: Data type of the element's tensors.
     """

cheetah/accelerator/cavity.py

@@ -43,7 +43,7 @@ class Cavity(Element):
     :param metadata: Dictionary of arbitrary, serialisable annotations attached to the
         element (e.g. control-system addresses or PVs). This information is *not* used
         in simulation and may contain any extra data the user wants to store along with
-        the lattice. See :doc:`/examples/including_metadata` for more information.
+        the lattice. See :doc:`/getting_started/control_systems` for more information.
     :param device: Device on which to create the element's tensors.
     :param dtype: Data type of the element's tensors.
     """

cheetah/accelerator/combined_corrector.py

@@ -31,7 +31,7 @@ class CombinedCorrector(Element):
     :param metadata: Dictionary of arbitrary, serialisable annotations attached to the
         element (e.g. control-system addresses or PVs). This information is *not* used
         in simulation and may contain any extra data the user wants to store along with
-        the lattice. See :doc:`/examples/including_metadata` for more information.
+        the lattice. See :doc:`/getting_started/control_systems` for more information.
     :param device: Device on which to create the element's tensors.
     :param dtype: Data type of the element's tensors.
     """

cheetah/accelerator/custom_transfer_map.py

@@ -23,7 +23,7 @@ class CustomTransferMap(Element):
     :param metadata: Dictionary of arbitrary, serialisable annotations attached to the
         element (e.g. control-system addresses or PVs). This information is *not* used
         in simulation and may contain any extra data the user wants to store along with
-        the lattice. See :doc:`/examples/including_metadata` for more information.
+        the lattice. See :doc:`/getting_started/control_systems` for more information.
     :param device: Device on which to create the element's tensors.
     :param dtype: Data type of the element's tensors.
     """

cheetah/accelerator/dipole.py

@@ -48,7 +48,7 @@ class Dipole(Element):
     :param metadata: Dictionary of arbitrary, serialisable annotations attached to the
         element (e.g. control-system addresses or PVs). This information is *not* used
         in simulation and may contain any extra data the user wants to store along with
-        the lattice. See :doc:`/examples/including_metadata` for more information.
+        the lattice. See :doc:`/getting_started/control_systems` for more information.
     :param device: Device on which to create the element's tensors.
     :param dtype: Data type of the element's tensors.
     """

cheetah/accelerator/drift.py

@@ -25,7 +25,7 @@ class Drift(Element):
     :param metadata: Dictionary of arbitrary, serialisable annotations attached to the
         element (e.g. control-system addresses or PVs). This information is *not* used
         in simulation and may contain any extra data the user wants to store along with
-        the lattice. See :doc:`/examples/including_metadata` for more information.
+        the lattice. See :doc:`/getting_started/control_systems` for more information.
     :param device: Device on which to create the element's tensors.
     :param dtype: Data type of the element's tensors.
     """

cheetah/accelerator/element.py

@@ -26,7 +26,7 @@ class Element(ABC, nn.Module):
     :param metadata: Dictionary of arbitrary, serialisable annotations attached to the
         element (e.g. control-system addresses or PVs). This information is *not* used
         in simulation and may contain any extra data the user wants to store along with
-        the lattice. See :doc:`/examples/including_metadata` for more information.
+        the lattice. See :doc:`/getting_started/control_systems` for more information.
     :param device: Device on which to create the element's tensors.
     :param dtype: Data type of the element's tensors.
     """

cheetah/accelerator/horizontal_corrector.py

@@ -29,7 +29,7 @@ class HorizontalCorrector(Element):
     :param metadata: Dictionary of arbitrary, serialisable annotations attached to the
         element (e.g. control-system addresses or PVs). This information is *not* used
         in simulation and may contain any extra data the user wants to store along with
-        the lattice. See :doc:`/examples/including_metadata` for more information.
+        the lattice. See :doc:`/getting_started/control_systems` for more information.
     :param device: Device on which to create the element's tensors.
     :param dtype: Data type of the element's tensors.
     """

cheetah/accelerator/marker.py

@@ -20,7 +20,7 @@ class Marker(Element):
     :param metadata: Dictionary of arbitrary, serialisable annotations attached to the
         element (e.g. control-system addresses or PVs). This information is *not* used
         in simulation and may contain any extra data the user wants to store along with
-        the lattice. See :doc:`/examples/including_metadata` for more information.
+        the lattice. See :doc:`/getting_started/control_systems` for more information.
     :param device: Device on which to create the element's tensors.
     :param dtype: Data type of the element's tensors.
     """

cheetah/accelerator/quadrupole.py

@@ -41,7 +41,7 @@ class Quadrupole(Element):
     :param metadata: Dictionary of arbitrary, serialisable annotations attached to the
         element (e.g. control-system addresses or PVs). This information is *not* used
         in simulation and may contain any extra data the user wants to store along with
-        the lattice. See :doc:`/examples/including_metadata` for more information.
+        the lattice. See :doc:`/getting_started/control_systems` for more information.
     :param device: Device on which to create the element's tensors.
     :param dtype: Data type of the element's tensors.
     """

cheetah/accelerator/rbend.py

@@ -41,7 +41,7 @@ class RBend(Dipole):
     :param metadata: Dictionary of arbitrary, serialisable annotations attached to the
         element (e.g. control-system addresses or PVs). This information is *not* used
         in simulation and may contain any extra data the user wants to store along with
-        the lattice. See :doc:`/examples/including_metadata` for more information.
+        the lattice. See :doc:`/getting_started/control_systems` for more information.
     :param device: Device on which to create the element's tensors.
     :param dtype: Data type of the element's tensors.
     """

cheetah/accelerator/screen.py

@@ -55,7 +55,7 @@ class Screen(Element):
     :param metadata: Dictionary of arbitrary, serialisable annotations attached to the
         element (e.g. control-system addresses or PVs). This information is *not* used
         in simulation and may contain any extra data the user wants to store along with
-        the lattice. See :doc:`/examples/including_metadata` for more information.
+        the lattice. See :doc:`/getting_started/control_systems` for more information.
     :param device: Device on which to create the element's tensors.
     :param dtype: Data type of the element's tensors.
     """

cheetah/accelerator/segment.py

@@ -33,7 +33,7 @@ class Segment(Element):
     :param metadata: Dictionary of arbitrary, serialisable annotations attached to the
         element (e.g. control-system addresses or PVs). This information is *not* used
         in simulation and may contain any extra data the user wants to store along with
-        the lattice. See :doc:`/examples/including_metadata` for more information.
+        the lattice. See :doc:`/getting_started/control_systems` for more information.
     :param device: Device on which to create the element's tensors.
     :param dtype: Data type of the element's tensors.
     """

cheetah/accelerator/sextupole.py

@@ -33,7 +33,7 @@ class Sextupole(Element):
     :param metadata: Dictionary of arbitrary, serialisable annotations attached to the
         element (e.g. control-system addresses or PVs). This information is *not* used
         in simulation and may contain any extra data the user wants to store along with
-        the lattice. See :doc:`/examples/including_metadata` for more information.
+        the lattice. See :doc:`/getting_started/control_systems` for more information.
     :param device: Device on which to create the element's tensors.
     :param dtype: Data type of the element's tensors.
     """

cheetah/accelerator/solenoid.py

@@ -33,7 +33,7 @@ class Solenoid(Element):
     :param metadata: Dictionary of arbitrary, serialisable annotations attached to the
         element (e.g. control-system addresses or PVs). This information is *not* used
         in simulation and may contain any extra data the user wants to store along with
-        the lattice. See :doc:`/examples/including_metadata` for more information.
+        the lattice. See :doc:`/getting_started/control_systems` for more information.
     :param device: Device on which to create the element's tensors.
     :param dtype: Data type of the element's tensors.
     """

cheetah/accelerator/space_charge_kick.py

@@ -46,7 +46,7 @@ class SpaceChargeKick(Element):
     :param metadata: Dictionary of arbitrary, serialisable annotations attached to the
         element (e.g. control-system addresses or PVs). This information is *not* used
         in simulation and may contain any extra data the user wants to store along with
-        the lattice. See :doc:`/examples/including_metadata` for more information.
+        the lattice. See :doc:`/getting_started/control_systems` for more information.
     :param device: Device on which to create the element's tensors.
     :param dtype: Data type of the element's tensors.
     """

cheetah/accelerator/superimposed.py

@@ -31,7 +31,7 @@ class Superimposed(Element):
     :param metadata: Dictionary of arbitrary, serialisable annotations attached to the
         element (e.g. control-system addresses or PVs). This information is *not* used
         in simulation and may contain any extra data the user wants to store along with
-        the lattice. See :doc:`/examples/including_metadata` for more information.
+        the lattice. See :doc:`/getting_started/control_systems` for more information.
     :param device: Device on which to create the element's tensors.
     :param dtype: Data type of the element's tensors.
     """

cheetah/accelerator/transverse_deflecting_cavity.py

@@ -36,7 +36,7 @@ class TransverseDeflectingCavity(Element):
     :param metadata: Dictionary of arbitrary, serialisable annotations attached to the
         element (e.g. control-system addresses or PVs). This information is *not* used
         in simulation and may contain any extra data the user wants to store along with
-        the lattice. See :doc:`/examples/including_metadata` for more information.
+        the lattice. See :doc:`/getting_started/control_systems` for more information.
     :param device: Device on which to create the element's tensors.
     :param dtype: Data type of the element's tensors.
     """

cheetah/accelerator/undulator.py

@@ -30,7 +30,7 @@ class Undulator(Element):
     :param metadata: Dictionary of arbitrary, serialisable annotations attached to the
         element (e.g. control-system addresses or PVs). This information is *not* used
         in simulation and may contain any extra data the user wants to store along with
-        the lattice. See :doc:`/examples/including_metadata` for more information.
+        the lattice. See :doc:`/getting_started/control_systems` for more information.
     :param device: Device on which to create the element's tensors.
     :param dtype: Data type of the element's tensors.
     """

cheetah/accelerator/vertical_corrector.py

@@ -29,7 +29,7 @@ class VerticalCorrector(Element):
     :param metadata: Dictionary of arbitrary, serialisable annotations attached to the
         element (e.g. control-system addresses or PVs). This information is *not* used
         in simulation and may contain any extra data the user wants to store along with
-        the lattice. See :doc:`/examples/including_metadata` for more information.
+        the lattice. See :doc:`/getting_started/control_systems` for more information.
     :param device: Device on which to create the element's tensors.
     :param dtype: Data type of the element's tensors.
     """