29 Coordinate Systems
This chapter describes the coordinate and placement concepts used by OPALX and a proposed extension based on named ports and a geometry graph. Current OPALX provides rigid element placement, element-local field frames, and LINE and RING sequences. General named-port connections, patch objects, graph assembly and time-dependent rigid placement are design proposals, not current input interfaces.
29.1 Quick Reader
29.1.1 Symbols and notation
To keep the formulas uniform, this chapter uses the following notation.
| Symbol | Meaning |
|---|---|
| \(K\) | Laboratory or floor Cartesian frame with coordinates \(\mathbf r=(X,Y,Z)\). |
| \(\mathcal B\) | Reference base of the lattice, typically an interval for a transfer line or a closed path for a ring. |
| \(s\) | Reference or reporting coordinate on \(\mathcal B\); in an \(s\)-integrator it is also the independent variable. |
| \(t\) | Physical time and the independent variable of the current OPALX tracker. |
| \(U_i\), \(u_i\) | Canonical local chart of element \(i\) and the corresponding local coordinates. |
| \(\psi_i:U_i\to\mathbb{R}^3\) | Intrinsic geometry map of element \(i\) in its canonical frame. |
| \(\Omega_i\subset U_i\) | Local support region on which the element field, aperture, or material model is defined. |
| \(\Sigma_{i,\alpha}\subset\overline{U_i}\) | Marked geometric interface chart of element \(i\); it need not lie on the boundary of the field support. |
| \(p_{i,\alpha}=(\Sigma_{i,\alpha},F_{i,\alpha})\) | Port \(\alpha\) of element \(i\), consisting of a boundary chart together with an adapted frame \(F_{i,\alpha}\). |
| \(P_i(u_i,t)\) | Placement map that embeds the local chart of element \(i\) into the laboratory frame. |
| \(\mathcal S_i(t)=P_i(\Omega_i,t)\) | Placed support of element \(i\) in laboratory space at time \(t\). |
| \(T_i(t)\) | Rigid placement transform of element \(i\) at time \(t\); it may be written as a rotation matrix \(R_i(t)\) together with a translation vector \(\mathbf a_i(t)\). |
| \(\Gamma_i(\ell)\) | Optional local reference path of element \(i\), parameterized by the local longitudinal coordinate \(\ell\in[0,L_i]\). |
| \(C_{pq}\) | Rigid transition or patch transform from port \(p\) to port \(q\). |
| \(g_{ij}\) | Transition map between neighboring local charts. |
29.1.2 A geometric viewpoint
Following Forest and Hirata [1], one should distinguish the placed physical object from the coordinates used to describe it. In that spirit, an OPALX element is not first of all an interval in one global coordinate \(s\). It is a local chart \(U_i\), an intrinsic geometry map \(\psi_i\), a support region \(\Omega_i\subset U_i\), and a finite set of marked interfaces through which that local chart is connected to neighboring charts.
In the proposed model, a port of element \(i\) consists of a marked geometric interface chart and an adapted frame:
\[\Sigma_{i,\alpha}\subset\overline{U_i},\qquad p_{i,\alpha}=(\Sigma_{i,\alpha},F_{i,\alpha}).\]
Examples are entrance, exit, branch, fiducial and ring-closure interfaces. A body entrance or exit need not coincide with the boundary of the field support \(\Omega_i\), particularly when fringe fields extend beyond the body. The advantage of introducing the word “port” is that the same notion works for a straight drift, a curved bend, a patch, a branch, or a ring-closing connection.
In the proposed representation, connecting two ports would store transition data between their local descriptions. This is a chart-to-chart coordinate change; the fibre-bundle interpretation relates local trivializations [1]. Ports organize that proposed connectivity without introducing new physics. Current OPALX instead stores element transforms and ordered sequence membership, without a general named-port connection object.
A transfer line is then an open chain of ports, while a ring is a closed chain, possibly only up to a prescribed symmetry transform. That is the geometric reason the same placement model can cover both linear and circular machines.
29.1.3 Why the independent variable matters
Comparisons with established accelerator codes provide a useful baseline: MAD-X describes the machine primarily as an ordered sequence of elements along a reference orbit, and survey or optics calculations are performed relative to that backbone [2], [3]. The cited manuals illustrate different emphases in placement and modeling: Elegant remains strongly sequence-centric, MARYLIE is more map-first, IMPACT-T uses ordered field regions with local frame changes, and Bmad exposes geometry operators such as patches and fiducials [4], [5], [6], [7].
In an \(s\)-based tracker, longitudinal position along a reference curve is the independent variable. Many lattice descriptions also use that coordinate to order elements. This does not prevent three-dimensional survey geometry, local coordinate changes, field overlap or branch connections.
In a \(t\)-based tracker, particles advance in physical time and may simultaneously occupy different machine regions. Field evaluation therefore needs the particle position and each element’s local frame and support. OPALX combines time-based tracking with an ordered reference-coordinate representation; compatible analytic rings also use spatial support selection. Named ports are a proposed way to organize connectivity, not a requirement imposed by choosing \(t\) as the independent variable.
This leads to the main OPALX conclusion:
- topology,
- survey or reference-curve metadata,
- rigid placement in laboratory space, and
- physics field evaluation
should be treated as separate concepts, even if they are often conflated in traditional \(s\)-based lattice descriptions.
29.2 Geometry Design Principles
29.2.1 Forest-Hirata bundles versus differential geometry
The Forest-Hirata appendix gives a clean abstract reformulation of local element placement [1]. The lattice is treated as a fibre bundle over the machine loop; local neighbourhoods are element intervals; the fibres may be coordinate frames, particle coordinates, maps, or envelopes; and the matching block between local descriptions is a transition function \(g_{ij}\in G\).
The present OPALX note uses a more concrete differential-geometric language. Each element may carry a reference path \(\Gamma_i(\ell)\), a moving orthonormal frame, marked interface charts, and a placed support region in laboratory space. This is closer to implementation because it directly supports field evaluation, aperture checks, and coordinate conversion inside an element.
The two viewpoints answer different questions:
- use differential geometry locally inside an element whenever a curved or adapted chart is numerically useful;
- use fibre-bundle-style transition maps to connect neighboring charts, branches, anchors, and closures without pretending that there must be one globally preferred frame.
29.2.2 Current OPALX implementation context
The current tracker advances particles in physical time. Ordinary particle transport uses a Boris-Buneman update. Elements have rigid spatial placement and local field frames; field assembly uses orbit-threader support queries or specialized spatial selection for compatible analytic rings.
The port graph, generalized placement tuple and dynamic-motion transforms below are proposed extensions. They do not describe an existing general port-graph implementation.
29.2.3 A geometry graph and placement tuple
The cleanest generalization is to represent machine geometry by a directed placement graph
\[ \mathcal G=(\mathcal N,\mathcal E) . \]
In this proposed graph, \(\mathcal N\) contains named ports, free anchors and, when needed, internal junction nodes. Each edge in \(\mathcal E\) represents a two-ended connection or a two-port placed object. A multiport object, such as a splitter, requires an explicit internal subgraph rather than one ordinary directed edge. Physics elements, drifts and geometry-only operators can be represented within this convention.
This representation unifies linear and circular machines immediately:
- a transfer line is an open connected path in \(\mathcal G\) with two exposed boundary ports,
- a ring is a closed cycle in \(\mathcal G\),
- a sector machine is a subgraph together with one or more symmetry transforms that replicate it.
Every two-port placed object \(i\) should be representable by a tuple
\[ \mathfrak E_i= \bigl( M_i,\, U_i,\, \Omega_i,\, \psi_i,\, p_i^{\mathrm{in}},\, p_i^{\mathrm{out}},\, A_i,\, B_i,\, \Delta T_i^{\mathrm{err}},\, \Delta T_i^{\mathrm{dyn}}(t),\, \tau_i \bigr) . \]
Here \(M_i\) is the physics model, \(U_i\) the canonical local chart, \(\Omega_i\subset U_i\) the local support, \(\psi_i\) the intrinsic geometry map, and \(p_i^{\mathrm{in}}\) and \(p_i^{\mathrm{out}}\) the named ports. For the displayed active-pose products, define \(A_i\) to map canonical element coordinates into entrance-port coordinates, and \(B_i\) to map exit-port coordinates into canonical element coordinates. Products act right to left. The static correction \(\Delta T_i^{\mathrm{err}}\) and dynamic correction \(\Delta T_i^{\mathrm{dyn}}(t)\) are expressed in that canonical frame; \(\tau_i\) denotes timing metadata. These are conventions of the proposed model, not the direction of the current stored CoordinateSystemTrafo objects.
If \(T(p_i^{\mathrm{in}})\) denotes the laboratory-frame pose of the entrance port, then the runtime pose of the canonical element frame is
\[ T_i(t)=T(p_i^{\mathrm{in}})\,A_i\,\Delta T_i^{\mathrm{err}}\,\Delta T_i^{\mathrm{dyn}}(t) . \]
The corresponding exit-port pose is
\[ T(p_i^{\mathrm{out}},t)=T_i(t)\,B_i . \]
29.2.4 Transition maps as first-class objects
Whenever two local charts meet, OPALX should store two closely related pieces of information:
- the rigid port-to-port patch transform \(C_{pq}\) attached to the named interface;
- the induced change from chart \(j\) to chart \(i\), \(g_{ij}(u_j,t)=P_i^{-1}(P_j(u_j,t),t)\), restricted to points for which \(P_j(u_j,t)\in P_i(U_i,t)\) and the local inverse exists.
For compatible Cartesian port frames, the frame change can be represented by the rigid patch transform \(C_{pq}\). A coordinate change between curved element charts also includes their intrinsic maps and need not be rigid:
\[g_{ij}=\psi_i^{-1}\circ T_i^{-1}\circ T_j\circ\psi_j,\]
on the domain where these local maps and inverses exist. Sharing only a face does not by itself make the chart-coordinate map rigid.
29.2.5 Two complementary coordinate charts
For OPALX it is useful to distinguish explicitly between:
- a reference chart \(s\) for lattice description, sequence order, optics-style diagnostics, and survey reports;
- a world chart \((\mathbf r,t)\) for actual field evaluation, particle pushing, aperture collisions, and self-field coupling.
In a purely MAD-X-like mode the two charts nearly collapse onto one another. In a time-based OPALX mode they do not. The code should therefore allow both to coexist without forcing one to masquerade as the other.
29.2.6 Minimal front-end semantics
The front-end syntax should compile to the graph-based placement model above. The intent is to extend the present manual concepts rather than replace them with an unrelated syntax.
| Input notion | Current status | Proposed semantics |
|---|---|---|
LINE |
Implemented ordered sequence | Represent as an ordered open path in the proposed placement graph. |
RING |
Implemented periodic sequence topology | Represent as a cycle; geometric closure and closed-orbit conditions remain separate. |
| Line origin and explicit element poses | Implemented | Reuse these poses as roots or anchors; generic named free anchors would be an extension. |
ELEMEDGE |
Implemented reference-coordinate placement | Compile into element transforms; keep reference-coordinate bookkeeping distinct from field-support selection. |
| Alignment errors | Implemented static misalignment transform | Relate the stored parent-to-local transform to the proposed active correction explicitly. |
| Named ports and patch objects | Proposed extension | Declare interface charts, geometry transforms and closure constraints independently of physics elements. |
| Generic chart, support and timing attributes | Proposed extension | Define any STRAIGHT, ARC or USER syntax and dynamic timing semantics before exposing them as an input interface. |
29.3 Geometric Background
This section records the small amount of differential-geometric and fibre-bundle language used in the placement discussion. The point, following Forest and Hirata [1], is to separate the placed object from any one chosen coordinate description.
29.3.1 The bookkeeping base
Let \(\mathcal B\) denote the reference base used for ordering and reporting. For a transfer line, \(\mathcal B\) may be an interval. For a ring, \(\mathcal B\) may be a circle. For a machine whose reference-order topology contains a junction, an extraction line, a splitter, or a switchyard, \(\mathcal B\) may be a graph with labeled edges and junction nodes.
The important point is that \(\mathcal B\) is a bookkeeping base, not the full physical geometry.
29.3.2 Local charts and supports
An individual element is described locally by a chart
\[ \psi_i:U_i\to\mathbb{R}^3 , \]
where \(U_i\) is the canonical local coordinate domain of element \(i\). The subset
\[ \Omega_i\subset U_i \]
is the local support on which the field, aperture, material, or map model is defined. The intrinsic geometry map and the placed map are distinct. In the proposed notation, let \(T_i(t)\) map Cartesian coordinates in the canonical element frame into laboratory coordinates. Then
\[P_i(u_i,t)=T_i(t)\,\psi_i(u_i).\]
Here the rigid transform acts on the Cartesian point produced by \(\psi_i\); it is not generally a rigid map of curvilinear coordinates \(u_i\) themselves. The current CoordinateSystemTrafo::transformTo() uses the opposite direction, from parent coordinates into local coordinates; its inverse corresponds to the local-to-laboratory rigid map above.
29.3.3 Ports
A port is a distinguished geometric interface chart with an adapted frame. It need not be a boundary of the field support. If
\[\Sigma_{i,\alpha}\subset\overline{U_i}\]
is such an interface and \(F_{i,\alpha}\) is its adapted frame, then
\[ p_{i,\alpha}=(\Sigma_{i,\alpha},F_{i,\alpha}) \]
is a port of the element.
In the simplest case the ports are just the entrance and exit faces. Junctions, splitters, extraction devices, or ring closures introduce additional named interface charts, but they do not change the basic definition.
29.3.4 Transition maps and closure
At a fixed time, the transition from local chart \(j\) into chart \(i\) is
\[g_{ij}(u_j,t)=P_i^{-1}(P_j(u_j,t),t).\]
It is defined only where the placed charts overlap and \(P_i\) has a local inverse. Restrict the maps to a compatible interface when only a face is shared; a global inverse over an entire ring or all element charts is not assumed.
For compatible Cartesian port frames, store their rigid frame change as \(C_{pq}\). For general local charts, retain the intrinsic-coordinate maps as well; the full \(g_{ij}\) need not be rigid. This separates the proposed port-frame connection from the coordinate representation used inside each element.
For rings, distinguish the geometric closure of the placed machine from the rotation accumulated by a transported frame. Forest and Hirata discuss a nontrivial rotation of a parallel-transported frame that requires a matching transformation to close the coordinate description [1]. This does not license a physical gap between the ends of a full ring.
A nonidentity residual must be identified as frame transport, an intentional sector/symmetry identification, or a geometric closure mismatch. Current OPALX RING declares periodic sequence topology; it does not by itself validate three-dimensional geometric closure or find a closed orbit.