# 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](CITATION) file.

For further reading, the main references for CLICopti are listed in the [REFERENCES](REFERENCES) file.

CLICopti is published under the GNU Lesser General Public License Version 3, please respect it.
For details see the [LICENSE](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](CITATION) file,
along with reading through [structure.h](h/structure.h).

### C++
For C++, the examples shown in the [src](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](Octave) folder.

### Python
For Python, an example notebook is in the [Python](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](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](dist) subfolder containing `.whl` (wheel) files.

## Documentation

The main documentation of the code and the methods implemented is found in the [REFERENCES](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](swig) folder as discussed above.
The, in the folder [swig/sphinx-doc-python](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](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/`
