# heal-research/simsharp architecture

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

- Interactive diagram: https://gitdiagram.com/heal-research/simsharp
- Repository: https://github.com/heal-research/simsharp

## Overview

##### Project type and purpose
- SimSharp is an open-source .NET library (a port and extension of Python’s SimPy) for process-based discrete-event simulation.
- It targets .NET Framework 4.5 and .NET Standard 2.0 and is distributed via NuGet.
- It provides core simulation primitives (Environment, Events, Resources), data structures (priority queues), random number generators, and monitoring/analysis tools.

##### File structure
- Top-level solution (SimSharp.sln) contains four main sub-projects under `src/`:
- SimSharp (the core library)
- Samples (example simulations that consume the library)
- Benchmark (performance tests against sample models)
- Tests (unit and integration tests of the core API)
- Within the SimSharp project:
- Core: simulation engine (Environment, ActiveObject, Events, Resources)
- Collections: high-speed priority queues and utility data structures
- Random: multiple RNG implementations and distributions
- Analysis: monitors and reporting facilities
- Auxiliary: formatting and helpers
- CI/configuration files: AppVeyor YAML, .gitignore, .gitattributes, VSCode settings, NuGet packaging metadata (SimSharp.snk).

##### README for additional insights
- Describes the API design: process‐based models yield `Event` objects.
- Notes the dual API for time units (DateTime/TimeSpan vs. double‐API).
- Mentions monitoring capabilities, preemption, extensibility, and performance benchmarks.
- References external dependencies: .NET runtimes and the high-speed priority queue origin.

a. Main components
- SimSharp Core Library
- Core Engine
- Collections Module
- Random Module
- Analysis Module
- Auxiliary Helpers
- Consumers of the library
- Samples Project (example simulators)
- Benchmark Project (performance harness)
- Test Project (automated tests)
- External/Infrastructure
- .NET Runtime (.NET Framework / .NET Standard)
- NuGet Package Repository
- CI Server (AppVeyor)
- Source Control (Git/GitHub)
- Documentation (docs/ folder, docs site)
b. Relationships and interactions
- The Core Engine depends on Collections (for event queues) and Random (for sampling).
- Analysis hooks into Core and Resources to collect metrics.
- Auxiliary is a helper library used by all other modules.
- Samples, Benchmark, and Tests each reference the SimSharp Core project.
- CI pulls code from Git, builds solution, runs Tests, publishes NuGet and Docs.
c. Architectural patterns and principles
- Modular design: clear separation of concerns (Engine vs. Data Structures vs. RNG vs. Analysis).
- Process‐based discrete‐event simulation pattern (yielding events).
- Dependency inversion: consumers depend on abstractions (interfaces IRandom, IMonitor).
- Extensibility: pluggable RNGs, custom monitors, user‐defined processes.
d. Key technologies and frameworks
- C#, .NET Framework 4.5, .NET Standard 2.0
- NuGet packaging
- AppVeyor CI
- High-speed priority queue (adapted from BlueRaja)
- xUnit (or built-in test runner) for unit tests

##### Elements
- Labels: name every module, project, and external system explicitly.
- From CI → GitHub (source) → build solution → run Tests → publish package/docs.
- From Samples/Benchmark/Tests → SimSharp Core.
- From Core → Collections, Random, Analysis, Auxiliary.

##### Detail
- Interfaces (e.g., IDistribution, IRandom, IMonitor) and their implementations.
- High-speed priority queue origin and license files if licensing compliance needs visibility.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% SimSharp Library Modules
    subgraph "SimSharp Core Library"
        direction TB
        CoreEngine["Core Engine"]:::internal
        Collections["Collections Module"]:::internal
        RandomMod["Random Module"]:::internal
        AnalysisMod["Analysis Module"]:::internal
        Auxiliary["Auxiliary Helpers"]:::internal
    end

    %% Consumer Projects
    subgraph "Consumer Projects"
        direction TB
        Samples["Samples Project"]:::consumer
        Benchmark["Benchmark Project"]:::consumer
        Tests["Test Project"]:::consumer
    end

    %% Infrastructure and External
    subgraph "Infrastructure"
        direction TB
        GitHub["GitHub (Source)"]:::external
        CI["CI Server (AppVeyor)"]:::external
        Solution["Solution File"]:::external
        NuGet["NuGet Repository"]:::external
        Docs["Documentation Site"]:::docs
    end

    %% Relationships within SimSharp Library
    CoreEngine -->|"uses"| Collections
    CoreEngine -->|"uses"| RandomMod
    CoreEngine -->|"depends on"| AnalysisMod
    CoreEngine -->|"helper from"| Auxiliary
    Collections -->|"helper from"| Auxiliary
    RandomMod -->|"helper from"| Auxiliary
    AnalysisMod -->|"helper from"| Auxiliary

    %% Consumers reference Core Library
    Samples -->|"reference"| CoreEngine
    Benchmark -->|"reference"| CoreEngine
    Tests -->|"reference"| CoreEngine

    %% CI/CD Pipeline
    GitHub -->|"source checkout"| CI
    CI -->|"build solution"| Solution
    CI -->|"run tests"| Tests
    CI -->|"publish package"| NuGet
    CI -->|"publish docs"| Docs

    %% Classes and Click Events
    classDef internal fill:#B3CDE3,stroke:#6497B1,color:#03396C,stroke-width:1px;
    classDef consumer fill:#C7E9C0,stroke:#74C476,color:#00441B,stroke-width:1px;
    classDef external fill:#FDD0A2,stroke:#FC8D59,color:#7F2704,stroke-width:1px;
    classDef docs fill:#F2F0F7,stroke:#CBC9E2,color:#49006A,stroke-width:1px;

    click CoreEngine "https://github.com/heal-research/simsharp/tree/master/src/SimSharp/Core"
    click Collections "https://github.com/heal-research/simsharp/tree/master/src/SimSharp/Collections"
    click RandomMod "https://github.com/heal-research/simsharp/tree/master/src/SimSharp/Random"
    click AnalysisMod "https://github.com/heal-research/simsharp/tree/master/src/SimSharp/Analysis"
    click Auxiliary "https://github.com/heal-research/simsharp/tree/master/src/SimSharp/Auxiliary"
    click Samples "https://github.com/heal-research/simsharp/blob/master/src/Samples/Samples.csproj"
    click Benchmark "https://github.com/heal-research/simsharp/blob/master/src/Benchmark/Benchmark.csproj"
    click Tests "https://github.com/heal-research/simsharp/blob/master/src/Tests/Tests.csproj"
    click CI "https://github.com/heal-research/simsharp/blob/master/appveyor.yml"
    click Docs "https://github.com/heal-research/simsharp/blob/master/docs/README.md"
    click Solution "https://github.com/heal-research/simsharp/blob/master/src/SimSharp.sln"
```
