Skip to content

README.md

Latest commit

 

History

History
201 lines (142 loc) · 4.87 KB

README.md

File metadata and controls

201 lines (142 loc) · 4.87 KB
Raw

ABIDES Rust

A high-performance, Rust-only implementation of an agent-based market simulator for market microstructure research, execution strategy testing, and privacy-preserving federated learning experiments.

Project Summary

This project focuses on building a production-grade simulation core in Rust with deterministic behavior, reproducible experiments, and configurable large-scale multi-agent scenarios.

It is designed to showcase:

  • Systems engineering for event-driven simulation
  • Quant/market microstructure modeling
  • Multi-agent architecture and message protocols
  • Research-oriented experiment design and benchmarking

Why This Is Portfolio-Ready

  • End-to-end discrete-event kernel with deterministic scheduling
  • Rich library of trading and market agents (exchange, MM, execution, RL, ETF arbitrage, PPFL)
  • Realistic simulation scenarios from toy demos to stress-style market environments
  • Reproducible runs with seed control and environment-based configuration
  • Test suite and data/report artifacts for analysis workflows

Tech Stack

  • Rust 2021
  • Key crates: chrono, clap, serde, serde_json, csv, rand, rand_distr, bzip2, sha2, x25519-dalek, serde-pickle

Architecture

  • src/main.rs: CLI entrypoint and simulation orchestration
  • src/kernel.rs: event queue, simulation clock, message dispatch
  • src/message.rs: inter-agent message protocol
  • src/order.rs, src/order_book.rs: order model and matching logic
  • src/trading_agent.rs: shared trading-agent behavior
  • src/config.rs: simulation builders and environment parsing
  • src/oracle.rs: fundamental value oracles (sparse/mean/data/external)
  • src/*_agent.rs: strategy-specific agents

Getting Started

Prerequisites

  • Rust toolchain (rustup, cargo)
  • Latest stable Rust recommended

Setup

git clone <your-repository-url>
cd <your-repository-folder>
cargo check
cargo test

CLI Usage

cargo run -- --help
cargo run -- --config-help

Main options:

  • -c, --config <NAME>: simulation configuration
  • -s, --seed <U64>: global seed
  • -l, --log_dir <DIR>: output log directory
  • -v, --verbose: verbose runtime logs
  • --config-help: list available configs

Available Configurations

Core / Demo

  • sum
  • lob_demo
  • value_noise
  • value_noise_mean
  • value_noise_data
  • sparse_zi_100
  • sparse_zi_1000

Market Simulation

  • random_fund_value
  • random_fund_diverse
  • execution
  • exp_agent_demo
  • impact
  • obi_rmsc02
  • loop_obi
  • qlearning
  • marketreplay
  • parallel

Research Scenarios

  • rmsc01
  • rmsc02
  • rmsc03
  • twoSymbols
  • hist_fund_value
  • hist_fund_diverse
  • ppfl_template
  • ppfl_icaif20

Quick Run Examples

# Kernel sanity check
cargo run -- -c sum

# Execution scenario (TWAP default)
ABIDES_EXECUTION_TRADE=true cargo run -- -c execution

# Execution scenario with VWAP
ABIDES_EXECUTION_STRATEGY=VWAP ABIDES_EXECUTION_TRADE=true cargo run -- -c execution

# Historical fundamentals from external .bz2 source
ABIDES_HIST_FUND_FILE=data/synthetic_fundamental.bz2 cargo run -- -c hist_fund_value

# PPFL template scenario
cargo run -- -c ppfl_template

Environment Configuration

Scenarios are controlled through ABIDES_* environment variables.

Common groups:

  • ABIDES_TICKER
  • ABIDES_HIST_FUND_FILE
  • ABIDES_EXECUTION_*
  • ABIDES_EXP_AGENT_*
  • ABIDES_RMSC01_*, ABIDES_RMSC02_*, ABIDES_RMSC03_*
  • ABIDES_PPFL_*
  • ABIDES_QLEARNING_*
  • ABIDES_TWOSYMBOLS_*

To extract the complete, source-of-truth list from code:

rg -o "ABIDES_[A-Z0-9_]+" src/config.rs src/main.rs src/ppfl_client_agent.rs src/ppfl_service_agent.rs | sort -u

Output Artifacts

Primary outputs:

  • Run logs under log/ (or --log_dir)
  • Analysis/result files under results/

PPFL artifacts:

  • results/all_results.csv
  • results/timing_log.csv
  • results/collusion_weights.csv (when enabled)
  • results/collusion_selected_noise.csv (when enabled)
  • results/collusion_consensus.csv (when enabled)

Data / Oracle Support

ExternalFileOracle supports:

  • Native CSV
  • Native .bz2 CSV
  • Native .bz2 pandas-Series pickle decoding

Current limitation:

  • pandas DataFrame pickle support is not yet available in Rust-only mode.

Quality & Validation

cargo fmt
cargo check
cargo test

Reproducibility

  • Explicit run seeds via --seed
  • Deterministic-friendly configuration model
  • Runtime parameters centralized in src/config.rs

Current Limitations

  • Some scenarios remain compatibility-first relative to historical implementations.
  • External pickle support is currently focused on pandas Series.

Roadmap

  • Add pandas DataFrame pickle support in the external oracle loader
  • Expand benchmark and performance reporting pipeline
  • Increase test coverage for long-horizon, high-agent-count scenarios

License

BSD-3-Clause. See LICENSE.txt.