# edocipriano/basilisk-sandbox-ecipriano architecture

> Architecture diagram of the GitHub repository edocipriano/basilisk-sandbox-ecipriano, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/edocipriano/basilisk-sandbox-ecipriano
- Repository: https://github.com/edocipriano/basilisk-sandbox-ecipriano

## Overview

##### Project type and purpose
- This is a scientific simulation library and sandbox built on top of the Basilisk CFD framework. It provides core modules for fluid dynamics (Navier–Stokes solvers, evaporation, two-phase flows), chemical kinetics (OpenSMOKE integration), and a collection of example “run” programs to study droplet combustion, boiling, and related phenomena.

##### File structure
- Top‐level directories:
- src – the core header-only library modules (flow solvers, physics kernels, property models)
- dev – parallel copy of src used for active development or experimental patches
- run & run_dev – collections of stand-alone C example programs + Makefiles + input/data files
- test – automated regression tests verifying individual modules
- doc – high-level documentation and tutorials
- Build scripts: Makefiles in src/, run/, run_dev/, dev/
- Data directories: example datasets under run/data and run_dev/data

##### README
- Confirms that this is a personal sandbox of Basilisk modules at http://basilisk.fr/sandbox/ecipriano/

a. Main components
- Core Library (src) – contains physics headers: navier-stokes, evaporation, multicomponent, thermodynamics, radiation, chemistry interfaces.
- Development Layer (dev) – experimental forks of the same modules for patch testing.
- Build System – Makefiles orchestrating compilation of src/dev into object code and linking of examples.
- Example Executables (run & run_dev) – C programs that #include library headers to set up specific simulation cases.
- Data Inputs – CSV or .exp files providing boundary conditions, initial profiles, or reference data.
- Test Suite (test) – small harness programs that include individual modules to verify correctness.
- Documentation (doc) – explanatory guides, but not part of runtime.

b. Relationships and interactions
1. The Build System reads Makefiles in src and dev → compiles headers into static or header-only library artifacts (object files or inline code).
2. Example programs in run/run_dev #include these modules → Link step produces executables.
3. Executables consume Data Inputs → produce simulation outputs.
4. Tests in test/ also #include core headers → compare results against stored .ref files.
5. Optional: dev/ modules can override or extend src/ modules by altering include paths in Makefiles.

c. Architectural patterns and design principles
– Modular, header-only design (no central monolithic binary).
– Plugin pattern for physics modules: include only the needed headers in each C program.
– Clear separation between library code, examples, and test harness.
– Reuse of common Makefile patterns for consistent builds.

d. Key technologies and libraries
– C99 (ANSI C) with heavy use of headers
– Basilisk framework conventions (wavelet adaptivity, VOF, GFM, low-Mach, etc.)
– GSL for nonlinear solves (fsolve-gsl)
– OpenSMOKE for gas-phase chemistry
– Standard Make + Unix toolchain

## Diagram (Mermaid)

