-
Notifications
You must be signed in to change notification settings - Fork 19
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Document how to add custom beamline elements to ImpactX as a user workflow.
- Loading branch information
Showing
6 changed files
with
93 additions
and
14 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,80 @@ | ||
.. _usage-workflows-add-element: | ||
|
||
Add New Beamline Elements | ||
========================= | ||
|
||
In ImpactX, one can easily add new beamline elements as a user. | ||
There are multiple ways to achieve this, which are introduced in this section. | ||
|
||
|
||
Python Programmable Element | ||
--------------------------- | ||
|
||
Using the :ref:`ImpactX Python interface <usage-python>`, a custom element named :py:class:`impactx.elements.Programmable` can be defined to advance particles using NumPy, CuPy, Numba, PyTorch or any other compatible Python library. | ||
|
||
... | ||
|
||
Detailed examples that show usage of the programmable element are: | ||
|
||
* :ref:`FODO cell <examples-fodo-programmable>`: implements a user-defined drift | ||
* :ref:`15 stage laser-plasma accelerator <examples-ml-surrogate>`: implements a user-defined LPA accelerator element using a neural network surrogate via PyTorch | ||
|
||
|
||
Linear Map | ||
---------- | ||
|
||
.. note:: | ||
|
||
We plan to add a simple, linear map element that can be configured in user input. | ||
Follow `issue #538 <https://github.com/ECP-WarpX/impactx/issues/538>`__ for progress. | ||
|
||
|
||
C++ Element | ||
----------- | ||
|
||
Adding a new beamline element directly to the C++ code base of ImpactX is easy and described in the following. | ||
|
||
We store all beamline elements under `src/particles/elements/ <https://github.com/ECP-WarpX/impactx/tree/development/src/particles/elements>`__. | ||
|
||
Let's take a look at an example, the `Drift <https://impactx.readthedocs.io/en/latest/_static/doxyhtml/structimpactx_1_1_drift.html>`__ implementation. | ||
To simplify the logic, we use so-called `mixin classes <https://en.wikipedia.org/wiki/Mixin>`__, which provide commonly used logic for `parallelization, thin/thick elements, alignment error support, etc <https://impactx.readthedocs.io/en/latest/_static/doxyhtml/namespaceimpactx_1_1elements.html>`__. | ||
|
||
.. literalinclude:: ../../../src/particles/elements/Drift.H | ||
:language: cpp | ||
:dedent: 4 | ||
:start-at: struct Drift | ||
:end-at: static constexpr auto name = "Drift"; | ||
|
||
After this brief boilerplate, our beamline elements implement three simple parts: | ||
|
||
* a constructor: storing element options | ||
* a single-particle operator: pushing the beam particles | ||
* a reference-particle operator: pushing the reference particle | ||
|
||
.. dropdown:: Example Element: Drift.H | ||
:color: light | ||
:icon: info | ||
:animate: fade-in-slide-down | ||
|
||
.. literalinclude:: ../../../src/particles/elements/Drift.H | ||
:language: cpp | ||
|
||
As a last step, we expose our C++ beamline elements to Python in `src/python/elements.cpp <https://github.com/ECP-WarpX/impactx/blob/development/src/python/elements.cpp>`__. | ||
|
||
.. dropdown:: Example Python Binding for Drift | ||
:color: light | ||
:icon: info | ||
:animate: fade-in-slide-down | ||
|
||
.. literalinclude:: ../../../src/python/elements.cpp | ||
:language: cpp | ||
:dedent: 8 | ||
:start-at: py::class_<Drift, elements::Thick, elements::Alignment> py_Drift(me, "Drift"); | ||
:end-at: register_beamoptics_push(py_Drift); | ||
|
||
Example pull requests that added a new element and can be taken as an example are: | ||
|
||
* `Chromatic Plasma Lens <https://github.com/ECP-WarpX/impactx/pull/514>`__ | ||
* `Thin-Kick Dipole <https://github.com/ECP-WarpX/impactx/pull/472>`__ | ||
* `Chromatic Elements for Drift, Quad, Uniform Focusing+Solenoid <https://github.com/ECP-WarpX/impactx/pull/356>`__ | ||
* other pull requests under the `component: elements <https://github.com/ECP-WarpX/impactx/pulls?q=is%3Apr+label%3A%22component%3A+elements%22+is%3Amerged+>`__ label |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters