CLICopti 2.1.1

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.

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

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 cleanall 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/