# polatucha16/python_boids architecture

> Architecture diagram of the GitHub repository polatucha16/python_boids, 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/polatucha16/python_boids
- Repository: https://github.com/polatucha16/python_boids

## Overview

Cucker–Smale is a configurable boid simulation with an interactive Matplotlib interface. The user runs the CLI with a YAML experiment configuration; configuration is parsed and assembled into model components, an initial state, and a simulator, which advances the boids for visualization and interactive control. The graph includes the documented configuration/build stages and major domain and visualization capabilities. Some subsystem links rely on the README or SOURCE INDEX references; unsampled implementation details are not assumed.

Main entry points: [`src/cucker_smale/visualization/matplotlib/mpl_simulation_view.py`](https://github.com/polatucha16/python_boids/blob/master/src/cucker_smale/visualization/matplotlib/mpl_simulation_view.py) (Simulation view), [`src/cucker_smale/config/factories.py`](https://github.com/polatucha16/python_boids/blob/master/src/cucker_smale/config/factories.py) (Object factories), [`src/cucker_smale/domain/dynamics.py`](https://github.com/polatucha16/python_boids/blob/master/src/cucker_smale/domain/dynamics.py) (Dynamics and controls), [`src/cucker_smale/domain/state.py`](https://github.com/polatucha16/python_boids/blob/master/src/cucker_smale/domain/state.py) (Boid state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and configuration"]
  node_cli["CLI<br/>[cli.py]"]
  node_yaml["Experiment YAML<br/>[basic_CS.yaml]"]
  node_loader["Config loader<br/>[load.py]"]
  node_schema["Config schema<br/>[schema.py]"]
  node_factory["Object factories<br/>[factories.py]"]
end

subgraph group_model["Simulation model"]
  node_initial["Initial conditions<br/>[base.py]"]
  node_state["Boid state<br/>[state.py]"]
  node_geometry["Geometry<br/>[geometry.py]"]
  node_communication["Communication rules"]
  node_topology["Communication topology"]
  node_dynamics["Dynamics and controls<br/>[dynamics.py]"]
  node_interaction["Interaction models<br/>[interaction.py]"]
end

subgraph group_runtime["Simulation runtime"]
  node_controller["Experiment controller"]
  node_simulator["Simulator<br/>[simulator.py]"]
  node_integrator["RK45 integrator<br/>[scipy_rk45.py]"]
end

subgraph group_viz["Interactive visualization"]
  node_view["Simulation view"]
  node_layout["Figure layout<br/>[mpl_layout.py]"]
  node_builder["Figure builder<br/>[figure_builder.py]"]
  node_renderer["Boid renderer"]
  node_manipulator["Boid manipulator"]
  node_widgets["Interactive widgets<br/>[wigets.py]"]
end

node_user(("User"))

node_user -->|"runs"| node_cli
node_user -->|"configures"| node_yaml
node_cli -->|"loads config"| node_loader
node_yaml -->|"provides settings"| node_loader
node_loader -->|"parses into"| node_schema
node_cli -->|"creates"| node_controller
node_cli -->|"opens"| node_view
node_controller -->|"builds through"| node_factory
node_factory -->|"constructs"| node_geometry
node_factory -->|"constructs"| node_communication
node_factory -->|"constructs"| node_topology
node_factory -->|"generates"| node_initial
node_initial -->|"creates"| node_state
node_factory -->|"constructs"| node_dynamics
node_dynamics -->|"uses distances"| node_geometry
node_dynamics -->|"uses weights"| node_communication
node_dynamics -->|"uses neighbors"| node_topology
node_dynamics -->|"reads state"| node_state
node_factory -->|"builds"| node_simulator
node_controller -->|"creates"| node_simulator
node_simulator -->|"specialized by"| node_integrator
node_integrator -->|"integrates"| node_dynamics
node_integrator -->|"updates"| node_state
node_view -->|"controls"| node_controller
node_view -->|"advances"| node_simulator
node_view -->|"arranges axes"| node_layout
node_view -->|"assembles figure"| node_builder
node_view -->|"mounts renderer"| node_renderer
node_view -->|"mounts controls"| node_manipulator
node_view -->|"uses widgets"| node_widgets
node_renderer -->|"renders"| node_state
node_manipulator -->|"updates"| node_state
node_interaction -.->|"contributes to model"| node_dynamics

click node_cli "https://github.com/polatucha16/python_boids/blob/master/src/cucker_smale/cli.py"
click node_yaml "https://github.com/polatucha16/python_boids/blob/master/src/cucker_smale/config/basic_CS.yaml"
click node_loader "https://github.com/polatucha16/python_boids/blob/master/src/cucker_smale/config/load.py"
click node_schema "https://github.com/polatucha16/python_boids/blob/master/src/cucker_smale/config/schema.py"
click node_factory "https://github.com/polatucha16/python_boids/blob/master/src/cucker_smale/config/factories.py"
click node_controller "https://github.com/polatucha16/python_boids/blob/master/src/cucker_smale/experiment_controll/experiment_controller.py"
click node_initial "https://github.com/polatucha16/python_boids/blob/master/src/cucker_smale/initial_conditions/base.py"
click node_state "https://github.com/polatucha16/python_boids/blob/master/src/cucker_smale/domain/state.py"
click node_geometry "https://github.com/polatucha16/python_boids/blob/master/src/cucker_smale/domain/geometry.py"
click node_communication "https://github.com/polatucha16/python_boids/blob/master/src/cucker_smale/domain/communication_kernel.py"
click node_topology "https://github.com/polatucha16/python_boids/blob/master/src/cucker_smale/domain/communication_topology.py"
click node_dynamics "https://github.com/polatucha16/python_boids/blob/master/src/cucker_smale/domain/dynamics.py"
click node_interaction "https://github.com/polatucha16/python_boids/blob/master/src/cucker_smale/domain/interaction.py"
click node_simulator "https://github.com/polatucha16/python_boids/blob/master/src/cucker_smale/simulation/simulator.py"
click node_integrator "https://github.com/polatucha16/python_boids/blob/master/src/cucker_smale/simulation/scipy_rk45.py"
click node_view "https://github.com/polatucha16/python_boids/blob/master/src/cucker_smale/visualization/matplotlib/mpl_simulation_view.py"
click node_layout "https://github.com/polatucha16/python_boids/blob/master/src/cucker_smale/visualization/matplotlib/mpl_layout.py"
click node_builder "https://github.com/polatucha16/python_boids/blob/master/src/cucker_smale/visualization/matplotlib/figure_builder.py"
click node_renderer "https://github.com/polatucha16/python_boids/blob/master/src/cucker_smale/visualization/matplotlib/mpl_boid_renderer.py"
click node_manipulator "https://github.com/polatucha16/python_boids/blob/master/src/cucker_smale/visualization/matplotlib/mpl_boid_manipulator.py"
click node_widgets "https://github.com/polatucha16/python_boids/blob/master/src/cucker_smale/visualization/matplotlib/wigets.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_cli,node_yaml,node_loader,node_schema,node_factory,node_user toneBlue
class node_initial,node_state,node_geometry,node_communication,node_topology,node_dynamics,node_interaction toneAmber
class node_controller,node_simulator,node_integrator toneMint
class node_view,node_layout,node_builder,node_renderer,node_manipulator,node_widgets toneRose
```

## Components

### Entry and configuration

- [CLI](https://github.com/polatucha16/python_boids/blob/master/src/cucker_smale/cli.py): `src/cucker_smale/cli.py`
- [Experiment YAML](https://github.com/polatucha16/python_boids/blob/master/src/cucker_smale/config/basic_CS.yaml): `src/cucker_smale/config/basic_CS.yaml`
- [Config loader](https://github.com/polatucha16/python_boids/blob/master/src/cucker_smale/config/load.py): `src/cucker_smale/config/load.py`
- [Config schema](https://github.com/polatucha16/python_boids/blob/master/src/cucker_smale/config/schema.py): `src/cucker_smale/config/schema.py`
- [Object factories](https://github.com/polatucha16/python_boids/blob/master/src/cucker_smale/config/factories.py): `src/cucker_smale/config/factories.py`

### Simulation model

- [Initial conditions](https://github.com/polatucha16/python_boids/blob/master/src/cucker_smale/initial_conditions/base.py): `src/cucker_smale/initial_conditions/base.py`
- [Boid state](https://github.com/polatucha16/python_boids/blob/master/src/cucker_smale/domain/state.py): `src/cucker_smale/domain/state.py`
- [Geometry](https://github.com/polatucha16/python_boids/blob/master/src/cucker_smale/domain/geometry.py): `src/cucker_smale/domain/geometry.py`
- [Communication rules](https://github.com/polatucha16/python_boids/blob/master/src/cucker_smale/domain/communication_kernel.py): `src/cucker_smale/domain/communication_kernel.py`
- [Communication topology](https://github.com/polatucha16/python_boids/blob/master/src/cucker_smale/domain/communication_topology.py): `src/cucker_smale/domain/communication_topology.py`
- [Dynamics and controls](https://github.com/polatucha16/python_boids/blob/master/src/cucker_smale/domain/dynamics.py): `src/cucker_smale/domain/dynamics.py`
- [Interaction models](https://github.com/polatucha16/python_boids/blob/master/src/cucker_smale/domain/interaction.py): `src/cucker_smale/domain/interaction.py`

### Simulation runtime

- [Experiment controller](https://github.com/polatucha16/python_boids/blob/master/src/cucker_smale/experiment_controll/experiment_controller.py): `src/cucker_smale/experiment_controll/experiment_controller.py`
- [Simulator](https://github.com/polatucha16/python_boids/blob/master/src/cucker_smale/simulation/simulator.py): `src/cucker_smale/simulation/simulator.py`
- [RK45 integrator](https://github.com/polatucha16/python_boids/blob/master/src/cucker_smale/simulation/scipy_rk45.py): `src/cucker_smale/simulation/scipy_rk45.py`

### Interactive visualization

- [Simulation view](https://github.com/polatucha16/python_boids/blob/master/src/cucker_smale/visualization/matplotlib/mpl_simulation_view.py): `src/cucker_smale/visualization/matplotlib/mpl_simulation_view.py`
- [Figure layout](https://github.com/polatucha16/python_boids/blob/master/src/cucker_smale/visualization/matplotlib/mpl_layout.py): `src/cucker_smale/visualization/matplotlib/mpl_layout.py`
- [Figure builder](https://github.com/polatucha16/python_boids/blob/master/src/cucker_smale/visualization/matplotlib/figure_builder.py): `src/cucker_smale/visualization/matplotlib/figure_builder.py`
- [Boid renderer](https://github.com/polatucha16/python_boids/blob/master/src/cucker_smale/visualization/matplotlib/mpl_boid_renderer.py): `src/cucker_smale/visualization/matplotlib/mpl_boid_renderer.py`
- [Boid manipulator](https://github.com/polatucha16/python_boids/blob/master/src/cucker_smale/visualization/matplotlib/mpl_boid_manipulator.py): `src/cucker_smale/visualization/matplotlib/mpl_boid_manipulator.py`
- [Interactive widgets](https://github.com/polatucha16/python_boids/blob/master/src/cucker_smale/visualization/matplotlib/wigets.py): `src/cucker_smale/visualization/matplotlib/wigets.py`

### Other components

- **User**

## Connections

- User → CLI: runs (evidence: `README.md`)
- User → Experiment YAML: configures (evidence: `README.md`)
- CLI → Config loader: loads config (evidence: `src/cucker_smale/cli.py`)
- Experiment YAML → Config loader: provides settings (evidence: `README.md`)
- Config loader → Config schema: parses into (evidence: `src/cucker_smale/config/load.py`)
- CLI → Experiment controller: creates (evidence: `src/cucker_smale/cli.py`)
- CLI → Simulation view: opens (evidence: `src/cucker_smale/cli.py`)
- Experiment controller → Object factories: builds through (evidence: `src/cucker_smale/experiment_controll/experiment_controller.py`)
- Object factories → Geometry: constructs (evidence: `src/cucker_smale/config/factories.py`)
- Object factories → Communication rules: constructs (evidence: `src/cucker_smale/config/factories.py`)
- Object factories → Communication topology: constructs (evidence: `src/cucker_smale/config/factories.py`)
- Object factories → Initial conditions: generates (evidence: `src/cucker_smale/config/factories.py`)
- Initial conditions → Boid state: creates (evidence: `src/cucker_smale/initial_conditions/base.py`)
- Object factories → Dynamics and controls: constructs (evidence: `src/cucker_smale/config/factories.py`)
- Dynamics and controls → Geometry: uses distances (evidence: `src/cucker_smale/domain/dynamics.py`)
- Dynamics and controls → Communication rules: uses weights (evidence: `src/cucker_smale/domain/dynamics.py`)
- Dynamics and controls → Communication topology: uses neighbors (evidence: `src/cucker_smale/domain/dynamics.py`)
- Dynamics and controls → Boid state: reads state (evidence: `src/cucker_smale/domain/dynamics.py`)
- Object factories → Simulator: builds (evidence: `src/cucker_smale/config/factories.py`)
- Experiment controller → Simulator: creates (evidence: `src/cucker_smale/experiment_controll/experiment_controller.py`)
- Simulator → RK45 integrator: specialized by (evidence: `src/cucker_smale/config/factories.py`)
- RK45 integrator → Dynamics and controls: integrates (evidence: `src/cucker_smale/simulation/scipy_rk45.py`)
- RK45 integrator → Boid state: updates (evidence: `src/cucker_smale/simulation/scipy_rk45.py`)
- Simulation view → Experiment controller: controls (evidence: `src/cucker_smale/visualization/matplotlib/mpl_simulation_view.py`)
- Simulation view → Simulator: advances (evidence: `src/cucker_smale/visualization/matplotlib/mpl_simulation_view.py`)
- Simulation view → Figure layout: arranges axes (evidence: `src/cucker_smale/visualization/matplotlib/mpl_simulation_view.py`)
- Simulation view → Figure builder: assembles figure (evidence: `src/cucker_smale/visualization/matplotlib/mpl_simulation_view.py`)
- Simulation view → Boid renderer: mounts renderer (evidence: `src/cucker_smale/visualization/matplotlib/mpl_simulation_view.py`)
- Simulation view → Boid manipulator: mounts controls (evidence: `src/cucker_smale/visualization/matplotlib/mpl_simulation_view.py`)
- Simulation view → Interactive widgets: uses widgets (evidence: `src/cucker_smale/visualization/matplotlib/mpl_simulation_view.py`)
- Boid renderer → Boid state: renders (evidence: `src/cucker_smale/visualization/matplotlib/mpl_boid_renderer.py`)
- Boid manipulator → Boid state: updates (evidence: `src/cucker_smale/visualization/matplotlib/mpl_boid_manipulator.py`)
- Interaction models → Dynamics and controls: contributes to model