# rodyherrera/trybo architecture

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

- Interactive diagram: https://gitdiagram.com/rodyherrera/trybo
- Repository: https://github.com/rodyherrera/trybo

## Overview

##### Project type and purpose
- Trybo is a domain-specific simulation and analysis tool built around LAMMPS.
- It generates LAMMPS input scripts, runs simulations with GPU-accelerated LAMMPS, parses output data, performs multiple tribological analyses, and produces visualizations.

##### File structure
- Top‐level directories
- src/core: core engine (CLI entrypoint, configuration parser, simulation runner, helpers)
- src/templates: LAMMPS input templates grouped by analysis type
- src/analyzers: plugin analyzers (energy, debris, hotspots, CNA, PTM, etc.)
- src/visualizers: matching visualizers for each analyzer
- src/utilities: shared utilities
- toolchain: scripts to build custom LAMMPS executable
- examples, potentials: data inputs
- Patterns
- Plugin architecture: analyzers and visualizers implement common interfaces (analyzer.py, visualizer.py)
- Template‐based code generation for LAMMPS inputs
- CLI → configuration → runner → external simulation → post-processing

##### README insights
- Emphasizes need for custom GPU-enabled LAMMPS
- Lists 14 analysis modules (each maps to one analyzer + visualizer pair)
- Outputs: dump files, text logs (wear_data.txt, friction_data.txt, etc.), screenshots

