Configuration Guide

Comprehensive guide to configuring the simulation via config.py.

Configuration Overview

All simulation parameters are defined in config.py and can be customized by:

  1. Editing config.py directly (permanent changes)

  2. ImGui sliders (real-time, per session)

  3. Python API config_override (programmatic)

For detailed parameter reference, see Parameters.

File Structure

# config.py is organized into sections:

# 1. Integration & Timestep
DT = 0.001
SUBSTEPS = 4
INTEGRATOR = "leapfrog"

# 2. Physics Constants
COULOMB_K = 40.0
GRAVITY_G = 6.0
SPEED_OF_LIGHT = 30.0
USE_RELATIVITY = True

# 3. Forces & Fields
MAGNETIC_FIELD = (0.0, 0.0, 2.0)
E_FIELD = (0.0, 1.0, 0.0)

# 4. Rendering & Visualization
WINDOW_WIDTH = 2560
WINDOW_HEIGHT = 1600
TRAIL_LENGTH = 40

# 5. Presets
PRESETS = { "default": {...}, ... }

Common Configuration Scenarios

Scenario 1: Smooth motion at 1k particles

DT = 0.001                           # Keep physics accurate
SUBSTEPS = 4                         # More steps per frame
TRAIL_LENGTH = 40                    # Full trails (Phase 1 optimized)
COULOMB_K = 40.0                     # Normal Coulomb
GRAVITY_G = 6.0                      # Gentle gravity
MIN_TRAIL_SPEED_FOR_RENDER = 0.1     # All trails shown

# Expected: 8-15 FPS

Scenario 2: Very smooth motion, fewer particles (100)

DT = 0.0005                          # Very fine timestep
SUBSTEPS = 8                         # Many substeps
TRAIL_LENGTH = 80                    # Extra-long trails
COULOMB_K = 40.0
GRAVITY_G = 6.0

# Expected: 30-60 FPS

Scenario 3: Fast and loose, 2k particles

DT = 0.002                           # Faster timestep (less accurate)
SUBSTEPS = 2                         # Fewer steps
TRAIL_LENGTH = 20                    # Shorter trails (Phase 1 optimization)
COULOMB_K = 20.0                     # Reduce forces for stability
GRAVITY_G = 3.0
MIN_TRAIL_SPEED_FOR_RENDER = 0.2     # Skip slower particles

# Expected: 20-30 FPS

Scenario 4: High-energy collisions (LHC)

DT = 0.0005                          # Fine for accuracy
SUBSTEPS = 6
STRONG_FORCE_K = 50.0                # Strong force enabled
COULOMB_K = 40.0
USE_RELATIVITY = True                # Relativistic kinematics
PAIR_CREATION_THRESHOLD = 15.0       # High-energy pairs

# Expected: 5-15 FPS (many particles after collisions)

Scenario 5: Real-time exploration, GPU-limited

WINDOW_WIDTH = 1280                  # Cut resolution 40%
WINDOW_HEIGHT = 720
TRAIL_LENGTH = 10                    # Minimal trails
TRAILS_ENABLED_DEFAULT = False       # Start with trails off
SUBSTEPS = 2                         # Lower physics cost
BASE_PARTICLE_RADIUS = 0.1           # Smaller particles to render faster

# Expected: 30+ FPS even at 2k particles

Phase 1 Trail Optimization Guide

The TRAIL_LENGTH parameter is critical for performance. It controls:

  • Vertex count per particle (4 segments/particle/frame → vertices-rendered)

  • GPU memory for trail ring buffers

  • Trail “smoothness” and visual quality

Quick presets:

Use Case

TRAIL_LENGTH

Particles

Expected FPS

Notes

Smooth visualization

40

500

30+

Default; good for exploration

Moderate scaling

40

1k

10-15

Phase 1 baseline

Dense scenario

20

1k

20-30

Half trails, still smooth

Heavy scaling

10

1k

30-60

Sparse trails, acceptable

Extreme scaling

5

2k

20-30

Minimal trails, dense particles

Points only

1

5k

60

No trails; just particles

Tuning for Different GPU Capabilities

High-End GPU (RTX 3080+ or RX 6800+, 12GB+ VRAM)

WINDOW_WIDTH = 3840        # 4K rendering
WINDOW_HEIGHT = 2160
TRAIL_LENGTH = 100         # Very long trails
PARTICLE_RADIUS_SCALE = 1.0  # Show mass differences clearly
CAMERA_FOV = 45            # Narrower for detail
# Target: 2k-3k particles @ 60 FPS

Mid-Range GPU (RTX 2080 / RX 5700, 6-8GB VRAM)

WINDOW_WIDTH = 2560
WINDOW_HEIGHT = 1600
TRAIL_LENGTH = 40          # Phase 1 default
PARTICLE_RADIUS_SCALE = 0.45
CAMERA_FOV = 55            # Typical
# Target: 1k-1.5k particles @ 30 FPS

Entry-Level GPU (GTX 1660 / RX 6600, 2-4GB VRAM)

WINDOW_WIDTH = 1920
WINDOW_HEIGHT = 1080
TRAIL_LENGTH = 20          # Reduced
BASE_PARTICLE_RADIUS = 0.1
PARTICLE_RADIUS_SCALE = 0.3
# Target: 500-1k particles @ 30 FPS

Integrated GPU (Intel iGPU, 0.5-1.5GB shared VRAM)

WINDOW_WIDTH = 1280
WINDOW_HEIGHT = 720
TRAIL_LENGTH = 5           # Minimal
TRAILS_ENABLED_DEFAULT = False  # Start with trails off
SUBSTEPS = 1               # Single step per frame
# Target: 100-300 particles @ 30 FPS

