How fwrock/hyperbolic-time-chamber works
Project type and purpose
• HTC-Simulator is an open-source, actor-based, multi-agent discrete-event simulation framework written in Scala, using Apache Pekko (Akka).
• It loads simulation configurations (JSON), instantiates and manages actors, orchestrates events over simulated time, supports reporting, snapshot, and distributed execution via Kafka, Cassandra, and Redis.
Top-level structure & architectural patterns
• Top-level files: Dockerfile, build.sbt, shell scripts (CLI entrypoints), application.conf.
• src/main/protobuf: message schemas (entities, events, data models).
• src/main/scala: three main packages:
• core – the simulation engine (HyperbolicTimeChamber, actor managers, event & state machinery, serialization, utilities)
• model – plug-in domains (mobility, supermarket) containing domain-specific actor definitions, entity/state/event classes
• system – runtime services (actor system bootstrap, Kafka broker integration, Cassandra & Redis persistence)
• Config files: application.conf, logback.xml, Docker Compose for local orchestration.
• Architectural patterns:
• Actor Model – all simulation logic is encapsulated in Pekko (Akka) actors.
• Event-driven / discrete-event simulation – TimeManager schedules ticks and dispatches events.
• Layered design – Core engine, domain models, infrastructure services.
• Plugin-style extensibility – new models can be dropped under model/.
Main components & their relationships
A. Configuration & Initialization
• JSON simulation config + actor data files → Config Loader (in Core)
• Protobuf schemas define message contracts → ProtobufSerializer
• build-and-run.sh / docker-compose.yml start the entire stack
B. Core Simulation Engine
• HyperbolicTimeChamber (entry point)
• Manager actors (subclasses of BaseManager):
• LoadDataManager – reads actor definitions, spawns BaseActor instances
• SimulationManager – coordinates start/stop of simulation
• TimeManager – advances simulation time, emits tick events
• SnapshotManager – takes/restores state snapshots
• ReportManager – formats and routes simulation results
• DataFlowManager, DigitalTwinManager, MLManager (in development)
• BaseActor – handles domain events (SpontaneousEvent, ActorInteractionEvent)
C. Domain Model Actors
• model/mobility actors (Bus, Car, TrafficSignal, etc.)
• model/supermarket actors (Client, Cashier, etc.)
• Each actor has associated State, Event, and utility classes
D. Infrastructure / System Services
• Actor System bootstrap – BaseActorSystem
• Message Broker – KafkaPublisher & KafkaSubscriber; PublisherConfiguration / SubscriberConfiguration
• Persistence –
• CassandraEntityManager (via CassandraConnection) for event or state storage
• RedisClientManager for caching or ephemeral coordination
• Reporting backends – CsvReportData, JsonReportData, CassandraReportData
• Input Layer
• Core Simulation Layer
• Domain Model Layer
• Infrastructure Layer
• Input Layer: “JSON Config Files”, “Protobuf Schemas”
• Domain: “Mobility Actors”, “Supermarket Actors”
• Infra: “Kafka Cluster”, “Cassandra Cluster”, “Redis Cache”, “BaseActorSystem”
Interactions & data flows
• TimeManager → emits Tick Events → Manager Actors → dispatch to BaseActors
• BaseActors → generate Events → may be serialized by ProtobufSerializer → published to Kafka → consumed by other nodes (for distributed sim)
• SnapshotManager → writes state to Redis (or Cassandra)
• ReportManager → writes results to Cassandra or CSV/JSON sinks
Important patterns & technologies
• Protobuf message contracts (annotate the link between actors & broker)