Installation

Download

The reommended way to obtain the LightWin code is by using git. Navigate to the directory where you want to store LightWin and run:

Alternatively, you download the code as a .zip file from the repository’s page. However, please note that using this method requires manually downloading updates whenever changes are made to the repository.

Python (mandatory)

LightWin requires Python 3.12 or higher. Ensure that you have an appropriate version of Python installed on your system. If not, you can download the latest version from the official Python website.

Packages

Mandatory

The following packages are mandatory for LightWin to execute:

  • matplotlib

  • numpy

  • palettable

  • pandas

  • scipy

  • tkinter

  • pymoo - This package is used for genetic optimization algorithms. If you prefer not to use pymoo, you can remove the related imports in fault.py and fault_scenario.py.

Optional

  • Note: Installing cython prior to pymoo enable compilation of some pymoo functions for improved performance.

  • pytest - To run tests and ensure everything is working as expected.

  • cloudpickle - To pickle/unpickle some objects (see the util.pickling documentation).

For developers

To compile the documentation, the following packages are necessary:

  • sphinx_rtd_theme

  • myst-parser

  • nbsphinx

The files are formatted with black.

Reminders

Installation of a package

To install a package, use the appropriate method based on your environment:

  • If using pip:

    pip install <package>

  • If using conda, avoid mixing with pip to prevent potential conflicts. Instead, use:

    conda install <package>

Note

Since pymoo is not available on the default Anaconda channels, you should create a conda environment and use conda-forge:

conda create -n <env-name> -c conda-forge python=3.12
conda activate <env-name>
conda install cython matplotlib numpy palettable pandas scipy tkinter pymoo pytest -c conda-forge

Always specify -c conda-forge when installing or updating packages.

Warning

pip and conda are not fully compatible. Avoid using them together, or create a dedicated environment to prevent conflicts. For more details, you may refer to this video.

Set up the Python Path

You must add the /path/to/lightwin/source directory to your PYTHONPATH environment variable.

Todo

Consider providing more detailed instructions for setting the PYTHONPATH. For now, you can search for “PYTHONPATH” or “ModuleNotFoundError” online for additional guidance.

Cython setup

Cython is an optional but highly recommended tool to speed up beam dynamics calculations. Here’s how to properly install and use Cython with the project:

1. Installing Cython

Ensure Cython is installed before installing other packages like pymoo to take full advantage of its capabilities:

  • Using pip:

    pip install cython

  • Using conda:

    conda install cython -c conda-forge

2. Compiling Cython modules

Some parts of LightWin, in particular the Envelope1D module, have Cython-optimized code that need to be optimized. Follow this steps to compile the modules:

  1. Navigate to the source directory:

cd /path/to/lightwin/source

  1. Run the setup script:

python util/setup.py build_ext --inplace

This command compiles the Cython files and places the compiled modules (.pyd or .so extensions) in the appropriate directories.

3. Handling compiled files

After compilation, the compiled files should be automatically places in the correct locations. If not, manually move the created files:

  • Unix (Linux/macOS): build/lib.linux-XXX-cpython=3XX/beam_calculation/envelope_1d/transfer_matrices_c.cpython-3XX-XXXX-linux-gnu.so

  • Windows: build/lib.win-XXXX-cpython-3XX/beam_calculation/envelope_1d/transfer_matrices_c.cp3XX-win_XXXX.pyd

To:

  • /path/to/lightwin/source/beam_calculation/envelope_1d/.

4. Troubleshooting compilation issues

  • On Windows, if you encounter a Microsoft Visual C++ 14.0 or greater is required error:

    1. Go to visual studio website and download Build Tools.

    2. Download and execute vs_BuildTools.exe.

    3. Check “C++ Development Desktop” checkbox.

    4. Install.

5. Restarting Your Interpreter

If you are using an IDE like Spyder or VSCode, remember to restart the kernel after compiling the Cython modules to ensure they are correctly loaded.

6. Testing Cython Compilation

To verify that everything is set up correctly, run the test suite using pytest. This will check if the Cython modules are properly integrated:

pytest -m cython

See also

Cython documentation.

Todo

  • Revise integration so that a missing Cython does not lead to import errors.

  • Specific Cython tests

TraceWin (facultative)

Pre-requisite: TraceWin must be installed on your computer or server, and you must have a valid license.

Configuring the machine_configuration.toml file

To specify the location of the TraceWin installation, you need to create machine_configuration.toml file. This file should include entries like the following:

[lpsc5057x]
noX11_full = "/usr/local/bin/TraceWin/./TraceWin_noX11"
noX11_minimal = "/home/placais/TraceWin/exe/./tracelx64"
no_run = ""
X11_full = "/usr/bin/local/bin/TraceWin/./TraceWin"

[LPSC5011W]
X11_full = "D:/tw/TraceWin.exe"
noX11_full = "D:/tw/TraceWin.exe"

[a_name_to_override_default_machine_name]
X11_full = "D:/tw/TraceWin_old.exe"
noX11_full = "D:/tw/TraceWin_old.exe"

Replace the bracketed names with your machine’s name. If you’re unsure of your machine’s name, use the following Python code to find it:

import socket
machine_name = socket.gethostname()
print(f"Entry in the machine_configuration.toml file should be:\n[{machine_name}]")

Linking with the lightwin.toml main configuration file

After setting up machine_configuration.toml, you need to link it with the lightwin.toml file. Include the following configuration:

[my_tracewin_configuration]
# Can be relative to `lightwin.toml`, or absolute:
machine_config_file = "/path/to/machine_configuration.toml"
# The corresponding path must be defined in `machine_configuration.toml`
simulation_type = "X11_full"
# Optional: override the actual machine name if provided:
machine_name = "a_name_to_override_default_machine_name"
# Note that additional entries will be required

See dedicated documentation for lightwin.toml.

Testing

Pytest

To test your installation, navigate to the base directory (where the pyproject.toml file is located) and run the following command:

pytest

If TraceWin is not installed, you can skip tests requiring it by running:

pytest -m not tracewin

If Cython is not installed or Cython modules not compiled, you can skip corresponding tests with:

pytest -m not cython

You can also combine test markers as defined in pyproject.toml. For example, to run only fast smoke tests, use:

pytest -m "(smoke and not slow)"

Frequent errors

  • E   ModuleNotFoundError: No module named 'beam_calculation'.

  • Your PYTHONPATH is not properly set. Ensure that the directory containing the LightWin source code is included in your PYTHONPATH.

  • xfailed errors.

  • xfailed stands for “expected to fail” and these errors are usually intended for developers to track issues. They are not necessarily problematic for users.