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.

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 for a full explanation. Once this is set up, you can create and activate a virtual environment, or venv for short. This helps isolate installed dependencies from your system and makes it easier to work on multiple independent projects.

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

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:

$ pip install geoff-app

And you can run the installed version via:

$ python -m geoff_app

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

$ 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:

$ # 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, or European Union Public License, Version 1.2 or later, at your option. See 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.