CLICopti 2.2

No project description provided

CLICopti

CLICopti is a C++ library for quickly estimating the parameters of an RF structure from its length, apertures, tapering, and cell design. It can be ran directly or from a Octave- or Python wrapper. Typical estimated parameters are the input power required to reach a certain voltage with a given beam current, the maximum safe pulse length for a given input power and the minimum bunch spacing in RF cycles allowed by a given long-range wake limit.

Current maintainer: Andrea Latina (CERN)

Authors:

• Kyrre Sjobak, University of Oslo and CERN (2013-2014, 2021, 2024-)
• Daniel Schulte, CERN (2013-)
• Alexej Grudiev, CERN (2013-2014)
• Andrea Latina, CERN (2014-)
• Jim Ögren, Uppsala University and CERN (2017-2019)

Citing CLICopti and references

We have invested a lot of time and effort in creating and maintaining the CLICopti library, please cite it when using it. For information for how to cite CLICopti, please see the CITATION file.

For further reading, the main references for CLICopti are listed in the REFERENCES file.

CLICopti is published under the GNU Lesser General Public License Version 3, please respect it. For details see the LICENSE file.

Installing and using CLICopti

To understand how to use CLICopti, a good place to start is the top-level report listed in the CITATION file, along with reading through structure.h.

C++

For C++, the examples shown in the src folder should hopefully be instructive. CLICopti can be compiled for C++ by running make in the top-level directory; the test programs are compiled into the top-level folder.

Octave

For Octave, some examples are given in the Octave folder.

Python

For Python, an example notebook is in the Python folder. To install CLICopti for Python to your machine, you can simply run:

pip install git+https://gitlab.cern.ch/clic-software/clicopti.git

To remove it (e.g. for installing a later version), you can run:

pip uninstall CLICopti

You can also download the code to a folder (e.g. with git clone), modify it, and install using:

pip install -v -e path/to/CLICopti

where the path/to/CLICopti is the path to the root of the repository, i.e. the folder containing the README.md you are currently reading.

Here the options -v (verbose) and -e editable have been included. This shows more information during the installation, and also makes the python code in path/to/CLICopti/Python/CLICopti be the version generally seen by your system. The effect is that you can change the code and it will immediately take effect everywhere.

The Python interface is build using SWIG. This means that if the underlying C++ API changes, you must manually update the wrapper code before installing with pip. The developers have normally done this in any versions published to the master branch of the project git repository, however if needed this can be regenerated by

1. Running make clean then make in the top-level folder
2. Running make cleanall then make install in the swig folder.

This will recreate the files CLICopti.py and CLICopti_python_wrap.cc and place them in the correct locations for Python's setuptools to find them. It will also copy the cell database files to locations where they will be included in the Python package.

To test the Python build scripts without installing, you can run

python -m build

in the top level folder. This produces a new dist subfolder containing .whl (wheel) files.

Testing

The Python interface comes with an automatic unit test suite using pyTest. To run it, after installing (with -e if wanted) run pytest -v in the root folder of the repository.

To add more tests, make files called test_XXX.py in the subfolder Python/tests, where XXX is a name you choose. In these files, add functions called test_YYY, with the decorator @pytest.mark.ZZZ. Here YYY and ZZZ is a name you choose, and the mark name ZZZ should also be listed in pytest.ini in the root folder.

Coverage of tests

In order to produce a coverage report, run pytest as: pytest --cov=CLICopti --cov-report=html -v The coverage report, inclucing line-by-line descriptions, can be opened with: firefox htmlcov/index.html

Documentation

The main documentation of the code and the methods implemented is found in the REFERENCES file. In addition, the C++ code has (some) Doxygen documentation.

For the Python interface, this is used to generate Sphinx documentation. To build this, you must first compile the Python interface using the make commands in the swig folder as discussed above. The, in the folder swig/sphinx-doc-python you must run e.g. make html to build the HTML documentation. This will then appear in swig/sphinx-doc-python/build/html - see the file index.html.

Releasing new versions of CLICopti

The version number is saved in two files:

• swig/splash.cc
• pyproject.toml, under header [project]

Please keep them synchronized and bump as appropriate.

See also publishToPyPi for more information on how to update the version there.

Before releasing, we must update the interface files for Python and Octave which are generated by SWIG, and also the documentation generated using SPHINX. To do this, run make clean and then make install in the toplevel folder. This will clean the autogenerated files from the swig, Python/CLICopti, and doc/python-sphinx folders.

TODO: Create make gitrelease which will add the files to the commit index, ready to be comitted.

NOTE: if the package is installed (in place?) with pip when running make install, the documentation will not build correctly

FOR DEBUGGING: CPPFLAGS="-g -O0 -Wall" pip install -v -e ~/code/clicopti/

Cloning the GIT repository on Windows

The Git repository contains files and folders named aux, which due to backwards-compatibility is not allowed on Microsoft Windows. Therefore, these folders must be carefully excluded in order to sucessfully checkout the project. Furthermore, the project uses symlinks to make some files be accessible in multiple locations of the repository without making multiple copies; this must be manually enabled in git-for-windows.

For these commands I used PowerShell on Windows 10 with git version 2.47.1.windows.2 and anaconda's base environment with Python 3.12.7.

1. Do a sparse checkout:

git clone --no-checkout https://gitlab.cern.ch/clic-software/clicopti.git
cd .\clicopti\
ls
git sparse-checkout init --cone
notepad.exe .\.git\info\sparse-checkout
git checkout master

The sparse-checkout files should contain the following lines:

/*
!/aux/
!/doc/CLICnote-1028/aux

2. Try to build the Python files: python -m build You might need to do pip install build for this to work. If the compilation fails due to missing compiler, follow the instructions to download and install the MSVC compiler.

3. Install properly and run the tests:

pip install -v -e .
pytest -v

It should all PASS. If symlinks are not properly enabled, some tests will fail on parsing CellBase files. 4. Enable symlinks: If this command does not return true, then symlinks are not enabled: git config --get core.symlinks. This means that the copies of the database in the Python folder are not correctly present; instead they are just represented by files containing a one-line reference to the database location.

Enable symlinks in git with: git config core.symlinks true Run these inside the git repository. After this, git status should return:

Changes not staged for commit:
typechange: Python/CLICopti/TD_12GHz_v1.dat
typechange: Python/CLICopti/TD_12GHz_v2.dat
typechange: Python/CLICopti/TD_30GHz.dat 

Then, check-out the files using git checkout Python/CLICopti/TD_12GHz_v1.dat Python/CLICopti/TD_12GHz_v2.dat Python/CLICopti/TD_30GHz.dat. If this fails with a "permission denied" message, switch on "Developer Mode" in Windows and try again. Opening the files should now reveil the databases.