# pyrddlgym-project/pyrddlgym architecture

> Architecture diagram of the GitHub repository pyrddlgym-project/pyrddlgym, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pyrddlgym-project/pyrddlgym
- Repository: https://github.com/pyrddlgym-project/pyrddlgym

## Overview

Based on our analysis of the file structure and README, the pyRDDLGym project is a Python toolkit that automatically generates OpenAI Gym environments from RDDL description files. It serves as both a parser/compiler for RDDL and as a simulator/visualization framework for dynamic stochastic environments. The architecture is modular, with clearly separated components for parsing, compiling, simulation, visualization, and debugging, and it also provides integration points for various planners and external optimizers (like JaxPlan, GurobiPlan, PROST, and RL toolkits).

##### Main Components
- Environment Loader / Maker: The entry point (via pyRDDLGym.make()) that instantiates an environment from either preloaded domains (via rddlrepository) or custom RDDL files.
- RDDL Parser: Found inside the pyRDDLGym/core/parser directory. This component is responsible for reading RDDL domain and instance files and converting them into internal representations.
- Compiler: Under pyRDDLGym/core/compiler. It takes the parsed RDDL data and builds models (including extracting DBNs and XADDs) which describe transition dynamics.
- Simulation Engine: Located in modules such as pyRDDLGym/core/simulator and pyRDDLGym/core/env.py. This part is responsible for environment interactions (e.g., implementing reset, step, and simulation of episodes).
- Visualizer & Debug Tools: In pyRDDLGym/core/visualizer and pyRDDLGym/core/debug. Responsible for rendering environments (both live and movie recording via MovieGenerator) and logging internal states.
- Policy Handling: Found in pyRDDLGym/core/policy. Provides built-in agents (e.g., RandomAgent) to demonstrate and test environment interactions.
- Server Component (optional): Found in pyRDDLGym/core/server.py, which is used for communication over TCP when running environments in a networked or distributed setup.
- Examples: The example scripts bundled (in pyRDDLGym/examples) show various use cases (for instance, running environments with both automated and explicit interaction).

##### Representing the Relationships and Data Flow
- Optionally, include a branch that integrates with external planning modules (JaxPlan, GurobiPlan, PROST, and RL frameworks) to emphasize the pluggable nature.
- If applicable, include a Server module handling TCP communications (if running as a networked environment).

##### Architectural Patterns and Design Principles
- The system follows a modular design where each core functionality (parsing, compiling, simulation, visualization) is separated into its specialty module.
- Encourage clear separation of concerns, for instance by distinguishing between data processing (parser/compiler) and runtime execution (simulation/visualization).
- The use of subclassing is highlighted in custom visualizer creation (via pyRDDLGym.core.visualizer.viz.BaseViz), suggesting a strategy design pattern for extensibility.
- Dependency injection is used in some components (for example, passing a custom MovieGenerator to the visualizer).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Input & Processing"
        user["User/Client"]:::external
        envLoader["Environment Loader (pyRDDLGym.make())"]:::fileProcessing
        parser["RDDL Parser<br>pyRDDLGym/core/parser"]:::fileProcessing
        compiler["Compiler<br>pyRDDLGym/core/compiler"]:::fileProcessing
    end

    subgraph "Runtime Simulation"
        simulator["Simulation Engine<br>pyRDDLGym/core/simulator & env"]:::simulation
        policy["Policy Handling<br>pyRDDLGym/core/policy"]:::simulation
    end

    subgraph "Visualization & Debug Layer"
        visualizer["Visualizer<br>pyRDDLGym/core/visualizer"]:::ui
        debug["Debug Tools<br>pyRDDLGym/core/debug"]:::ui
    end

    subgraph "External & Optional"
        server["Server Component<br>pyRDDLGym/core/server.py"]:::external
        planner["External Planners<br>JaxPlan,GurobiPlan,PROST,RL_toolkits"]:::external
        examples["Examples<br>pyRDDLGym/examples"]:::external
    end

    user -->|"calls"| envLoader
    envLoader -->|"loads_RDDL"| parser
    parser -->|"parses_to"| compiler
    compiler -->|"builds_model_for"| simulator
    simulator -->|"renders"| visualizer
    simulator -->|"logs"| debug
    simulator -->|"interfaces"| policy
    simulator -->|"communicates"| server
    simulator -->|"integrates_with"| planner
    envLoader -->|"demo_usage"| examples

    classDef fileProcessing fill:#add8e6,stroke:#333,stroke-width:2px;
    classDef simulation fill:#90ee90,stroke:#333,stroke-width:2px;
    classDef ui fill:#fffacd,stroke:#333,stroke-width:2px;
    classDef external fill:#ffcccb,stroke:#333,stroke-width:2px;

    click envLoader "https://github.com/pyrddlgym-project/pyrddlgym/blob/main/pyRDDLGym/registration.py"
    click envLoader "https://github.com/pyrddlgym-project/pyrddlgym/blob/main/pyRDDLGym/__init__.py"
    click parser "https://github.com/pyrddlgym-project/pyrddlgym/tree/main/pyRDDLGym/core/parser/"
    click compiler "https://github.com/pyrddlgym-project/pyrddlgym/tree/main/pyRDDLGym/core/compiler/"
    click simulator "https://github.com/pyrddlgym-project/pyrddlgym/blob/main/pyRDDLGym/core/simulator.py"
    click simulator "https://github.com/pyrddlgym-project/pyrddlgym/blob/main/pyRDDLGym/core/env.py"
    click visualizer "https://github.com/pyrddlgym-project/pyrddlgym/tree/main/pyRDDLGym/core/visualizer/"
    click debug "https://github.com/pyrddlgym-project/pyrddlgym/tree/main/pyRDDLGym/core/debug/"
    click policy "https://github.com/pyrddlgym-project/pyrddlgym/blob/main/pyRDDLGym/core/policy.py"
    click server "https://github.com/pyrddlgym-project/pyrddlgym/blob/main/pyRDDLGym/core/server.py"
    click examples "https://github.com/pyrddlgym-project/pyrddlgym/tree/main/pyRDDLGym/examples/"
```
