Merge pull request #130 from Benezivas/4.0.0-rc

Release version 4.0.0

Author: Benezivas

.devcontainer/devcontainer.json

@@ -0,0 +1,17 @@
+// For format details, see https://aka.ms/devcontainer.json. For config options, see the
+// README at: https://github.com/devcontainers/templates/tree/main/src/docker-existing-dockerfile
+{
+	"name": "Algobattle",
+	"build": {
+		"context": "..",
+		"dockerfile": "../Dockerfile.dev"
+	},
+    "mounts": [
+        "source=${localWorkspaceFolder}/../algobattle-problems/algobattle_problems,target=/algobattle/problems,type=bind",
+        "source=algobattle_input,target=/algobattle/input",
+        "source=algobattle_output,target=/algobattle/output"
+    ],
+    "features": {
+        "ghcr.io/devcontainers/features/docker-outside-of-docker": {}
+    }
+}

.flake8

@@ -0,0 +1,14 @@
+[flake8]
+count = True
+show_source = True
+statistics = True
+max_line_length = 120
+per_file_ignores =
+    tests/*: D102, D104, D107
+    docs/*: D100, E261
+docstring_convention = google
+ignore = D105, D401, E302, W503
+exclude =
+    .git,
+    __pycache__,
+ignore_decorators=inherit_docs

.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI code checks
+
+on:
+  pull_request:
+    branches: [ main, develop ]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Python
+      uses: actions/setup-python@v2
+      with:
+        python-version: "3.11"
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install flake8 flake8-docstrings
+    - name: Lint with flake8
+      run: flake8 .
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Python
+      uses: actions/setup-python@v2
+      with:
+        python-version: "3.11"
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install . --user
+    - name: Test using unittests
+      run: python -m unittest --failfast

.github/workflows/python-app.yml

@@ -0,0 +1,69 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - v*.*.*
+
+jobs:
+  pypi-publish:
+    name: Upload release to PyPI
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      # IMPORTANT: this permission is mandatory for trusted publishing
+      id-token: write
+    steps:
+      - uses: actions/checkout@v3
+      - uses: pdm-project/setup-pdm@v3
+      - name: Publish package distributions to PyPI
+        run: pdm publish
+
+  release:
+    name: Create Github release
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
+        with:
+          python-version: 3.11
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV 
+      - uses: actions/cache@v3
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install mkdocs-material pymdown-extensions mkdocstrings[python] mdx_include
+      - name: Build docs
+        run: mkdocs build -d ./site
+      - name: zip docs
+        run: zip -r docs.zip ./site
+      - name: tar docs
+        run: tar czf docs.tar.gz -C ./site .
+      - name: Release
+        uses: softprops/action-gh-release@v1
+        with:
+          generate_release_notes: true
+          files: |
+            docs.zip
+            docs.tar.gz
+
+  deploy-docs:
+    name: Deploy docs to github pages
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV 
+      - uses: actions/cache@v3
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install mkdocs-material pymdown-extensions mkdocstrings[python] mdx_include
+      - run: mkdocs gh-deploy --force

.github/workflows/release.yml

@@ -1,3 +1,12 @@
 **/__pycache__
