# fangq/mcx architecture

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

- Interactive diagram: https://gitdiagram.com/fangq/mcx
- Repository: https://github.com/fangq/mcx

## Overview

##### Main Components Overview

The system should be divided into these major components:

a) Core Simulation Engine
- CUDA-based Monte Carlo simulation kernel
- Photon transport physics implementation
- Memory management for GPU operations

b) Input/Output Interfaces
- Multiple file format handlers (JSON, .inp, binary formats)
- Data compression/decompression modules
- Results storage and export systems

c) User Interfaces
- Command-line interface (CLI)
- MATLAB/Octave interface (MCXLAB)
- Python interface (PMCX)
- GUI interface (MCX Studio)

##### Detailed Component Relationships

**[User Interfaces]**
- ↓
**[Input Processing]**
- ↓
**[Simulation Core] ←→ [GPU Management]**
- ↓
**[Output Processing]**
- ↓
**[Data Storage/Export]**

##### Key Architectural Elements

a) Input Layer:
- JSON parser (cJSON)
- Configuration validator
- Volume data loader

b) Computation Layer:
- CUDA kernel manager
- Multi-GPU scheduler
- Memory allocator
- Random number generators
- Photon physics engine

c) Output Layer:
- Volumetric data formatter
- Detector data processor
- Trajectory recorder
- Format converters (mc2, nii, jnii, bnii)

##### Integration Points

Interfaces with:
- MATLAB/Octave (MCXLAB)
- Python (PMCX)
- GUI (MCX Studio)
- External visualization tools

##### Performance-Critical Paths

High-throughput paths:
- GPU memory transfers
- Photon transport calculations
- Output data accumulation

##### The modular design allowing for different simulation types

- Special symbols
- Component types

This design captures MCX's sophisticated architecture while maintaining clarity about its primary purpose as a GPU-accelerated photon transport simulator.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph UI["User Interfaces"]
        CLI["Command Line Interface"]:::ui
        MATLAB["MATLAB/Octave Interface"]:::ui
        Python["Python Interface"]:::ui
        Studio["MCX Studio"]:::ui
    end

    subgraph Input["Input Processing Layer"]
        JSON["JSON Parser"]:::io
        Config["Configuration Validator"]:::io
        VolumeLoader["Volume Data Loader"]:::io
        ShapeProc["Shape Processor"]:::io
    end

    subgraph Core["Computation Layer"]
        direction TB
        CUDAKernel["CUDA Kernel Manager"]:::gpu
        MultiGPU["Multi-GPU Scheduler"]:::gpu
        MemAlloc["Memory Allocator"]:::gpu
        RNG["Random Number Generators"]:::core
        Physics["Photon Physics Engine"]:::core
    end

    subgraph Output["Output Layer"]
        DataFormat["Volumetric Data Formatter"]:::io
        DetectorProc["Detector Data Processor"]:::io
        TrajRecord["Trajectory Recorder"]:::io
        FormatConv["Format Converters"]:::io
    end

    %% Connections
    CLI --> Input
    MATLAB --> Input
    Python --> Input
    Studio --> Input

    JSON --> Config
    Config --> VolumeLoader
    VolumeLoader --> ShapeProc
    ShapeProc --> CUDAKernel

    CUDAKernel <--> MultiGPU
    MultiGPU <--> MemAlloc
    CUDAKernel --> Physics
    Physics --> RNG

    Physics --> DataFormat
    Physics --> DetectorProc
    Physics --> TrajRecord
    DataFormat --> FormatConv
    DetectorProc --> FormatConv
    TrajRecord --> FormatConv

    %% Click Events
    click CLI "https://github.com/fangq/mcx/blob/master/src/mcx.c"
    click MATLAB "https://github.com/fangq/mcx/tree/master/mcxlab/"
    click Python "https://github.com/fangq/mcx/tree/master/pmcx/"
    click Studio "https://github.com/fangq/mcx/tree/master/mcxstudio/"
    click JSON "https://github.com/fangq/mcx/tree/master/src/cjson/"
    click ShapeProc "https://github.com/fangq/mcx/blob/master/src/mcx_shapes.c"
    click Physics "https://github.com/fangq/mcx/blob/master/src/mcx_mie.cpp"
    click RNG "https://github.com/fangq/mcx/blob/master/src/mcx_rand_posix.cu"
    click CUDAKernel "https://github.com/fangq/mcx/blob/master/src/mcx_core.cu"

    %% Styles
    classDef ui fill:#FFA500,stroke:#333,stroke-width:2px
    classDef io fill:#90EE90,stroke:#333,stroke-width:2px
    classDef core fill:#87CEEB,stroke:#333,stroke-width:2px
    classDef gpu fill:#DDA0DD,stroke:#333,stroke-width:2px

    %% Legend
    subgraph Legend
        UI_L["User Interface"]:::ui
        IO_L["I/O Operations"]:::io
        Core_L["Core Components"]:::core
        GPU_L["GPU Components"]:::gpu
    end
```
