# Scripts

This directory is intentionally split into two categories:

- **Main Experiments**: long-running entry points that execute the real VM-scheduling evaluator via `test_baselines.py`.
- **Postprocess / Figures**: fast scripts that only summarize shipped artifacts or regenerate figures from shipped data and hard-coded reference values.

If you want the paper's primary runtime results, start with `python scripts/ijoc_main.py` or `bash scripts/run_ijoc.sh`.
If you only need deterministic tables or figures, use the postprocess scripts below.

## Quickstart Helper

| Script | Purpose | Runs `test_baselines.py`? | Expected cost | Key inputs and outputs |
| --- | --- | --- | --- | --- |
| `scripts/task1_e2e_minimal.sh` | Minimal end-to-end smoke test for the full Stage 1 → Stage 2 pipeline. Uses a stub LLM by default (`LLM_USE_STUB=1`) so no real API key is required. Runs Stage 1 with `--auto_export_function_list 1`, auto-locates the resulting `function_list/` directory, and feeds it to Stage 2 via `--option_miner_function_list_dir`. | No (stub evaluator path; real `test_baselines.py` is not invoked). | Fast with the stub; actual duration scales with `STAGE1_SAMPLE_NUM` and `STAGE2_SAMPLE_NUM` (both default to 1). | Writes Stage 1 samples and `function_list/{ranked_functions.json,pruned_functions.json}` under `${MICO_LOG_ROOT:-./log}/optionMiner/`. Writes Stage 2 logs under `${MICO_LOG_ROOT:-./log}/optionComposer/`. Key env-var overrides: `PYTHON_BIN` (defaults to `python3`), `MICO_LOG_ROOT`, `STAGE1_SAMPLE_NUM`, `STAGE2_SAMPLE_NUM`, `TOP_OPTION_MINER_FUNCS`, `PROCESS_INDEX_LIST`, `SERVER_NUM`. |

## Main Experiments

These are the only scripts in `scripts/` that should be treated as main experiment entry points.
They call `test_baselines.py`, are environment-heavy, and can take a long time to finish.

| Script | Purpose | Runs `test_baselines.py`? | Expected cost | Key inputs and outputs |
| --- | --- | --- | --- | --- |
| `scripts/ijoc_main.py` | Preferred Python entry point for the paper's main results: Table 2 and Figure 7. | Yes, directly. | Slow. It launches multiple real baseline evaluations, so expect a long run and use the evaluator environment that can run `src/optionComposer/implementation/vm/VMAgent_plus/vmagent/test_baselines.py`. | Reads `results/runtime/upper_bound/scenario_results.csv`, `results/runtime/schedrl/schedrl_train_scenarios.csv`, `results/runtime/schedrl/schedrl_test_episodes.csv`, `results/runtime/optionComposer/composer.py`, and `results/runtime/optionMiner/heuristics/`. Prints Table 2 and Figure 7 summaries to the terminal, and saves `figure7_scheduled_length.png` under `scripts/figures/` by default or `${MICO_FIGURES_DIR}` if set. |
| `scripts/run_ijoc.sh` | Shell wrapper around `scripts/ijoc_main.py`. Use this if you prefer a one-line shell entry point. | Yes, indirectly through `scripts/ijoc_main.py`. | Same as above. | Same inputs and outputs as `scripts/ijoc_main.py`. |

## Postprocess / Figures

These scripts do **not** run the expensive baseline evaluator.
They are intended for deterministic table regeneration, result summarization, or figure drawing.
Hard-coded numbers are acceptable here when they are reproducing paper tables or figures from a fixed snapshot.