Force Configuration Examples

Rutherford Scattering (strong Coulomb)

COULOMB_K = 80.0           # Strong repulsion
GRAVITY_G = 0.0            # NO gravity
STRONG_FORCE_K = 0.0       # NO strong force
# Interaction: Pure Coulomb only

Stable Orbital System

COULOMB_K = 0.0            # NO Coulomb (uncharged)
GRAVITY_G = 8.0            # Strong gravity
STRONG_FORCE_K = 0.0
# Kinematics: Pure gravitational

Magnetic Confinement (Cyclotron)

COULOMB_K = 0.0
GRAVITY_G = 0.0
MAGNETIC_FIELD = (0, 0, 5.0)  # Strong B-field in z
SYNCHROTRON_COEFF = 0.5    # Add damping
# Interaction: Lorentz force only

Balanced (Default)

COULOMB_K = 40.0           # Moderate
GRAVITY_G = 6.0            # Moderate
STRONG_FORCE_K = 0.0       # Off by default
# Interaction: Both EM and gravity

Physics Accuracy vs. Performance

Trade performance against accuracy:

For maximum accuracy:

DT = 0.0001                # Very small timestep
SUBSTEPS = 10              # Many steps per frame
INTEGRATOR = "leapfrog"    # Symplectic
USE_RELATIVITY = True      # Full relativity
# Trade-off: 2-3 FPS; scientific-grade

For interactive exploration:

DT = 0.001                 # Moderate
SUBSTEPS = 4
INTEGRATOR = "leapfrog"    # Still symplectic
USE_RELATIVITY = True
# Trade-off: 10-15 FPS; good balance

For speed (less accurate):

DT = 0.002                 # Larger timestep
SUBSTEPS = 1               # Single step
INTEGRATOR = "euler"       # Faster but drifts energy
USE_RELATIVITY = False     # Skip gamma correction
# Trade-off: 30+ FPS; visualization-grade

Camera & Rendering Configuration

Wide-angle view (cinematic):

CAMERA_FOV = 75            # Wide view
CAMERA_POS = (-10, 5, 25)  # Stand back
CAMERA_LOOKAT = (0, 0, 0)

Detailed inspection:

CAMERA_FOV = 30            # Narrow, zoom-like
CAMERA_POS = (2, 2, 8)     # Close-up
CAMERA_LOOKAT = (0, 0, 0)

Overview (teaching mode):

CAMERA_FOV = 60
CAMERA_POS = (0, 5, 20)    # Top view from distance

Color & Appearance

Dark mode (default):

BACKGROUND_COLOR = (0.01, 0.01, 0.03)  # Deep blue-black

Light mode:

BACKGROUND_COLOR = (0.9, 0.9, 0.95)    # Off-white

Custom theme:

BACKGROUND_COLOR = (0.1, 0.2, 0.3)     # Custom blue-green

Particle Appearance

Emphasis particle differences (by mass):

PARTICLE_RADIUS_SCALE = 1.0            # Show mass width
BASE_PARTICLE_RADIUS = 0.15            # Larger base

# Result: Protons 3x larger than electrons

Uniform appearance:

PARTICLE_RADIUS_SCALE = 0.0            # All same size
BASE_PARTICLE_RADIUS = 0.15

Minimal (fast):

BASE_PARTICLE_RADIUS = 0.05            # Tiny dots

Programmatic Configuration

Override config in Python:

from quantum_collider_sandbox.simulation import Simulation
from quantum_collider_sandbox import config

# Before creating sim, override
config.TRAIL_LENGTH = 20
config.COULOMB_K = 80.0

sim = Simulation(preset="lhc_pp", particles=50)
# Sim uses overridden values

Or use config_override parameter:

sim = Simulation(
    preset="lhc_pp",
    particles=50,
    config_override={
        "TRAIL_LENGTH": 20,
        "COULOMB_K": 80.0,
    }
)

Preset-Based Configuration

Presets are pre-packaged configurations for common scenarios. Edit in config.py:

PRESETS = {
    "my_custom": {
        "preset_name": "My Custom Setup",
        "initial_particles": 30,
        "coulomb_k": 50.0,
        "gravity_g": 2.0,
        "magnetic_field": (0, 0, 1.0),
        "dt": 0.001,
        "substeps": 4,
        "trail_length": 30,
    }
}

Then selectfrom ImGui “Presets” dropdown.

Testing Configuration Changes

Before running long simulations, test:

  1. Check energy conservation:

    make test

  2. Monitor FPS:

    • Run simulation with new config

    • Watch ImGui FPS display (left panel)

    • If < 20 FPS, reduce particles or TRAIL_LENGTH

  3. Check particle stability:

    • Watch for erratic motion (means forces too strong)

    • Check kinetic energy display (should stay roughly constant)

  4. Validation:

    • Run 100 timesteps

    • Export final state: Ctrl+S

    • Verify file created in data/exports/

Configuration Checklist

Before deep simulation work:

  • [ ] GPU drivers installed and working

  • [ ] Simulation target FPS chosen (20, 30, or 60)

  • [ ] Target particle count set (100, 1k, 2k)

  • [ ] TRAIL_LENGTH configured appropriately

  • [ ] Timestep (DT) and substeps (SUBSTEPS) chosen

  • [ ] Integrator (leapfrog recommended) selected

  • [ ] Forces configured (Coulomb, gravity, strong)

  • [ ] Relativity enabled/disabled appropriately

  • [ ] Window resolution appropriate for GPU

  • [ ] Data export directory exists (data/exports/, data/logs/)

  • [ ] Tests pass: make test

  • [ ] Linting clean: make lint

See Performance for detailed performance tuning. See Parameters for complete parameter reference.