Calculate Linear Transfer Map #1256

ax3l · 2026-01-02T23:35:59Z

Add a transfer_map(ref, order="linear", fallback_identity_map=False) method to the element list, supporting the calculation of a linear transfer map of all elements in the list.

Close #1254

To Do / To Discuss

Python: implementation, test, docs
Implementation: Do we need to advance the reference particle with every element?
Do we need an output/diagnostics (to a file) for inputs files? Should we skip it and add it later/when users ask for it?
Will we ever be able to support on lattice a transfer map calculation that is non-linear via a lattice... method or should we rather add an interface to sim. ... (assuming higher-order transfer maps require particle tracking) - discussed: the primary use cases are only on the reference particle trajectory (linear and higher order). We could add this to tracking for the few collective effects that change the reference particle, but this is uncommon.

Add a `transfer_map(ref, order="linear", fallback_identity_map=False)` method to the element list, supporting the calculation of a linear transfer map of all elements in the list.

src/python/elements.cpp

ax3l · 2026-01-08T00:10:04Z

docs/source/usage/python.rst

      :return: True if at least one element of the specified kind exists
      :rtype: bool

+   .. py::method:: transfer_map(ref, order="linear", fallback_identity_map=False)


For review: we could also make order a number, if that is more sensible (linear: 1, etc.).

I think this is fine as-is for now. The best key word really depends on what options we would like to support in the future. For example, we could have multiple methods of computing the map (e.g., using Taylor maps or automatic differentiation or Lie maps), and "method" would be a good key word.

I could also remove the order keyword at all for now, since we do not use it. We can always introduce more keywords when we need them.

ax3l · 2026-01-08T00:10:37Z

docs/source/usage/python.rst

+      :param ref: A reference particle.
+      :param order: So far, only the calculation of linear transfer maps is supported.
+      :param fallback_identity_map: For elements with an undefined transfer map in the lattice, assume the identity matrix.
+      :return: The transfer map of all elements in the list.


For review: if we are later on calculating higher orders, should we return a list of transfer maps (one per order)?

For higher orders, there are several ways to represent the map, which may be organized into one (or more) arrays. It's useful to organize these by order-by-order. However, regarding terminology all this information is usually referred to as one map (singular).

ax3l · 2026-01-08T00:11:34Z

src/python/elements.cpp

+        .def(
+            "transfer_map",
+            [](
+                KnownElementsList &v,
+                RefPart ref, // note: intentional copy
+                std::string order,
+                bool fallback_identity_map
+            )
+            {


I think we could also implement this part fully in Python and it would probably be cleaner.
Only the exception handling in the inner loop is likely (quite) slower.

Can also be done later, when we find that we like to implement higher order logic rather in Python than C++.

src/python/elements.cpp

cemitch99 · 2026-01-08T17:23:17Z

tests/python/test_lattice_optics.py

+            [9.98334297e-02, 4.99583537e-02, 0, 0, 1.00000000e00, -1.66466013e-03],
+            [0, 0, 0, 0, 0, 1.00000000e00],
+        ]
+    )


Are these currently the true expected values or just dummy values?

I quickly put in the current computational result as expected. We should verify manually.

Oh, def wrong values because of the multiplication order mix up :D

tests/python/test_lattice_optics.py

Co-authored-by: Chad Mitchell <[email protected]>

src/python/elements.cpp

Co-authored-by: Chad Mitchell <[email protected]>

cemitch99

I fixed the existing test and ran some additional sanity checks, and everything looks good.

ax3l · 2026-01-13T00:54:53Z

Thank you! :)

ax3l · 2026-01-13T00:55:41Z

src/python/elements.cpp

-                    linear_transfer_map = linear_transfer_map * element_transport_map;
+                    linear_transfer_map = element_transport_map * linear_transfer_map;
                    // TODO: shorthand needs https://github.com/AMReX-Codes/amrex/pull/4880 from AMReX 26.02+
                    // result *= element_transport_map;


Comment cleanup needed: result *= element_transport_map; is not identical to the line above.

Follow-up to #1256

Calculate Linear Transfer Map

f673247

Add a `transfer_map(ref, order="linear", fallback_identity_map=False)` method to the element list, supporting the calculation of a linear transfer map of all elements in the list.

ax3l requested a review from cemitch99 January 2, 2026 23:35

ax3l assigned cemitch99 Jan 2, 2026

ax3l added component: elements Elements/external fields component: python Python bindings tracking: reference orbit component: diagnostics all types of outputs labels Jan 2, 2026

ax3l added this to the Advanced Methods (SciDAC-5) milestone Jan 2, 2026

ax3l mentioned this pull request Jan 2, 2026

Output of transfer maps #961

Open

ax3l commented Jan 2, 2026

View reviewed changes

src/python/elements.cpp Outdated Show resolved Hide resolved

ax3l commented Jan 8, 2026

View reviewed changes

Push Reference Particle

d2185ef

ax3l force-pushed the topic-lin-transport-map branch from 8730e11 to d2185ef Compare January 8, 2026 00:14

ax3l mentioned this pull request Jan 8, 2026

SmallMatrix operator*= for MM AMReX-Codes/amrex#4880

Closed

5 tasks

cemitch99 reviewed Jan 8, 2026

View reviewed changes

src/python/elements.cpp Show resolved Hide resolved

cemitch99 reviewed Jan 8, 2026

View reviewed changes

tests/python/test_lattice_optics.py Outdated Show resolved Hide resolved

Fix Typo

58da126

Co-authored-by: Chad Mitchell <[email protected]>

cemitch99 reviewed Jan 8, 2026

View reviewed changes

src/python/elements.cpp Outdated Show resolved Hide resolved

cemitch99 reviewed Jan 8, 2026

View reviewed changes

src/python/elements.cpp Outdated Show resolved Hide resolved

ax3l and others added 2 commits January 8, 2026 14:12

Fix transport

9816f22

Co-authored-by: Chad Mitchell <[email protected]>

Update test to account for modified multiplication order.

a71d1d8

cemitch99 approved these changes Jan 8, 2026

View reviewed changes

cemitch99 merged commit 8f0acde into BLAST-ImpactX:development Jan 12, 2026
17 checks passed

ax3l deleted the topic-lin-transport-map branch January 13, 2026 00:54

ax3l commented Jan 13, 2026

View reviewed changes

ax3l added a commit that referenced this pull request Jan 13, 2026

Cleanup Comment of Map Multiply

4d38126

Follow-up to #1256

Calculate Linear Transfer Map #1256

Calculate Linear Transfer Map #1256

Uh oh!

Conversation

ax3l commented Jan 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

To Do / To Discuss

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cemitch99 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ax3l commented Jan 13, 2026

Uh oh!

ax3l Jan 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

ax3l commented Jan 2, 2026 •

edited

Loading

ax3l Jan 13, 2026 •

edited

Loading