Documentation

.github/workflows/quality.yml

@@ -11,7 +11,7 @@ jobs:
     steps:
     - uses: actions/checkout@v4
       with:
-        submodules: 'true'
+        submodules: 'recursive'
     - name: Install poetry
       run: pipx install poetry
     - name: Set up Python 3.11

.gitmodules

@@ -1,6 +1,3 @@
-[submodule "trackml-library"]
-	path = trackml-library
-	url = [email protected]:stroblme/trackml-library.git
 [submodule "hepqpr-qallse"]
 	path = hepqpr-qallse
 	url = [email protected]:lfd/hepqpr-qallse.git

CONTRIBUTING.md

@@ -12,10 +12,11 @@ Start of by..
 ## Setup
 
 Contributing to this project requires some more dependencies besides the "standard" packages.
-Those are specified in the groups `dev` and `docs`.
+Those are specified in the groups `dev`.
 ```
-poetry install --with dev,docs
+poetry install --with dev
 ```
+These dependencies are essentially flake8, black, pre-commit and licensecheck which we use for quality assurance and code formatting.
 
 Additionally, we have pre-commit hooks in place, which can be installed as follows: 
 ```
@@ -24,25 +25,4 @@ poetry run pre-commit install
 ```
 
 Currently the only purpose of the hook is to run Black on commit which will do some code formatting for you.
-However be aware, that this might reject your commit and you have to re-do the commit.
-
-## Testing
-
-We do our testing with Pytest. Corresponding tests can be triggered as follows:
-```
-poetry run pytest
-```
-There are Github action pipelines in place, that will do linting and testing once you open a pull request.
-However, it's a good idea to run tests and linting (either Black or Flake8) locally before pushing.
-
-## Documentation
-
-We use MkDocs for our documentation. To run a server locally, run:
-```
-poetry run mkdocs serve
-```
-This will automatically trigger a rebuild each time you make changes.
-See the [MkDocs Documentation](https://cirkiters.github.io/qml-essentials/usage/) for more details.
-
-Publishing (and building) the documentation is done automagically using Github actions.
-This action is triggered when a new release is made.
+However be aware, that this might reject your commit and you have to re-do the commit.

README.md

@@ -1,12 +1,16 @@
 # From Hope To Heuristics
 **Realistic Runtime Estimates for Quantum Optimisation in NHEP**
 
-## Approach
+## :book: Project Description
 
-For the QUBO formulation we build on the [HEPQPR.Qallse](https://github.com/derlin/hepqpr-qallse) project.
+This is the repository for our contribution to [CHEP24](https://indico.cern.ch/event/1338689/contributions/6010081/) consisting of two key aspects:
+Firstly, we estimate runtimes and scalability for common NHEP problems addressed via QUBO formulations by identifying minimum energy solutions of intermediate Hamiltonian operators encountered during the annealing process. 
+Secondly, we investigate how the classical parameter space in the QAOA, together with approximation techniques such as a Fourier-analysis based heuristic, proposed by Zhou et al. (2018), can help to achieve (future) quantum advantage, considering a trade-off between computational complexity and solution quality.
+Those approaches are evaluated on two benchmark problems: the Maxcut problem and the track reconstruction problem.
 
-<!-- TODO: add description -->
+## Approach
 
+For the QUBO formulation of the track reconstruction problem, we build on the [HEPQPR.Qallse](https://github.com/derlin/hepqpr-qallse) project.
 To work with smaller sized QUBOs, we only focus on hit-triplets present in a specified angle, similar to the approach presented by [Schwägerl et al.](https://arxiv.org/pdf/2303.13249).
 
 ## :rocket: Getting Started
@@ -17,20 +21,13 @@ When cloning, make sure to get the submodule:
 ```
 git clone --recurse-submodules [email protected]:lfd/spectral_gap_nhep.git
 ```
+This will clone [our fork of hepqr-qallse](https://github.com/lfd/hepqpr-qallse) and [our fork of trackml](https://github.com/lfd/trackml) recursively.
+The latter is needed by hepqr-qallse but is not shipped via pip.
 
 If you have poetry installed, run `poetry install`.
-With pip, make sure to include the dependencies in the submodule `trackml-library` (pandas and numpy) and `hepqpr-qallse` (pandas, numpy, plotly).
+With pip, make sure to include the dependencies in the submodule `hepqpr-qallse` (pandas, numpy, plotly) and `trackml` (pandas, numpy).
 
 
-<!-- To get the data, head over to the [Kaggle TrackML Particle Tracking Challenge](https://www.kaggle.com/c/trackml-particle-identification/data) and download e.g. the `train_sample.zip` file which is a reduced version of the overall dataset.
-Extract the data into a `dataset` folder, such that the structure is as follows:
-```bash
-\data\01_raw\event*-hits.csv
-\data\01_raw\event*-particles.csv
-\data\01_raw\event*-truth.csv
-```
-Head over to the [TrackML Library Repo](https://github.com/stroblme/trackml-library) for more details. -->
-
 ### Quickstart
 
 After installing all the dependencies, simply execute
@@ -39,6 +36,10 @@ kedro run
 ```
 
 This will run the default pipeline which consists of all individual pipelines described in the following section.
+You can get an interactive overview of the pipeline in your browser by running
+```
+kedro viz
+```
 
 ### Pipelines
 
@@ -79,16 +80,22 @@ The following list gives a brief explanation of the most important locations in
 
 Besides that, we make use of two submodules:
 - `hepqpr-qallse`: Currently, all the data loading and QUBO formulation is done using this submodule
-- `trackml-library`: Not in use currently
 
 ## Hyperparameter Optimization
 
 This project uses Optuna for hyperparameter optimization.
-You can take a look at the experiments by running
+There is a dedicated kedro pipeline that takes care of the hyperparameter optimization and submission of jobs to a SLURM cluster.
+```
+kedro run --pipeline hyperparameter_study
+```
+
+If you don't have a SLURM cluster available, head to `pipelines/hyperparameter_study/nodes.py` switch the subprocess command such that it spawns a single kedro job instead of a submission to the cluster.
+
+Supposing everything goes well, you can take a look at the experiments by running
 ```
 optuna-dashboard sqlite:///studies/fhth.db
 ```
-supposing that the path to the sqlite database where Optuna stores its results is `storage/fhth.db`.
+supposing that the path to the sqlite database where Optuna stores its results is `studies/fhth.db`.
 
 ## 🚧 Contributing