simba-accelerator 0.6.0__tar.gz → 0.7.0__tar.gz

simba_accelerator-0.7.0/.github/workflows/tests.yml

@@ -0,0 +1,77 @@
+name: Tests
+
+on:
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: "0 3 * * *"
+  workflow_dispatch:
+
+jobs:
+  unit-tests:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install simba
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .[test,simcodes]
+
+      - name: Use LAURA's branch of the same name, if there is one
+        run: |
+          laura=https://github.com/astec-stfc/laura.git
+          branch="${{ github.head_ref || github.ref_name }}"
+          if git ls-remote --exit-code --heads "$laura" "$branch" >/dev/null; then
+            # LAURA's v* tags are lightweight, so a branch build describes itself as 0.9b1.postN,
+            # below simba's laura-accelerator>=1.1.0: version it as the latest release + the branch
+            release=$(git ls-remote --tags --sort=-v:refname "$laura" 'v*' | grep -v '\^{}' | head -1 | sed 's|.*refs/tags/v||')
+            export SETUPTOOLS_SCM_PRETEND_VERSION_FOR_LAURA_ACCELERATOR="$release+$(echo "$branch" | tr -c '[:alnum:]\n' '.')"
+            pip install "laura-accelerator @ git+$laura@$branch"
+          fi
+
+      - name: Run unit tests (no container image needed)
+        run: pytest unit_tests/ -v -m "not needs_container"
+
+  container-tests:
+    # The simcodes image is several GB, so only pull it nightly or on demand.
+    if: github.event_name != 'pull_request'
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install simba
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .[test,simcodes]
+
+      - name: Use LAURA's branch of the same name, if there is one
+        run: |
+          laura=https://github.com/astec-stfc/laura.git
+          branch="${{ github.head_ref || github.ref_name }}"
+          if git ls-remote --exit-code --heads "$laura" "$branch" >/dev/null; then
+            # LAURA's v* tags are lightweight, so a branch build describes itself as 0.9b1.postN,
+            # below simba's laura-accelerator>=1.1.0: version it as the latest release + the branch
+            release=$(git ls-remote --tags --sort=-v:refname "$laura" 'v*' | grep -v '\^{}' | head -1 | sed 's|.*refs/tags/v||')
+            export SETUPTOOLS_SCM_PRETEND_VERSION_FOR_LAURA_ACCELERATOR="$release+$(echo "$branch" | tr -c '[:alnum:]\n' '.')"
+            pip install "laura-accelerator @ git+$laura@$branch"
+          fi
+
+      - name: Pull simcodes image
+        run: docker pull ghcr.io/astec-stfc/simcodes-docker:master
+
+      - name: Run tracking tests via docker
+        run: pytest unit_tests/ -v -m needs_container

