Table of contents

User’s Guide

• User’s guide
  • Installation
    • Basic installation
    • Developer installation
    • Optional dependencies
    • GPU/Multithreading support
    • Install Miniforge
    • Advanced information for developers
  • Getting started
    • A simple example
    • Step-by-step description
  • Unit conventions
    • Core quantities
  • Xsuite environment
    • Overview
    • Variables
    • Elements
    • Lines
    • Reference particles
    • Saving and loading environment or individual lines
    • Loading MAD-X lattices
  • Configure lattice model
    • Magnet models and integrators
    • Apply misalignments (tilt, shift) to elements
    • Add multipolar components to elements
    • Extend multipolar component order
    • Propagation of multipolar components to sliced elements
    • Simulation of small rings: drifts, bends, fringe fields
  • Twiss
    • Basic usage (ring)
    • Inspecting twiss output
    • 4d method (RF off)
    • Off-momentum twiss
    • Twiss with “initial” conditions
    • Periodic twiss on a portion of a line
    • Beam sizes from twiss table
    • Particles normalized coordinates
    • Reverse reference frame
    • Twiss defaults
    • Twiss with synchrotron radiation
  • Match
    • Basic usage
    • Match at specific locations
    • Boundary conditions and target values from existing table
    • Match involving multiple lines
    • Callables and inequalities in targets
    • Matching on results of arbitrary actions
    • Interactive match
    • Create new knobs by matching
    • Targets from variables and from line elements
  • Track
    • Tracking particles with Xsuite
    • Dynamic aperture
    • Monitors
    • Start/stop tracking at specific elements
    • Backtracking
    • Freeze longitudinal coordinates
    • Time-dependent line properties
    • Acceleration
    • Off-momentum from RF frequency change
    • Optimize line for multi-turn tracking speed
  • Particles
    • Introduction
    • Building particles with the Particles class
    • The build_particles function
    • Generating particles distributions
    • Copying a Particles object (optionally across contexts)
    • Saving and loading Particles objects to/from dictionary or file
    • Merging and filtering Particles objects
    • Accessing particles coordinates on GPU contexts
  • Closed orbit and trajectory correction
    • Basic usage
    • MICADO correction
    • Customized correction
    • Threading
    • Trajectory correction for transfer lines
  • Spin and polarization
    • Equilibrium polarization and spin closed solution
    • Tracking with spin and Monte Carlo simulation of radiative depolarization
  • Collective effects
    • Tracking with collective elements
    • Xwakes: wakefields and impedances
    • Space charge
    • Beam-beam
    • Combined CPU - GPU simulations
    • Pipeline for multibunch simulations
  • Particle-matter interaction and collimation
    • Introduction
    • Collimator objects
    • BaseBlock and EverestBlock
    • Creating a Collimator or Block object
    • Generating particles on a collimator
    • Lossmaps
    • Loss location refinement
    • Material definitions
    • Beam interaction (generation of secondary particles)
    • Linking external codes for material Interactions
  • Synchrotron radiation
    • Twiss and track with radiation
    • Compensate radiation energy loss (tapering)
  • Intra-Beam Scattering
    • Analytical Growth Rates
    • Steady State Emittances in the Presence of Synchrotron Radiation, Quantum Excitation and Intra-Beam Scattering
    • IBS Kicks for Tracking
  • Tune footprint and stability diagram
    • Basic usage
    • Linear rescale on knobs
    • Stability diagram
  • Data management in Xsuite
    • Hybrid objects, xofields, xobjects
    • Contexts and buffers
    • Move and copy operations
    • Memory management in xtrack trackers
    • References
    • Advanced memory behaviours with HybridClass
  • Lost particles state codes

Reference manual

