# Mean Field Auction Mechanism Design (PyTorch Implementation)

This code provides a PyTorch-based implementation for training and evaluating mechanisms in dynamic mean-field auction environments. It supports both first-order (gradient-based) and zeroth-order (derivative-free) optimization. While this implementation does not use the adjoint method for efficient gradient computation, training is fully implemented using standard PyTorch backpropagation. The codebase includes utilities for evaluating policy and analyzing convergence to the mean-field equilibrium using N-player simulations.

---
## Directory Structure

- `mfg_batched_auction/`
  - `alg/`: Mean-field game algorithms (OMD, Q-function solver)
  - `analysis/`: Plotting utilities and result summarization
  - `env/`: Batched auction environment and transition dynamics
  - `evaluation/`
    - `exploitability.py`: Exploitability evaluation, ppo train
    - `run_n_player_simulation.py`: Runs N-player simulations using learned MFG policy
    - `simulate_n_player.py`: N-player simulation logic
  - `experiments/configs/`: Experiment configuration files
  - `mechanism_design/`: Mechanism definitions and training logic
    - `mechanism.py`: Core class defining the mechanism
    - `train_mechanism.py`: First-order training loop
    - `train_zero_order.py`: Zeroth-order (gradient-free) optimization
- `results/` : Output results for code runned with run_experiment.py
- `submission_experiments/`: Output results for each experiment runned with run_multiple_experiments.py
- `run_experiment.py`: Run a single training experiment
- `run_multiple_experiments.py`: Run multiple seeds (first- or zero-order)
- `run_zero_order_experiment.py`: (Alternative entry point for zero-order)

---

## Requirements

You can install dependencies with:

```bash
pip install -r requirements.txt
```

---

## Running Experiments

### Run a Single Training Experiment

```bash
python run_experiment.py <config_name>
```

### Run Multiple Seeds for an Experiment

```bash
python run_multiple_experiments.py <config_name> <first|zero> [num_runs]
```

### Simulate N-Player Game Using a Trained MFG Policy

```bash
python -m mfg_batched_auction.evaluation.run_n_player_simulation <config_name> [num_trials]
```

### Example Commands

```bash
python run_experiment.py example_exp
python run_multiple_experiments.py example_exp first 5
python python -m mfg_batched_auction.evaluation.run_n_player_simulation example_exp 50
```

---

## Outputs

Results are saved under (when running multiple experiments at once):

```
submission_experiments/<experiment_name>/<first|zero>/seed_<seed>/
```

Each run includes:

* `mechanism_best.pt`: Best model checkpoint
* `summary.csv`: Iteration-level score summary (mean and std)
* `different plots `


Results are saved under (when running with run_experiment or run_zero_order_experiment):

```
results/<first_order|zero_order>/<experiment_name>
```
A run includes

* `mechanism_best.pt`: Best model checkpoint
* `different plots `