Add market impact trading environments with pluggable cost models

[LRAbbade]

Summary

This PR adds a new meta/env_market_impact/ module with three Gymnasium-compatible trading environments that integrate realistic, nonlinear market impact models. Most open-source RL trading environments assume negligible or fixed transaction costs (typically 10 bps), which causes agents to learn policies that break under real execution. This module provides pluggable cost models grounded in established microstructure theory so that researchers can evaluate how cost assumptions affect agent behavior.

Paper: L. R. Abbade and A. H. R. Costa, "Realistic Market Impact Modeling for Reinforcement Learning Trading Environments," arXiv:2603.29086, 2026. [arXiv]

Environments

Environment	File	Description
MACE Stock Trading	env_mace_stock_trading.py	New long-only env with DSR reward, drawdown penalty, online observation normalization, and train→test state transfer
Margin Trading	env_margin_trader_impact.py	Adapted from Gu et al. (ICAIF '23) — long/short with 2× leverage, margin accounting, and maintenance detection
Portfolio Optimization	env_portfolio_optimization_impact.py	Adapted from Costa & Costa (BWAIF '23) — softmax weight-based rebalancing with log-return reward

Market Impact Models

Model	Description
BaselineImpactModel	Fixed 10 bps fee (the standard assumption in RL trading papers)
SqrtImpactModel	Empirically validated square-root law (Tóth et al. 2011)
ACImpactModel	Almgren-Chriss with permanent + temporary decomposition
OWImpactModel	Obizhaeva-Wang with transient LOB resilience decay

All models inherit from an ImpactModel ABC, track per-symbol permanent impact state with exponential decay, and record full impact history for post-hoc analysis.

Supporting Infrastructure

• market_data.py — Data pipeline: download via FinRL-Meta's DataProcessor, compute volatility/ADV20, cache, and split into train/trade sets
• backtest_config.py — Shared config: BacktestParams dataclass, MODEL_KWARGS, network architecture presets, Optuna parameter reconstruction
• backtest_report_generator.py — Interactive Plotly HTML reports from backtest summary JSON files
• utils.py — Logger, compute_performance_stats() (single source of truth for all metrics)
• example_*.py — Runner scripts for each environment with epoch-by-epoch training and multi-mode evaluation (IS, OOS continued, OOS blank-slate)
• optuna_*.py — Optuna HPO scripts for each environment (TPE + median pruning, objective = OOS Sharpe)

Key Results (NASDAQ-100, $1B initial capital, 2010–2026)

• The cost model materially changes both absolute performance and relative algorithm ranking across all three environments
• Under Almgren-Chriss, agents learn dramatically different behavior: daily costs drop from ~$200k to ~$8k, turnover falls from 19% to 1%
• Algorithm–cost model interactions are environment-specific (e.g., DDPG's OOS Sharpe jumps from −2.1 to 0.3 under AC in margin trading, while SAC's drops from −0.5 to −1.2)
• HPO is essential: costs drop up to 82% with tuned parameters

Design Decisions

• Self-contained module: all new code lives under meta/env_market_impact/ with no modifications to existing FinRL-Meta files
• Pluggable architecture: any ImpactModel subclass works with any environment, enabling controlled experiments where only the cost assumption varies
• Backward compatible: the BaselineImpactModel(basis_points=10) reproduces the fixed-fee assumption, so existing workflows are unaffected
• SB3 compatible: all environments produce flat Box observation/action spaces and work with DRLAgent + DummyVecEnv

[BruceYanghy]

Thanks for this substantial contribution — I’m happy to merge it.

This PR adds meaningful new capability to FinRL-Meta by introducing a self-contained meta/env_market_impact/ module with Gymnasium-compatible environments and pluggable nonlinear market impact models. The design is especially strong in three aspects:
1. Practical relevance: it addresses a real gap in open-source RL trading environments, where execution costs are often oversimplified and can lead to unrealistic policies.
2. Clean architecture: the impact-model abstraction is modular and reusable, and the implementation remains backward compatible with existing workflows.
3. Research value: the inclusion of multiple environments, multiple impact models, and supporting evaluation/HPO infrastructure makes this useful not just for benchmarking, but for systematic study of agent–cost model interactions.

I also appreciate that the module is self-contained and does not require intrusive changes to the existing FinRL-Meta codebase.

Overall, this is a strong addition that improves the realism, extensibility, and experimental rigor of the framework. Merging.

Bruce