Add pure-Python market game simulator checks

[RobertFrenken]

Summary

Adds a dependency-free pure-Python simulator for the market game, plus focused checks that validate rule behavior and parity with the stock example houses.

This does not change the HELICS runtime path. The existing market_maker.py, battery.py, and house federates continue to run the official co-simulation. The new simulator provides a fast local path for checking market-game rules, battery constraints, invalid-demand penalties, and expected strategy outcomes without starting HELICS federates.

What Changed

• Added python/market_game/simulation/
  • config.py: market-game constants and demand profiles
  • rules.py: price calculation, battery clamping, and validation helpers
  • simulator.py: 24-hour pure-Python episode runner
• Added simulator documentation:
  • python/market_game/docs/simulation.md
  • python/market_game/simulation/README.md
• Added focused checks:
  • python/market_game/tests/check_simulation.py
  • python/market_game/tests/check_simulation_core.py
  • python/market_game/tests/check_simulation_parity.py
• Updated python/market_game/market_game.md to mention the simulator checks and docs.

Parity Coverage

The parity check verifies the expected 24-hour totals for the stock example houses:

House	Total market load	Total cost	Final battery
FlattenDemandHouse	127.0	$35.4467	7.0
FullCycleHouse	120.0	$47.7467	0.0
PriceAwareHouse	125.0	$21.9533	5.0

Validation

Tested with:

python3 python/market_game/tests/check_simulation.py
python3 python/market_game/tests/check_battery_validation.py
git diff --cached --check

[RobertFrenken]

Note

This is one step towards a series of potential PRs that would range from increased testing up to teams able to train small reinforcement learning (RL) models for the CTF competition. Below is a potential set of incremental PRs.

PR: Baseline Evaluator
Add a small command that runs built-in strategies through the simulator and prints/exports results.

Shape:

python/market_game/simulation/policies.py
python/market_game/simulation/evaluate.py
python/market_game/tests/check_simulation_evaluate.py
python/market_game/docs/simulation.md

Scope:

• move baseline policy classes out of the parity test into reusable code
• add FollowDemand, FlattenDemand, FullCycle, PriceAware

PR: Scenario Configs
Add repeatable scenario definitions.

Shape:

python/market_game/simulation/scenarios.py
python/market_game/simulation/scenario_configs/
  stock.json
  flat.json
  solar.json
  spike.json
python/market_game/tests/check_simulation_scenarios.py
python/market_game/docs/scenarios.md

Scope:

• named demand profiles
• fixed policy populations
• deterministic random seeds
• no RL, no Gym, no training dependencies

PR: Strategy Workbench
Make it easy for users to test one compute_demand(...) strategy locally.

Shape:

python/market_game/simulation/load_policy.py
python/market_game/simulation/run_strategy.py
python/market_game/docs/strategy_testing.md

Scope:

• load a local Python file with compute_demand(...)
• run it against baseline opponents
• report cost, battery, warnings, clamps
• still dependency-free

PR: Lightweight Observation/Feature Helpers
Only if useful after scenarios exist.

Shape:

python/market_game/simulation/features.py
python/market_game/tests/check_simulation_features.py
python/market_game/docs/features.md

Scope:

• price history summaries
• inferred previous average load from price
• distance to price-tier boundaries
• no RL policy training yet

PR: Optional Gym Adapter
This should be explicitly optional.

Shape:

python/market_game/optional/gym_env.py
python/market_game/optional/requirements-gym.txt
python/market_game/docs/gymnasium.md

Scope:

• Gymnasium wrapper around the simulator
• skip tests gracefully if Gymnasium is not installed
• no Ray/RLlib yet

PR: Export/Submission Validator
Useful if this becomes competition-facing.

Shape:

python/market_game/submission/validators.py
python/market_game/submission/example_submission.py
python/market_game/docs/submissions.md
python/market_game/tests/check_submission_validation.py

Scope:

• validate compute_demand(price, hour, battery_charge, demand, price_history)
• reject obvious unsafe imports/side effects if needed
• run 24-hour smoke simulation