# mybzlab/faabpstransportfieldsim architecture

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

- Interactive diagram: https://gitdiagram.com/mybzlab/faabpstransportfieldsim
- Repository: https://github.com/mybzlab/faabpstransportfieldsim

## Overview

##### Project type and purpose
- This is a Python-based scientific simulation application (“FAABPsTransportFieldSim”) that models a swarm of Force-Aligning Active Brownian Particles cooperatively transporting a payload to a goal. It’s primarily a command-line driven simulation engine with modular components for force computation, physics utility functions, simulation orchestration, and result visualization.

##### File structure
- Top-level:
- main.py – CLI entry point
- requirements.txt – Python dependencies
- docs/ – design notes and implementation plans
- src/:
- forces.py – force-computation routines
- physics_utils.py – generic physics helpers (e.g. vector algebra, random sampling)
- runner.py – high-level simulation orchestration
- simulation.py – core time-stepping and state-update logic
- visualization.py – plotting/animation output

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    UI["User Interface / CLI"]:::cli
    click UI "https://github.com/mybzlab/faabpstransportfieldsim/blob/main/main.py"

    %% Core Logic Subgraph
    subgraph "Core Logic"
        direction TB
        Orchestrator["Simulation Orchestrator"]:::core
        click Orchestrator "https://github.com/mybzlab/faabpstransportfieldsim/blob/main/src/runner.py"

        FCE["Force Computation Engine"]:::core
        PDI["Particle Dynamics Integrator"]:::core
        SCPT["Swarm Coordination & Payload Transport"]:::core
    end

    %% Utilities
    Utils["Physics Utilities"]:::util
    click Utils "https://github.com/mybzlab/faabpstransportfieldsim/blob/main/src/physics_utils.py"

    %% Visualization Layer
    Visualization["Visualization Engine"]:::viz
    click Visualization "https://github.com/mybzlab/faabpstransportfieldsim/blob/main/src/visualization.py"

    %% External Libraries & Data
    ExtLib["External Libraries & Dependencies"]:::external
    click ExtLib "https://github.com/mybzlab/faabpstransportfieldsim/blob/main/requirements.txt"

    %% Documentation
    Docs1["Design Notes & Implementation Plans"]:::docs
    click Docs1 "https://github.com/mybzlab/faabpstransportfieldsim/blob/main/docs/algorithm_notes.md"
    click Docs1 "https://github.com/mybzlab/faabpstransportfieldsim/blob/main/docs/wall_implementation_plan.md"

    Docs2["Project README / High-level Overview"]:::docs
    click Docs2 "https://github.com/mybzlab/faabpstransportfieldsim/blob/main/README.md"

    %% Connections
    UI -->|"parses args & config"| Orchestrator

    Orchestrator -->|"calls"| FCE
    Orchestrator -->|"calls"| PDI
    Orchestrator -->|"calls"| SCPT

    FCE -->|"uses"| Utils
    PDI -->|"uses"| Utils
    SCPT -->|"uses"| Utils

    Orchestrator -->|"generates state"| Visualization
    Utils --> Visualization

    ExtLib --> FCE
    ExtLib --> PDI
    ExtLib --> SCPT
    ExtLib --> Utils
    ExtLib --> Visualization

    Docs1 --> Orchestrator
    Docs2 --> UI

    %% Styles
    classDef cli fill:#D0E8FF,stroke:#0366D6,color:#0366D6;
    classDef core fill:#DFFFE0,stroke:#2F8F18,color:#2F8F18;
    classDef util fill:#FFF8DC,stroke:#FFD700,color:#DAA520;
    classDef viz fill:#FFEFD5,stroke:#FF8C00,color:#FF8C00;
    classDef external fill:#F0F0F0,stroke:#A0A0A0,color:#606060,stroke-dasharray: 2 2;
    classDef docs fill:#FFF0F5,stroke:#C71585,color:#C71585;
```
