ASPEN Repository Guide — Tech Transfer

Section 1

Repository Map

ASPEN is composed of five repositories. The SDK orchestrates the others as git submodules (except the C2 UI, which is standalone).

ASPENSDK/ # Master orchestrator (v1.1.0) ├── src/aspensdk/core/ # Simulation engine │ ├── simulation/ # envs/, managers/ │ ├── objects/ # environment/, robots/ │ ├── utils/ # helpers, coordinate transforms │ ├── acoustics/ # acoustic propagation │ └── rl/ # reinforcement learning ├── src/aspenenvmodels/ # Submodule: ASPENEnvModels ├── src/aspenrobotmodels/ # Submodule: ASPENRobotModels ├── assets/ # Submodule: ASPENAssets (9.5 GB) └── examples/ # Runnable simulation scripts aspen-c2-ui/ # Standalone: React C2 interface ├── src/components/ # UI panels and viewport ├── src/store/ # Zustand state management └── src/api/ # Mock service layer

🎯

ASPENSDK Main Package · v1.1.0

The master orchestrator. Contains the other repos as git submodules and provides the simulation engine, environment management, and RL integration.

Key Paths

src/aspensdk/core/simulation/ Environment loop, step managers

src/aspensdk/core/objects/ Robots, environments, bathymetry, ocean

src/aspensdk/core/utils/ Coordinate transforms, helpers

src/aspensdk/core/acoustics/ Acoustic propagation models

src/aspensdk/core/rl/ Reinforcement learning integration

Entry Point

src/aspensdk/core/simulation/envs/Env.py Start here — the main environment class

🌊

ASPENEnvModels Submodule · src/aspenenvmodels

Environmental data processing. Converts raw bathymetry, ocean model, and atmospheric data into simulation-ready formats (NanoVDB sparse grids).

Key Paths

src/aspenenvmodels/models/bathymetry/ Seafloor terrain processing

src/aspenenvmodels/models/ocean_model/ Hydrodynamic data (currents, temp, salinity)

src/aspenenvmodels/models/atmosphere/ Wind and weather data

Key Utilities

CoordinateUtils.py Geo-to-simulation coordinate transforms

VoxelizeDataUtils.py Data → NanoVDB voxel grid conversion

IOUtils.py File I/O for NetCDF, GeoTIFF, NVDB formats

🤖

ASPENRobotModels Submodule · src/aspenrobotmodels

Vehicle physics, sensors, and control systems. Implements 6DoF dynamics for multiple vehicle types plus 11 sensor models and guidance algorithms.

Physics Models

models/physics/remus100/ REMUS 100 AUV dynamics

models/physics/iver_6DoF/ IVER AUV 6-DOF model

models/physics/blue_rov2/ BlueROV2 thruster model

models/physics/toy_drone/ Simplified test vehicle

Sensors & Control

models/sensors/ 11 sensor types (DVL, CTD, ADCP, sidescan, etc.)

control/ PID controllers, autopilots

guidance/ Waypoint following, path planners

📦

ASPENAssets Submodule · assets/ · 9.5 GB

All data files: vehicle meshes, USD assets, environment datasets (bathymetry NVDB, ocean NVDB), and visualization resources. Tracked with Git LFS.

Vehicle Assets

vehicle_assets/BlueROV/ BlueROV2 meshes and USD

vehicle_assets/REMUS100/ REMUS 100 meshes and USD

vehicle_assets/remus/ Additional REMUS configs

vehicle_assets/IVER/ IVER AUV assets

Environment Data

narr_assets/ Narragansett Bay environment

dabob_assets/ Dabob Bay environment

east_river_assets/ East River environment

puerto_rico_assets/ Puerto Rico trench environment

Visualization

cloud_water_surface_assets/ Water surface rendering, skybox, clouds

🖥

aspen-c2-ui Separate Repo · React 18 + TypeScript

Command and control web interface built with React 18, TypeScript, and deck.gl. Provides mission planning, vehicle monitoring, and environment visualization in the browser.

Key Paths

src/components/TopBar/ Navigation and mode switching

src/components/Viewport/ deck.gl 3D map rendering

src/components/MissionPanel/ Waypoint and mission editing

src/components/EnvironmentPanel/ Env data overlays

src/components/TimelinePanel/ Playback and time scrubbing

State & Data

src/store/ Zustand stores (mission, vehicle, environment)

src/api/ Mock service layer — ready for real backend swap

Section 2

Read These First

Start with these 10 files in order. They'll give you the mental model needed to navigate everything else.

ASPENSDK/README.md

Project overview, installation instructions, and quickstart guide. Gives you the full picture before diving in.
ASPENSDK/GLOBAL_PATHS.yaml

Where all data paths are configured. Every asset, environment, and config file is referenced here. Change a path here and the whole system follows.
examples/Remus_Dabob_Bay_GPU.py

A complete, runnable simulation example. Shows how to configure vehicles, load an environment, and run the sim loop end-to-end.
src/aspensdk/core/simulation/envs/Env.py

The main environment class. This is the entry point for every simulation — creates the World, manages the step loop, and coordinates all subsystems.
src/aspensdk/core/objects/environment/Bathymetry.py

How the seafloor is loaded and queried. Reads NanoVDB grids and provides depth lookups for collision detection and physics.
src/aspensdk/core/objects/environment/OceanModel.py

How ocean data (currents, temperature, salinity) is loaded and queried at any 3D point in the simulation volume.
src/aspensdk/core/objects/robots/OVRobot.py

The vehicle abstraction layer. Wraps physics, sensors, and control into a single object that the simulation manages.
src/aspenrobotmodels/models/physics/remus100/REMUS_physics_manager_GPU.py

