Package: commonroad-geometric
Introductioncommonroad-geometricis a Python framework that facilitates deep-learning based research projects in the autonomous driving domain, e.g. related to behavior planning and state representation learning.At its core, it provides a standardized interface for heterogeneous graph representations of traffic scenes using thePyTorch Geometricframework.The package aims to serve as a flexible framework that, without putting restrictions on potential research directions, minimizes the time spent on implementing boilerplate code. Through its object-oriented design with highly flexible and extendable class interfaces, it is meant to be imported viapip installand utilized in a plug-and-play manner.Highlighted featuresA framework forPyTorch Geometric-basedheterogeneous graph data extraction from traffic scenes and road networks supporting user-made feature computers and edge drawers.Built-in functionality for collection and storing of graph-based traffic datasets asPyTorch datasets.Build-in support for both supervised learning tasks as well as reinforcement learning.AOpenGL-basedtraffic renderer with customizable plugins facilitating real-time visualization and debugging (see video above).AnOpenStreetMapscraper offering virtually unlimited access to real-world road networks.An interface to aSUMO-basedtraffic simulator enabling both automated scenario generation, dataset collection as well as closed-loop training of autonomous agents.High-level package architectureGetting startedThe easiest way of getting familiar with the framework is to consult thetutorial directory, which contains a multitude of simple application demos that showcase the intended usage of the package. Also, additional learning resources can be found in the repository'sWikisection.Research guidelines:It is highly recommended to incorporate the package's extendablerendering capabilitiesas an integral part of your development workflow. This allows you to visualize what is going on in your experiment, greatly simplifying debugging efforts.If you ever find yourself in a situation where you have to modify the internals of this package while working on your research project, it probably means that commonroad-geometric is not flexible enough - pleasecreate a corresponding GitLab issue.Design principles and developer guidelines:Frequent use of abstraction classes for a modular and clean framework.Class interfaces should be understandable and well-documented. We use the Google style docstring format across the package (seePyCharm,VSCode).As a general rule, everything should be configurable and externalized through class APIs. While ensuring flexibility, however, make sure to provide reasonable defaults for most things to avoid unnecessary overhead for users.Add tutorial scripts to thetutorials/directory for easy testing, reviewing and showcasing of new functionality.Usetype hintingeverywhere - it enhances readability and makes the IDE developer experience a lot smoother. Performstatic type checkingwithmypy(pip install mypy+/commonroad-geometric$ mypy) for easily discovering inconsistent typing (seePyCharm extension,VS Code extension).Create issues for new tasks with appropriate priority and category labels as well as a corresponding branch.  Create a merge request to the develop branch afterwards.Adhere toPEP8(except linewidths).Use private_attributesand_methodsfor hiding internal implementation details, as well as private_Classesfor helper classes not supposed to be exposed to end users.InstallationThe installation scriptscripts/create-dev-environment.shinstalls the commonroad-geometric package and all its dependencies into a conda environment:Execute the script inside the directory which you want to use for your development environment.Note: make sure that the CUDA versions are compatible with your setup.Related wiki pages:Manual installationTroubleshootingNote: Headless renderingIf you want to export the rendering frames without the animation window popping up, please use the command given below.echo"export PYGLET_HEADLESS=...">>~/.bashrcYou can replace.bashrcwith.zshrc, if you usezshWeights & Biases Integrationcommonroad-geometricoffers a built-inWeights & Biasesintegration for metric tracking of deep learning experiments.Setup guideCreate your account athttps://wandb.ai/.Create your project at Wandb and you should see a quickstart guide for pytorch.Copy theapi keygive in the quickstart guide and set it as the environment variableWANDB_API_KEY.Copy theproject nameand set it as the environment variablePROJECT_NAME.Finally, set theENTITY_NAMEenvironment variable with your username or in the case of service accounts, the name of the configuredservice
account.Dashboard demoHyperparameter optimizationBy default bothWeights & Biases SweepsandOptunaare supported.W&B sweepsYou can run the scriptscripts/sweeps_optimization.shwith the parameters for the script you want to run:./scripts/sweeps_optimization.sh-e"<conda-env-name>"-s"<python-file>"-w"<path-to-sweep-file>"-a"(optional) <command-line-arguments-to-script>"-n"<number-of-runs>"For example:./scripts/sweeps_optimization.sh-ecommonroad-3.8-stutorials/train_geometric_model/run.py-w../sweep_configs/dummy_model.yaml-a"train --model DummyModel --no-render --optimizer wandb --epochs 1"Consult thescripts/sweep.template.yamltemplate for an introduction to configuring the your optimization run.Theentityandprojectname must be set in thesweep.yamlfile.The metric specified in the yaml filemustbe logged to wandb with the exact same string.For demonstration, refer to thetutorials/train_geometric_model/run.pyscript and pass the parameter--optimizer wandbin the script arguments (-a).OptunaFor optuna demonstration, refer to thetutorials/train_geometric_model/run.pyscript.