# akavosi/sqep architecture

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

- Interactive diagram: https://gitdiagram.com/akavosi/sqep
- Repository: https://github.com/akavosi/sqep

## Overview

SQEP is a reference implementation for choosing queen activations on a shrinking-survivor n-queens board to minimize cumulative conflicts. A user builds board data from an initial placement, then simulates a trajectory using an activation policy; policies include random-admissible, greedy-degree, and ACG. Exact backward induction supplies an optimal value function for validation, while a separate deterministic p=1 MIP solver returns an activation sequence that can be replayed through the simulator for a cross-check. The README and excerpts document these capabilities; no CLI or service layer is present.

Main entry points: [`src/sqep/sqep_model.py`](https://github.com/akavosi/sqep/blob/main/src/sqep/sqep_model.py) (Conflict Logic), [`src/sqep/sqep_mip.py`](https://github.com/akavosi/sqep/blob/main/src/sqep/sqep_mip.py) (Deterministic MIP), [`src/sqep/sqep_algorithms.py`](https://github.com/akavosi/sqep/blob/main/src/sqep/sqep_algorithms.py) (ACG Policy)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_model["Board and Dynamics"]
  node_placement["Initial Placement<br/>[sqep_model.py]"]
  node_board["Board Data<br/>[sqep_model.py]"]
  node_conflicts["Conflict Logic<br/>[sqep_model.py]"]
  node_trajectory["Trajectory Simulator<br/>[sqep_model.py]"]
end

subgraph group_policies["Activation Policies"]
  node_random_policy["Random Policy<br/>[sqep_model.py]"]
  node_degree_policy["Greedy Degree<br/>[sqep_model.py]"]
  node_acg_policy["ACG Policy<br/>[sqep_algorithms.py]"]
  node_gain["Closed-form Gain<br/>[sqep_algorithms.py]"]
end

subgraph group_optimization["Exact Optimization"]
  node_optimal_values["Optimal Values<br/>[sqep_algorithms.py]"]
  node_optimal_action["Optimal Action<br/>[sqep_algorithms.py]"]
  node_mip["Deterministic MIP<br/>[sqep_mip.py]"]
  node_replay["MIP Replay Check<br/>[sqep_mip.py]"]
end

node_user(("Researcher"))
node_pulp{{"PuLP / CBC"}}

node_user -->|"provides positions"| node_placement
node_placement -->|"builds data"| node_board
node_board -->|"precomputes attacks"| node_conflicts
node_user -->|"runs simulation"| node_trajectory
node_trajectory -->|"queries neighborhood"| node_conflicts
node_trajectory -->|"dispatches policy"| node_random_policy
node_trajectory -->|"dispatches policy"| node_degree_policy
node_trajectory -->|"dispatches policy"| node_acg_policy
node_random_policy -->|"gets admissible actions"| node_conflicts
node_degree_policy -->|"gets neighborhoods"| node_conflicts
node_acg_policy -->|"scores actions"| node_gain
node_gain -->|"evaluates conflicts"| node_conflicts
node_user -->|"requests values"| node_optimal_values
node_optimal_values -->|"evaluates states"| node_conflicts
node_optimal_action -->|"evaluates actions"| node_conflicts
node_user -->|"requests solution"| node_mip
node_mip -->|"uses board data"| node_board
node_mip -->|"solves model"| node_pulp
node_user -->|"requests replay"| node_replay
node_replay -->|"simulates deterministic kills"| node_conflicts

click node_placement "https://github.com/akavosi/sqep/blob/main/src/sqep/sqep_model.py"
click node_board "https://github.com/akavosi/sqep/blob/main/src/sqep/sqep_model.py"
click node_conflicts "https://github.com/akavosi/sqep/blob/main/src/sqep/sqep_model.py"
click node_trajectory "https://github.com/akavosi/sqep/blob/main/src/sqep/sqep_model.py"
click node_random_policy "https://github.com/akavosi/sqep/blob/main/src/sqep/sqep_model.py"
click node_degree_policy "https://github.com/akavosi/sqep/blob/main/src/sqep/sqep_model.py"
click node_acg_policy "https://github.com/akavosi/sqep/blob/main/src/sqep/sqep_algorithms.py"
click node_gain "https://github.com/akavosi/sqep/blob/main/src/sqep/sqep_algorithms.py"
click node_optimal_values "https://github.com/akavosi/sqep/blob/main/src/sqep/sqep_algorithms.py"
click node_optimal_action "https://github.com/akavosi/sqep/blob/main/src/sqep/sqep_algorithms.py"
click node_mip "https://github.com/akavosi/sqep/blob/main/src/sqep/sqep_mip.py"
click node_replay "https://github.com/akavosi/sqep/blob/main/src/sqep/sqep_mip.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_placement,node_board,node_conflicts,node_trajectory toneBlue
class node_random_policy,node_degree_policy,node_acg_policy,node_gain toneAmber
class node_optimal_values,node_optimal_action,node_mip,node_replay toneMint
class node_user,node_pulp toneIndigo
```

## Components

### Board and Dynamics

- [Initial Placement](https://github.com/akavosi/sqep/blob/main/src/sqep/sqep_model.py): `src/sqep/sqep_model.py`
- [Board Data](https://github.com/akavosi/sqep/blob/main/src/sqep/sqep_model.py): `src/sqep/sqep_model.py`
- [Conflict Logic](https://github.com/akavosi/sqep/blob/main/src/sqep/sqep_model.py): `src/sqep/sqep_model.py`
- [Trajectory Simulator](https://github.com/akavosi/sqep/blob/main/src/sqep/sqep_model.py): `src/sqep/sqep_model.py`

### Activation Policies

- [Random Policy](https://github.com/akavosi/sqep/blob/main/src/sqep/sqep_model.py): `src/sqep/sqep_model.py`
- [Greedy Degree](https://github.com/akavosi/sqep/blob/main/src/sqep/sqep_model.py): `src/sqep/sqep_model.py`
- [ACG Policy](https://github.com/akavosi/sqep/blob/main/src/sqep/sqep_algorithms.py): `src/sqep/sqep_algorithms.py`
- [Closed-form Gain](https://github.com/akavosi/sqep/blob/main/src/sqep/sqep_algorithms.py): `src/sqep/sqep_algorithms.py`

### Exact Optimization

- [Optimal Values](https://github.com/akavosi/sqep/blob/main/src/sqep/sqep_algorithms.py): `src/sqep/sqep_algorithms.py`
- [Optimal Action](https://github.com/akavosi/sqep/blob/main/src/sqep/sqep_algorithms.py): `src/sqep/sqep_algorithms.py`
- [Deterministic MIP](https://github.com/akavosi/sqep/blob/main/src/sqep/sqep_mip.py): `src/sqep/sqep_mip.py`
- [MIP Replay Check](https://github.com/akavosi/sqep/blob/main/src/sqep/sqep_mip.py): `src/sqep/sqep_mip.py`

### Other components

- **Researcher**
- **PuLP / CBC**

## Connections

- Researcher → Initial Placement: provides positions (evidence: `README.md`)
- Initial Placement → Board Data: builds data (evidence: `src/sqep/sqep_model.py`)
- Board Data → Conflict Logic: precomputes attacks (evidence: `src/sqep/sqep_model.py`)
- Researcher → Trajectory Simulator: runs simulation (evidence: `README.md`)
- Trajectory Simulator → Conflict Logic: queries neighborhood (evidence: `src/sqep/sqep_model.py`)
- Trajectory Simulator → Random Policy: dispatches policy (evidence: `src/sqep/sqep_model.py`)
- Trajectory Simulator → Greedy Degree: dispatches policy (evidence: `src/sqep/sqep_model.py`)
- Trajectory Simulator → ACG Policy: dispatches policy (evidence: `README.md`)
- Random Policy → Conflict Logic: gets admissible actions (evidence: `src/sqep/sqep_model.py`)
- Greedy Degree → Conflict Logic: gets neighborhoods (evidence: `src/sqep/sqep_model.py`)
- ACG Policy → Closed-form Gain: scores actions (evidence: `src/sqep/sqep_algorithms.py`)
- Closed-form Gain → Conflict Logic: evaluates conflicts (evidence: `src/sqep/sqep_algorithms.py`)
- Researcher → Optimal Values: requests values (evidence: `README.md`)
- Optimal Values → Conflict Logic: evaluates states (evidence: `src/sqep/sqep_algorithms.py`)
- Optimal Action → Conflict Logic: evaluates actions (evidence: `src/sqep/sqep_algorithms.py`)
- Researcher → Deterministic MIP: requests solution (evidence: `README.md`)
- Deterministic MIP → Board Data: uses board data (evidence: `src/sqep/sqep_mip.py`)
- Deterministic MIP → PuLP / CBC: solves model (evidence: `src/sqep/sqep_mip.py`)
- Researcher → MIP Replay Check: requests replay (evidence: `README.md`)
- MIP Replay Check → Conflict Logic: simulates deterministic kills (evidence: `src/sqep/sqep_mip.py`)