• Reference guide
  • Beam elements (xtrack)
    • Marker
      • Marker
    • Drift
      • Drift
    • Bend
      • Bend
    • RBend
      • RBend
    • Quadrupole
      • Quadrupole
    • Sextupole
      • Sextupole
    • Octupole
      • Octupole
    • Multipole
      • Multipole
    • UniformSolenoid
      • UniformSolenoid
    • VariableSolenoid
      • VariableSolenoid
    • Cavity
      • Cavity
    • CrabCavity
      • CrabCavity
    • RFMultipole
      • RFMultipole
    • ReferenceEnergyIncrease
      • ReferenceEnergyIncrease
    • Exciter
      • Exciter
    • AC-Dipole
      • ACDipole
    • Elens
      • Elens
    • NonLinearLens
      • NonLinearLens
    • ElectronCooler
      • ElectronCooler
    • Wire
      • Wire
    • FirstOrderTaylorMap
      • FirstOrderTaylorMap
    • SecondOrderTaylorMap
      • SecondOrderTaylorMap
    • LineSegmentMap
      • LineSegmentMap
    • XYShift
      • XYShift
    • SRotation
      • SRotation
    • XRotation
      • XRotation
    • YRotation
      • YRotation
    • ZetaShift
      • ZetaShift
    • LimitEllipse
      • LimitEllipse
    • LimitRect
      • LimitRect
    • LimitRectEllipse
      • LimitRectEllipse
    • LimitRacetrack
      • LimitRacetrack
    • LimitPolygon
      • LimitPolygon
    • LongitudinalLimitRect
      • LongitudinalLimitRect
    • ParticlesMonitor
      • ParticlesMonitor
    • LastTurnsMonitor
      • LastTurnsMonitor
    • BeamPositionMonitor
      • BeamPositionMonitor
    • BeamProfileMonitor
      • BeamProfileMonitor
    • BeamSizeMonitor
      • BeamSizeMonitor
  • Beam elements (xfields)
    • Beam-beam Bi-Gaussian 2D
      • BeamBeamBiGaussian2D
    • Beam-beam Bi-Gaussian 3D
      • BeamBeamBiGaussian3D
    • Space Charge Bi-Gaussian
      • SpaceChargeBiGaussian
    • Space Charge 3D
      • SpaceCharge3D
    • Intra-Beam Scattering Kicks
      • IBSKineticKick
  • Beam elements (xwakes)
    • Wakefield definitions
    • WakeResonator
      • WakeResonator
    • WakeThickResistiveWall
      • WakeThickResistiveWall
    • WakeFromTable
      • WakeFromTable
    • Wake
      • Wake
    • Utilities
      • read_headtail_file()
  • Element misalignment
  • xtrack.Environment class
    • Members - short description
    • Members - full description
      • Editing, Inspection, Variables and Configuration
      • Reference Particle and Particle Generation
      • Analysis and Matching
      • Tracker Setup
      • Constructors and Serialization
      • Deprecated
      • Upcoming deprecations
  • xtrack.Line class
    • Members - short description
    • Members - full description
      • Line Editing
      • Compose Mode
      • Inspection, Variables and Configuration
      • Reference Particle and Particle Generation
      • Tracking and Analysis
      • Matching and Corrections
      • Magnet Model Configuration
      • Radiation, Spin and Intra-Beam Scattering
      • Energy & Longitudinal State
      • Tracker Setup
      • Constructors and Serialization
      • Element Internal Logging
      • Cleanup and Simplification
      • MAD-NG Integration
      • Deprecated Methods
      • Upcoming Deprecations
  • Track
    • Line.track()
  • Twiss
    • Line.twiss()
  • Match
    • Line.match()
    • Optimize
      • Optimize.from_callable()
      • Optimize.run_jacobian()
      • Optimize.run_ls_trf()
      • Optimize.run_ls_dogbox()
      • Optimize.run_l_bfgs_b()
      • Optimize.run_bfgs()
      • Optimize.run_nelder_mead()
      • Optimize.run_simplex()
      • Optimize.run_direct()
      • Optimize.step()
      • Optimize.solve()
      • Optimize.solve_homotopy()
      • Optimize.vary_status()
      • Optimize.target_status()
      • Optimize.target_mismatch()
      • Optimize.get_knob_values()
      • Optimize.show()
      • Optimize.log()
      • Optimize.reload()
      • Optimize.clear_log()
      • Optimize.add_point_to_log()
      • Optimize.tag()
      • Optimize.enable()
      • Optimize.disable()
      • Optimize.get_merit_function()
      • Optimize.enable_vary()
      • Optimize.disable_vary()
      • Optimize.enable_targets()
      • Optimize.disable_targets()
      • Optimize.disable_all_targets()
      • Optimize.enable_all_targets()
      • Optimize.disable_all_vary()
      • Optimize.enable_all_vary()
    • Vary and Target
      • Vary
      • VaryList
      • Target
      • TargetSet
      • TargetRelPhaseAdvance
  • Trajectory correction
    • TrajectoryCorrection
      • TrajectoryCorrection.correct()
      • TrajectoryCorrection.thread()
      • TrajectoryCorrection.clear_correction_knobs()
  • Build particles
    • Line.build_particles()
  • Particles class
    • Particles
      • Particles.from_dict()
      • Particles.to_dict()
      • Particles.to_json()
      • Particles.from_pandas()
      • Particles.to_pandas()
      • Particles.to_table()
      • Particles.get_table()
      • Particles.merge()
      • Particles.filter()
      • Particles.sort()
      • Particles.reorganize()
      • Particles.hide_lost_particles()
      • Particles.unhide_lost_particles()
      • Particles.remove_unused_space()
      • Particles.add_particles()
      • Particles.get_active_particle_id_range()
      • Particles.show()
      • Particles.get_classical_particle_radius0()
      • Particles.hide_first_n_particles()
      • Particles.unhide_first_n_particles()
      • Particles.update_delta()
      • Particles.update_ptau()
      • Particles.update_p0c()
      • Particles.update_gamma0()
      • Particles.update_beta0()
      • Particles.add_to_energy()
  • Generation of particles distributions
    • Gaussian bunch generation (6D)
      • generate_matched_gaussian_bunch()
    • Longitudinal coordinates generation
      • generate_longitudinal_coordinates()
    • Normalized transverse coordinates generation
      • Gaussian
      • Polar grid
      • Uniform circular sector
      • Pencil
  • CPU and GPU contexts
    • Cupy context
      • ContextCupy
    • PyOpenCL context
      • ContextPyopencl
    • CPU context
      • ContextCpu
  • Configuration tools
    • xtrack.Multisetter class
      • MultiSetter
    • Space charge configuration
      • install_spacecharge_frozen()
      • replace_spacecharge_with_quasi_frozen()
      • replace_spacecharge_with_PIC()
    • Loss location refinement
      • LossLocationRefinement

