# riadhossain56/cse307-os-term-paper architecture

> Architecture diagram of the GitHub repository riadhossain56/cse307-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/riadhossain56/cse307-os-term-paper
- Repository: https://github.com/riadhossain56/cse307-os-term-paper

## Overview

This is a research simulator for comparing classical and learned page-replacement policies under a synthetic workload shift. The main workflow generates a trace, runs policies through the paging simulator, and evaluates hit ratios; the learned-policy branch trains on warmup telemetry and scores resident pages. An optional explanation branch checks eviction decisions against Belady’s MIN and reports confidence calibration. The experiment runner coordinates benchmarks and writes results. Relationships are limited to calls shown in excerpts or module references in the SOURCE INDEX; unsampled implementation details are not inferred.

Main entry points: [`src/simulator.py`](https://github.com/riadhossain56/cse307-os-term-paper/blob/main/src/simulator.py) (Paging Simulator), [`experiments/run_experiments.py`](https://github.com/riadhossain56/cse307-os-term-paper/blob/main/experiments/run_experiments.py) (Experiment Runner), [`src/learned_policy.py`](https://github.com/riadhossain56/cse307-os-term-paper/blob/main/src/learned_policy.py) (Learned Policy), [`src/workload.py`](https://github.com/riadhossain56/cse307-os-term-paper/blob/main/src/workload.py) (Trace Generator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workload["Workload"]
  node_generator["Trace Generator<br/>[workload.py]"]
end

subgraph group_policies["Replacement Policies"]
  node_classical["Classical Policies"]
  node_learned_policy["Learned Policy<br/>[learned_policy.py]"]
  node_models["NumPy Classifiers<br/>[learned_models.py]"]
end

subgraph group_simulation["Simulation"]
  node_simulator["Paging Simulator<br/>[simulator.py]"]
  node_explanations["Explanation Engine"]
end

subgraph group_evaluation["Evaluation"]
  node_experiment_runner["Experiment Runner<br/>[run_experiments.py]"]
  node_results["Benchmark Results"]
end

node_researcher(("Researcher"))

node_researcher -->|"runs benchmarks"| node_experiment_runner
node_experiment_runner -->|"generates trace"| node_generator
node_experiment_runner -->|"runs policies"| node_simulator
node_generator -->|"provides trace"| node_simulator
node_simulator -->|"dispatches policy"| node_classical
node_simulator -->|"dispatches policy"| node_learned_policy
node_learned_policy -->|"inherits base"| node_classical
node_learned_policy -->|"scores candidates"| node_models
node_simulator -->|"records decisions"| node_explanations
node_simulator -->|"evaluates calibration"| node_explanations
node_experiment_runner -->|"writes metrics"| node_results

click node_generator "https://github.com/riadhossain56/cse307-os-term-paper/blob/main/src/workload.py"
click node_experiment_runner "https://github.com/riadhossain56/cse307-os-term-paper/blob/main/experiments/run_experiments.py"
click node_simulator "https://github.com/riadhossain56/cse307-os-term-paper/blob/main/src/simulator.py"
click node_classical "https://github.com/riadhossain56/cse307-os-term-paper/blob/main/src/classical_policies.py"
click node_learned_policy "https://github.com/riadhossain56/cse307-os-term-paper/blob/main/src/learned_policy.py"
click node_models "https://github.com/riadhossain56/cse307-os-term-paper/blob/main/src/learned_models.py"
click node_explanations "https://github.com/riadhossain56/cse307-os-term-paper/blob/main/src/explanation_engine.py"
click node_results "https://github.com/riadhossain56/cse307-os-term-paper/tree/main/results"

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_generator toneBlue
class node_classical,node_learned_policy,node_models toneAmber
class node_simulator,node_explanations toneMint
class node_experiment_runner,node_results toneRose
class node_researcher toneIndigo
```

## Components

### Workload

- [Trace Generator](https://github.com/riadhossain56/cse307-os-term-paper/blob/main/src/workload.py): `src/workload.py`

### Replacement Policies

- [Classical Policies](https://github.com/riadhossain56/cse307-os-term-paper/blob/main/src/classical_policies.py): `src/classical_policies.py`
- [Learned Policy](https://github.com/riadhossain56/cse307-os-term-paper/blob/main/src/learned_policy.py): `src/learned_policy.py`
- [NumPy Classifiers](https://github.com/riadhossain56/cse307-os-term-paper/blob/main/src/learned_models.py): `src/learned_models.py`

### Simulation

- [Paging Simulator](https://github.com/riadhossain56/cse307-os-term-paper/blob/main/src/simulator.py): `src/simulator.py`
- [Explanation Engine](https://github.com/riadhossain56/cse307-os-term-paper/blob/main/src/explanation_engine.py): `src/explanation_engine.py`

### Evaluation

- [Experiment Runner](https://github.com/riadhossain56/cse307-os-term-paper/blob/main/experiments/run_experiments.py): `experiments/run_experiments.py`
- [Benchmark Results](https://github.com/riadhossain56/cse307-os-term-paper/tree/main/results): `results`

### Other components

- **Researcher**

## Connections

- Researcher → Experiment Runner: runs benchmarks (evidence: `README.md`)
- Experiment Runner → Trace Generator: generates trace (evidence: `experiments/run_experiments.py`)
- Experiment Runner → Paging Simulator: runs policies (evidence: `experiments/run_experiments.py`)
- Trace Generator → Paging Simulator: provides trace (evidence: `experiments/run_experiments.py`)
- Paging Simulator → Classical Policies: dispatches policy (evidence: `src/simulator.py`)
- Paging Simulator → Learned Policy: dispatches policy (evidence: `src/simulator.py`)
- Learned Policy → Classical Policies: inherits base (evidence: `src/learned_policy.py`)
- Learned Policy → NumPy Classifiers: scores candidates (evidence: `src/learned_policy.py`)
- Paging Simulator → Explanation Engine: records decisions (evidence: `src/simulator.py`)
- Paging Simulator → Explanation Engine: evaluates calibration (evidence: `src/simulator.py`)
- Experiment Runner → Benchmark Results: writes metrics (evidence: `experiments/run_experiments.py`)