```mermaid
graph TB
    %% Core Library Modules
    subgraph "Core Library"
        direction TB
        NavierStokesCore["Navier–Stokes Solvers"]:::code
        EvaporationCore["Evaporation Module"]:::code
        MulticomponentCore["Multicomponent Flows"]:::code
        ThermodynamicsCore["Thermodynamics"]:::code
        RadiationCore["Radiation"]:::code
        ChemistryCore["Chemistry Interface (OpenSMOKE)"]:::code
        GSLCore["GSL Nonlinear Solver Interface"]:::code
    end

    %% Development Layer Modules
    subgraph "Development Layer (dev)"
        direction TB
        NavierStokesDev["Navier–Stokes Solvers"]:::dev
        EvaporationDev["Evaporation Module"]:::dev
        MulticomponentDev["Multicomponent Flows"]:::dev
        ThermodynamicsDev["Thermodynamics"]:::dev
        RadiationDev["Radiation"]:::dev
        ChemistryDev["Chemistry Interface (OpenSMOKE)"]:::dev
    end

    %% Build Systems
    subgraph "Build System"
        direction TB
        BuildCore["Makefile (src)"]:::build
        BuildDev["Makefile (dev)"]:::build
        BuildRun["Makefile (run)"]:::build
        BuildRunDev["Makefile (run_dev)"]:::build
        BuildTest["Makefile (test)"]:::build
    end

    %% Consumers
    subgraph "Example Executables"
        direction TB
        RunExamples["run/*.c"]:::consumers
        RunDevExamples["run_dev/*.c"]:::consumers
    end

    %% Test Suite
    Tests["test/*.c & test/*.ref"]:::consumers

    %% Data Inputs
    DataRun["run/data"]:::data
    DataRunDev["run_dev/data"]:::data

    %% Outputs
    Outputs["Simulation Outputs"]:::data

    %% Documentation
    Documentation["Documentation (doc)"]:::data

    %% Relationships: Build to Modules
    BuildCore -->|"compile"| NavierStokesCore
    BuildCore -->|"compile"| EvaporationCore
    BuildCore -->|"compile"| MulticomponentCore
    BuildCore -->|"compile"| ThermodynamicsCore
    BuildCore -->|"compile"| RadiationCore
    BuildCore -->|"compile"| ChemistryCore
    BuildCore -->|"compile"| GSLCore

    BuildDev -->|"compile"| NavierStokesDev
    BuildDev -->|"compile"| EvaporationDev
    BuildDev -->|"compile"| MulticomponentDev
    BuildDev -->|"compile"| ThermodynamicsDev
    BuildDev -->|"compile"| RadiationDev
    BuildDev -->|"compile"| ChemistryDev

    %% Build to Consumers (link)
    BuildRun -->|"link"| RunExamples
    BuildRunDev -->|"link"| RunDevExamples
    BuildTest -->|"link"| Tests

    %% Consumers to Data Inputs
    RunExamples -->|"read"| DataRun
    RunDevExamples -->|"read"| DataRunDev
    Tests -->|"read"| DataRun

    %% Examples to Outputs
    RunExamples -->|"write"| Outputs
    RunDevExamples -->|"write"| Outputs

    %% Dev override arrow
    NavierStokesDev -.->|"override/include-path"| NavierStokesCore

    %% Click Events
    click NavierStokesCore "https://github.com/edocipriano/basilisk-sandbox-ecipriano/tree/main/src/navier-stokes"
    click EvaporationCore "https://github.com/edocipriano/basilisk-sandbox-ecipriano/blob/main/src/evaporation.h"
    click MulticomponentCore "https://github.com/edocipriano/basilisk-sandbox-ecipriano/blob/main/src/multicomponent.h"
    click ThermodynamicsCore "https://github.com/edocipriano/basilisk-sandbox-ecipriano/blob/main/src/thermodynamics.h"
    click RadiationCore "https://github.com/edocipriano/basilisk-sandbox-ecipriano/blob/main/src/radiation.h"
    click ChemistryCore "https://github.com/edocipriano/basilisk-sandbox-ecipriano/blob/main/src/opensmoke.h"
    click GSLCore "https://github.com/edocipriano/basilisk-sandbox-ecipriano/blob/main/src/fsolve-gsl.h"
    click NavierStokesDev "https://github.com/edocipriano/basilisk-sandbox-ecipriano/tree/main/dev/navier-stokes"
    click EvaporationDev "https://github.com/edocipriano/basilisk-sandbox-ecipriano/blob/main/dev/evaporation.h"
    click MulticomponentDev "https://github.com/edocipriano/basilisk-sandbox-ecipriano/blob/main/dev/multicomponent.h"
    click ThermodynamicsDev "https://github.com/edocipriano/basilisk-sandbox-ecipriano/blob/main/dev/thermodynamics.h"
    click RadiationDev "https://github.com/edocipriano/basilisk-sandbox-ecipriano/blob/main/dev/opensmoke/radiation.h"
    click ChemistryDev "https://github.com/edocipriano/basilisk-sandbox-ecipriano/blob/main/dev/opensmoke/opensmoke.h"
    click BuildCore "https://github.com/edocipriano/basilisk-sandbox-ecipriano/tree/main/src/Makefile"
    click BuildDev "https://github.com/edocipriano/basilisk-sandbox-ecipriano/tree/main/dev/Makefile"
    click BuildRun "https://github.com/edocipriano/basilisk-sandbox-ecipriano/tree/main/run/Makefile"
    click BuildRunDev "https://github.com/edocipriano/basilisk-sandbox-ecipriano/tree/main/run_dev/Makefile"
    click BuildTest "https://github.com/edocipriano/basilisk-sandbox-ecipriano/tree/main/test/Makefile"
    click RunExamples "https://github.com/edocipriano/basilisk-sandbox-ecipriano/blob/main/run/*.c"
    click RunDevExamples "https://github.com/edocipriano/basilisk-sandbox-ecipriano/blob/main/run_dev/*.c"
    click DataRun "https://github.com/edocipriano/basilisk-sandbox-ecipriano/tree/main/run/data"
    click DataRunDev "https://github.com/edocipriano/basilisk-sandbox-ecipriano/tree/main/run_dev/data"
    click Tests "https://github.com/edocipriano/basilisk-sandbox-ecipriano/blob/main/test/*.c"
    click Documentation "https://github.com/edocipriano/basilisk-sandbox-ecipriano/tree/main/doc"

    %% Styles
    classDef code fill:#D0E8FF,stroke:#0066CC,color:#000
    classDef dev fill:#FFE0E0,stroke:#CC0000,color:#000
    classDef consumers fill:#E0FFE0,stroke:#009900,color:#000
    classDef data fill:#FFE8CC,stroke:#CC6600,color:#000
    classDef build fill:#DDDDDD,stroke:#777777,color:#000
```
