Survey

Xtrack provides a survey method associated to the line that can be used to compute the position and orientation of the local reference frame in a global coordinate system. The returned table contains, among other quantities, the global coordinates X, Y and Z and the orientation angles theta, phi and psi at each element.

For a complete description of the available options, please refer to the Survey API reference.

Basic usage

The following example builds a small line, computes its survey, inspects a few columns from the resulting table, and makes a floor plot using survey.plot.

import numpy as np
import xtrack as xt

# Build a simple line with four bending magnets and three quadrupoles.
env = xt.Environment(particle_ref=xt.Particles(p0c=1e9))

line = env.new_line(length=12, components=[
    env.new('b1', xt.Bend, length=0.5, angle=np.deg2rad(22.5),
            k0_from_h=False, at=1.5),
    env.new('qf1', xt.Quadrupole, length=0.3, k1=0.4, at=2.8),
    env.new('b2', xt.Bend, length=0.5, angle=-np.deg2rad(22.5),
            k0_from_h=False, at=4.0),
    env.new('qd1', xt.Quadrupole, length=0.3, k1=-0.4, at=5.5),
    env.new('b3', xt.Bend, length=0.5, angle=-np.deg2rad(22.5),
            k0_from_h=False, at=8.0),
    env.new('qf2', xt.Quadrupole, length=0.3, k1=0.4, at=9.2),
    env.new('b4', xt.Bend, length=0.5, angle=np.deg2rad(22.5),
            k0_from_h=False, at=10.5),
])

# Compute the survey.
survey = line.survey()

# Inspect selected columns of the survey table.
survey.cols['name s X Y Z theta phi psi']

# Make a floor plot of the reference trajectory in the Z-X plane.
import matplotlib.pyplot as plt
plt.close('all')

survey.plot(
    projection='ZX',
    labels=['b1', 'b2', 'b3', 'b4'],
    element_width=0.12,
    figsize=(6.4, 4.8),
)

fig1 = plt.gcf()
plt.title('Survey floor plot')
fig1.subplots_adjust(left=.13, right=.95, bottom=.13, top=.90)
plt.show()

# Complete source: xtrack/examples/survey/000_survey.py

Floor plot of the reference trajectory as obtained from Xtrack survey.

Starting from a selected element

By default, line.survey() starts from the beginning of the line with the global frame aligned to the local reference frame. A different origin and orientation can be selected with element0 and the initial coordinates X0, Y0, Z0, theta0, phi0 and psi0.