| Script | Purpose | Runs `test_baselines.py`? | Expected cost | Key inputs and outputs |
| --- | --- | --- | --- | --- |
| `scripts/ijoc_deterministic.py` | Reprints Tables 3-6 from deterministic, hard-coded reference values sourced from the former `results/runtime/reference/*.csv` snapshot. | No. | Fast, usually seconds. | Prints tables to the terminal only. It does not save CSV files by default. |
| `scripts/run_ijoc_det.sh` | Shell wrapper around `scripts/ijoc_deterministic.py`. | No. | Same as above. | Same as `scripts/ijoc_deterministic.py`. |
| `scripts/figure_scripts/run_all_figures.sh` | One-click figure runner for Figure 2, Figure 6, Figure 8, and Figure EC4. Azure-based Figure EC2 and Figure EC3 are optional via `--include-azure`. | No. | Fast for non-Azure figures; Azure figures depend on `--azure-nrows` and local I/O speed. | Writes PNGs to `scripts/figures/` by default or `${MICO_FIGURES_DIR}` if set. Reads repo-shipped datasets and, when Azure figures are enabled, `data/azure/vmtable.csv`. |
| `scripts/figure_scripts/figure_2.py` | Figure 2 dataset statistics from `dataset_clean.csv`: duration over time, VM ratio over time, and request counts over time. | No. | Fast. | Reads `src/optionComposer/vmagent/data/dataset_clean.csv`. Writes PNGs to `scripts/figures/` or `--out-dir`. |
| `scripts/figure_scripts/figure_6.py` | Figure 6 stacked bar chart of scenario VM-size proportions. | No. | Fast. | Uses hard-coded proportions and writes `figure6_scenario.png`. |
| `scripts/figure_scripts/figure_8.py` | Figure 8 hyperparameter sensitivity plots. | No. | Fast. | Uses hard-coded numbers and writes `figure8_sample_length.png` and `figure8_temperature.png`. |
| `scripts/figure_scripts/figure_ec2.py` | Figure EC2 Azure trace request statistics. | No. | Moderate if `--nrows` is large. | Reads `data/azure/vmtable.csv` and writes Azure statistics figures to `scripts/figures/` or `--out-dir`. |
| `scripts/figure_scripts/figure_ec3.py` | Figure EC3 mixed postprocess script: scenario ratios are computed from the Azure trace, while the scheduled-length boxplot uses hard-coded experiment results. | No. | Moderate if `--nrows` is large. | Reads `data/azure/vmtable.csv`, writes `figure_ec3_scenario_azure.png` and `figure_ec3_test_results_50_azure.png`. |
| `scripts/figure_scripts/figure_ec4.py` | Figure EC4 scheduled-length boxplots for two settings. | No. | Fast. | Uses hard-coded scheduled-length results and writes two PNGs under `scripts/figures/` or `--out-dir`. |

## Output and Environment Notes

- Figure scripts are expected to run in the `sf` conda environment. Use `bash scripts/figure_scripts/run_all_figures.sh`, which invokes `conda run -n sf python` by default.
- `MICO_FIGURES_DIR`: overrides the default figure output directory for `scripts/ijoc_main.py` and the figure scripts. If unset, generated figures go to `scripts/figures/`.
- `PYTHON`: optional interpreter override used by `scripts/figure_scripts/run_all_figures.sh`; set it only if you do not want the default `conda run -n sf python`.
- `MPLCONFIGDIR`: optional Matplotlib cache/config directory. `run_all_figures.sh` sets a safe writable default automatically.

Neither `scripts/ijoc_main.py` nor `scripts/ijoc_deterministic.py` requires CLI arguments.
The shell wrappers also ignore extra positional arguments.

## Results Layout

The main runtime artifacts kept in this repository live under `results/runtime/`:

- `results/runtime/optionComposer/composer.py`: the retained MiCo selector artifact passed to `test_baselines.py` via `--priority_filename`.
- `results/runtime/optionMiner/heuristics/`: the retained heuristic functions passed to `test_baselines.py` via `--heuristics_dir`.
- `results/runtime/schedrl/schedrl_train_scenarios.csv`: scenario-level SchedRL results used in Table 2.
- `results/runtime/schedrl/schedrl_test_episodes.csv`: per-episode SchedRL results used in Figure 7.
- `results/runtime/upper_bound/scenario_results.csv`: upper-bound normalization values used when reporting performance ratios.

Generated figures are written to `scripts/figures/` by default.
The scripts in this folder do **not** create a repository-owned `results/tables/` tree by default.
If you want to save terminal tables locally, prefer an external path such as `${MICO_TABLES_DIR:-/tmp/clean_mico_results/tables}` rather than committing more generated files into the repository.

## Guardrails For Large Data

`data/azure/vmtable.csv` is intentionally kept out of Git because it can be very large. Before publishing or pushing changes, it is worth running:

```bash
git ls-files --error-unmatch data/azure/vmtable.csv
```

That command should fail. If it succeeds, the Azure trace has been staged or tracked by mistake and should be removed from the index before release.

## Why Only Main Results Are Stored

Full search, training, and evaluator runs are expensive and slow.
To keep the artifact lightweight while preserving reproducibility of the main conclusions:

- the repository keeps the critical runtime artifacts needed by the main MiCo baseline runs under `results/runtime/`;
- the expensive paper entry point is exposed explicitly as `scripts/ijoc_main.py`;
- the remaining tables and figures are regenerated by lightweight postprocess scripts, often from shipped data or fixed reference values, instead of versioning every intermediate CSV or trace.

In short: the repository stores the main artifacts that are costly to recompute, and expects the rest to be regenerated from scripts when needed.

## Missing Heuristic Outputs

Some historical heuristic outputs referenced by older experiment logs are missing in this snapshot.
Those files were lost after a machine failure/reset and a later disk format, so `results/runtime/optionMiner/heuristics/` should be understood as a retained subset rather than a complete archive of every historical candidate.

The important part for reproducibility is that the repository still includes the key artifacts needed for the main MiCo runs:

- `results/runtime/optionComposer/composer.py`
- `results/runtime/optionMiner/heuristics/heuristic_1.py`
- `results/runtime/optionMiner/heuristics/heuristic_2.py`
- `results/runtime/optionMiner/heuristics/heuristic_3.py`
- `results/runtime/optionMiner/heuristics/heuristic_4.py`
