FCC Lattice Simulation Toolkit

A Python package for constructing and simulating FCC-ee lattices using XSuite and MAD-X.

Features

• Lattice Construction: Build FCC lattices from MAD-X sequences
• Beam Dynamics: Configure beam parameters and optics
• Injection Modeling: Realistic injection scenarios
• Tracking: Particle tracking with synchrotron radiation
• Analysis: Tools for lattice diagnostics and optimization

Installation

Installation

pip install xutil

Development Installation

git clone https://gitlab.cern.ch/kskoufar/xutil.git
cd xutil
pip install -e ".[dev,doc]"

Development

Building the Package

To build the package locally:

# Install build dependencies
pip install build twine

# Build the package
python -m build

# The built packages will be in the dist/ directory

Publishing to PyPI

To publish to the main PyPI repository:

python -m twine upload dist/*

# Or for the test repo
python -m twine upload --repository testpypi dist/*

Documentation

Full documentation is available at: https://xutil.readthedocs.io

To build documentation locally:

cd docs
make html
open ./build/html/index.html

Contributing

We welcome contributions! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/your-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin feature/your-feature)
5. Open a Merge Request

Citation

@software{xutil,
  author = {Kyriacos Skoufaris, Giulia Nigrelli, Maël Le Garrec},
  title = {Xutil - FCC Lattice Simulation Toolkit},
  year = {2025},
  publisher = {GitLab},
  journal = {GitLab repository},
  howpublished = {\url{https://gitlab.cern.ch/kskoufar/xutil}},
  version = {0.1.0}
}

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.