GPU-accelerated 6-DOF physics for the REMUS 100. Shows how hydrodynamic forces, buoyancy, and thruster models are computed on-device.
src/aspenrobotmodels/guidance/REMUS_Guidance_GPU.py

Waypoint navigation and path following. Takes a list of waypoints and generates heading/depth/speed commands for the autopilot.
vehicle_configs/ (directory)

YAML configuration files defining vehicle parameters — mass, dimensions, thruster layout, sensor loadout, and control gains. The single source of truth for each vehicle type.

Section 3

Key Patterns

Mental models that will help you understand how the code fits together.

Simulation Loop

Env creates a World, then calls step() each frame to advance physics, update sensors, and collect observations. Everything flows from this loop.

Submodule Architecture

The SDK imports from aspenenvmodels and aspenrobotmodels as Python packages. They are git submodules checked out inside the SDK repo. Edit them in-place; commit in each submodule separately.

Config-Driven Design

Vehicle parameters come from YAML files. Simulation settings come from YAML. Environment paths come from GLOBAL_PATHS.yaml. Change behavior by editing config, not code.

fVDB / NanoVDB Everywhere

Ocean data (currents, temperature, salinity) and bathymetry are stored as NanoVDB sparse voxel grids. These live on the GPU and allow O(1) lookups at any 3D point in the sim volume.

Coordinate System Convention

Physics uses NED (North-East-Down) — positive Z is downward into the ocean. Isaac Sim uses a world-up coordinate system. The SDK negates Z-values when handing off to the renderer. When debugging, always check which frame you're in.

Section 4

How to Make Your First Change

Four common modifications, ranked from easiest to most involved.

Change Waypoints

Edit the YAML config for the mission, or modify the waypoints array directly in the example script (e.g., Remus_Dabob_Bay_GPU.py). Each waypoint is a [lat, lon, depth] tuple. Re-run the simulation to see the new path.

Change Vehicle Count

Modify NUM_VEHICLES in the simulation config or example script. The Env class will spawn that many instances with independent physics. Make sure your GPU has enough memory for the additional vehicles.

Add a New Environment

Process new bathymetry and ocean data through the ASPENEnvModels pipeline. Generate NVDB files for bathymetry and ocean fields. Place output in the assets directory and update GLOBAL_PATHS.yaml with the new paths.

Add a New Sensor

Extend the BaseSensor class in ASPENRobotModels. Implement the measure() method with your sensor physics. Register the new sensor type in SensorLookup.py so the system can instantiate it from config.

Section 5

Configuration Reference

The two most important config files you will interact with, annotated field by field.

GLOBAL_PATHS.yaml
YAML
# ── Master path configuration ──
# Every component reads paths from here. Edit this file to
# point the simulation at different data or environments.

asset_root: "./assets"                   # Root of ASPENAssets submodule

environments:
  dabob_bay:
    bathymetry_nvdb: "dabob_assets/bathy.nvdb"     # Seafloor voxel grid
    ocean_nvdb: "dabob_assets/ocean.nvdb"          # Currents, temp, salinity grid
    origin_lat: 47.803                            # Geo origin latitude (WGS84)
    origin_lon: -122.804                           # Geo origin longitude
    bounds_km: [10, 8]                              # Simulation extent [east, north] km
  narragansett:
    bathymetry_nvdb: "narr_assets/bathy.nvdb"
    ocean_nvdb: "narr_assets/ocean.nvdb"
    origin_lat: 41.49
    origin_lon: -71.42
    bounds_km: [15, 12]

vehicles:
  remus100:
    config: "vehicle_configs/remus100.yaml"       # Vehicle parameter file
    usd_asset: "vehicle_assets/REMUS100/remus.usd"  # 3D mesh for rendering
  bluerov2:
    config: "vehicle_configs/bluerov2.yaml"
    usd_asset: "vehicle_assets/BlueROV/bluerov.usd"

visualization:
  water_surface: "cloud_water_surface_assets/"   # Ocean surface shader assets

vehicle_configs/remus100.yaml
YAML
# ── Vehicle configuration ──
# Defines every parameter for a REMUS 100 AUV instance.
# The physics engine and autopilot read from this file.

vehicle:
  name: "REMUS-100"
  type: "remus100"                       # Maps to physics model class

physical:
  mass_kg: 31.0                            # Dry mass
  length_m: 1.6                            # Hull length
  diameter_m: 0.19                         # Hull diameter
  buoyancy_N: 0.2                          # Net buoyancy (positive = floats)
  max_depth_m: 100                          # Operating depth limit

propulsion:
  max_thrust_N: 12.0                        # Peak propeller thrust
  max_rpm: 1500                              # Propeller speed limit
  thrust_curve: "quadratic"                # Thrust vs RPM relationship

control:
  heading_pid: [2.0, 0.1, 0.5]             # [Kp, Ki, Kd] for heading hold
  depth_pid: [3.0, 0.2, 0.8]               # [Kp, Ki, Kd] for depth hold
  speed_pid: [1.5, 0.05, 0.3]              # [Kp, Ki, Kd] for speed hold

sensors:                                     # Sensor loadout for this vehicle
  - type: "dvl"                              # Doppler Velocity Log
    rate_hz: 5
  - type: "ctd"                              # Conductivity-Temperature-Depth
    rate_hz: 1
  - type: "imu"                              # Inertial Measurement Unit
    rate_hz: 100
  - type: "gps"                              # GPS (surface only)
    rate_hz: 1

guidance:
  waypoint_radius_m: 5.0                   # Distance to mark waypoint reached
  lookahead_m: 20.0                        # Carrot-chase lookahead distance
  default_speed_ms: 1.5                    # Cruise speed between waypoints
  default_depth_m: 10.0                    # Default transit depth