Physics Guide

• Physics guide

Developer’s Guide

• Developer’s guide
  • Definition of new Xtrack-compatible beam elements
    • Introduction
    • Definition and management of the data structure
      • Allocation of beam elements on CPU or GPU
      • Python access to beam-element data
      • Underlying xobject
      • Custom __init__ method
    • Definition of the tracking function
      • Accessing beam-element data from C
      • Writing the tracking code
    • Data recording in beam elements
      • Introduction
      • Recording of an individual table
      • Recording of multiple tables
      • Internal record for elements used in standalone mode
    • Lost particles state codes
  • Multiplatform programming with xobjects
    • Data management
      • Definition of a simple data structure class
      • Allocation of a data object on CPU or GPU
      • Access to the data
      • Numpy-like access
    • Kernel functions in C
      • Autogenerated C API
      • Writing a C kernel
      • Compiling the kernel
      • Calling the kernel
      • Inspecting the source code
  • Code autogeneration
    • vectorize_over block
    • only_for_context directive
    • gpukern directive
    • gpuglmem directive
  • Numerical reproducibility
    • Using conda to create a numerically reproducible environment
  • Continuous testing of xsuite
    • Setup of the test runner machine (Ubuntu)
      • An OpenStack GPU-capable machine
      • Configure the test machine
      • Install the GitHub Actions runner
    • Setup of the test runner machine (Alma 8)
      • Synopsis
      • Setup a user account
      • Install a Container Engine
      • Installing Nvidia drivers (can be skipped for CPU-only VM)
      • Installing the Nvidia Container Toolkit (can be skipped for a CPU-only VM)
      • Setup the GitHub runner

Jupyter Tutorials

• Jupyter tutorials