Merge pull request #63 from KIT-MRT/pacman-demo

Pacman demo

.env

@@ -0,0 +1 @@
+version

.gitignore

@@ -12,4 +12,3 @@ _site/
 .bundle/
 vendor/
 Gemfile.lock
-

Dockerfile

@@ -24,7 +24,11 @@ RUN git clone https://github.com/KIT-MRT/util_caching.git /tmp/util_caching && \
 
 
 # Install arbitration_graphs
-COPY . /tmp/arbitration_graphs
+COPY CMakeLists.txt /tmp/arbitration_graphs/
+COPY cmake /tmp/arbitration_graphs/cmake
+COPY include /tmp/arbitration_graphs/include
+COPY test /tmp/arbitration_graphs/test
+
 RUN mkdir /tmp/arbitration_graphs/build && \
     cd /tmp/arbitration_graphs/build && \
     cmake .. && \

README.md

@@ -2,43 +2,83 @@
 
 [![License](https://img.shields.io/github/license/KIT-MRT/arbitration_graphs)](./LICENSE)
 
-Arbitration graphs combine simple atomic behavior components into more complex behaviors for decision-making and behavior generation
+**Hierarchical behavior models for complex decision-making and behavior generation in robotics!**
+
+<!-- 
+TODO: add example arbitration graph from robotics (with POMDP, RL methods)
+<img
+  src="./docs/assets/img/pacman_arbitrator_safe.svg"
+  alt="Example arbitration graph from robotics"
+  style="margin:10px; width: 50%"
+  align="right"
+/>
+-->
+
+- 🌱 **Bottom-up**  
+  Combine simple atomic behavior components to generate complex behaviors.
+- 🧩 **Functional decomposition**  
+  Behavior components address *How to do it?* and *Can we do it?*, while Arbitrators decide *What to do?*
+ - 🧠 **Meta-framework**  
+  Integrate diverse methods in one decision-making framework. Why not combine optimization-based planning, probabilistic approaches (POMDPs), and machine learning (RL)? Use any approach where it performs best!
+- 📈 **Scalability**  
+  Stack behavior components in arbitrators to create hierarchical behavior models.
+- 🛠️ **Maintainability**  
+  Add new behaviors without having to touch existing ones – did we mention strict modularity and functional decomposition?
+- 💡 **Transparency**  
+  Easily follow and understand the decision-making process.
+- 🛡️ **Behavior Verification**  
+  Use tightly integrated verifiers to ensure that only safe and valid behavior commands are executed.
+- 🪂 **Graceful Degradation**  
+  Your behavior is unreliable or unsafe? Arbitrators will gracefully fall back to the next-best option.
+
+
+## Demo
+
+We provide a demo of this library using Pac-Man as an example application.  
+The arbitration graph controls Pac-Man on its journey to collect tasty dots 🍬
+
+Run the demo with:
 
-## Demonstration
+```bash
+git clone https://github.com/KIT-MRT/arbitration_graphs.git
+cd arbitration_graphs/demo
+docker compose up
+```
 
-We are currently working on a demonstration of this library using Pac-Man as an example application.
+### Explanation
+
+You will see the *Pacman Agent* arbitrator selecting between five behavior options (by priority).  
+The *Eat Dots* option is itself an arbitrator with two sub-behaviors (selecting by expected benefit).
+
+In this scene,
+- the *Chase Ghost* and *Avoid Ghost* behaviors are not applicable (no ghosts in close vicinity) → grey background,
+- the *Eat Closest Dot* and *Move Randomly* behavior failed verification (our verification showcase) → red background,
+- thus, the least-prioritized *Stay in Place* behavior is being executed → green background.
 
 <p align="center">
-  <img src="docs/assets/img/pacman_scenario.png" width="400" />
+  <img src="docs/assets/img/pacman_scenario_cropped.png" width="300" />
 </p>
 <p align="center">
   <img src="docs/assets/img/pacman_arbitrator_safe.svg" width="500" /> 
 </p>
 
-Feel free to take a look at the work in progress in the [pacman-demo branch](https://github.com/KIT-MRT/arbitration_graphs/tree/pacman-demo).
 
-## Installation
+We will shortly add an [arbitration graph GUI](https://github.com/KIT-MRT/arbitration_graphs/pull/10) and a [tutorial](https://github.com/KIT-MRT/arbitration_graphs/pull/51) based on this demo – stay tuned! 
 
-First, clone this repository:
 
-```bash
-git clone https://github.com/KIT-MRT/arbitration_graphs.git
-cd arbitration_graphs
-```
+## Installation
 
+From easy to advanced:
 
 ### Using Docker image
 
-We provide a [`Dockerfile`](./Dockerfile) with the library already installed globally.
-
-In the source directory, build and run the docker image with `docker compose`:
+We provide a Docker image with the library already installed globally.
 
 ```bash
-docker compose build
-docker compose run --rm arbitration_graphs
+docker pull ghcr.io/kit-mrt/arbitration_graphs
 ```
 
-The library is installed in the Docker image under `/usr/local/include/arbitration_graphs/` and `/usr/local/lib/cmake/arbitration_graphs/`.
+The library is located under `/usr/local/include/arbitration_graphs/` and `/usr/local/lib/cmake/arbitration_graphs/`.
 So, it can be easily loaded with CMake:
 
 ```cmake
@@ -56,6 +96,13 @@ First make sure all dependencies are installed:
 
 See also the [`Dockerfile`](./Dockerfile) for how to install these packages under Debian or Ubuntu.
 
+Now, clone the repository:
+
+```bash
+git clone https://github.com/KIT-MRT/arbitration_graphs.git
+cd arbitration_graphs
+```
+
 Compile and install the project with CMake:
 
 ```bash
@@ -71,12 +118,13 @@ sudo cmake --install .
 
 ### Using Docker image
 
-Follow the steps above to setup the Docker image.
-Then, run the development image.
+Clone the repository and run the development image
 
 ```bash
-docker compose -f docker-compose.devel.yaml build
-docker compose -f docker-compose.devel.yaml run --rm arbitration_graphs_devel
+git clone https://github.com/KIT-MRT/arbitration_graphs.git
+cd arbitration_graphs
+docker compose build
+docker compose run --rm arbitration_graphs_devel
 ```
 
 This mounts the source into the container's `/home/blinky/arbitration_graphs` folder.

demo/.clang-format

@@ -0,0 +1,92 @@
+Language: Cpp
+BasedOnStyle: LLVM
+AccessModifierOffset: -4
+AlignAfterOpenBracket: Align
+AlignConsecutiveAssignments: false
+AlignConsecutiveDeclarations: false
+AlignEscapedNewlines: Left
+AlignOperands: true
+AlignTrailingComments: true
+AllowAllParametersOfDeclarationOnNextLine: true
+AllowShortBlocksOnASingleLine: Never
+AllowShortCaseLabelsOnASingleLine: false
+AllowShortFunctionsOnASingleLine: None
+AllowShortIfStatementsOnASingleLine: Never
+AllowShortLoopsOnASingleLine: false
+AlwaysBreakAfterDefinitionReturnType: None
+AlwaysBreakAfterReturnType: None
+AlwaysBreakBeforeMultilineStrings: false
+AlwaysBreakTemplateDeclarations: Yes
+BinPackArguments: false
+BinPackParameters: false
+BraceWrapping:   
+  AfterClass:      false
+  AfterControlStatement: Never
+  AfterEnum:       false
+  AfterFunction:   false
+  AfterNamespace:  false
+  AfterObjCDeclaration: false
+  AfterStruct:     false
+  AfterUnion:      false
+  BeforeCatch:     false
+  BeforeElse:      false
+  IndentBraces:    false
+BreakBeforeBinaryOperators: None
+BreakBeforeBraces: Attach
+BreakBeforeTernaryOperators: true
+BreakConstructorInitializersBeforeComma: false
+ColumnLimit: 120
+CommentPragmas:  '^ IWYU pragma:'
+ConstructorInitializerAllOnOneLineOrOnePerLine: false
+ConstructorInitializerIndentWidth: 8
+ContinuationIndentWidth: 4
+Cpp11BracedListStyle: true
+DerivePointerAlignment: false
+DisableFormat:   false
+ExperimentalAutoDetectBinPacking: false
+ForEachMacros:   [ foreach, Q_FOREACH, BOOST_FOREACH ]
+IncludeCategories: 
+  - Regex:           '^<.*\/.*\/.*>'
+    Priority:        3
+  - Regex:           '^<.*\/.*>'
+    Priority:        2
+  - Regex:           '^<.*>'
+    Priority:        1
+  - Regex:           '^".*\/.*\/.*"'
+    Priority:        6
+  - Regex:           '^".*\/.*"'
+    Priority:        5
+  - Regex:           '^".*"'
+    Priority:        4
+  - Regex:           '.*'
+    Priority:        7
+IndentCaseLabels: false
+IndentWidth: 4
+IndentWrappedFunctionNames: false
+KeepEmptyLinesAtTheStartOfBlocks: true
+MacroBlockBegin: ''
+MacroBlockEnd:   ''
+MaxEmptyLinesToKeep: 2
+NamespaceIndentation: None
+PenaltyBreakBeforeFirstCallParameter: 19
+PenaltyBreakComment: 300
+PenaltyBreakFirstLessLess: 120
+PenaltyBreakString: 1000
+PenaltyExcessCharacter: 1000000
+PenaltyReturnTypeOnItsOwnLine: 2000
+PointerAlignment: Left
+ReflowComments:  true
+SortIncludes:    true
+SpaceAfterCStyleCast: false
+SpaceBeforeAssignmentOperators: true
+SpaceBeforeParens: ControlStatements
+SpaceInEmptyParentheses: false
+SpacesBeforeTrailingComments: 1
+SpacesInAngles:  false
+SpacesInContainerLiterals: true
+SpacesInCStyleCastParentheses: false
+SpacesInParentheses: false
+SpacesInSquareBrackets: false
+Standard:        Latest
+TabWidth:        4
+UseTab:          Never