.gitignore

+__pycache__
+.devcontainer
 .dll
+.env
+.pytest_cache
 .so
+.venv
 .vscode
-.pytest_cache
-__pycache__
-generator.log
+*.bkp
 *.orig
+build
+deps
+generator.log
+MODULE.*

.gitmodules

-[submodule "engine/deps/yase"]
-	path = engine/deps/yase
-	url = https://gitlab.eclipse.org/eclipse/simopenpass/yase.git
-	branch = main
-[submodule "engine/deps/scenario_api"]
-	path = engine/deps/scenario_api
-	url = https://gitlab.eclipse.org/eclipse/simopenpass/scenario_api.git
-[submodule "engine/deps/units"]
-	path = engine/deps/units
-	url = https://github.com/nholthaus/units.git
-[submodule "engine/deps/openscenario_api"]
-	path = engine/deps/openscenario_api
-	url = https://github.com/RA-Consulting-GmbH/openscenario.api.test

CODE_OF_CONDUCT.md

+# Community Code of Conduct
+
+**Version 2.0  
+January 1, 2023**
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as community members, contributors, Committers[^1], and Project Leads (collectively "Contributors") pledge to make participation in our projects and our community a harassment-free and inclusive experience for everyone.
+
+This Community Code of Conduct ("Code") outlines our behavior expectations as members of our community in all Eclipse Foundation activities, both offline and online. It is not intended to govern scenarios or behaviors outside of the scope of Eclipse Foundation activities. Nor is it intended to replace or supersede the protections offered to all our community members under the law. Please follow both the spirit and letter of this Code and encourage other Contributors to follow these principles into our work. Failure to read or acknowledge this Code does not excuse a Contributor from compliance with the Code.
+
+## Our Standards
+
+Examples of behavior that contribute to creating a positive and professional environment include:
+
+- Using welcoming and inclusive language;
+- Actively encouraging all voices;
+- Helping others bring their perspectives and listening actively. If you find yourself dominating a discussion, it is especially important to encourage other voices to join in;
+- Being respectful of differing viewpoints and experiences;
+- Gracefully accepting constructive criticism;
+- Focusing on what is best for the community;
+- Showing empathy towards other community members;
+- Being direct but professional; and
+- Leading by example by holding yourself and others accountable
+
+Examples of unacceptable behavior by Contributors include:
+
+- The use of sexualized language or imagery;
+- Unwelcome sexual attention or advances;
+- Trolling, insulting/derogatory comments, and personal or political attacks;
+- Public or private harassment, repeated harassment;
+- Publishing others' private information, such as a physical or electronic address, without explicit permission;
+- Violent threats or language directed against another person;
+- Sexist, racist, or otherwise discriminatory jokes and language;
+- Posting sexually explicit or violent material;
+- Sharing private content, such as emails sent privately or non-publicly, or unlogged forums such as IRC channel history;
+- Personal insults, especially those using racist or sexist terms;
+- Excessive or unnecessary profanity;
+- Advocating for, or encouraging, any of the above behavior; and
+- Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Our Responsibilities
+
+With the support of the Eclipse Foundation employees, consultants, officers, and directors (collectively, the "Staff"), Committers, and Project Leads, the Eclipse Foundation Conduct Committee (the "Conduct Committee") is responsible for clarifying the standards of acceptable behavior. The Conduct Committee takes appropriate and fair corrective action in response to any instances of unacceptable behavior.
+
+## Scope
+
+This Code applies within all Project, Working Group, and Interest Group spaces and communication channels of the Eclipse Foundation (collectively, "Eclipse spaces"), within any Eclipse-organized event or meeting, and in public spaces when an individual is representing an Eclipse Foundation Project, Working Group, Interest Group, or their communities. Examples of representing a Project or community include posting via an official social media account, personal accounts, or acting as an appointed representative at an online or offline event. Representation of Projects, Working Groups, and Interest Groups may be further defined and clarified by Committers, Project Leads, or the Staff.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the Conduct Committee via conduct@eclipse-foundation.org. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. Without the explicit consent of the reporter, the Conduct Committee is obligated to maintain confidentiality with regard to the reporter of an incident. The Conduct Committee is further obligated to ensure that the respondent is provided with sufficient information about the complaint to reply. If such details cannot be provided while maintaining confidentiality, the Conduct Committee will take the respondent‘s inability to provide a defense into account in its deliberations and decisions. Further details of enforcement guidelines may be posted separately.
+
+Staff, Committers and Project Leads have the right to report, remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code, or to block temporarily or permanently any Contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful. Any such actions will be reported to the Conduct Committee for transparency and record keeping.
+
+Any Staff (including officers and directors of the Eclipse Foundation), Committers, Project Leads, or Conduct Committee members who are the subject of a complaint to the Conduct Committee will be recused from the process of resolving any such complaint.
+
+## Responsibility
+
+The responsibility for administering this Code rests with the Conduct Committee, with oversight by the Executive Director and the Board of Directors. For additional information on the Conduct Committee and its process, please write to <conduct@eclipse-foundation.org>.
+
+## Investigation of Potential Code Violations
+
+All conflict is not bad as a healthy debate may sometimes be necessary to push us to do our best. It is, however, unacceptable to be disrespectful or offensive, or violate this Code. If you see someone engaging in objectionable behavior violating this Code, we encourage you to address the behavior directly with those involved. If for some reason, you are unable to resolve the matter or feel uncomfortable doing so, or if the behavior is threatening or harassing, please report it following the procedure laid out below.
+
+Reports should be directed to <conduct@eclipse-foundation.org>. It is the Conduct Committee’s role to receive and address reported violations of this Code and to ensure a fair and speedy resolution.
+
+The Eclipse Foundation takes all reports of potential Code violations seriously and is committed to confidentiality and a full investigation of all allegations. The identity of the reporter will be omitted from the details of the report supplied to the accused. Contributors who are being investigated for a potential Code violation will have an opportunity to be heard prior to any final determination. Those found to have violated the Code can seek reconsideration of the violation and disciplinary action decisions. Every effort will be made to have all matters disposed of within 60 days of the receipt of the complaint.
+
+## Actions
+Contributors who do not follow this Code in good faith may face temporary or permanent repercussions as determined by the Conduct Committee.
+
+This Code does not address all conduct. It works in conjunction with our [Communication Channel Guidelines](https://www.eclipse.org/org/documents/communication-channel-guidelines/), [Social Media Guidelines](https://www.eclipse.org/org/documents/social_media_guidelines.php), [Bylaws](https://www.eclipse.org/org/documents/eclipse-foundation-be-bylaws-en.pdf), and [Internal Rules](https://www.eclipse.org/org/documents/ef-be-internal-rules.pdf) which set out additional protections for, and obligations of, all contributors. The Foundation has additional policies that provide further guidance on other matters.
+
+It’s impossible to spell out every possible scenario that might be deemed a violation of this Code. Instead, we rely on one another’s good judgment to uphold a high standard of integrity within all Eclipse Spaces. Sometimes, identifying the right thing to do isn’t an easy call. In such a scenario, raise the issue as early as possible.
+
+## No Retaliation
+
+The Eclipse community relies upon and values the help of Contributors who identify potential problems that may need to be addressed within an Eclipse Space. Any retaliation against a Contributor who raises an issue honestly is a violation of this Code. That a Contributor has raised a concern honestly or participated in an investigation, cannot be the basis for any adverse action, including threats, harassment, or discrimination. If you work with someone who has raised a concern or provided information in an investigation, you should continue to treat the person with courtesy and respect. If you believe someone has retaliated against you, report the matter as described by this Code. Honest reporting does not mean that you have to be right when you raise a concern; you just have to believe that the information you are providing is accurate.
+
+False reporting, especially when intended to retaliate or exclude, is itself a violation of this Code and will not be accepted or tolerated.
+
+Everyone is encouraged to ask questions about this Code. Your feedback is welcome, and you will get a response within three business days. Write to <conduct@eclipse-foundation.org>.
+
+## Amendments
+
+The Eclipse Foundation Board of Directors may amend this Code from time to time and may vary the procedures it sets out where appropriate in a particular case.
+
+### Attribution
+
+This Code was inspired by the [Contributor Covenant](https://www.contributor-covenant.org/), version 1.4, available [here](https://www.contributor-covenant.org/version/1/4/code-of-conduct/).
+
+[^1]: Capitalized terms used herein without definition shall have the meanings assigned to them in the Bylaws.

CONTRIBUTING.md

+# Contributing to Eclipse openPASS
+
+This guide provides all necessary information to enable [contributors and committers](https://www.eclipse.org/projects/dev_process/#2_3_1_Contributors_and_Committers) to contribute to Eclipse openPASS. 
+
+## Eclipse openPASS  
+Eclipse openPASS provides a software platform that enables the simulation of traffic scenarios to predict the real-world effectiveness of advanced driver assistance systems or automated driving functions. 
+
+## Developer resources
+
+  * [Working Group Website](https://openpass.eclipse.org/)
+  * [Developer Website](https://projects.eclipse.org/projects/automotive.openpass)
+  * [Development process](https://gitlab.eclipse.org/groups/eclipse/openpass/-/wikis/home)
+  * Mailing list: Join our [developer list](httphttps://projects.eclipse.org/projects/automotive.openpass/contact)
+  * Bugs can be reported in [GitLab](https://gitlab.eclipse.org/groups/eclipse/openpass/-/issues/?sort=updated_desc&state=opened&first_page_size=100) by anybody who owns an Eclipse account. Please use type “Incident”
+  * [Documentation](https://openpass.eclipse.org/resources/#documentation)
+
+## Eclipse Contributor / Committer Agreement
+
+Before your contribution can be accepted by the project team, contributors and committers must sign the correct agreement depending on their status. Please read on how to proceed on: https://www.eclipse.org/legal/committer_process/re-sign/.
+
+For more information, please see the Eclipse Committer Handbook: https://www.eclipse.org/projects/handbook/#resources-commit.
+
+## Contact
+
+Contact the project developers via the project's "dev" list.
+
+* openpass-dev@eclipse.org
+
+## How to contribute
+
+The openPASS source code can be found [here](https://gitlab.eclipse.org/eclipse/openpass/opSimulation).
+
+The branch 'develop' contains the contributions that will be included in the next release. The 'main' branch contains the latest stable release.
+
+A detailed development process can be found [here](https://gitlab.eclipse.org/groups/eclipse/openpass/-/wikis/home).

Jenkinsfile

+/********************************************************************************
+ * Copyright (c) 2023-2024 Bayerische Motoren Werke Aktiengesellschaft (BMW AG)
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0.
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ ********************************************************************************/
+
+pipeline {
+  agent none
+  parameters {
+    booleanParam(name: 'BUILD_DOCKER_IMAGE', defaultValue: false, description: 'Force docker image (re-)build')
+  }
+  options {
+    checkoutToSubdirectory('repo')
+    timeout(time: 4, unit: 'HOURS')
+  }
+  environment {
+    IMAGE_NAME = "eclipseopenpass/ose"
+    REPO_URL = "https://gitlab.eclipse.org/eclipse/openpass/openscenario1_engine.git"
+    DOCKERFILE_PATH = "utils/Dockerfile"
+  }
+  stages {
+    stage('Build docker image or set image tag') {
+      agent {
+            kubernetes {
+              inheritFrom 'openpass-agent-pod-' + env.BUILD_NUMBER
+              yaml """
+apiVersion: v1
+kind: Pod
+spec:
+  containers:
+  - name: ose-build
+    image: eclipseopenpass/ubuntu:base
+    tty: true
+    resources:
+      limits:
+        memory: "16Gi"
+        cpu: "4"
+      requests:
+        memory: "16Gi"
+        cpu: "4"
+  - name: jnlp
+    volumeMounts:
+    - name: volume-known-hosts
+      mountPath: /home/jenkins/.ssh
+  volumes:
+  - name: volume-known-hosts
+    configMap:
+      name: known-hosts
+"""
+            }
+          }
+      stages {
+        stage('Build docker image') {
+          when {
+            expression {
+              return params.BUILD_DOCKER_IMAGE
+            }
+          }
+          steps {
+            script {
+              env.IMAGE_TAG = "testing"
+            }
+            build job: 'Docker-build', parameters: [string(name: 'IMAGE_NAME', value: "${env.IMAGE_NAME}"), 
+                                                    string(name: 'IMAGE_TAG', value:'testing'),
+                                                    string(name: 'REPO_URL', value: "${env.REPO_URL}"), 
+                                                    string(name: 'BRANCH_NAME', value: "${env.GIT_BRANCH}"), 
+                                                    string(name: 'DOCKERFILE_PATH', value: "${env.DOCKERFILE_PATH}")],
+                                       propagate: true
+          }
+        }
+        stage('Set image tag') {
+          when {
+            expression {
+              return !params.BUILD_DOCKER_IMAGE
+            }
+          }
+          steps {
+            script {
+              env.IMAGE_TAG = "testing"
+            }
+          }
+        }
+      }
+    }
+    stage('Linux and Windows build') {
+      parallel {
+        stage('Linux') {
+          agent {
+            kubernetes {
+              inheritFrom 'openscenarioengine_image-agent-pod-' + env.BUILD_NUMBER
+              yaml """
+apiVersion: v1
+kind: Pod
+spec:
+  containers:
+  - name: openscenarioengine-image
+    image: "${env.IMAGE_NAME}:${env.IMAGE_TAG}"
+    tty: true
+    resources:
+      limits:
+        memory: "16Gi"
+        cpu: "4"
+      requests:
+        memory: "16Gi"
+        cpu: "4"
+  - name: jnlp
+    volumeMounts:
+    - name: volume-known-hosts
+      mountPath: /home/jenkins/.ssh
+  volumes:
+  - name: volume-known-hosts
+    configMap:
+      name: known-hosts
+"""
+            }
+          }
+          environment {
+            CONAN_HOME = '/OSE/conan'
+          }
+          stages {
+            stage('Linux: Prepare Dependencies') {
+              steps {
+                  container('openscenarioengine-image') {
+                    sh 'bash repo/utils/ci/scripts/10_build_prepare.sh'
+                    sh 'bash repo/utils/ci/scripts/15_prepare_thirdParty.sh'
+                }
+              }
+            }
+            stage('Linux: Configure build') {
+              steps {
+                  container('openscenarioengine-image') {
+                    sh 'bash repo/utils/ci/scripts/20_configure.sh'
+                }
+              }
+            }
+
+            stage('Linux: Build and install project') {
+              steps {
+                  container('openscenarioengine-image') {
+                    sh 'bash repo/utils/ci/scripts/30_build.sh'
+                }
+              }
+            }
+            stage('Linux: Build and run unit tests') {
+              steps {
+                  container('openscenarioengine-image') {
+                    sh 'bash repo/utils/ci/scripts/40_unit_tests.sh'
+                }
+              }
+            }
+          }
+        }
+        stage('Windows') {
+          agent {
+            label 'windows10'
+          }
+          environment {
+            MSYSTEM = 'MINGW64'
+            CHERE_INVOKING = 'yes'
+            PYTHON_WINDOWS_EXE = 'C:/op/python/python.exe'
+          }
+          stages {
+            stage('Windows: Prepare dependencies') {
+              steps {
+                bat 'subst W: %WORKSPACE%'
+                dir('W:/') {
+                  bat 'C:\\op\\msys64\\usr\\bin\\bash -lc repo/utils/ci/scripts/10_build_prepare.sh'
+                  bat 'C:\\op\\msys64\\usr\\bin\\bash -lc repo/utils/ci/scripts/15_prepare_thirdParty.sh'
+                }
+              }
+            }
+            stage('Windows: Configure build') {
+              steps {
+                dir('W:/') {
+                  bat 'C:\\op\\msys64\\usr\\bin\\bash -lc repo/utils/ci/scripts/20_configure.sh'
+                }
+              }
+            }
+            stage('Windows: Build and install project') {
+              steps {
+                dir('W:/') {
+                  bat 'C:\\op\\msys64\\usr\\bin\\bash -lc repo/utils/ci/scripts/30_build.sh'
+                }
+              }
+            }
+            stage('Windows: Build and run unit tests') {
+              steps {
+                dir('W:/') {
+                  bat 'C:\\op\\msys64\\usr\\bin\\bash -lc repo/utils/ci/scripts/40_unit_tests.sh'
+                }
+              }
+            }
+          }
+          post {
+            always {
+              bat 'subst W: /d'
+            }
+          }
+        }
+      }
+    }
+  }
+}

NOTICE.md

+# Notices for Eclipse openpass
+
+This content is produced and maintained by the Eclipse openpass project.
+
+ * Project home: https://projects.eclipse.org/projects/automotive.openpass
+
+## Copyright
+
+All content is the property of the respective authors or their employers.
+For more information regarding authorship of content, please consult the
+listed source code repository logs.
+
+## Declared Project Licenses
+
+This program and the accompanying materials are made available under the terms
+of the Eclipse Public License v. 2.0 which is available at
+https://www.eclipse.org/legal/epl-2.0/.
+
+SPDX-License-Identifier: EPL-2.0
+
+## Source Code
+
+The project maintains the following source code repositories:
+
+ * https://gitlab.eclipse.org/eclipse/openpass/openscenario1-engine
+
+## Third-party Content
+
+Google Protobuf (3.20.0)
+
+ * License: New BSD License
+ * Source: https://github.com/protocolbuffers/protobuf
+
+Google Test (1.13.0)
+
+ * License: New BSD License
+ * Source: https://github.com/google/googletest
+
+ca-certificates
+ * License: MPL 2.0
+
+libboost-filesystem-dev
+ * License: Boost Software License
+
+libgmock-dev
+ * License: BSD License
+
+libqt5xmlpatterns5-dev
+ * License: LGPL 3.0
+
+openjdk-17-jre
+* License: GPL 2.0 with Classpath Exception
+
+python3
+ * License: Python Software Foundation License
+
+python3-distutils
+ * License: Python Software Foundation License
+
+python3-pip
+ * License: MIT
+
+qtbase5-dev
+ * License: LGPL 3.0
+
+uuid-dev
+ * License: BSD License
+
+Bazel
+ * License: Apache-2.0
+
+Bazel Rules
+ * License: Apache-2.0
+
+Yase
+ * License: EPL 2.0
+
+units_nhh
+ * License: MIT
+
+nlohmann (JSON for Modern C++)
+ * License: MIT License
+ * Homepage: https://nlohmann.github.io/json/
+ * Repository: https://github.com/nlohmann/json
+ * Version: 3.9.1
+
+MantleAPI
+ * License: EPL 2.0
+
+Antlr4Runtime
+ * License: BSD License
+
+pthread
+ * License: LGPL 2.1
+
+OpenSCENARIO API (Parser)
+ * License: Apache-2.0
+
+openpass/stochastics-library
+ * License: EPL 2.0
+
+Boost
+ * License: Boost Software License 1.0
+
+## Cryptography
+
+Content may contain encryption software. The country in which you are currently
+may have restrictions on the import, possession, and use, and/or re-export to
+another country, of encryption software. BEFORE using any encryption software,
+please check the country's laws, regulations and policies concerning the import,
+possession, or use, and re-export of encryption software, to see if this is
+permitted.

SECURITY.md

+<!--- https://www.eclipse.org/security/ --->
+_ISO 27005 defines vulnerability as:
+ "A weakness of an asset or group of assets that can be exploited by one or more threats."_
+
+## The Eclipse Security Team
+
+The Eclipse Security Team provides help and advice to Eclipse projects
+on vulnerability issues and is the first point of contact
+for handling security vulnerabilities.
+Members of the Security Team are committers on Eclipse Projects
+and members of the Eclipse Architecture Council.
+
+Contact the [Eclipse Security Team](mailto:security@eclipse.org).
+
+**Note that, as a matter of policy, the security team does not open attachments.**
+
+## Reporting a Security Vulnerability
+
+Vulnerabilities can be reported either via email to the Eclipse Security Team
+or directly with a project via the Eclipse Foundation's Bugzilla instance.
+
+The general security mailing list address is security@eclipse.org.
+Members of the Eclipse Security Team will receive messages sent to this address.
+This address should be used only for reporting undisclosed vulnerabilities;
+regular issue reports and questions unrelated to vulnerabilities in Eclipse software
+will be ignored.
+Note that this email address is not encrypted.
+
+The community is also encouraged to report vulnerabilities using the
+[Eclipse Foundation's Bugzilla instance](https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Community&component=Vulnerability%20Reports&keywords=security&groups=Security_Advisories).
+Note that you will require an Eclipse Foundation account to create an issue report,
+but by doing so you will be able to participate directly in the resolution of the issue.
+
+Issue reports related to vulnerabilities must be marked as "committers-only",
+either automatically by clicking the provided link, by the reporter,
+or by a committer during the triage process.
+Note that issues marked "committers-only" are visible to all Eclipse committers.
+By default, a "committers-only" issue is also accessible to the reporter
+and individuals explicitly indicated in the "cc" list.
+
+## Disclosure
+
+Disclosure is initially limited to the reporter and all Eclipse Committers,
+but is expanded to include other individuals, and the general public.
+The timing and manner of disclosure is governed by the
+[Eclipse Security Policy](https://www.eclipse.org/security/policy.php).
+
+Publicly disclosed issues are listed on the
+[Disclosed Vulnerabilities Page](https://www.eclipse.org/security/known.php).

doc/architecture.md

+# OpenScenarioEngine Documentation
+
+- [User Guide](../README.md)
+- [Architecture Documentation](#Overview) (this document)
+- [Generator Documentation](generator.md)
+
+# Architecture Documentation
+
+## Overview
+
+Figure 1 shows, how the engine is orchestrated:
+
+![Dependency Graph](figures/dependencies.png)
+
+<small>_Figure 1: Dependency Graph_</small>
+
+For **reading** and **validation** of an OpenSCENARIO description, the engine uses the [**OpenScenarioLib**](https://github.com/RA-Consulting-GmbH/openscenario.api.test/), publicly hosted by [RA-Consulting GmbH](https://www.rac.de/).
+The library interfaces over the **OpenScenario API** and is available for all current OpenSCENARIO 1.X standards.
+
+Aside of this, the engine uses several other openPASS APIs and libraries:
+- [openPASS::MantleAPI](https://gitlab.eclipse.org/eclipse/openpass/mantle-api): The scenario agnostic interface definition is used to interface against the actual environment simulator, such as [openPASS::opSimulation](https://gitlab.eclipse.org/eclipse/openpass/opSimulation). 
+In one direction, the engine implements `mantle_api::IScenarioEngine`, which allows to control the execution (e.g. `Init()` or `Step()`).
+In the other direction it needs access to the `mantle_api::IEnvironment` (e.g. to setup and control entities), implemented by the environment simulator.
+  > As the **MantleAPI** relies on the [nholthaus/units](https://github.com/nholthaus/units) library for physically correct representation of its properties, this dependency is also injected and used by the OpenScenarioEngine.
+- [openPASS::stochastics-library](https://gitlab.eclipse.org/eclipse/openpass/stochastics-library): Responsible for generation and management of random numbers.
+- [openPASS::yase](https://gitlab.eclipse.org/eclipse/openpass/yase): An agnostic behavior tree library, used to represent the interaction between conditions and actions according to the OpenScenario standard. As such it defines and controls what should be triggered when and allows to model the actions and conditions as independent leaves within the tree.
+
+The following shows an (beautified) excerpt of the such an actual behavior tree, taken from the demo example:
+```
+[RUNNING] - ParallelUntil[AllChildrenSucceed][OpenScenarioEngine]
+|  [RUNNING] - Storyboard
+|    [RUNNING] - StopTrigger
+|    |  [RUNNING] - ConditionGroups
+|    |    [RUNNING] - Conditions
+|    |      [RUNNING] - SimulationTimeCondition
+|    [RUNNING] - Child
+|      [RUNNING] - ExecuteOnce
+|      |  [RUNNING] - ParallelUntil[AllChildrenSucceed][InitActions]
+|      |    [RUNNING] - ParallelUntil[AllChildrenSucceed][PrivateActions]
+|      |      [SUCCESS] - TeleportAction
+|      |      [RUNNING] - SpeedAction
+...
+```
+
+## Design Principles
+
+The "ground truth" of [ASAM **OpenSCENARIO**](https://www.asam.net/standards/detail/openscenario/) is an UML model, used to generate the XML specification, documentation, the OpenScenarioLib, and OpenSCENARIO API.
+When reading an OpenSCENARIO description with the parser component of the OpenScenarioLib, it generates objects implementing the OpenSCENARIO API.
+As such the (validated) information of the scenario file is available, but (a) not their logical relation and (b) no business logic.
+
+> Major parts of the engine are generated using a python code generator, which uses the same UML model to generate a full set of concrete business logic objects that inherently know about their relationship.  
+_<small>See also [Generator Documentation](generator.md)</small>_
+
+For example, a `Condition` object holds either a `ByEntityCondition` or a `ByValueCondition` (logical relation).
+Based on the current openSCENARIO description, the engine translates from pure **OpenSCENARIO API** objects into actual nodes of the internal behavior tree.
+Tree generation is described in the following.
+
+### Generation of the Behavior Tree
+
+The heart of the engine is a behavior tree, based on the openPASS project [Yase](https://gitlab.eclipse.org/eclipse/openpass/yase).
+Its responsibility is to handle the **interaction between conditions and actions** according to the standard.
+
+**Example**
+
+> A condition group triggers when all its conditions are satisfied, which means that the corresponding action needs to be executed after a given delay and potentially receive all triggering entities.
+
+Thereby the behavior of the tree is parameterized by the scenario description.
+In the example the user can decide whether **any** or **all** triggering entities lead to satisfaction of the corresponding condition.
+
+**✍️ Principle**
+
+> The engine strives to separate the interaction logic from the final conditions and actions.
+
+The **OpenScenarioLib** is used to interpret each individual XML element of the scenario definition.
+This scenario description is transformed into elements of the behavior tree.
+The following example shows, how the hierarchical and parameterized structure is transformed into the final tree.
+
+**Example**
+
+Suppose that somewhere in the scenario definition, the user specifies a `DistanceCondition`:
+
+```xml
+<ConditionGroup>
+  <Condition name="distance_reached" conditionEdge="rising" delay="0">
+    <ByEntityCondition>
+      <TriggeringEntities triggeringEntitiesRule="all">
+        <EntityRef name="Ego">
+      </TriggeringEntities>
+      <DistanceCondition freespace="True" rule="lessThan" value="5">
+        <Position>
+          <WorldPosition x="100" y="200">
+        </Position>
+      </DistanceCondition>
+    </ByEntityCondition>
+  </Condition>
+<ConditionGroup>
+```
+
+When the conversion reaches the `ConditionGroup`, the function `parse(condition)` is called, which shall act as entry point of this example (see `src/Conversion/OscToNode/ParseCondition.cpp`):
+
+```cpp
+yase::BehaviorNode::Ptr parse(std::shared_ptr<NET_ASAM_OPENSCENARIO::v1_3::ICondition> condition)
+{
+  return std::make_shared<yase::ConditionNode>(
+      condition->GetName(),
+      condition->GetDelay(),
+      OPENSCENARIO::ConvertScenarioConditionEdge(condition->GetConditionEdge()),
+      detail::resolveChildCondition(condition));
+}
+```
+
+According to the standard, the condition needs to interpret the condition edge and a delay.
+As such, its functionality is bundled in a specialized `yase::ConditionNode`.
+
+Two design principles can be derived from this example:
+
+1. **✍️ Principle**
+   > Separation of Interaction
+
+    The implementation is almost completely independent of the underlying condition.
+    All it needs to know is the state of the condition (in terms of yase `success` or `running`).
+    Hence, the underlying condition is again **parsed** (`resolveChildCondition` will be discussed below), which is also the term used within the engine for any translation from the context of an *OpenScenario API type** to a *YASE Node*. Corresponding functions can be found under `src/Conversion/OscToNode`.
+
+2. **✍️ Principle**
+   > Separation of Values
+
+     The implementation should only know only what it needs to do its job.
+     Passing in values of type `NET_ASAM_OPENSCENARIO::*` would violate this principle, as the *OpenScenario API type* generally offers access to more functionality than necessary and would introduce an unnecessary dependency.
+
+     Internal values are either *MantelAPI types* or *C++17 types*, if no other option is available.
+     This also makes testing lot easier.
+
+     The functions for conversion from *OpenScenario API type** to *MantleAPI or C++17 types* are always named `ConvertScenarioTypeToBeConverted()`, here `ConvertScenarioConditionEdge()` and can be found under `src/Conversion/OscToMantle`.
+
+The function `resolveChildCondition` (same source file) shows how the engine makes use of semantic information of the description:
+
+```cpp
+namespace detail
+{
+yase::BehaviorNode::Ptr resolveChildCondition(const std::shared_ptr<NET_ASAM_OPENSCENARIO::v1_3::ICondition>& condition)
+{
+  if (auto element = condition->GetByEntityCondition(); element)
+  {
+    return parse(element);
+  }
+  if (auto element = condition->GetByValueCondition(); element)
+  {
+    return parse(element);
+  }
+  throw std::runtime_error("Corrupted openSCENARIO file: No choice made within std::shared_ptr<NET_ASAM_OPENSCENARIO::v1_3::ICondition>");
+}
+}  // namespace detail
+```
+
+Here, the standard states that a condition is either a `ByValueCondition` or a `ByEntityCondition`, which is why the function simply checks one after the other.
+Depending on the outcome of the checks, **parsing** simply continues with the next layer.
+Note that *specifying no condition* is not allowed and that the engine uses the **OpenScenarioLib** to validate the scenario *before building the tree*.
+So reaching the end of the function is literally an exception:
+
+**✍️ Principle**
+> The engine assumes that the description is complete.
+> If not, exceptions are allowed.
+
+### Handling of Union and List Types
+
+Very often, the standard allow _xor_ (union) or _sequence_ (list) relations within elements the scenario description.
+In the following, some special rules for these types are described:
+
+#### Union Types
+
+Suppose that the user specified a `ByValueCondition`, namely a `SimulationTimeCondition`, as `Condition`.
+As `ByValueCondition`s are just a **union type** without additional information, no intermediate node is generated.
+Instead the result of the next `parse` is directly returned (see `ParseByValueCondition.cpp`).
+In other words `SimulationTimeCondition` will become the direct child `ConditionNode`.
+
+**✍️ Principle**
+> **Skip** tree nodes for **union type**s, if they do not contain additional logic.
+
+#### List Types
+
+For *list type*s, such as `Actions` in the `Event` element, parsing unwraps the individual elements into children of an ``yase::ParallelNode`` (see `gen/Conversion/OscToNode/ParseActions.cpp`):
+
+```cpp
+yase::BehaviorNode::Ptr parse(std::vector<std::shared_ptr<NET_ASAM_OPENSCENARIO::v1_3::IAction>> actions)
+{
+auto node = std::make_shared<yase::ParallelNode>("Actions");
+for (const auto& action : actions)
+{
+    node->addChild(parse(action));
+}
+return node;
+}
+```
+
+**✍️ Principle**
+> Use `ParallelNode`s for **list types**, if they do not contain additional logic.
+
+---
+
+Figure 2 shows both principles at work:
+
+![Tree Structure](figures/init_path.png)
+
+<small>_Figure 2: Init Path_</small>
+
+The list of `InitAction`s is transformed into individual children of the `ParallelNode` _InitActions_.
+Yet, no `Action` node exist as intermediate layer.
+Instead each child is directly specialized to the lowest possible occurrence (_union type_).
+This could be a concrete action, such as an `EnvironmentAction`, or another intermediate node, such as an `EntityAction`.
+
+### Conditions and Actions
+
+Concrete conditions and actions are the leafs of the tree.
+As conditions precede actions, they will be described first.
+
+#### Conditions
+
+When the parsing process reaches a concrete condition, a leaf is instantiated.
+
+In general, `ByEntityCondition`s and `ByValueCondition`s are supported, with `ByEntityCondition`s being an extension of `ByValueCondition`s, also including the management of triggering entities.
+
+Note that interaction (_"who is triggering what"_) is responsibility of the tree.
+This means that for `ByEntityCondition`s, the parsing stage generates an intermediate layer (`AllTriggeringEntitiesNode` or `AnyTriggeringEntitiesNode`), separating the individual triggering entities from each other.
+
+In other words:
+
+**✍️ Principle**
+
+> Conditions do not know about each other and therefore a `ByEntityCondition` only refers to a single triggering entity.
+
+The basic structure of a fictitious `ByEntityCondition` is shown in Figure 3 as an example.
+For a `ByValueCondition`, entity-specific parts can simply be left out.
+
+![Tree Structure](figures/conditions.png)
+
+<small>_Figure 3: Composition of an Condition leaf_</small>
+
+> **Note that this structure is autogenerated by a code generator and only the implementation files should be customized to implement the actual behavior of a condition.**
+
+Condition leaves have two responsibilities:
+1. **Interfacing w.r.t the behavior tree**  
+
+   The entry point of the behavior tree is the `executeTick()` method of the `ActionNode` base.  
+   _⚠️YASE context: Do not to confuse with an openSCENARIO Action._
+
+   The condition node (here `FooCondition`) wraps the result in the `tick()` method, required by the base class.
+
+   The actual implementation (`impl_`) of the condition only returns `true` or `false` and is unaware of the behavior tree, which corresponds to the _Separation of Interaction_ principle (see above).
+   To achieve this, the implementation of a condition obeys the following principle:
+
+   **✍️ Principle**
+   > If an condition is satisfied, its implementation returns `true`.
+
+2. **Instantiation of a concrete implementation**  
+
+   Again, _Separation of Values_ (see according Principle above) is used to make the conditions independent of _OpenScenario API_ datatypes.
+   Each parameter, requested by the standard is transformed into its corresponding _Mantle API (or C++)_ type into a structure called `Values`.
+
+   The conditions base class (here `FooConditionBase`) makes all parameters available to its specialization through a struct named `value`.
+   Thereby, the name of each field follows the name as defined in the openSCENARIO standard, e.g. `freespace` in a `RelativeDistanceCondition` and is accessed within the implementation as follows:
+
+   ```cpp
+   // evaluation of param "freespace" done at initialization
+   if (values.freespace) { /*...*/ }
+   ```
+
+   Whenever possible, conversion is already executed at the instantiation of the implementation.
+   In some cases, as for evaluation of the `Position` _in the very moment_, a parameterless lambda expression is constructed, which can be used as follows:
+
+   ```cpp
+   // evaluation of param "position" done during runtime, via GetPosition()
+   std::optional<mantle_api::Pose> position = values.GetPosition();
+
+   // or simply
+   auto position = values.GetPosition();
+   ```
+
+   **✍️ Principle**
+   > Within an condition, available parameters are accessed via the member `values`.
+
+
+   The conditions base class (here `FooConditionBase`) also bundles all necessary interfaces w.r.t. the environment simulator in a struct `Interfaces` made available by the member `mantle`:
+
+   ```cpp
+   auto& repository = mantle.environment->GetEntityRepository();
+   ```
+
+   **✍️ Principle**
+   > Within an condition, available mantle interfaces are accessed via the member `mantle`.
+
+   To make a `ByEntityCondition` aware of the `triggeringEntity` an additional member is added to the `Values` struct, typically used as follows:
+
+   ```cpp
+   const auto& triggeringEntity = EntityUtils::GetEntityByName(mantle.environment, values.triggeringEntity);
+   ```
+
+   **✍️ Principle**
+   > Within an `ByEntityCondition`, the triggering entity is accessed via the field `values.triggeringEntity`.
+
+
+#### Actions
+
+In general actions are very similar to conditions.
+To explain the differences, a fictitious action shall be used, that follows the fundamental leaf structure shown in Figure 4:
+
+![Tree Structure](figures/actions.png)
+
+<small>_Figure 4: Composition of an Action leaf_</small>
+
+> **Note that this structure is autogenerated by a code generator and only the implementation files should be customized to implement the actual behavior of a condition.**
+
+Action leaves have two responsibilities:
+1. **Interfacing w.r.t the behavior tree**  
+   As conditions, actions are and unaware of the behavior tree.
+   The main difference is that actions use the method `Step()` to report their state and it has to be distinguished whether they are executed immediately or continuously:
+
+   **✍️ Principle**
+   > If an action is done, the implementation returns `true`.  
+     Continuous actions **always** return `false`.
+
+2. **Instantiation of a concrete implementation**  
+    _Separation of Values_ (see according Principle above) also applies to actions and the following principles can be adopted:
+
+   **✍️ Principles**
+   > Within an action, available parameters are accessed via the member `values`.
+
+   > Within an action, available mantle interfaces are accessed via the member `mantle`.
+
+   The main difference is, that if an action has to be applied to a triggering entity, an additional vector `entities` is added to the `Values` struct, typically used as follows:
+
+   ```cpp
+   for (const auto& entity_name : values.entities)
+   {
+     const auto& entity = EntityUtils::GetEntityByName(mantle.environment, entity_name);
+   }
+   ```
+
+   **✍️ Principle**
+   > Within actions interacting with triggering entities, these entities are accessed via the field `values.entities`.
+
+## Logging and error handling
+
+The OpenScenarioEngine uses the log framework provided by the MantleAPI: https://gitlab.eclipse.org/eclipse/openpass/mantle-api/-/blob/master/include/MantleAPI/Common/i_logger.h 
+
+It consists of an ILogger interface class, which is passed to the OpenScenarioEngine on construction and therefore can be implemented outside of the OpenScenarioEngine. The OpenScenarioEngine forwards all log messages to the implementation of ILogger. The implementation of the ILogger interface class can then forward log messages of the OpenScenarioEngine to own logging implementations of a simulator or test framework.
+
+The different log levels defined in the [MantleAPI](https://gitlab.eclipse.org/eclipse/openpass/mantle-api/-/blob/master/include/MantleAPI/Common/i_logger.h#L21) are used by the OpenScenarioEngine in the following way:
+- the logs of the OpenScenario API while reading / parsing and validating the scenario are forwarded with the same log levels (e.g. **warning** when deprecated elements are used, **error** when scenario does not validate against schema) together with a summary of the found warnings and errors
+- for the use-case of scenario execution the OpenScenarioEngine additionally stop execution by **throwing a runtime error**, if there were errors during the parsing and validation of the scenario
+- for the use-case of only scenario validation no runtime error is thrown and it's left to the caller of the validation method how to proceed
+- if features are used in a scenario which are not yet supported by the OpenScenarioEngine, then an **error** is logged and the respective feature is not executed
+- if scenarios contain semantically wrong information the OpenScenarioEngine can currently only detect this upon execution of the feature and therefore also stops the execution by **throwing a runtime error**. In the future semantic checks could also partially be implemented in the OpenScenario API (parser & validator), so semantic errors in scenarios could also be detected in the "validation only" use-case

doc/json_properties/exponential_distribution.json

+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ExponentialDistribution",
+  "type": "object",
+  "properties": {
+      "lowerLimit": {
+          "type": "number",
+          "description": "Lower limit"
+      },
+      "upperLimit": {
+          "type": "number",
+          "description": "Upper limit"
+      },
+      "expectedValue": {
+          "type": "number",
+          "description": "Reciprocal of the rate parameter lambda"
+      }
+  },
+  "required": ["lowerLimit", "upperLimit", "expectedValue"]
+}
\ No newline at end of file

doc/json_properties/gamma_distribution.json

+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "GammaDistribution",
+  "type": "object",
+  "properties": {
+      "lowerLimit": {
+          "type": "number",
+          "description": "Lower limit",
+          "minimum": 0.0
+      },
+      "upperLimit": {
+          "type": "number",
+          "description": "Upper limit",
+          "minimum": 0.0
+      },
+      "expectedValue": {
+          "type": "number",
+          "description": "Expected value (mean) of the distribution, calculated as alpha / beta",
+          "minimum": 0.0
+      },
+      "variance": {
+          "type": "number",
+          "description": "Variance of the distribution, calculated as alpha / beta^2",
+          "minimum": 0.0
+      }
+  },
+  "required": ["lowerLimit", "upperLimit", "expectedValue", "variance"]
+}
\ No newline at end of file

doc/json_properties/lognormal_distribution.json

+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ExponentialDistribution",
+  "type": "object",
+  "properties": {
+      "lowerLimit": {
+          "type": "number",
+          "description": "Lower limit"
+      },
+      "upperLimit": {
+          "type": "number",
+          "description": "Upper limit"
+      },
+      "expectedValue": {
+          "type": "number",
+          "description": "Reciprocal of the rate parameter lambda"
+      }
+  },
+  "required": ["lowerLimit", "upperLimit", "expectedValue"]
+}
\ No newline at end of file

doc/json_properties/normal_distrubution.json

+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "NormalDistribution",
+  "type": "object",
+  "properties": {
+      "lowerLimit": {
+          "type": "number",
+          "description": "Lower limit",
+          "minimum": 0.0
+      },
+      "upperLimit": {
+          "type": "number",
+          "description": "Upper limit",
+          "minimum": 0.0
+      },
+      "expectedValue": {
+          "type": "number",
+          "description": "Expected value",
+          "minimum": 0.0
+      },
+      "variance": {
+          "type": "number",
+          "description": "Variance (square of standard deviation)",
+          "minimum": 0.0
+      }
+  },
+  "required": ["lowerLimit", "upperLimit", "expectedValue", "variance"]
+}
\ No newline at end of file

doc/json_properties/readme.md

+# JSON Property Strings
+
+The OpenSCENARIO standard does not impose strict requirements on the format of custom properties, allowing for flexibility in their definition.
+To facilitate this, the OpenScenarioEngine uses JSON to parse string-type properties into an internal object format.
+This approach enables the definition of complex properties, such as distributions, which can be used within actions.
+For example, a velocity distribution might be defined and used in a `TrafficAreaAction`.
+
+This folder contains JSON schemas for property strings used by the **OpenScenarioEngine**.
+While these schemas are not enforced, they serve as a reference for how to properly define properties, such as distributions, in a way that they are correctly parsed.
+
+## General Usage
+
+```xml
+ <Property name="SomeProp" value="{ 'type': 'InterpretableType', 'value': 'InterpretableString'" />
+```
+
+## Available Distribution Types
+
+- [ExponentialDistribution](./exponential_distribution.json)
+- [ǸormalDistribution](./normal_distribution.json)
+- [GammaDistribution](./gamma_distribution.json)
+- [LogNormalDistribution](./lognormal_distribution.json)
+- [UniformDistribution](./uniform_distribution.json)
+
+**Example**
+
+```xml
+ <Property
+   name="velocity"
+   value="{
+            'type': 'NormalDistribution',
+            'value':
+            {
+              'lowerLimit': 19.265,
+              'upperLimit': 43.685,
+              'expectedValue': 31.475,
+              'variance': 37.271025
+            }
+          }" />
+```