-algobattle.egg-info/*
-.vscode/*
+algobattle.egg-info
+.vscode
+.pdm-python
+pdm.lock
+build
+dist
+site
+docs/src/pairsum_solver/target
+docs/src/pairsum_solver/Cargo.lock
+.results
+.project

.gitignore

@@ -0,0 +1,8 @@
+FROM python:3.11
+
+WORKDIR /src/algobattle
+COPY . .
+RUN pip install .
+
+ENTRYPOINT [ "algobattle" ]
+CMD ["-h"]

Dockerfile

@@ -0,0 +1,8 @@
+FROM python:3.11
+
+ENV ALGOBATTLE_IO_VOLUMES=true
+WORKDIR /workspaces/algobattle
+COPY . .
+RUN pip install -e . --config-settings editable_mode=compat
+WORKDIR /
+RUN rm -rf /workspaces

Dockerfile.dev

@@ -2,58 +2,60 @@
 
 The lab course "Algorithmic Battle" is offered by the 
 [Computer Science Theory group of RWTH Aachen University](https://tcs.rwth-aachen.de/)
-since 2019. This repository contains the necessary code and documentation to
-set up the lab course yourself.
-
-The idea of the lab is to pose several, usually NP-complete problems during the
-semester.  
-Groups of students then write code that generates hard-to-solve instances for
-these problems and solvers that solve these problems quickly. In the default
-setting, the groups then battle against each other, generating instances of
-increasing size that the other group has to solve within a time limit.  
-Points are distributed relative to the biggest instance size for which a group
-was still able to solve an instance.
-
-# Installation
-This project has been delevoped to run on Linux and may not work on other
-platforms. Support for other platforms may be implemented in the future.
-
-`python3` in version at least `3.6` and `docker` are required.
-
-We recommend installing the package as a user using `pip`
-```
-pip install . --user
-```
-
-Adjust the parameters set in the `algobattle/configs/config.ini` file to set
-which hardware resources you want to assign. You can pass alternative
-configuration files to the script using the `--config_file` option.
-
-This program requires the `curses` module which is available by default on Linux
-and can be manually installed on windows, e.g. with
-```
-pip install windows-curses
-```
-
-# Usage
-This repository does not include any practical problems. For a selection of problems
-that have been posed to students in practice, have a look at the
-[algobattle-problems](https://github.com/Benezivas/algobattle-problems) repository.
-
-To start a basic run on a problem, using the `solver` and `generator` that
-are part of the problem directory, use
-```
-battle path/to/concrecte/problem/folder
-```
-
-The `battle` script offers several options, e.g. to give custom paths for
-solvers and generators. Run `battle --help` for all options.
-
-On Windows you will need to either use a workaround such as [this one](https://stackoverflow.com/a/55619189)
-or invoke it with
-```
-python path\to\installed\battle\script
-```
-followed by your arguments instead of just `battle`.
-
-Check the [wiki](https://github.com/Benezivas/algobattle/wiki) for further documentation.
+since 2019. This repository contains the necessary code and
+documentation to set up the lab course yourself.
+
+In an Algorithmic Battle, pairs of teams compete against one another
+in order to solve a problem of your choice, e.g. a problem from the
+class NP. The teams each design a `generator`, that outputs
+hard-to-solve instances for a given instance size, as well as a
+`solver` that accepts an instance and outputs a solution to it as
+quickly as possible.
+
+The framework is written to be completely language-agnostic regarding
+the code of the `generator` and the `solver`, as each is wrapped in a
+docker container that only needs to adhere to an I/O structure of your
+choice (by default, in the form of `json`-files.)
+
+If you are interested in how to use the framework for a
+lab course of your own, please consult our
+[teaching concept](https://www.algobattle.org/docs/teaching_concept/english).
+# Installation and Usage
+This project is developed and tested on all major operating systems.
+
+Please consult the official [documentation](https://www.algobattle.org/docs/)
+for detailed instructions on installation and usage.
+
+# Related projects
+This repository only includes the core framework for executing an
+`Algorithmic Battle`. For a selection of concrete problems that you
+can use to play around with the framework, have a look at the
+[algobattle-problems](https://github.com/Benezivas/algobattle-problems)
+repository. These are problems that have been posed to students in
+some form over the past years.
+
+While the framework provides all essential tools to host a tournament
+yourself, e.g. in the form of a lab course, you may be interested in
+the [algobattle-web](https://github.com/Benezivas/algobattle-problems)
+project.  The `algobattle-web` project implements a webframework with
+which you are able to comfortably manage your students teams and their
+code, your problem files and their documentation as well as schedule
+matches to be fought between registered student teams, using the
+`algobattle` API.
+
+# Contributing
+
+We welcome any input on how to make this project accessible to as many
+people as possible. If you have feedback regarding the usage of the
+framework, the documentation or would even like to help us out with
+corrections, new features, or translations, feel free to open an issue
+or pull request. We have developed this project on the basis of
+practical experience inside our lab courses, thus some design elements
+may be unintuitive to you. Feel free to point out anything that
+appears odd to you.
+
+# Funding
+The development of version `4.0.0` was funded by
+[`Stiftung Innovation in der Hochschullehre`](https://stiftung-hochschullehre.de/en/) (Project 
+`FRFMM-106/2022 Algobattle`) and by the [Department of Computer Science of
+RWTH Aachen University](https://www.informatik.rwth-aachen.de/go/id/mxz/?lidx=1).