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
  • Line and environment
    • Creating a simple Line object
    • Save and reload lines
    • Line inspection, Line.get_table(), Line.attr[...]
    • References and deferred expressions
    • Role of the Environment
    • Define a line by specifying the s positions of the elements
    • Repeated elements, replicas and clones
    • Line mirroring and composition
    • Insert elements
    • Append elements
    • Remove elements
    • Replace elements
    • Slice elements
    • Cut line elements at given s positions
    • Apply transformations (tilt, shift) to elements
    • Add multipolar components to elements
    • Importing a line from MAD-X
    • Simulation of small rings: drifts, bends, fringe fields
    • Extraction of second order transfer maps
  • 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
    • Match and twiss with symmetry constraints on one boundary
  • 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
  • Collective effects
    • Tracking with collective elements
    • Space charge
    • Beam-beam
    • Interface to PyHEADTAIL
    • Combined CPU - GPU simulations
    • Pipeline for multibunch simulations
  • Collimation
    • Introduction
    • Collimator objects
    • BaseBlock and EverestBlock
    • Creating a Collimator or Block object
    • Generating particles on a collimator
    • Lossmaps
  • Loss location refinement
    • Beam interaction (generation of secondary particles)
  • Synchrotron radiation
    • Twiss and track with radiation
    • Compensate radiation energy loss (tapering)
  • Intra-Beam Scattering
    • Analytical Growth Rates
    • 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 manual
  • xtrack.Environment class
    • Environment
      • Environment.new()
      • Environment.new_line()
      • Environment.place()
      • Environment.new_builder()
      • Environment.call()
      • Environment.import_line()
      • Environment.from_json()
      • Environment.to_json()
      • Environment.from_madx()
      • Environment.set_multipolar_errors()
      • Environment.set()
      • Environment.get()
      • Environment.eval()
      • Environment.info()
      • Environment.get_expr()
      • Environment.new_expr()
      • Environment.twiss()
      • Environment.discard_trackers()
      • Environment.build_trackers()
      • Environment.match()
      • Environment.match_knob()
      • Environment.install_beambeam_interactions()
      • Environment.configure_beambeam_interactions()
      • Environment.apply_filling_pattern()
  • xtrack.Line class
    • Line
      • Line.from_dict()
      • Line.from_json()
      • Line.from_sequence()
      • Line.from_sixinput()
      • Line.from_madx_sequence()
      • Line.to_dict()
      • Line.to_madx_sequence()
      • Line.to_madng()
      • Line.to_json()
      • Line.to_pandas()
      • Line.get_aperture_table()
      • Line.copy()
      • Line.build_tracker()
      • Line.discard_tracker()
      • Line.track()
      • Line.slice_thick_elements()
      • Line.build_particles()
      • Line.twiss()
      • Line.twiss4d()
      • Line.match()
      • Line.match_knob()
      • Line.survey()
      • Line.correct_trajectory()
      • Line.find_closed_orbit()
      • Line.compute_T_matrix()
      • Line.get_footprint()
      • Line.get_amplitude_detuning_coefficients()
      • Line.compute_one_turn_matrix_finite_differences()
      • Line.get_non_linear_chromaticity()
      • Line.get_length()
      • Line.get_s_elements()
      • Line.get_s_position()
      • Line.cut_at_s()
      • Line.append()
      • Line.insert()
      • Line.remove()
      • Line.replace()
      • Line.insert_element()
      • Line.append_element()
      • Line.filter_elements()
      • Line.cycle()
      • Line.freeze_energy()
      • Line.freeze_longitudinal()
      • Line.freeze_vars()
      • Line.unfreeze_vars()
      • Line.configure_bend_model()
      • Line.configure_radiation()
      • Line.configure_intrabeam_scattering()
      • Line.compensate_radiation_energy_loss()
      • Line.optimize_for_tracking()
      • Line.start_internal_logging_for_elements_of_type()
      • Line.stop_internal_logging_for_all_elements()
      • Line.stop_internal_logging_for_elements_of_type()
      • Line.extend_knl_ksl()
      • Line.remove_markers()
      • Line.remove_inactive_multipoles()
      • Line.remove_zero_length_drifts()
      • Line.merge_consecutive_drifts()
      • Line.remove_redundant_apertures()
      • Line.use_simple_quadrupoles()
      • Line.use_simple_bends()
      • Line.get_elements_of_type()
      • Line.check_aperture()
      • Line.merge_consecutive_multipoles()
      • Line.get_line_with_second_order_maps()
      • Line.copy_element_from()
      • Line.set()
      • Line.get()
      • Line.info()
      • Line.eval()
      • Line.new_expr()
      • Line.get_expr()
      • Line.name
  • 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.Multiline class
      • Multiline
    • xtrack.Multisetter class
      • MultiSetter
    • Space charge configuration
      • install_spacecharge_frozen()
      • replace_spacecharge_with_quasi_frozen()
      • replace_spacecharge_with_PIC()
    • Loss location refinement
      • LossLocationRefinement
  • Beam elements (xtrack)
    • Marker
      • Marker
    • Drift
      • Drift
    • Bend
      • Bend
    • RBend
      • RBend
    • Quadrupole
      • Quadrupole
    • CombinedFunctionMagnet
      • CombinedFunctionMagnet
    • DipoleEdge
      • DipoleEdge
    • Sextupole
      • Sextupole
    • Multipole
      • Multipole
    • Solenoid
      • Solenoid
    • NonLinearLens
      • NonLinearLens
    • Cavity
      • Cavity
    • RFMultipole
      • RFMultipole
    • ReferenceEnergyIncrease
      • ReferenceEnergyIncrease
    • Elens
      • Elens
    • Exciter
      • Exciter
    • Wire
      • Wire
    • FirstOrderTaylorMap
      • FirstOrderTaylorMap
    • SecondOrderTaylorMap
      • SecondOrderTaylorMap
    • LineSegmentMap
      • LineSegmentMap
    • LinearTransferMatrix
      • LinearTransferMatrix
    • LongitudinalLimitRect
      • LongitudinalLimitRect
    • XYShift
      • XYShift
    • SRotation
      • SRotation
    • XRotation
      • XRotation
    • YRotation
      • YRotation
    • ZetaShift
      • ZetaShift
    • LimitEllipse
      • LimitEllipse
    • LimitRect
      • LimitRect
    • LimitRectEllipse
      • LimitRectEllipse
    • LimitRacetrack
      • LimitRacetrack
    • LimitPolygon
      • LimitPolygon
    • ParticlesMonitor
      • ParticlesMonitor
    • LastTurnsMonitor
      • LastTurnsMonitor
  • 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
      • IBSAnalyticalKick
      • IBSKineticKick

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