README.md

LunaticAI Driver for CARLA-Simulator

The full documentation is hosted online at ReadTheDocs. Click here for the API documentation.

---

This repository offers a modularized rule-based agent system for the CARLA simulator designed to be easily extendable and configurable. Special submodules like the rule system, the configuration system and the information gathering can directly or with slight modifications be used in other projects as stand alone.

If you are familiar with the CARLA simulator, our agent builds up on the standard agents provided by the CARLA developers, but remodels and extends them in many ways. The key changes are:

• Full, dynamic and transparent Configuration, backed by Hydra:
  • Adjust the agent's behavior at runtime.
  • Automatically logged and repeatable experiments.
  • Hierarchically structured configuration allow for coarse and fine-grained changes to configure experiments
  • Backed by schemas that can be optionally enforced for validation and statically provide type-hints and autocompletion.
• Rule System: Customizing the agent's behavior by defining rules and actions.
• Efficient reuse of existing information

Most important Branches

branch	Supporting	notes
main	CARLA 0.9.14+, Python 3.7+ with/without RSS build	Trying to keep it stable
dev/main	CARLA 0.9.14, Python 3.7+ without RSS build. CARLA 0.9.15 Python 3.10 with RSS build	potentially unstable
dev/daniel	Supporting CARLA 0.9.15+, Python 3.10+ with RSS build	nightly

Note: The Leaderboard 2.0 supporting LunaticChallenger, only supports CARLA 0.9.15 and Python 3.10+.

Installation

See the Installation Guide for more details.

Agent Classes

At the core is the LunaticAgent(agents/lunatic_agent.py) which offers full flexibility in terms of rules and actions and how you control it during a custom written game loop.

The LunaticChallenger(agents/leaderboard_agent.py) is a simplified version wrapped version to be compatible with CARLAS's Leaderboard 2.0 interface.

You can look at the workflow diagram at the end of this document to see how the agent system is structured.

Rule and Phase System

Rules

Rules for the agent have three core components: a phase where it can be applied, a condition and lastly an action that is executed depending on the result of the condition.

For example, the following rule will slow down the agent when it is at a junction:

class SlowDownAtIntersectionRule(Rule):
    """
    Slow down the agent when it is at a junction.
    """
    phase = Phase.TURNING_AT_JUNCTION | Phase.BEGIN
    @ConditionFunction
    def condition(self, ctx: Context) -> Hashable:
        return ctx.agent.is_at_junction
    def action(self, ctx: Context):
        ctx.agent.set_target_speed(agent.live_info.target_speed - 10)

For more details look into the Rules documentation.

Phases

The agent system is based on a phase system, which allows to define rules for specific situations. To see which phases are available and how they are defined, see the Phase class in constants.py.

At the beginning (Phase.BEGIN) and end (Phase.END) of a phase associated rules are evaluated and depending on their outcome the agent will perform certain actions.

Configuration

Behavioral aspects of the agent but also the environment and user interface are configured via YAML files. Hydra is used to manage the configuration files and to provide a clean way to access and manage the configuration in a flexible way.

The configuration backend is designed to make coarse and fine-grained changes by using combination of different configs on demand or by adjusting single parameters or blocks via the command line. The configuration files are stored in the conf/ directory.

For more info continue read the Configuration section.

Workflow and Component Diagram of the Agent System

(Click on the image to enlarge it)