Skip to main content
AlpaSim uses gRPC for inter-service communication, enabling distributed simulation of autonomous vehicles. The gRPC API is defined using Protocol Buffers and consists of several specialized services.

​
Architecture

The simulation runtime coordinates multiple services via gRPC: 
┌──────────────────┐
│  AlpaSim Runtime │
└────────┬─────────┘
         │
         ├──────► SensorSim Service (rendering)
         ├──────► Traffic Service (background actors)
         ├──────► Physics Service (ground interaction)
         ├──────► Controller Service (vehicle dynamics)
         └──────► Driver Service (ego behavior)

​
Core Services

Controller Service

Vehicle dynamics controller and propagation

Driver Service

Autonomous driving policy and planning

Physics Service

Ground intersection and collision detection

SensorSim Service

Camera and LiDAR rendering

Traffic Service

Background vehicle simulation

​
Common Types

All services share common message types defined in common.proto:

​
Pose

Represents a 3D pose with translation and rotation.
​
vec
Vec3
Translation vector (x, y, z in meters)
​
quat
Quat
Rotation quaternion (w, x, y, z)

​
Trajectory

A sequence of poses over time.
​
poses
PoseAtTime[]
Array of timestamped poses

​
DynamicState

Velocity and acceleration information.
​
angular_velocity
Vec3
Angular velocity (rad/s)
​
linear_velocity
Vec3
Linear velocity (m/s)
​
linear_acceleration
Vec3
Linear acceleration (m/s²)
​
angular_acceleration
Vec3
Angular acceleration (rad/s²)

​
Coordinate Systems

All services follow consistent coordinate frame conventions:
  • Local frame: World/map coordinate system
  • Rig frame: Vehicle body-fixed frame (origin at rear axle center)
  • AABB frame: Bounding box center frame
Transforms are specified as “active transforms” (e.g., local->rig transforms points from local to rig frame).See CONTRIBUTING.md in the source repository for detailed coordinate system documentation.

​
Session Management

Most services support session-based workflows:
  1. Start Session: Initialize service with configuration
  2. Execute Operations: Perform rendering, simulation, etc.
  3. Close Session: Clean up resources
# Example session workflow
status = service.start_session(session_request)
# ... perform operations ...
service.close_session(close_request)

​
Version Compatibility

All services implement get_version() returning:
​
version_id
string
Semantic version (e.g., “0.3.0”)
​
git_hash
string
Git commit hash of the service
​
grpc_api_version
APIVersion
gRPC API version (major, minor, patch)

​
Protocol Buffer Files

Proto definitions are located at: 
src/grpc/alpasim_grpc/v0/
├── common.proto       # Shared types
├── controller.proto   # Vehicle dynamics
├── egodriver.proto    # Autonomous driver
├── physics.proto      # Ground physics
├── sensorsim.proto    # Sensor rendering
└── traffic.proto      # Traffic simulation

​
Code Generation

Generate Python stubs from proto files: 
./setup_local_env.sh  # Compiles protos automatically
Generated code is available in the alpasim_grpc package: 
from alpasim_grpc.v0 import common_pb2
from alpasim_grpc.v0 import controller_pb2_grpc

Build docs developers (and LLMs) love

Get started for freeTalk to us