# peddrinn/cassotis_optimization architecture

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

- Interactive diagram: https://gitdiagram.com/peddrinn/cassotis_optimization
- Repository: https://github.com/peddrinn/cassotis_optimization

## Overview

Cassotis is a mineral-pile optimization project. Its implemented mono-objective workflow loads a CSV instance, constructs a truck-slot solution, searches it with GVNS, and reports cost or quality objectives subject to feasibility rules. The README also describes multiobjective optimization, multicriteria decision support, and a Streamlit app as pending deliverables; their directories are represented as capabilities, not inferred runtime pipelines. Edges for the experiment runner follow README documentation; unsampled implementation details are omitted.

Main entry points: [`src/cassotis_optimization/algorithms/gvns.py`](https://github.com/peddrinn/cassotis_optimization/blob/main/src/cassotis_optimization/algorithms/gvns.py) (GVNS and VND), [`scripts/run_mono_experiments.py`](https://github.com/peddrinn/cassotis_optimization/blob/main/scripts/run_mono_experiments.py) (Mono experiments), [`src/cassotis_optimization/evaluator.py`](https://github.com/peddrinn/cassotis_optimization/blob/main/src/cassotis_optimization/evaluator.py) (Solution evaluator), [`src/cassotis_optimization/io.py`](https://github.com/peddrinn/cassotis_optimization/blob/main/src/cassotis_optimization/io.py) (Instance loader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_instance["Problem instance"]
  node_csv["Example CSV data"]
  node_loader["Instance loader<br/>[io.py]"]
  node_model["Problem model<br/>[domain.py]"]
  node_validation["Instance validation<br/>[validation.py]"]
end

subgraph group_search["Optimization search"]
  node_experiment["Mono experiments"]
  node_solution["Truck-slot solution<br/>[solution.py]"]
  node_construct["Initial construction<br/>[constructive.py]"]
  node_gvns["GVNS and VND<br/>[gvns.py]"]
  node_neighbors["Neighborhood moves<br/>[vizinhancas.py]"]
  node_shakes["Search perturbations<br/>[perturbacoes.py]"]
end

subgraph group_assessment["Evaluation"]
  node_evaluator["Solution evaluator<br/>[evaluator.py]"]
  node_objectives["Objective selection<br/>[objectives.py]"]
  node_feasibility["Feasibility rule<br/>[feasibility.py]"]
  node_visualization["Result plots<br/>[visualization.py]"]
  node_outputs["Experiment outputs"]
end

subgraph group_decision["Decision support"]
  node_multiobjective["Multiobjective methods"]
  node_mcda["Multicriteria decisions"]
  node_app["Streamlit application"]
end

node_user(("Engineer"))

node_user -->|"runs"| node_experiment
node_experiment -->|"loads"| node_loader
node_csv -->|"provides CSV"| node_loader
node_loader -->|"creates"| node_model
node_experiment -->|"validates"| node_validation
node_experiment -->|"runs search"| node_gvns
node_gvns -->|"initializes with"| node_construct
node_construct -->|"builds"| node_solution
node_gvns -->|"searches with"| node_neighbors
node_gvns -->|"perturbs with"| node_shakes
node_gvns -->|"evaluates candidates"| node_evaluator
node_evaluator -->|"reads instance"| node_model
node_evaluator -->|"scores"| node_solution
node_gvns -->|"selects objective"| node_objectives
node_gvns -->|"ranks feasibility"| node_feasibility
node_experiment -->|"plots results"| node_visualization
node_visualization -->|"evaluates solution"| node_evaluator
node_experiment -->|"writes reports"| node_outputs

click node_experiment "https://github.com/peddrinn/cassotis_optimization/blob/main/scripts/run_mono_experiments.py"
click node_csv "https://github.com/peddrinn/cassotis_optimization/tree/main/data/example_instance"
click node_loader "https://github.com/peddrinn/cassotis_optimization/blob/main/src/cassotis_optimization/io.py"
click node_model "https://github.com/peddrinn/cassotis_optimization/blob/main/src/cassotis_optimization/domain.py"
click node_validation "https://github.com/peddrinn/cassotis_optimization/blob/main/src/cassotis_optimization/validation.py"
click node_solution "https://github.com/peddrinn/cassotis_optimization/blob/main/src/cassotis_optimization/solution.py"
click node_construct "https://github.com/peddrinn/cassotis_optimization/blob/main/src/cassotis_optimization/algorithms/constructive.py"
click node_gvns "https://github.com/peddrinn/cassotis_optimization/blob/main/src/cassotis_optimization/algorithms/gvns.py"
click node_neighbors "https://github.com/peddrinn/cassotis_optimization/blob/main/src/cassotis_optimization/algorithms/vizinhancas.py"
click node_shakes "https://github.com/peddrinn/cassotis_optimization/blob/main/src/cassotis_optimization/algorithms/perturbacoes.py"
click node_evaluator "https://github.com/peddrinn/cassotis_optimization/blob/main/src/cassotis_optimization/evaluator.py"
click node_objectives "https://github.com/peddrinn/cassotis_optimization/blob/main/src/cassotis_optimization/objectives.py"
click node_feasibility "https://github.com/peddrinn/cassotis_optimization/blob/main/src/cassotis_optimization/feasibility.py"
click node_visualization "https://github.com/peddrinn/cassotis_optimization/blob/main/src/cassotis_optimization/visualization.py"
click node_outputs "https://github.com/peddrinn/cassotis_optimization/tree/main/results"
click node_multiobjective "https://github.com/peddrinn/cassotis_optimization/tree/main/src/cassotis_optimization/multiobjective"
click node_mcda "https://github.com/peddrinn/cassotis_optimization/tree/main/src/cassotis_optimization/mcda"
click node_app "https://github.com/peddrinn/cassotis_optimization/tree/main/app"

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_csv,node_loader,node_model,node_validation toneBlue
class node_experiment,node_solution,node_construct,node_gvns,node_neighbors,node_shakes toneAmber
class node_evaluator,node_objectives,node_feasibility,node_visualization,node_outputs toneMint
class node_multiobjective,node_mcda,node_app toneRose
class node_user toneIndigo
```

## Components

### Problem instance

- [Example CSV data](https://github.com/peddrinn/cassotis_optimization/tree/main/data/example_instance): `data/example_instance`
- [Instance loader](https://github.com/peddrinn/cassotis_optimization/blob/main/src/cassotis_optimization/io.py): `src/cassotis_optimization/io.py`
- [Problem model](https://github.com/peddrinn/cassotis_optimization/blob/main/src/cassotis_optimization/domain.py): `src/cassotis_optimization/domain.py`
- [Instance validation](https://github.com/peddrinn/cassotis_optimization/blob/main/src/cassotis_optimization/validation.py): `src/cassotis_optimization/validation.py`

### Optimization search

- [Mono experiments](https://github.com/peddrinn/cassotis_optimization/blob/main/scripts/run_mono_experiments.py): `scripts/run_mono_experiments.py`
- [Truck-slot solution](https://github.com/peddrinn/cassotis_optimization/blob/main/src/cassotis_optimization/solution.py): `src/cassotis_optimization/solution.py`
- [Initial construction](https://github.com/peddrinn/cassotis_optimization/blob/main/src/cassotis_optimization/algorithms/constructive.py): `src/cassotis_optimization/algorithms/constructive.py`
- [GVNS and VND](https://github.com/peddrinn/cassotis_optimization/blob/main/src/cassotis_optimization/algorithms/gvns.py): `src/cassotis_optimization/algorithms/gvns.py`
- [Neighborhood moves](https://github.com/peddrinn/cassotis_optimization/blob/main/src/cassotis_optimization/algorithms/vizinhancas.py): `src/cassotis_optimization/algorithms/vizinhancas.py`
- [Search perturbations](https://github.com/peddrinn/cassotis_optimization/blob/main/src/cassotis_optimization/algorithms/perturbacoes.py): `src/cassotis_optimization/algorithms/perturbacoes.py`

### Evaluation

- [Solution evaluator](https://github.com/peddrinn/cassotis_optimization/blob/main/src/cassotis_optimization/evaluator.py): `src/cassotis_optimization/evaluator.py`
- [Objective selection](https://github.com/peddrinn/cassotis_optimization/blob/main/src/cassotis_optimization/objectives.py): `src/cassotis_optimization/objectives.py`
- [Feasibility rule](https://github.com/peddrinn/cassotis_optimization/blob/main/src/cassotis_optimization/feasibility.py): `src/cassotis_optimization/feasibility.py`
- [Result plots](https://github.com/peddrinn/cassotis_optimization/blob/main/src/cassotis_optimization/visualization.py): `src/cassotis_optimization/visualization.py`
- [Experiment outputs](https://github.com/peddrinn/cassotis_optimization/tree/main/results): `results`

### Decision support

- [Multiobjective methods](https://github.com/peddrinn/cassotis_optimization/tree/main/src/cassotis_optimization/multiobjective): `src/cassotis_optimization/multiobjective`
- [Multicriteria decisions](https://github.com/peddrinn/cassotis_optimization/tree/main/src/cassotis_optimization/mcda): `src/cassotis_optimization/mcda`
- [Streamlit application](https://github.com/peddrinn/cassotis_optimization/tree/main/app): `app`

### Other components

- **Engineer**

## Connections

- Engineer → Mono experiments: runs
- Mono experiments → Instance loader: loads
- Example CSV data → Instance loader: provides CSV
- Instance loader → Problem model: creates
- Mono experiments → Instance validation: validates
- Mono experiments → GVNS and VND: runs search
- GVNS and VND → Initial construction: initializes with
- Initial construction → Truck-slot solution: builds
- GVNS and VND → Neighborhood moves: searches with
- GVNS and VND → Search perturbations: perturbs with
- GVNS and VND → Solution evaluator: evaluates candidates
- Solution evaluator → Problem model: reads instance
- Solution evaluator → Truck-slot solution: scores
- GVNS and VND → Objective selection: selects objective
- GVNS and VND → Feasibility rule: ranks feasibility
- Mono experiments → Result plots: plots results
- Result plots → Solution evaluator: evaluates solution
- Mono experiments → Experiment outputs: writes reports