# corail-research/seapearl.jl architecture

> Architecture diagram of the GitHub repository corail-research/seapearl.jl, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/corail-research/seapearl.jl
- Repository: https://github.com/corail-research/seapearl.jl

## Overview

SeaPearl is a Julia constraint-programming solver with classic heuristic-driven solving and an RL-driven mode that learns value-selection heuristics while solving generated problem instances. Its documented workflow combines a CP model and search choices with optional RL agents, state representations, rewards, and training/evaluation. The tree also shows substantial parser, constraint, and graph/NN subsystems; their internal connections are not asserted because no source excerpts were provided. Edges below are limited to relationships stated in the README.

Main entry points: [`src/experiment/training.jl`](https://github.com/corail-research/seapearl.jl/blob/master/src/experiment/training.jl) (Training), [`src/CP/valueselection/learning/learnedheuristic.jl`](https://github.com/corail-research/seapearl.jl/blob/master/src/CP/valueselection/learning/learnedheuristic.jl) (Learned Heuristic), [`src/RL/RL.jl`](https://github.com/corail-research/seapearl.jl/blob/master/src/RL/RL.jl) (RL Agent), [`src/RL/representation/representation.jl`](https://github.com/corail-research/seapearl.jl/blob/master/src/RL/representation/representation.jl) (State Representation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cp["Constraint Programming"]
  node_model["CP Model<br/>[model.jl]"]
  node_variables["CP Variables<br/>[variables.jl]"]
  node_constraints["CP Constraints<br/>[constraints.jl]"]
  node_solver["CP Solver<br/>[solver.jl]"]
  node_search["Search Strategies<br/>[strategies.jl]"]
  node_varselect["Variable Heuristics"]
  node_valueselect["Value Heuristics<br/>[valueselection.jl]"]
end

subgraph group_rl["Learning and Representation"]
  node_learned["Learned Heuristic"]
  node_agent["RL Agent<br/>[RL.jl]"]
  node_representation["State Representation<br/>[representation.jl]"]
  node_graph["Featured Graphs<br/>[featuredgraph.jl]"]
  node_nn["Graph Networks<br/>[nn_structures.jl]"]
  node_rewards["Reward Functions<br/>[rewards.jl]"]
end

subgraph group_problems["Problem Inputs"]
  node_generator["Instance Generator<br/>[datagen.jl]"]
  node_problemtypes["Problem Generators"]
end

subgraph group_experiments["Training and Evaluation"]
  node_training["Training<br/>[training.jl]"]
  node_evaluator["Evaluator<br/>[evaluation.jl]"]
  node_metrics["Metrics<br/>[metrics.jl]"]
end

subgraph group_interfaces["Model Interfaces"]
  node_parser["Problem Parser<br/>[parser.jl]"]
end

node_user(("Researcher"))

node_user -->|"declares"| node_varselect
node_user -->|"declares"| node_valueselect
node_user -->|"creates"| node_model
node_user -->|"adds variables"| node_variables
node_user -->|"adds constraints"| node_constraints
node_user -->|"declares"| node_learned
node_user -->|"defines"| node_agent
node_user -->|"may customize"| node_representation
node_user -->|"may customize"| node_rewards
node_user -->|"creates"| node_generator
node_user -->|"launches"| node_training
node_training -->|"uses"| node_generator
node_training -->|"uses"| node_search
node_training -->|"uses"| node_evaluator
node_training -->|"uses"| node_varselect
node_training -->|"trains"| node_learned
node_evaluator -->|"reports"| node_metrics
node_representation -->|"uses graph inputs"| node_graph
node_agent -->|"uses approximator"| node_nn
node_learned -->|"uses"| node_agent

click node_model "https://github.com/corail-research/seapearl.jl/blob/master/src/CP/core/model.jl"
click node_variables "https://github.com/corail-research/seapearl.jl/blob/master/src/CP/variables/variables.jl"
click node_constraints "https://github.com/corail-research/seapearl.jl/blob/master/src/CP/constraints/constraints.jl"
click node_solver "https://github.com/corail-research/seapearl.jl/blob/master/src/CP/core/solver.jl"
click node_search "https://github.com/corail-research/seapearl.jl/blob/master/src/CP/core/search/strategies.jl"
click node_varselect "https://github.com/corail-research/seapearl.jl/blob/master/src/CP/variableselection/variableselection.jl"
click node_valueselect "https://github.com/corail-research/seapearl.jl/blob/master/src/CP/valueselection/valueselection.jl"
click node_learned "https://github.com/corail-research/seapearl.jl/blob/master/src/CP/valueselection/learning/learnedheuristic.jl"
click node_agent "https://github.com/corail-research/seapearl.jl/blob/master/src/RL/RL.jl"
click node_representation "https://github.com/corail-research/seapearl.jl/blob/master/src/RL/representation/representation.jl"
click node_graph "https://github.com/corail-research/seapearl.jl/blob/master/src/RL/utils/featuredgraph/featuredgraph.jl"
click node_nn "https://github.com/corail-research/seapearl.jl/blob/master/src/RL/nn_structures/nn_structures.jl"
click node_rewards "https://github.com/corail-research/seapearl.jl/blob/master/src/CP/valueselection/learning/rewards/rewards.jl"
click node_generator "https://github.com/corail-research/seapearl.jl/blob/master/src/datagen/datagen.jl"
click node_problemtypes "https://github.com/corail-research/seapearl.jl/tree/master/src/datagen"
click node_parser "https://github.com/corail-research/seapearl.jl/blob/master/src/parser/parser.jl"
click node_training "https://github.com/corail-research/seapearl.jl/blob/master/src/experiment/training.jl"
click node_evaluator "https://github.com/corail-research/seapearl.jl/blob/master/src/experiment/evaluation.jl"
click node_metrics "https://github.com/corail-research/seapearl.jl/blob/master/src/experiment/metrics/metrics.jl"

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_model,node_variables,node_constraints,node_solver,node_search,node_varselect,node_valueselect toneBlue
class node_learned,node_agent,node_representation,node_graph,node_nn,node_rewards toneAmber
class node_generator,node_problemtypes toneMint
class node_training,node_evaluator,node_metrics toneRose
class node_parser,node_user toneIndigo
```

## Components

### Constraint Programming

- [CP Model](https://github.com/corail-research/seapearl.jl/blob/master/src/CP/core/model.jl): `src/CP/core/model.jl`
- [CP Variables](https://github.com/corail-research/seapearl.jl/blob/master/src/CP/variables/variables.jl): `src/CP/variables/variables.jl`
- [CP Constraints](https://github.com/corail-research/seapearl.jl/blob/master/src/CP/constraints/constraints.jl): `src/CP/constraints/constraints.jl`
- [CP Solver](https://github.com/corail-research/seapearl.jl/blob/master/src/CP/core/solver.jl): `src/CP/core/solver.jl`
- [Search Strategies](https://github.com/corail-research/seapearl.jl/blob/master/src/CP/core/search/strategies.jl): `src/CP/core/search/strategies.jl`
- [Variable Heuristics](https://github.com/corail-research/seapearl.jl/blob/master/src/CP/variableselection/variableselection.jl): `src/CP/variableselection/variableselection.jl`
- [Value Heuristics](https://github.com/corail-research/seapearl.jl/blob/master/src/CP/valueselection/valueselection.jl): `src/CP/valueselection/valueselection.jl`

### Learning and Representation

- [Learned Heuristic](https://github.com/corail-research/seapearl.jl/blob/master/src/CP/valueselection/learning/learnedheuristic.jl): `src/CP/valueselection/learning/learnedheuristic.jl`
- [RL Agent](https://github.com/corail-research/seapearl.jl/blob/master/src/RL/RL.jl): `src/RL/RL.jl`
- [State Representation](https://github.com/corail-research/seapearl.jl/blob/master/src/RL/representation/representation.jl): `src/RL/representation/representation.jl`
- [Featured Graphs](https://github.com/corail-research/seapearl.jl/blob/master/src/RL/utils/featuredgraph/featuredgraph.jl): `src/RL/utils/featuredgraph/featuredgraph.jl`
- [Graph Networks](https://github.com/corail-research/seapearl.jl/blob/master/src/RL/nn_structures/nn_structures.jl): `src/RL/nn_structures/nn_structures.jl`
- [Reward Functions](https://github.com/corail-research/seapearl.jl/blob/master/src/CP/valueselection/learning/rewards/rewards.jl): `src/CP/valueselection/learning/rewards/rewards.jl`

### Problem Inputs

- [Instance Generator](https://github.com/corail-research/seapearl.jl/blob/master/src/datagen/datagen.jl): `src/datagen/datagen.jl`
- [Problem Generators](https://github.com/corail-research/seapearl.jl/tree/master/src/datagen): `src/datagen`

### Training and Evaluation

- [Training](https://github.com/corail-research/seapearl.jl/blob/master/src/experiment/training.jl): `src/experiment/training.jl`
- [Evaluator](https://github.com/corail-research/seapearl.jl/blob/master/src/experiment/evaluation.jl): `src/experiment/evaluation.jl`
- [Metrics](https://github.com/corail-research/seapearl.jl/blob/master/src/experiment/metrics/metrics.jl): `src/experiment/metrics/metrics.jl`

### Model Interfaces

- [Problem Parser](https://github.com/corail-research/seapearl.jl/blob/master/src/parser/parser.jl): `src/parser/parser.jl`

### Other components

- **Researcher**

## Connections

- Researcher → Variable Heuristics: declares (evidence: `README.md`)
- Researcher → Value Heuristics: declares (evidence: `README.md`)
- Researcher → CP Model: creates (evidence: `README.md`)
- Researcher → CP Variables: adds variables (evidence: `README.md`)
- Researcher → CP Constraints: adds constraints (evidence: `README.md`)
- Researcher → Learned Heuristic: declares (evidence: `README.md`)
- Researcher → RL Agent: defines (evidence: `README.md`)
- Researcher → State Representation: may customize (evidence: `README.md`)
- Researcher → Reward Functions: may customize (evidence: `README.md`)
- Researcher → Instance Generator: creates (evidence: `README.md`)
- Researcher → Training: launches (evidence: `README.md`)
- Training → Instance Generator: uses (evidence: `README.md`)
- Training → Search Strategies: uses (evidence: `README.md`)
- Training → Evaluator: uses (evidence: `README.md`)
- Training → Variable Heuristics: uses (evidence: `README.md`)
- Training → Learned Heuristic: trains (evidence: `README.md`)
- Evaluator → Metrics: reports (evidence: `README.md`)
- State Representation → Featured Graphs: uses graph inputs (evidence: `README.md`)
- RL Agent → Graph Networks: uses approximator (evidence: `README.md`)
- Learned Heuristic → RL Agent: uses (evidence: `README.md`)