# faisalahmed3301/academic architecture

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

- Interactive diagram: https://gitdiagram.com/faisalahmed3301/academic
- Repository: https://github.com/faisalahmed3301/academic

## Overview

This is a single-script research experiment comparing classical and learned page-replacement policies on a synthetic trace with a deliberate distribution shift. The workflow runs from CLI parameters through workload generation, learned-policy training, policy simulation, and result reporting. The graph separates the experiment’s domain stages and its internal policy/feature layer. The source excerpt is partial, so broader training and reporting links rely on README documentation; no unsampled implementation details are inferred.

Main entry points: [`main.py`](https://github.com/faisalahmed3301/academic/blob/main/main.py) (Experiment runner), [`results/decision_tree_rules.txt`](https://github.com/faisalahmed3301/academic/blob/main/results/decision_tree_rules.txt) (Tree rules), [`results`](https://github.com/faisalahmed3301/academic/tree/main/results) (Result charts), [`results/summary_table.csv`](https://github.com/faisalahmed3301/academic/blob/main/results/summary_table.csv) (Summary table)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workload["Workload design"]
  node_trace["Shifted trace<br/>[main.py]"]
  node_locality["Locality phase<br/>[main.py]"]
  node_bursty["Bursty phase<br/>[main.py]"]
end

subgraph group_learning["Learned policy"]
  node_features["Eviction features<br/>[main.py]"]
  node_oracle["OPT labels<br/>[main.py]"]
  node_tree["Decision tree<br/>[main.py]"]
  node_rules["Tree rules"]
end

subgraph group_evaluation["Evaluation and outputs"]
  node_experiment["Experiment runner<br/>[main.py]"]
  node_policies["Replacement policies<br/>[main.py]"]
  node_metrics["Phase metrics<br/>[main.py]"]
  node_plots["Result charts"]
  node_summary["Summary table<br/>[summary_table.csv]"]
end

node_researcher(("Researcher"))
node_cli["CLI entry<br/>[main.py]"]

node_researcher -->|"runs"| node_cli
node_cli -->|"starts"| node_experiment
node_experiment -->|"generates"| node_trace
node_trace -->|"includes phase"| node_locality
node_trace -->|"includes phase"| node_bursty
node_experiment -->|"trains from"| node_features
node_features -->|"labeled by"| node_oracle
node_experiment -->|"trains"| node_tree
node_tree -->|"uses"| node_features
node_experiment -->|"simulates"| node_policies
node_policies -->|"predicts with"| node_tree
node_experiment -->|"computes"| node_metrics
node_metrics -->|"writes"| node_summary
node_experiment -->|"generates"| node_plots
node_tree -->|"exports"| node_rules

click node_cli "https://github.com/faisalahmed3301/academic/blob/main/main.py"
click node_experiment "https://github.com/faisalahmed3301/academic/blob/main/main.py"
click node_trace "https://github.com/faisalahmed3301/academic/blob/main/main.py"
click node_locality "https://github.com/faisalahmed3301/academic/blob/main/main.py"
click node_bursty "https://github.com/faisalahmed3301/academic/blob/main/main.py"
click node_features "https://github.com/faisalahmed3301/academic/blob/main/main.py"
click node_oracle "https://github.com/faisalahmed3301/academic/blob/main/main.py"
click node_tree "https://github.com/faisalahmed3301/academic/blob/main/main.py"
click node_policies "https://github.com/faisalahmed3301/academic/blob/main/main.py"
click node_metrics "https://github.com/faisalahmed3301/academic/blob/main/main.py"
click node_plots "https://github.com/faisalahmed3301/academic/tree/main/results"
click node_summary "https://github.com/faisalahmed3301/academic/blob/main/results/summary_table.csv"
click node_rules "https://github.com/faisalahmed3301/academic/blob/main/results/decision_tree_rules.txt"

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,node_locality,node_bursty toneBlue
class node_features,node_oracle,node_tree,node_rules toneAmber
class node_experiment,node_policies,node_metrics,node_plots,node_summary toneMint
class node_researcher toneIndigo
class node_cli toneTeal
```

## Components

### Workload design

- [Shifted trace](https://github.com/faisalahmed3301/academic/blob/main/main.py): `main.py`
- [Locality phase](https://github.com/faisalahmed3301/academic/blob/main/main.py): `main.py`
- [Bursty phase](https://github.com/faisalahmed3301/academic/blob/main/main.py): `main.py`

### Learned policy

- [Eviction features](https://github.com/faisalahmed3301/academic/blob/main/main.py): `main.py`
- [OPT labels](https://github.com/faisalahmed3301/academic/blob/main/main.py): `main.py`
- [Decision tree](https://github.com/faisalahmed3301/academic/blob/main/main.py): `main.py`
- [Tree rules](https://github.com/faisalahmed3301/academic/blob/main/results/decision_tree_rules.txt): `results/decision_tree_rules.txt`

### Evaluation and outputs

- [Experiment runner](https://github.com/faisalahmed3301/academic/blob/main/main.py): `main.py`
- [Replacement policies](https://github.com/faisalahmed3301/academic/blob/main/main.py): `main.py`
- [Phase metrics](https://github.com/faisalahmed3301/academic/blob/main/main.py): `main.py`
- [Result charts](https://github.com/faisalahmed3301/academic/tree/main/results): `results`
- [Summary table](https://github.com/faisalahmed3301/academic/blob/main/results/summary_table.csv): `results/summary_table.csv`

### Other components

- **Researcher**
- [CLI entry](https://github.com/faisalahmed3301/academic/blob/main/main.py): `main.py`

## Connections

- Researcher → CLI entry: runs (evidence: `README.md`)
- CLI entry → Experiment runner: starts (evidence: `main.py`)
- Experiment runner → Shifted trace: generates (evidence: `main.py`)
- Shifted trace → Locality phase: includes phase (evidence: `README.md`)
- Shifted trace → Bursty phase: includes phase (evidence: `README.md`)
- Experiment runner → Eviction features: trains from (evidence: `README.md`)
- Eviction features → OPT labels: labeled by (evidence: `main.py`)
- Experiment runner → Decision tree: trains (evidence: `README.md`)
- Decision tree → Eviction features: uses (evidence: `README.md`)
- Experiment runner → Replacement policies: simulates (evidence: `main.py`)
- Replacement policies → Decision tree: predicts with (evidence: `main.py`)
- Experiment runner → Phase metrics: computes (evidence: `README.md`)
- Phase metrics → Summary table: writes (evidence: `README.md`)
- Experiment runner → Result charts: generates (evidence: `README.md`)
- Decision tree → Tree rules: exports (evidence: `main.py`)
