How nico1as/gym-jsbsim works
Main Components
• Gym Environment Wrapper – The central component that implements the OpenAI Gym interface. This wraps around JSBSim’s simulation and maps its state and action vectors into Gym’s observations and actions. (Found in gym_jsbsim, specifically files like jsbsim_env.py, task.py, and individual environment definitions in gym_jsbsim/envs.)
• Simulation Engine Interface – A component that handles the low-level interaction with the external JSBSim simulator. This includes functions such as set_state(), get_state() and state update hooks. (Realized inside simulation.py and supported by catalogs and utility functions.)
• Task/Environment Definitions – Separate modules defining different tasks: HeadingControl, HeadingAltitude, Taxi, and Taxi with Autopilot. These modules define both the specific observation/action spaces as well as the reward computations, time limits, and termination conditions. (Contained in files such as heading_control_task.py, taxi_control_task.py, etc.)
• Geospatial Data Assets – The “amdb” directory contains shapefiles and related geospatial data used to extract runway paths, taxiway geometry, and aerial features. This enables the Taxi and Taxi Autopilot environments to read and compute distances and angles relative to predefined paths.
• Catalog and Configuration Management – Under gym_jsbsim/catalogs, helper modules (like catalog.py, jsbsim_catalog.py, my_catalog.py) aggregate the aircraft definitions and properties, meaning the system can dynamically load or update simulation parameters.
• Documentation and Examples – The docs and notebooks directories provide insight, tutorials, and test cases (for example, the notebooks show example runs). They are critical for understanding how to set up and experiment with the environments.
• Continuous Integration & Build Pipeline – The .github/workflows folder with its YAML files shows that automatic builds, tests, and version bumps are managed here.
Relationships and Interactions
• Gym Environment acts as the “front door” where an agent interacts with the environment by sending actions and receiving state observations and rewards.
• The Gym wrapper communicates with the Simulation Engine Interface that in turn issues commands to JSBSim. It periodically calls for state updates (e.g., using get_state()) and triggers state saves (e.g., with set_state() for planning algorithms).
• The Task modules decide which state variables to use, compute the reward based on deviations (for heading, altitude, or taxi centerlines) and call simulation actions.
• For taxi tasks, the system also integrates geospatial data from the amdb folder. A helper process reads the shapefiles, calculates distances and angles (d1…d4, a1…a4), and feeds these into the state vector.
• The Catalog modules provide standardized aircraft definitions from XML files found under gym_jsbsim/docs/aircraft.
• The CI/CD process runs tests (located under gym_jsbsim/tests and test_agent.py) and builds documentation and the package itself.
Important Architectural Patterns / Design Principles
• Modular Design: The code is organized by functionality (e.g., simulation, environments, catalogs) which helps maintain separation of concerns and ease of extension (for new tasks, environment types, or aircraft configurations).
• Plugin-like Extensibility: The catalog and documentation structure is designed so that new aircraft definitions or additional simulation features can be integrated without impacting the core Gym interface.
• Configuration and Data-Driven Design: The use of geospatial databases (the amdb directory) and aircraft XML files means the behavior of the taxi and approach tasks is driven by external data.
• Testability: With clear directories for tests and notebooks for experimentation, the architecture supports unit testing and rapid prototyping.
Technologies, Frameworks, and Libraries
• Python and OpenAI Gym – Core language and framework for the environment.
• JSBSim – The open-source flight dynamics model integrated to simulate the physics of aircraft flight.
• Shapely – A geospatial library (as mentioned in the README) used likely for processing the geodata from the amdb files.
• GitHub Actions/Travis CI – For the CI/CD processes running in .github/workflows.
• Standard Python packaging (setup.py, requirements.txt) to manage distribution and dependencies.
Specific Elements
– From “Agent” to “Gym Environment” (action commands).
– From “Gym Environment” to “Simulation Engine” (state update calls, set_state/get_state).
– From “Simulation Engine” back to “Gym Environment” (state and sensor feedback).
– From “Simulation Engine” to “Data Assets” (for taxi waypoint calculations).
– Core simulation logic (JSBSim integration and simulation tasks) vs.
– Data and configuration components (amdb, catalogs, aircraft XML).
– External processes (e.g., CI/CD pipelines).
• Modules for Testing and Documentation to showcase the complete lifecycle of development (from integration to testing and deployment).