SIMBI

  ███████╗██╗███╗   ███╗██████╗ ██╗
  ██╔════╝██║████╗ ████║██╔══██╗██║
  ███████╗██║██╔████╔██║██████╔╝██║
  ╚════██║██║██║╚██╔╝██║██╔══██╗██║
  ███████║██║██║ ╚═╝ ██║██████╔╝██║
  ╚══════╝╚═╝╚═╝     ╚═╝╚═════╝ ╚═╝

<div align="center">

A high-performance 3D relativistic magneto-gas dynamic code for astrophysical fluid simulations

Quick Start • Installation • Usage • Publications

</div>

---

[!NOTE] Research Impact: SIMBI powers seminal research published in The Astrophysical Journal and The Astrophysical Journal Letters, studying topics related to relativistic jets, relativisitc and non-relativistic shock morphology, and stellar explosions.

★ Overview

SIMBI enables state-of-the-art astrophysical fluid simulations with cutting-edge numerics and physics. From relativistic jets in active galactic nuclei to stellar explosions and magnetic turbulence, SIMBI handles the challenging physics of magnetohydrodynamics across both Newtonian and relativistic regimes.

Core Capabilities:

• Multi-Physics Regimes: Special Relativistic Magnetohydrodynamics (SRMHD), Special Relativistic Hydrodynamics (SRHD), and Newtonian Hydrodynamics
• High-Performance Computing: Native GPU acceleration for NVIDIA (CUDA) and AMD (HIP/ROCm) platforms
• Advanced Numerics: High-resolution shock capturing with multiple reconstruction schemes and Riemann solvers
• Flexible Boundaries: Immersed boundary method, dynamic meshes, and customizable boundary conditions
• Research-Ready: Python-driven configuration system with automatic CLI generation and type safety

---

🎬 Simulation Gallery

<div align="center">

| Relativistic Jet Evolution | Relativistic Shock Tube | Rayleigh-Taylor Instability | |:---:|:---:|:---:| | | | |

| Moving Mesh Techniques | Magnetic Turbulence | |:---:|:---:| | | |

</div>

---

▶ Quick Start

Get SIMBI running with the classic Marti & Müller relativistic shock tube problem:

<details> <summary><strong>🚀 5-Minute Setup (CPU)</strong></summary>

# 1. Install SIMBI with virtual environment
CC=gcc CXX=g++ python dev.py install --create-venv yes

# 2. Activate environment
source .simbi-venv/bin/activate

# 3. Run the classic test problem
simbi run marti_muller --mode cpu --resolution 400

# 4. Visualize results
simbi plot data/1000.chkpt.000_400.h5 --setup "Marti & Muller Problem 1" --field rho v p

</details> <details> <summary><strong>⚡ GPU Acceleration Setup</strong></summary>

For NVIDIA GPUs (V100 example with compute capability 7.0):

# Install with GPU support
CC=gcc CXX=g++ python dev.py install --gpu-compilation --dev-arch 70

# Run on GPU with higher resolution
simbi run marti_muller --mode gpu --resolution 1024

</details>

[!TIP] New to SIMBI? The Marti & Müller shock tube is a classic relativistic hydrodynamics test problem that demonstrates SIMBI's shock-capturing capabilities. It runs in seconds and produces publication-quality output.

---

📦 Installation

System Requirements

[!NOTE] Minimum Requirements: gcc ≥ 8 or clang ≥ 10, Python 3.10+, 8 GB RAM, Linux/macOS

Recommended: Latest stable compiler, Python 3.11+, 32+ GB RAM for large 3D simulations, Ubuntu 20.04+

Dependencies

SIMBI requires several core libraries and build tools:

• Build Systems: Meson, Ninja
• Libraries: pybind11, HDF5 libraries
• Python Packages: mypy, halo, pydantic, rich

<details> <summary><strong>⚙️ UV Package Manager (Recommended)</strong></summary>

For optimal dependency management, we recommend UV:

# Install UV (Unix-like systems)
curl -sSf https://install.astral.sh | sh

# Or with pip
pip install uv

UV provides faster dependency resolution and more reliable package management. When installed, SIMBI automatically detects and uses it.

</details>

Installation Options

Standard Installation:

CC=gcc CXX=g++ python dev.py install --create-venv yes

With Visualization Tools:

CC=gcc CXX=g++ python dev.py install --visual-extras --create-venv yes

<details> <summary><strong>🎯 GPU Compilation</strong></summary>

NVIDIA GPUs (specify compute capability without decimal):

# Example: V100 (compute capability 7.0)
CC=gcc CXX=g++ python dev.py install --gpu-compilation --dev-arch 70

# Example: A100 (compute capability 8.0)
CC=gcc CXX=g++ python dev.py install --gpu-compilation --dev-arch 80

AMD GPUs:

# Example: MI100 (gfx908)
CC=gcc CXX=g++ python dev.py install --gpu-compilation --gpu-platform hip --dev-arch gfx908

</details> <details> <summary><strong>🔧 Advanced Options</strong></summary>

# a bunch of features enabled
python dev.py install --create-venv yes --visual-extras --cli-extras --gpu-compilation --dev-arch 70

# Custom environment path
python dev.py install --create-venv yes --venv-path /custom/path

# View all options
python dev.py install --help

</details>

Environment Activation:

# After installation, always activate before use
source <wherever_you_instlled_simbi>/.venv/bin/activate

---

💻 Usage

Running Simulations

SIMBI uses a modern Python configuration system with automatic CLI generation:

# Basic usage
simbi run marti_muller --mode gpu --resolution 400 --adiabatic-index 1.4

# Full path (for custom configs)
simbi run simbi_configs/examples/marti_muller.py --mode cpu --resolution 1024

# With UV (recommended for isolation)
uv run simbi run marti_muller --mode gpu --resolution 512

[!NOTE] CLI Magic: SIMBI automatically generates command-line options from your configuration fields. Use simbi run <problem> --info to see all available parameters.

Global Options:

• --mode → Execution mode (cpu/gpu)
• --resolution → Grid resolution
• --adiabatic-index → Ratio of specific heats

Analysis & Visualization

# Plot simulation results
simbi plot data/1000.chkpt.000_400.h5 --setup "Marti & Muller Problem 1" --field rho v p

# Using UV
uv run simbi plot data/checkpoint.h5 --setup "Physics Setup" --field rho v p

Creating Custom Simulations

# Generate configuration template
simbi generate --name my_simulation

# Edit the generated file: simbi_configs/my_simulation.py
# Run your simulation
simbi run my_simulation --mode gpu

<details> <summary><strong>💡 UV Workflow Benefits</strong></summary>

Using UV with SIMBI provides:

• Faster dependency resolution - Up to 10x faster than pip
• Environment isolation - No conflicts with other Python projects
• Reproducible builds - Exact dependency versions across systems
• Conda compatibility - Works within existing conda environments

Shell Aliases (optional convenience):

# Add to .bashrc/.zshrc
alias simbi-run="uv run simbi run"
alias simbi-plot="uv run simbi plot"

</details>

---

⚛️ Physics & Configuration

Physics Regimes

[!IMPORTANT] SRMHD - Special Relativistic Magnetohydrodynamics Applications: AGN jets, pulsar wind nebulae, magnetic reconnection

SRHD - Special Relativistic Hydrodynamics Applications: Gamma-ray bursts, relativistic shocks, stellar explosions

Classical - Newtonian Hydrodynamics Applications: Stellar winds, ISM dynamics, classical turbulence

Modern Configuration System

SIMBI uses a type-safe, field-decorated configuration approach:

from pathlib import Path
from simbi.core.config.base_config import SimbiBaseConfig
from simbi.core.config.fields import SimbiField
from simbi.core.types.input import CoordSystem, Regime, Solver, BoundaryCondition

class KelvinHelmholtz(SimbiBaseConfig):
    """Kelvin Helmholtz instability in Newtonian fluid"""

    # Grid setup
    resolution: tuple[int, int] = SimbiField(
        (256, 256), description="Number of zones in x and y dimensions"
    )
    bounds: list[tuple[float, float]] = SimbiField(
        [(-0.5, 0.5), (-0.5, 0.5)], description="Domain boundaries"
    )

    # Physics configuration
    regime: Regime = SimbiField(Regime.CLASSICAL, description="Physics regime")
    solver: Solver = SimbiField(Solver.HLLC, description="Riemann solver")
    adiabatic_index: float = SimbiField(5.0/3.0, description="Ratio of specific heats")

    # Physical parameter