##### Main components and interactions
a. Components
1. User/CLI (use_trybo.sh or python -m src.main)
2. Configuration Loader (yaml_config)
3. Template Engine (src/templates)
4. Simulation Runner (invokes custom LAMMPS executable)
5. LAMMPS Engine (external GPU build from toolchain)
6. Analyzer Plugins (src/analyzers/*_analyzer.py)
7. Visualizer Plugins (src/visualizers/*_visualizer.py)
8. Data Stores
– Input data: potentials/*.eam, examples/*.yml
– Simulation outputs: dump files, thermo logs
– Analysis outputs: txt, dump files
– Plots/screenshots
b. Relationships & data flow
– CLI → reads YAML config → Template Engine to generate LAMMPS input
– Simulation Runner → calls LAMMPS executable → LAMMPS reads templates & potentials → writes output dumps & logs
– Analyzer Plugins → ingest LAMMPS outputs → compute metrics → write analysis files
– Visualizer Plugins → read analysis files → generate plots/screenshots
c. Architectural patterns
– Plugin pattern for analyzers/visualizers
– Separation of concerns: core, templates, analysis, visualization
– Factory or registry for dynamically loading analyzers/visualizers
d. Key technologies
– Python 3 (pyproject.toml)
– LAMMPS with GPU & additional packages (built via build_lammps_gpu.sh)
– YAML config parsing
– File‐based I/O (dumps, text logs)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        CLI["User/CLI"]:::core
        Config["Configuration Loader"]:::core
        Template["Template Engine"]:::core
    end

    %% Backend Layer
    subgraph "Backend Layer"
        Runner["Simulation Runner"]:::core
        LAMMPS["LAMMPS Engine"]:::external
    end

    %% Data Stores
    subgraph "Data Stores"
        Potentials["Potentials (*.eam)"]:::data
        Examples["Examples (*.yml)"]:::data
        Outputs["Simulation Outputs (dumps, logs)"]:::data
        AnalysisOutputs["Analysis Outputs (txt, dumps)"]:::data
        Screenshots["Screenshots"]:::data
    end

    %% Analyzer Plugins
    subgraph "Analyzer Plugins"
        CentroSymmetricAnalyzer(("Centro Symmetric Analyzer")):::plugin
        CNAAnalyzer(("CNA Analyzer")):::plugin
        CoordinationAnalyzer(("Coordination Analyzer")):::plugin
        DebrisAnalyzer(("Debris Analyzer")):::plugin
        EnergyAnalyzer(("Energy Analyzer")):::plugin
        HotspotAnalyzer(("Hotspot Analyzer")):::plugin
        PTMAnalyzer(("PTM Analyzer")):::plugin
        VelocitySquaredAnalyzer(("Velocity Squared Analyzer")):::plugin
        VonMisesAnalyzer(("Von Mises Analyzer")):::plugin
    end

    %% Visualizer Plugins
    subgraph "Visualizer Plugins"
        CentroSymmetricVisualizer(("Centro Symmetric Visualizer")):::plugin
        CNAVisualizer(("CNA Visualizer")):::plugin
        CoordinationVisualizer(("Coordination Visualizer")):::plugin
        DebrisVisualizer(("Debris Visualizer")):::plugin
        EnergyVisualizer(("Energy Visualizer")):::plugin
        HotspotVisualizer(("Hotspot Visualizer")):::plugin
        PTMVisualizer(("PTM Visualizer")):::plugin
        VelocitySquaredVisualizer(("Velocity Squared Visualizer")):::plugin
        VonMisesVisualizer(("Von Mises Visualizer")):::plugin
    end

    %% Connections
    CLI -->|"invokes"| Config
    Config -->|"generates templates"| Template
    Template -->|"provides input"| Runner
    Potentials -->|"feeds"| LAMMPS
    Templates -->|"feeds"| LAMMPS
    Runner -->|"executes"| LAMMPS
    LAMMPS -->|"writes outputs"| Outputs
    Outputs -->|"analyzed by"| CentroSymmetricAnalyzer
    Outputs -->|"analyzed by"| CNAAnalyzer
    Outputs -->|"analyzed by"| CoordinationAnalyzer
    Outputs -->|"analyzed by"| DebrisAnalyzer
    Outputs -->|"analyzed by"| EnergyAnalyzer
    Outputs -->|"analyzed by"| HotspotAnalyzer
    Outputs -->|"analyzed by"| PTMAnalyzer
    Outputs -->|"analyzed by"| VelocitySquaredAnalyzer
    Outputs -->|"analyzed by"| VonMisesAnalyzer
    CentroSymmetricAnalyzer -->|"writes"| AnalysisOutputs
    CNAAnalyzer -->|"writes"| AnalysisOutputs
    CoordinationAnalyzer -->|"writes"| AnalysisOutputs
    DebrisAnalyzer -->|"writes"| AnalysisOutputs
    EnergyAnalyzer -->|"writes"| AnalysisOutputs
    HotspotAnalyzer -->|"writes"| AnalysisOutputs
    PTMAnalyzer -->|"writes"| AnalysisOutputs
    VelocitySquaredAnalyzer -->|"writes"| AnalysisOutputs
    VonMisesAnalyzer -->|"writes"| AnalysisOutputs
    AnalysisOutputs -->|"visualized by"| CentroSymmetricVisualizer
    AnalysisOutputs -->|"visualized by"| CNAVisualizer
    AnalysisOutputs -->|"visualized by"| CoordinationVisualizer
    AnalysisOutputs -->|"visualized by"| DebrisVisualizer
    AnalysisOutputs -->|"visualized by"| EnergyVisualizer
    AnalysisOutputs -->|"visualized by"| HotspotVisualizer
    AnalysisOutputs -->|"visualized by"| PTMVisualizer
    AnalysisOutputs -->|"visualized by"| VelocitySquaredVisualizer
    AnalysisOutputs -->|"visualized by"| VonMisesVisualizer
    CentroSymmetricVisualizer -->|"saves"| Screenshots
    CNAVisualizer -->|"saves"| Screenshots
    CoordinationVisualizer -->|"saves"| Screenshots
    DebrisVisualizer -->|"saves"| Screenshots
    EnergyVisualizer -->|"saves"| Screenshots
    HotspotVisualizer -->|"saves"| Screenshots
    PTMVisualizer -->|"saves"| Screenshots
    VelocitySquaredVisualizer -->|"saves"| Screenshots
    VonMisesVisualizer -->|"saves"| Screenshots

    %% Click Events
    click CLI "https://github.com/rodyherrera/trybo/blob/main/src/main.py"
    click Config "https://github.com/rodyherrera/trybo/blob/main/src/core/yaml_config.py"
    click Template "https://github.com/rodyherrera/trybo/tree/main/src/templates/"
    click Runner "https://github.com/rodyherrera/trybo/blob/main/src/core/simulation_runner.py"
    click LAMMPS "https://github.com/rodyherrera/trybo/blob/main/toolchain/build_lammps_gpu.sh"
    click CentroSymmetricAnalyzer "https://github.com/rodyherrera/trybo/blob/main/src/analyzers/centro_symmetric_analyzer.py"
    click CNAAnalyzer "https://github.com/rodyherrera/trybo/blob/main/src/analyzers/cna_analyzer.py"
    click CoordinationAnalyzer "https://github.com/rodyherrera/trybo/blob/main/src/analyzers/coordination_analyzer.py"
    click DebrisAnalyzer "https://github.com/rodyherrera/trybo/blob/main/src/analyzers/debris_analyzer.py"
    click EnergyAnalyzer "https://github.com/rodyherrera/trybo/blob/main/src/analyzers/energy_analyzer.py"
    click HotspotAnalyzer "https://github.com/rodyherrera/trybo/blob/main/src/analyzers/hotspot_analyzer.py"
    click PTMAnalyzer "https://github.com/rodyherrera/trybo/blob/main/src/analyzers/ptm_analyzer.py"
    click VelocitySquaredAnalyzer "https://github.com/rodyherrera/trybo/blob/main/src/analyzers/velocity_squared_analyzer.py"
    click VonMisesAnalyzer "https://github.com/rodyherrera/trybo/blob/main/src/analyzers/vonmises_analyzer.py"
    click CentroSymmetricVisualizer "https://github.com/rodyherrera/trybo/blob/main/src/visualizers/centro_symmetric_visualizer.py"
    click CNAVisualizer "https://github.com/rodyherrera/trybo/blob/main/src/visualizers/cna_visualizer.py"
    click CoordinationVisualizer "https://github.com/rodyherrera/trybo/blob/main/src/visualizers/coordination_visualizer.py"
    click DebrisVisualizer "https://github.com/rodyherrera/trybo/blob/main/src/visualizers/debris_visualizer.py"
    click EnergyVisualizer "https://github.com/rodyherrera/trybo/blob/main/src/visualizers/energy_visualizer.py"
    click HotspotVisualizer "https://github.com/rodyherrera/trybo/blob/main/src/visualizers/hotspot_visualizer.py"
    click PTMVisualizer "https://github.com/rodyherrera/trybo/blob/main/src/visualizers/ptm_visualizer.py"
    click VelocitySquaredVisualizer "https://github.com/rodyherrera/trybo/blob/main/src/visualizers/velocity_squared_visualizer.py"
    click VonMisesVisualizer "https://github.com/rodyherrera/trybo/blob/main/src/visualizers/vonmises_visualizer.py"
    click Examples "https://github.com/rodyherrera/trybo/tree/main/examples/"
    click Potentials "https://github.com/rodyherrera/trybo/tree/main/potentials/"

    %% Styles
    classDef core fill:#D0E1FF,stroke:#0366d6,color:#0366d6;
    classDef plugin fill:#E0FFE0,stroke:#2D8A2A,color:#2D8A2A;
    classDef external fill:#FFE0B2,stroke:#D97706,color:#D97706,stroke-width:2px;
    classDef data fill:#F0F0F0,stroke:#666666,color:#333333,stroke-dasharray: 2 2;
```
