Metadata-Version: 2.1
Name: CLICopti
Version: 2.2
Author: Daniel Schulte, Alexej Grudiev, Andrea Latina, Jim Ögren
Author-email: Kyrre Sjobak <k.n.sjobak@fys.uio.no>
License: LGPL3+
Requires-Python: >=3
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy

# 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.

## 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](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

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](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.
