# antonio-cruciani/dreg-dynamicrandomexpandergenerator architecture

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

- Interactive diagram: https://gitdiagram.com/antonio-cruciani/dreg-dynamicrandomexpandergenerator
- Repository: https://github.com/antonio-cruciani/dreg-dynamicrandomexpandergenerator

## Overview

##### Project type and purpose
- This is a Python-based simulation framework (an open-source tool) for generating and analyzing dynamic random graphs under different models (Edge Dynamics, Vertex Dynamics, mixed models). It is driven by configuration files and supports both single-process and multiprocessing simulations.
- Users define P2P protocols (RAES, ERAES, VRAES, EVRAES) and experiment parameters in INI files, then run CLI scripts to produce adjacency lists, spectral statistics, flooding results, and other metrics.

##### File-structure analysis
- Top-level scripts:
- main.py         – entry point for ERAES/VRAES simulations
- mixedDynamic.py – entry point for mixed EVRAES with multiprocessing
- ERAES… / EVRAES… – convenience scripts for variants
- to_plot_eraes.py, write_properties.py – post-processing/plotting
- Configuration:
- config.ini      – master INI defining model and simulation params
- configurations/EdgeDynamics, VertexDynamics – sample INIs for reproduction
- Core code under src/:
- Algorithms/     – model implementations (EdgeDynamic.py, VertexDynamic.py)
- Graphs/         – custom graph data structures (MultipleEdge, Queue)
- MathModules/    – numeric utilities (MathTools.py)
- Protocols/      – P2P protocol logic (Consensus.py, FloodOBJ.py)
- FileOperations/ – persistence (WriteOnFile.py)
- StastModules/   – statistics & analysis (GraphAnalysis, SpectralAnalysis, Snapshot)
- tail_estimation_degree_distribution – tail-estimation script

##### Key README insights
- Distributed protocols run at each time step to maintain bounded node degree.
- External events (edge/node disappearance) are stochastic.
- Supports “offline” mode (dumping adjacency lists) and “only spectral” mode.
- Multiprocessing for mixed dynamics via mixedDynamic.py.

a. Main components:
1. Input Layer:
– User INI files (config.ini, model-specific INIs)
2. Orchestrator:
– CLI scripts (main.py, mixedDynamic.py)
– Configuration parser (reads INI, builds parameter sets)
3. Simulation Engine:
– Model Manager (instantiates EdgeDynamic or VertexDynamic classes)
– Protocol Executor (Consensus, FloodOBJ)
– Event Generator (internal random falls/join events)
4. Core Modules:
– Algorithms (model logic per time step)
– Graph Data Structures (Graph, Node, Edge handling)
– Math Utilities (epsilon estimation, Poisson rates)
5. Analysis & Output:
– Statistics Modules (GraphAnalysis, SpectralAnalysis, Snapshot)
– FileOperations (writes adjacency, metrics, logs)
– Post-processing scripts (tail estimation, plotting)
6. Multiprocessing Layer (for EVRAES mixedDynamic.py)

b. Relationships and data flow:
– Config files → Config parser → Parameter set
– Orchestrator → Simulation Engine → Model instance
– Each simulation round:
- Model instance invokes Protocol Executor
- Graph object updated via Algorithms
- MathTools invoked for convergence checks
- Events generated by Event Generator
– After each round or at end:
- StastModules compute metrics
- FileOperations flush data to disk
– Post run:
- to_plot_eraes.py / tail-estimation.py read output and generate visuals

c. Architectural patterns / principles:
– Layered architecture: separation of CLI, core engine, data structures, math, analysis
– Modular design: each functionality in its own package under src/
– Pipeline pattern: config → simulation → analysis → output → plotting

d. Key technologies and frameworks:
– Python 3.x
– ConfigParser (for INI parsing)
– Multiprocessing (built-in)
– Custom graph and protocol classes (no external graph library)
– Standard math, random, file I/O modules

