Metadata-Version: 2.4
Name: geoff-app
Version: 1.0.0
Summary: Reference GUI for the Geoff project
Author-email: Verena Kain <verena.kain@cern.ch>, Penny Madysa <penny.madysa@cern.ch>
Project-URL: gitlab, https://gitlab.cern.ch/geoff/geoff-app
Platform: CERN General Network
Platform: CERN Technical Network
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: X11 Applications :: Qt
Classifier: Intended Audience :: Science/Research
Classifier: License :: Other/Proprietary License
Classifier: Natural Language :: English
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: COPYING
Requires-Dist: PyQt5~=5.12
Requires-Dist: qtawesome~=1.0
Requires-Dist: cernml-coi>=0.9
Requires-Dist: cernml-coi-optimizers[bobyqa,cernml-es,scipy,skopt]>=3.0.0
Requires-Dist: cernml-coi-utils[matplotlib]~=0.3.0
Requires-Dist: numpy>=1.20
Requires-Dist: stable-baselines3~=2.3
Requires-Dist: typing-extensions>=4.6; python_version < "3.12"
Provides-Extra: test
Requires-Dist: freezegun>=1.5; extra == "test"
Requires-Dist: cernml-coi-optimizers[xopt]>=3.0.0; extra == "test"
Requires-Dist: pytest>=6.0; extra == "test"
Requires-Dist: pytest-qt>=4.2; extra == "test"
Dynamic: license-file

<!--
SPDX-FileCopyrightText: 2020-2026 CERN
SPDX-FileCopyrightText: 2023-2026 GSI Helmholtzzentrum für Schwerionenforschung
SPDX-FileNotice: All rights not expressly granted are reserved.

SPDX-License-Identifier: GPL-3.0-or-later OR EUPL-1.2+
-->

Generic Optimisation Frontend and Framework (GeOFF)
===================================================

This is the graphical application for generic numerical optimisation and
reinforcement learning on CERN accelerators. It bundles:
1. interfaces to the machines and simulations thereof, and
2. numerical optimisers and reinforcement learners that can use these
   interfaces.

This repository is available on CERN's [Gitlab][].

[Gitlab]: https://gitlab.cern.ch/geoff/geoff-app-zero

Table of Contents
=================

[[_TOC_]]

Installation
============

The information in this section is only relevant if you want to install this
application into your own environment. You typically want to do this when
developing a plugin for your own optimization problem. This section is
up-to-date as of July 2023.

Step 1: Acc-Py and Venv
-----------------------

As before, you have the choice between basing your environment either on the
Base or the Interactive distribution of Acc-Py. See [*Getting Started with
Acc-Py*][Acc-Py] for a full explanation. Once this is set up, you can create
and activate a *virtual environment*, or [*venv*][venv] for short. This helps
isolate installed dependencies from your system and makes it easier to work on
multiple independent projects.

```shell-session
$ # Set up production-stage release of Acc-Py Base, switch to Python 3.7.
$ source /acc/local/share/python/acc-py/base/pro/setup.sh

$ # At CERN, HOME is on the AFS filesystem and is strictly limited in space.
$ # Because GeOFF has some very large dependencies, we recommend putting your
$ # venv somewhere else when on a CERN machine. If you have a BE-provided VPC,
$ # one possibility is /opt/venvs.
$ mkdir -p ~/venvs

$ # Make a virtual environment based on Acc-Py base and activate it.
$ acc-py venv ~/venvs/geoff
$ source ~/venvs/geoff/bin/activate
```

[Acc-Py]: https://wikis.cern.ch/display/ACCPY/Getting+started+with+Acc-Py
[venv]: https://docs.python.org/3/library/venv.html

Of course, you're free to set up your virtual environment however you prefer.
The steps above have been tested to work.

Step 2: Installing the App
--------------------------

Once you've activated a virtual environment of your choice, installing the
application is dead-simple:

```shell-session
$ pip install geoff-app
```

And you can run the installed version via:

```shell-session
$ python -m geoff_app
```

If you have decided to clone this repository, you can install this clone
(instead of a published verison) like this:

```shell-session
$ git clone https://gitlab.cern.ch/geoff/geoff-app-zero
$ cd geoff-app
$ pip install .
```

Step 3: Using Your Own Optimisation Problem
-------------------------------------------

The app provides a number of built-in problems to solve; but it also provides a
_foreign-imports_ mechanism to temporarily add your own problem to its list.
This is a great fit for experimenting with your code from within the GUI and
preview it before submitting it for official inclusion.

To include your own code in the GUI, simply pass the path to it when running
the GUI:

```shell-session
$ # Import some_file.py from the current working directory.
$ python -m geoff_app some_file.py

$ # Go to ../path/to and import the package `directory` from there. The package
$ # must contain an __init__.py file.
$ python -m geoff_app ../path/to/directory/

$ # First import `package`, then import `package.submodule`.
$ python -m geoff_app path/to/package::submodule
```

Note the curious syntax in the third example; simply importing
`path/to/package/submodule.py` would not work, as Python would be unable to
resolve any package-relative imports in `submodule.py`. The double-colon chain
can obviously be extended to import the submodule of a submodule.

To import more than one module, simply pass the paths to all of them as
separate arguments. You can pass `--keep-going` to continue loading packages
even if one of them fails.

License
-------

Except as otherwise noted, this work is licensed under either of [GNU Public
License, Version 3.0 or later](LICENSES/GPL-3.0-or-later.txt), or [European
Union Public License, Version 1.2 or later](LICENSES/EUPL-1.2.txt), at your
option. See [COPYING](COPYING) for details.

Unless You explicitly state otherwise, any contribution intentionally submitted
by You for inclusion in this Work (the Covered Work) shall be dual-licensed as
above, without any additional terms or conditions.

For full authorship information, see the version control history.
