# pushpitarahmank-max/os-term-paper architecture

> Architecture diagram of the GitHub repository pushpitarahmank-max/os-term-paper, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pushpitarahmank-max/os-term-paper
- Repository: https://github.com/pushpitarahmank-max/os-term-paper

## Overview

This repository is an experimental study of learning-augmented page replacement. Its principal workflow generates a shifted memory-reference trace, trains eviction predictors from an offline Belady oracle, compares replacement policies in simulation, and reports performance and explanation-calibration results. The graph includes the documented policy families and experiment outputs. Source excerpts establish the main orchestration and explanation calls; some subsystem details are documented in the README rather than shown in sampled implementation.

Main entry points: [`src/simulator.py`](https://github.com/pushpitarahmank-max/os-term-paper/blob/main/src/simulator.py) (Comparative simulation), [`experiments/run_experiments.py`](https://github.com/pushpitarahmank-max/os-term-paper/blob/main/experiments/run_experiments.py) (Experiment runner), [`src/models.py`](https://github.com/pushpitarahmank-max/os-term-paper/blob/main/src/models.py) (Logistic regression), [`src/algorithms.py`](https://github.com/pushpitarahmank-max/os-term-paper/blob/main/src/algorithms.py) (Learned policies)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workload["Workload generation"]
  node_trace_generator["Shifted trace generator<br/>[workload.py]"]
end

subgraph group_prediction["Prediction and policies"]
  node_logistic_model["Logistic regression<br/>[models.py]"]
  node_tree_model["Decision tree<br/>[models.py]"]
  node_classical_policies["FIFO, LRU, Belady<br/>[algorithms.py]"]
  node_learned_policies["Learned policies<br/>[algorithms.py]"]
  node_adaptive_hybrid["Adaptive hybrid<br/>[algorithms.py]"]
end

subgraph group_simulation["Simulation"]
  node_oracle_training["Oracle training data<br/>[simulator.py]"]
  node_simulation_driver["Comparative simulation<br/>[simulator.py]"]
end

subgraph group_analysis["Evaluation and explanations"]
  node_experiment_runner["Experiment runner<br/>[run_experiments.py]"]
  node_explanation_engine["Eviction explanations<br/>[explanations.py]"]
  node_calibration_metrics["Calibration metrics<br/>[explanations.py]"]
  node_experiment_results["Metrics and plots<br/>[run_experiments.py]"]
end

node_experiment_runner -->|"generates traces"| node_trace_generator
node_experiment_runner -->|"runs simulations"| node_simulation_driver
node_simulation_driver -->|"extracts labels"| node_oracle_training
node_simulation_driver -->|"trains and uses"| node_logistic_model
node_simulation_driver -->|"trains and uses"| node_tree_model
node_simulation_driver -->|"compares policies"| node_classical_policies
node_simulation_driver -->|"compares policies"| node_learned_policies
node_simulation_driver -->|"compares policy"| node_adaptive_hybrid
node_learned_policies -->|"scores candidates"| node_logistic_model
node_adaptive_hybrid -->|"scores candidates"| node_logistic_model
node_simulation_driver -->|"generates explanations"| node_explanation_engine
node_simulation_driver -->|"computes calibration"| node_calibration_metrics
node_experiment_runner -->|"writes reports"| node_experiment_results

click node_experiment_runner "https://github.com/pushpitarahmank-max/os-term-paper/blob/main/experiments/run_experiments.py"
click node_trace_generator "https://github.com/pushpitarahmank-max/os-term-paper/blob/main/src/workload.py"
click node_oracle_training "https://github.com/pushpitarahmank-max/os-term-paper/blob/main/src/simulator.py"
click node_logistic_model "https://github.com/pushpitarahmank-max/os-term-paper/blob/main/src/models.py"
click node_tree_model "https://github.com/pushpitarahmank-max/os-term-paper/blob/main/src/models.py"
click node_classical_policies "https://github.com/pushpitarahmank-max/os-term-paper/blob/main/src/algorithms.py"
click node_learned_policies "https://github.com/pushpitarahmank-max/os-term-paper/blob/main/src/algorithms.py"
click node_adaptive_hybrid "https://github.com/pushpitarahmank-max/os-term-paper/blob/main/src/algorithms.py"
click node_simulation_driver "https://github.com/pushpitarahmank-max/os-term-paper/blob/main/src/simulator.py"
click node_explanation_engine "https://github.com/pushpitarahmank-max/os-term-paper/blob/main/src/explanations.py"
click node_calibration_metrics "https://github.com/pushpitarahmank-max/os-term-paper/blob/main/src/explanations.py"
click node_experiment_results "https://github.com/pushpitarahmank-max/os-term-paper/blob/main/experiments/run_experiments.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_trace_generator toneBlue
class node_logistic_model,node_tree_model,node_classical_policies,node_learned_policies,node_adaptive_hybrid toneAmber
class node_oracle_training,node_simulation_driver toneMint
class node_experiment_runner,node_explanation_engine,node_calibration_metrics,node_experiment_results toneRose
```

## Components

### Workload generation

- [Shifted trace generator](https://github.com/pushpitarahmank-max/os-term-paper/blob/main/src/workload.py): `src/workload.py`

### Prediction and policies

- [Logistic regression](https://github.com/pushpitarahmank-max/os-term-paper/blob/main/src/models.py): `src/models.py`
- [Decision tree](https://github.com/pushpitarahmank-max/os-term-paper/blob/main/src/models.py): `src/models.py`
- [FIFO, LRU, Belady](https://github.com/pushpitarahmank-max/os-term-paper/blob/main/src/algorithms.py): `src/algorithms.py`
- [Learned policies](https://github.com/pushpitarahmank-max/os-term-paper/blob/main/src/algorithms.py): `src/algorithms.py`
- [Adaptive hybrid](https://github.com/pushpitarahmank-max/os-term-paper/blob/main/src/algorithms.py): `src/algorithms.py`

### Simulation

- [Oracle training data](https://github.com/pushpitarahmank-max/os-term-paper/blob/main/src/simulator.py): `src/simulator.py`
- [Comparative simulation](https://github.com/pushpitarahmank-max/os-term-paper/blob/main/src/simulator.py): `src/simulator.py`

### Evaluation and explanations

- [Experiment runner](https://github.com/pushpitarahmank-max/os-term-paper/blob/main/experiments/run_experiments.py): `experiments/run_experiments.py`
- [Eviction explanations](https://github.com/pushpitarahmank-max/os-term-paper/blob/main/src/explanations.py): `src/explanations.py`
- [Calibration metrics](https://github.com/pushpitarahmank-max/os-term-paper/blob/main/src/explanations.py): `src/explanations.py`
- [Metrics and plots](https://github.com/pushpitarahmank-max/os-term-paper/blob/main/experiments/run_experiments.py): `experiments/run_experiments.py`

## Connections

- Experiment runner → Shifted trace generator: generates traces (evidence: `experiments/run_experiments.py`)
- Experiment runner → Comparative simulation: runs simulations (evidence: `experiments/run_experiments.py`)
- Comparative simulation → Oracle training data: extracts labels (evidence: `src/simulator.py`)
- Comparative simulation → Logistic regression: trains and uses (evidence: `src/simulator.py`)
- Comparative simulation → Decision tree: trains and uses (evidence: `src/simulator.py`)
- Comparative simulation → FIFO, LRU, Belady: compares policies (evidence: `src/simulator.py`)
- Comparative simulation → Learned policies: compares policies (evidence: `src/simulator.py`)
- Comparative simulation → Adaptive hybrid: compares policy (evidence: `src/simulator.py`)
- Learned policies → Logistic regression: scores candidates (evidence: `src/algorithms.py`)
- Adaptive hybrid → Logistic regression: scores candidates (evidence: `src/algorithms.py`)
- Comparative simulation → Eviction explanations: generates explanations (evidence: `src/simulator.py`)
- Comparative simulation → Calibration metrics: computes calibration (evidence: `src/simulator.py`)
- Experiment runner → Metrics and plots: writes reports (evidence: `experiments/run_experiments.py`)