{simba_accelerator-0.6.0 → simba_accelerator-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simba-accelerator
-Version: 0.6.0
+Version: 0.7.0
 Summary: A python framework for particle accelerator simulations
 Author-email: James Jones <james.jones@stfc.ac.uk>
 Maintainer-email: James Jones <james.jones@stfc.ac.uk>, Alex Brynes <alexander.brynes@stfc.ac.uk>, Mark Johnson <mark.johnson@stfc.ac.uk>
@@ -36,15 +36,19 @@ Requires-Dist: pyfftw
 Requires-Dist: numexpr
 Requires-Dist: openpmd-beamphysics>=0.10
 Requires-Dist: xopt
-Requires-Dist: laura-accelerator>=1.1.0
+Requires-Dist: laura-accelerator>=1.1.2
 Requires-Dist: pytao>=1.0.0
 Requires-Dist: nafflib
 Provides-Extra: simcodes
 Requires-Dist: ocelot-desy==25.06.0; extra == "simcodes"
 Requires-Dist: xsuite>=0.39.0; extra == "simcodes"
+Requires-Dist: xwakes>=0.2; extra == "simcodes"
 Requires-Dist: cheetah-accelerator>=0.8.4; extra == "simcodes"
 Requires-Dist: Wake-T>=0.8.0; extra == "simcodes"
 Requires-Dist: cpymad>=1.19.0; extra == "simcodes"
+Provides-Extra: fbpic
+Requires-Dist: fbpic>=0.27; extra == "fbpic"
+Requires-Dist: periodictable; extra == "fbpic"
 Provides-Extra: test
 Requires-Dist: pytest; extra == "test"
 Requires-Dist: pytest-cov; extra == "test"

{simba_accelerator-0.6.0 → simba_accelerator-0.7.0}/docs/source/SimCodes.rst

@@ -26,6 +26,7 @@ whether a container runtime is used for the other codes:
 
 * `Ocelot <https://github.com/ocelot-collab/ocelot>`_ :cite:`OCELOT`
 * `Xsuite <https://github.com/xsuite>`_ :cite:`Xsuite`
+* `ImpactX <https://impactx.readthedocs.io>`_
 * `Cheetah <https://github.com/desy-ml/cheetah>`_ :cite:`Cheetah`
 * `Wake-T <https://github.com/AngelFP/Wake-T>`_ :cite:`WakeT`
 
@@ -118,7 +119,7 @@ image via the local Docker daemon instead of writing a ``.sif`` file to the ``si
    | ``container_runtime`` covers ASTRA, Elegant, CSRTrack, OPAL, and Genesis. **GPT is not included**,
      as it is proprietary and requires a license; it must be installed locally (see
      :func:`~simba.Codes.Executables.Executables.define_gpt_command`) and run with ``GPTLICENSE`` set.
-   | The python-based codes (Ocelot, Xsuite, Cheetah, Wake-T) run in-process and are unaffected by
+   | The python-based codes (Ocelot, Xsuite, ImpactX, Cheetah, Wake-T) run in-process and are unaffected by
      ``container_runtime`` - install them locally via the ``simcodes`` extra regardless.
 
 .. _windows-wsl:

{simba_accelerator-0.6.0 → simba_accelerator-0.7.0}/docs/source/index.rst

@@ -17,6 +17,7 @@ It provides a wrapper for several well-known particle tracking codes:
 * `Ocelot <https://github.com/ocelot-collab/ocelot>`_ :cite:`OCELOT`
 * `Cheetah <https://github.com/desy-ml/cheetah>`_ :cite:`Cheetah`
 * `Xsuite <https://github.com/xsuite>`_ :cite:`Xsuite`
+* `ImpactX <https://impactx.readthedocs.io>`_
 * `Wake-T <https://github.com/AngelFP/Wake-T>`_ :cite:`WakeT`
 * `MAD-X <https://mad.web.cern.ch/mad/>`_
 * `Bmad <https://www.classe.cornell.edu/bmad/>`_

{simba_accelerator-0.6.0 → simba_accelerator-0.7.0}/docs/source/ring-studies.rst

@@ -257,8 +257,9 @@ is :math:`n \cdot T_{rev}` for 0-based :math:`n`, so each backend converts.
 **Values are the element's strength as the lattice states it** — a deflection angle
 in radians for a steering element, positive toward positive *x* (or *y*), not a
 fraction of anything. Each backend converts into its own code's attribute: a
-corrector's angle is Ocelot's ``angle``, MAD-X's ``kick`` and elegant's ``ANGLE``
-unchanged, but Xtrack's ``knl[0]`` with the **sign reversed**, because a positive
+corrector's angle is Ocelot's ``angle``, MAD-X's ``kick``, elegant's ``ANGLE``
+and ImpactX's ``xkick``/``ykick`` unchanged, but Xtrack's ``knl[0]`` with
+the **sign reversed**, because a positive
 normal multipole deflects the other way there.
 
 **The default rule is** ``hold``, **and that is no code's default.** Every tracking
@@ -409,13 +410,18 @@ How each code does it
    * - MAD-X
      - Between turns of SIMBA's loop: the ring's reference ``p0c`` and time are
        carried from turn to turn rather than taken from the bunch.
+   * - ImpactX
+     - Between turns of SIMBA's loop, as Ocelot: the reference is moved and each
+       particle's ``pt``, ``px`` and ``py`` re-expressed. Its strengths are
+       normalised, so the magnets follow. The exact solenoid's ``bz`` is a
+       field, so it is scaled with the reference's momentum each turn.
    * - Bmad
      - Not supported yet; its tracking path here is single-pass.
 
-``unit_tests/test_energy_ramp.py`` tracks one ramped ring through all four
+``unit_tests/test_energy_ramp.py`` tracks one ramped ring through all five
 codes. Over a 2% ramp with no RF, the ramp moves the orbit by about 1.2e-4 m.
-Xsuite and Ocelot agree with elegant to 1e-7 m and 3e-6 m. MAD-X, whose
-lenses are thin, agrees to 2e-5 m.
+Xsuite, Ocelot and ImpactX agree with elegant to 1e-7 m, 3e-6 m and 6e-8 m.
+MAD-X, whose lenses are thin, agrees to 2e-5 m.
 
 .. _rf-mode:
 
@@ -474,6 +480,10 @@ own. The reference reaches a cavity at
      - synchronous
      - each cavity's ``phi`` between passes. Its sign is the opposite of the
        others', because Ocelot's phase is cosine-based.
+   * - ImpactX
+     - synchronous
+     - each ``ShortRF``'s ``phase`` between passes; the lattice is rebuilt
+       every pass.
 
 .. note::
    **Ocelot's cavity moves the reference.** Its cavity map always adds
@@ -555,9 +565,34 @@ A code that cannot honour a setting warns and carries on.
      - yes
      - no
      - no
+   * - ImpactX
+     - yes
+     - yes
+     - quantum only
+     - yes
+     - yes
+     - yes
+     - yes
+     - no
+     - yes
+   * - BDSIM
+     - yes (circular mode)
+     - no
+     - no
+     - no
+     - no
+     - no
+     - no
+     - no
+     - no
 
 ASTRA, GPT, Cheetah, OPAL, Wake-T and CSRTrack track a line once and have none of these.
 
+BDSIM's turns run inside one Geant4 process, so nothing can change between them.
+It has no reference-momentum ramp, and its field modulators (a sinusoid, or one
+top-hat or linear window in time) cannot express a knotted program, so programs
+and ramps are left unsupported rather than approximated.
+
 .. _native-turns:
 
 Who Counts the Turns
@@ -591,8 +626,8 @@ The two paths are the same tracking, and ``unit_tests/test_madx_native_turns.py`
 holds them to it turn by turn. The override is what lets that test run both.
 
 .. note::
-   Ocelot and Bmad still count turns in Python, and neither has a native turn
-   count to switch to.
+   Ocelot, Bmad and ImpactX still count turns in Python, and none has a native
+   turn count to switch to.
 
    **Bmad.** Tao has no multi-turn beam tracking: ``beam_init`` carries no turn
    count, ``tao.track_beam`` is one pass, and the only turn counts in Tao are
@@ -607,6 +642,39 @@ holds them to it turn by turn. The override is what lets that test run both.
    ``track_nturns``, despite the name, takes a list of single particles and is
    the dynamic-aperture tool, not a ``ParticleArray`` path.
 
+.. note::
+   **BDSIM** takes the count natively, in its circular mode
+   (``option, circular=1, nturns=N``).
+   BDSIM builds the line in 3D and adds a terminator, which counts the turns,
+   and a teleporter, which moves each particle back to the start. The
+   teleporter only bridges a gap of 0.03 µm to 1 m along the beam, so the line
+   must close *geometrically*, through its bends.
+   A ring that closes exactly fails too, so SIMBA takes 2 µm off the last
+   drift. 1 µm of that goes to a drift after the last element, because a
+   sampler next to the terminator counts every turn twice (seen with BDSIM
+   1.7.7).
+
+   A single pass round a closed ring also runs in circular mode, with
+   ``nturns=1``. Otherwise nothing stops the particles and the run never ends.
+
+   Read ``z`` from BDSIM with care. SIMBA rebuilds it from the arrival time,
+   and BDSIM's default ``bdsimmatrix`` integrators leave each particle's path
+   length through a bend out of that time. Through dispersion, ``z`` then keeps
+   its starting spread while MAD-X and elegant show the bunch lengthen, and
+   SIMBA warns (:class:`~simba.exceptions.BunchLengthWarning`). The
+   ``bdsimtwo`` and ``geant4`` sets get the time right; pick one in the
+   ``tracking`` block:
+
+   .. code-block:: yaml
+
+       tracking: {turns: 1000, integrator_set: bdsimtwo}
+
+   On a test ring all three sets agreed with MAD-X particle by particle,
+   ``bdsimtwo`` and ``geant4`` on the bunch length as well. LAURA writes a
+   quadrupole's ``k1`` negated for a negative beam in the ``bdsim*`` sets,
+   whose quadrupole sets the field for a positive particle, and as it is for
+   ``geant4``; every other strength follows the particle's charge in all sets.
+
 What a Ring Run Reports
 -----------------------
 

simba_accelerator-0.7.0/docs/source/simba.Codes.ImpactX.rst

@@ -0,0 +1,21 @@
+simba.Codes.ImpactX package
+===========================
+
+Submodules
+----------
+
+simba.Codes.ImpactX.ImpactX module
+----------------------------------
+
+.. automodule:: simba.Codes.ImpactX.ImpactX
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+Module contents
+---------------
+
+.. automodule:: simba.Codes.ImpactX
+   :members:
+   :show-inheritance:
+   :undoc-members:

{simba_accelerator-0.6.0 → simba_accelerator-0.7.0}/docs/source/simba.Codes.rst

@@ -15,6 +15,7 @@ Subpackages
    simba.Codes.GPT
    simba.Codes.Generators
    simba.Codes.Genesis
+   simba.Codes.ImpactX
    simba.Codes.MADX
    simba.Codes.OPAL
    simba.Codes.Ocelot

{simba_accelerator-0.6.0 → simba_accelerator-0.7.0}/meta.yml

@@ -43,6 +43,7 @@ requirements:
     - ocelot-desy
     - openpmd-beamphysics
     - xsuite
+    - impactx
     - pyfftw
     - deap
     - paramiko

{simba_accelerator-0.6.0 → simba_accelerator-0.7.0}/pyproject.toml

@@ -40,7 +40,7 @@ dependencies = [
     "numexpr",
     "openpmd-beamphysics>=0.10",
     "xopt",
-    "laura-accelerator>=1.1.0",
+    "laura-accelerator>=1.1.2",
     "pytao>=1.0.0",
     "nafflib",
 ]
@@ -57,11 +57,19 @@ classifiers = [
 simcodes = [
     "ocelot-desy==25.06.0",
     "xsuite>=0.39.0",
+    "xwakes>=0.2",
     "cheetah-accelerator>=0.8.4",
     "Wake-T>=0.8.0",
     "cpymad>=1.19.0",
 ]
 
+# FBPIC on a GPU also needs cupy built for the local CUDA version
+# (e.g. cupy-cuda12x or cupy-cuda13x), which is left to the user.
+fbpic = [
+    "fbpic>=0.27",
+    "periodictable",
+]
+
 test = [
     "pytest",
     "pytest-cov",

{simba_accelerator-0.6.0 → simba_accelerator-0.7.0}/simba/Codes/ASTRA/ASTRA.py

@@ -22,7 +22,7 @@ from ...FrameworkHelperFunctions import expand_substitution, saveFile
 from ...Modules import Beams as rbf
 from laura.models.diagnostic import DiagnosticElement
 from laura.models.element import Screen
-from laura.models.physical import PhysicalElement, Position
+from laura.models.physical import PhysicalElement
 from laura.translator.converters.codes.astra import (
     AstraNewRun,
     AstraCharge,
@@ -59,6 +59,9 @@ class astraLattice(frameworkLattice):
     code: str = "astra"
     """String indicating the lattice object type"""
 
+    tracks_multiple_species: ClassVar[bool] = True
+    """ASTRA reads each particle's species from the index column of its distribution."""
+
     allow_negative_drifts: bool = True
     """Flag to indicate whether negative drifts are allowed"""
 
@@ -88,9 +91,6 @@ class astraLattice(frameworkLattice):
     astra_headers: Dict[str, Any] = Field(default_factory=dict)
     """Headers for ASTRA input file"""
 
-    local_frame: bool | None = None
-    """Write the deck in the lattice's own frame (see :meth:`to_local`) rather than world coordinates."""
-
     def model_post_init(self, __context: Any) -> None:
         super().model_post_init(__context)
         self.starting_offset = (
@@ -108,11 +108,6 @@ class astraLattice(frameworkLattice):
             else self.starting_rotation
         )
 
-        if "local_frame" in self.file_block:
-            self.local_frame = bool(self.file_block["local_frame"])
-        elif self.local_frame is None:
-            self.local_frame = abs(self.starting_rotation[2]) > 1e-9
-
         # Create a "newrun" block
         if "input" not in self.file_block:
             self.file_block["input"] = {}
@@ -269,48 +264,9 @@ class astraLattice(frameworkLattice):
         self._toffset = toffset
         self.astra_headers["newrun"].toffset = 1e9 * toffset
 
-    def to_local(self, point) -> np.ndarray:
-        """
-        Map a world position into the deck's frame: origin at the first element's entrance, along +z.
-
-        Parameters
-        ----------
-        point: Position | Sequence[float]
-            LAURA ``Position`` or ``(x, y, z)``
-
-        Returns
-        -------
-        np.ndarray
-            ``(x, y, z)`` in the deck's frame; unchanged if not :attr:`local_frame`
-        """
-        p = np.asarray(getattr(point, "array", point), dtype=float)
-        if not self.local_frame:
-            return p
-        physical = self.startObject.physical
-        origin = np.asarray(physical.start.array, dtype=float)
-        local = physical.rotation_matrix.T @ (p - origin)
-        return np.round(local, 9)
-
-    @property
-    def deck_section(self):
-        """
-        The section as written out; with :attr:`local_frame`, a deep copy moved into that frame.
-
-        Returns
-        -------
-        SectionLatticeTranslator
-        """
-        if not self.local_frame:
-            return self.section
-        section = self.section.model_copy(deep=True)
-        for element in section.elements.elements.values():
-            physical = getattr(element, "physical", None)
-            if physical is None or physical.middle is None:
-                continue
-            x, y, z = self.to_local(physical.middle)
-            physical.middle = Position(x=x, y=y, z=z)
-            physical.global_rotation.theta += self.starting_rotation[2]
-        return section
+    def _frame_rotation(self) -> float:
+        """ASTRA's frame turns by ``starting_rotation``, which a file block may set."""
+        return float(self.starting_rotation[2])
 
     def write(self) -> None:
         """Write :attr:`deck_section` as ASTRA input to ``<master_subdir>/<objectname>.in``."""
@@ -488,7 +444,7 @@ class astraLattice(frameworkLattice):
                 ).strip('"'),
                 normaliseZ=False,
             )
-            if not self.local_frame:
+            if not self.in_local_frame:
                 rbf.hdf5.rotate_beamXZ(
                     beam,
                     -1 * self.starting_rotation[2],
@@ -501,6 +457,7 @@ class astraLattice(frameworkLattice):
             rbf.openpmd.write_openpmd_beam_file(
                 beam,
                 self.global_parameters["master_subdir"] + "/" + HDF5filename,
+                toffset=float(beam._beam.toffset.val),
                 )
             if self.global_parameters["delete_tracking_files"]:
                 os.remove(