##### Details to capture
- The dual entry points (main.py vs mixedDynamic.py) and when each is used.
- The role of each src/ subdirectory.
- How external events (edge/node falls) plug into the main loop.
- Where and how users can plug in new protocols or analysis modules.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input Layer
    subgraph "Input Layer"
        CM["Master Config\n(config.ini)"]:::input
        SI1["EdgeDynamics Flooding INI"]:::input
        SI2["EdgeDynamics Spectral INI"]:::input
        SI3["VertexDynamics Flooding INI"]:::input
        SI4["VertexDynamics Spectral INI"]:::input
    end

    %% Orchestrator
    subgraph "Orchestrator"
        CP["Config Parser"]:::orchestrator
        MP["main.py"]:::orchestrator
        MX["mixedDynamic.py"]:::orchestrator
        EM1["ERAESMultiProcessing.py"]:::orchestrator
        EM2["ERAESMultiProcessingDD.py"]:::orchestrator
        ES["ERAESSprectralGapMP.py"]:::orchestrator
        EVDD["EVRAESMultiProcessingDD.py"]:::orchestrator
    end

    %% Simulation Engine
    subgraph "Simulation Engine"
        subgraph "Model Manager"
            ED["EdgeDynamic"]:::engine
            VD["VertexDynamic"]:::engine
        end
        subgraph "Protocol Executor"
            PC["Consensus"]:::engine
            PF["FloodOBJ"]:::engine
        end
        EG["Event Generator"]:::engine
    end

    %% Core Modules
    subgraph "Core Modules"
        subgraph "Graph Data Structures"
            ME["MultipleEdge"]:::core
            Q["Queue"]:::core
        end
        MT["MathTools"]:::core
    end

    %% Analysis & Output
    subgraph "Analysis & Output"
        GA["GraphAnalysis"]:::output
        SA["SpectralAnalysis"]:::output
        SS["Snapshot"]:::output
        WF["WriteOnFile"]:::output
    end

    %% Post-processing
    subgraph "Post-processing"
        TE["tail-estimation.py"]:::post
        PP["to_plot_eraes.py"]:::post
        WP["write_properties.py"]:::post
    end

    %% Connections
    CM --> CP
    SI1 --> CP
    SI2 --> CP
    SI3 --> CP
    SI4 --> CP

    CP --> MP
    CP --> MX

    MP --> ED
    MP --> VD
    MX --> ED
    MX --> VD

    ED --> PC
    ED --> PF
    VD --> PC
    VD --> PF

    PC --> ME
    PC --> Q
    PF --> ME
    PF --> Q

    ME --> MT
    Q --> MT
    EG --> MT

    ED --> EG
    VD --> EG

    PC --> GA
    PF --> GA
    EG --> SA

    GA --> WF
    SA --> WF
    SS --> WF

    WF --> PP
    WF --> TE
    WF --> WP

    %% Click Events
    click CM "https://github.com/antonio-cruciani/dreg-dynamicrandomexpandergenerator/blob/master/config.ini"
    click SI1 "https://github.com/antonio-cruciani/dreg-dynamicrandomexpandergenerator/blob/master/configurations/EdgeDynamics/edge_dynamics_flooding_conf.ini"
    click SI2 "https://github.com/antonio-cruciani/dreg-dynamicrandomexpandergenerator/blob/master/configurations/EdgeDynamics/edge_dynamics_spectral_conf.ini"
    click SI3 "https://github.com/antonio-cruciani/dreg-dynamicrandomexpandergenerator/blob/master/configurations/VertexDynamics/vertex_dynamics_flooding_conf.ini"
    click SI4 "https://github.com/antonio-cruciani/dreg-dynamicrandomexpandergenerator/blob/master/configurations/VertexDynamics/vertex_dynamics_spectral_conf.ini"
    click MP "https://github.com/antonio-cruciani/dreg-dynamicrandomexpandergenerator/blob/master/main.py"
    click MX "https://github.com/antonio-cruciani/dreg-dynamicrandomexpandergenerator/blob/master/mixedDynamic.py"
    click EM1 "https://github.com/antonio-cruciani/dreg-dynamicrandomexpandergenerator/blob/master/ERAESMultiProcessing.py"
    click EM2 "https://github.com/antonio-cruciani/dreg-dynamicrandomexpandergenerator/blob/master/ERAESMultiProcessingDD.py"
    click ES "https://github.com/antonio-cruciani/dreg-dynamicrandomexpandergenerator/blob/master/ERAESSprectralGapMP.py"
    click EVDD "https://github.com/antonio-cruciani/dreg-dynamicrandomexpandergenerator/blob/master/EVRAESMultiProcessingDD.py"
    click ED "https://github.com/antonio-cruciani/dreg-dynamicrandomexpandergenerator/blob/master/src/Algorithms/EdgeDynamic.py"
    click VD "https://github.com/antonio-cruciani/dreg-dynamicrandomexpandergenerator/blob/master/src/Algorithms/VertexDynamic.py"
    click PC "https://github.com/antonio-cruciani/dreg-dynamicrandomexpandergenerator/blob/master/src/Protocols/Consensus.py"
    click PF "https://github.com/antonio-cruciani/dreg-dynamicrandomexpandergenerator/blob/master/src/Protocols/FloodOBJ.py"
    click ME "https://github.com/antonio-cruciani/dreg-dynamicrandomexpandergenerator/blob/master/src/Graphs/Objects/MultipleEdge.py"
    click Q "https://github.com/antonio-cruciani/dreg-dynamicrandomexpandergenerator/blob/master/src/Graphs/Objects/Queue.py"
    click MT "https://github.com/antonio-cruciani/dreg-dynamicrandomexpandergenerator/blob/master/src/MathModules/MathTools.py"
    click GA "https://github.com/antonio-cruciani/dreg-dynamicrandomexpandergenerator/blob/master/src/StastModules/GraphAnalysis.py"
    click SA "https://github.com/antonio-cruciani/dreg-dynamicrandomexpandergenerator/blob/master/src/StastModules/SpectralAnalysis.py"
    click SS "https://github.com/antonio-cruciani/dreg-dynamicrandomexpandergenerator/blob/master/src/StastModules/Snapshot.py"
    click WF "https://github.com/antonio-cruciani/dreg-dynamicrandomexpandergenerator/blob/master/src/FileOperations/WriteOnFile.py"
    click TE "https://github.com/antonio-cruciani/dreg-dynamicrandomexpandergenerator/blob/master/src/tail_estimation_degree_distribution/tail-estimation.py"
    click PP "https://github.com/antonio-cruciani/dreg-dynamicrandomexpandergenerator/blob/master/to_plot_eraes.py"
    click WP "https://github.com/antonio-cruciani/dreg-dynamicrandomexpandergenerator/blob/master/write_properties.py"

    %% Styles
    classDef input fill:#AED6F1,stroke:#000
    classDef orchestrator fill:#ABEBC6,stroke:#000
    classDef engine fill:#F5B041,stroke:#000
    classDef core fill:#D2B4DE,stroke:#000
    classDef output fill:#BB8FCE,stroke:#000
    classDef post fill:#D5DBDB,stroke:#000
```
