mirror of
https://github.com/velocitatem/PHANTOM.git
synced 2026-05-31 16:43:36 +00:00
76 lines
3.3 KiB
Markdown
76 lines
3.3 KiB
Markdown
# MOS (Money Operating System)
|
||
|
||
Research-grade quote-control simulator for studying dynamic pricing and market making policies.
|
||
The system models pricing as a closed loop of **Quote → Arrival → Execution → Position**, enabling
|
||
controlled experimentation with demand models, inventory constraints, and reward shaping.
|
||
|
||
## Core Loop
|
||
|
||
1. **Quote** – the policy posts prices (one-sided or two-sided depending on the mechanism).
|
||
2. **Arrival** – a population model generates purchase opportunities or market orders.
|
||
3. **Execution** – an execution model decides whether an arrival converts at the quoted price.
|
||
4. **Position** – inventory/position limits censor fills and generate holding/shortage costs.
|
||
5. **Observation & Reward** – censored fills and aggregate metrics are exposed to the agent, while
|
||
objectives turn metrics into a scalar reward.
|
||
|
||
Each stage is pluggable via light-weight protocols so you can swap in alternative mechanisms,
|
||
demand models, or objectives without rewriting the rest of the simulator.
|
||
|
||
## Package Layout
|
||
|
||
| Module | Purpose |
|
||
|-------------------|---------|
|
||
| `lab.outlet` | Core simulation engine, domain types, pricing mechanisms, objectives. |
|
||
| `lab.population` | Demand arrival models, execution probability models, competitor/market dynamics. |
|
||
| `lab.experiments` | Rollout utilities, baseline policies, and off-policy evaluation helpers. |
|
||
| `lab.config` | Convenience factories for preconfigured retail and market-making environments. |
|
||
|
||
## Preconfigured Scenarios
|
||
|
||
### Retail Dynamic Pricing
|
||
- Mechanism: posted prices with margin and delta constraints.
|
||
- Arrivals: browsing sessions with contamination support (scrapers).
|
||
- Execution: elasticity model with competitor cross-effects.
|
||
- Position: inventory tracking with holding and shortage costs.
|
||
- Market: reactive competitor that can trigger price wars.
|
||
- Objective: PnL minus volatility, holding cost, and lost opportunity penalties.
|
||
|
||
```python
|
||
from lab.config import make_retail_platform
|
||
from lab.experiments import rollout, fixed_price_policy
|
||
|
||
platform = make_retail_platform()
|
||
policy = fixed_price_policy(platform.instruments.refs)
|
||
result = rollout(platform, policy, n_steps=100)
|
||
print(result.total_pnl)
|
||
```
|
||
|
||
### Market Making
|
||
- Mechanism: two-sided quoting with bid/ask spreads.
|
||
- Arrivals: Hawkes order flow for clustered demand.
|
||
- Execution: Avellaneda–Stoikov style intensity model.
|
||
- Position: inventory risk limits and quadratic penalty objective.
|
||
- Market: geometric Brownian motion mid-price process.
|
||
- Objective: PnL plus spread capture minus inventory risk.
|
||
|
||
```python
|
||
from lab.config import make_market_making_platform
|
||
from lab.experiments import rollout
|
||
|
||
platform = make_market_making_platform()
|
||
mm_policy = lambda obs, t: (platform.instruments.refs, 1.0)
|
||
result = rollout(platform, mm_policy, n_steps=200, seed=42)
|
||
print(result.total_pnl)
|
||
```
|
||
|
||
## Extending the Simulator
|
||
|
||
- Implement `lab.outlet.protocols.Mechanism` or `ArrivalModel` to introduce new pricing
|
||
domains or demand processes.
|
||
- Compose objectives with `lab.outlet.objectives.factory.make_composite` to study alternate
|
||
reward formulations.
|
||
- Use `lab.experiments.compare_policies` to benchmark candidate policies across multiple
|
||
random seeds.
|
||
|
||
Comprehensive API documentation lives in `lab/docs` (build with `make html`).
|