Getting Started#

This guide walks you through installing and running ElectroSim on desktop and web platforms.

System Requirements#

Desktop Version#

  • Operating System: Windows, Linux, or macOS

  • Python: 3.x

  • RAM: Minimum 2 GB, recommended 4 GB+

  • Display: 1280×800 or higher resolution

  • GPU: Not required (CPU-only simulation)

Web Version#

  • Browser: Chrome 90+, Firefox 88+, Safari 15+, or Edge 90+

  • RAM: Minimum 300 MB available for browser tab

  • Internet: Required for first load (~50-60 MB download)

  • JavaScript: Must be enabled

  • WebAssembly: Must be supported (enabled by default in modern browsers)

Quick Start (Choose Your Platform)#

Option 1: Web Version (Easiest - No Installation)#

Try the live demo: https://electro-sim.vercel.app/

  1. Open the link in a modern browser

  2. Wait for Pyodide and packages to load (30-60 seconds first time)

  3. Click “Start Simulation”

  4. Place particles with mouse, control with keyboard

That’s it. No installation required.

Option 2: Desktop Version (Best Performance)#

Full installation with Python environment:

Step 1: Clone or Download Repository#

If using git:

git clone https://github.com/DannyLuna17/ElectroSim.git
cd ElectroSim

Or download and extract the ZIP file, then navigate to the directory.

Step 2: Create Virtual Environment#

Windows (PowerShell):

python -m venv .venv
.venv\Scripts\Activate.ps1

Linux/macOS (bash/zsh):

python3 -m venv .venv
source .venv/bin/activate

Note: If PowerShell execution policy prevents activation:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Step 3: Install Dependencies#

pip install -r requirements.txt

This installs:

  • pygame>=2.6.1 - Graphics and windowing

  • numpy>=2.0.0 - Numerical arrays and linear algebra

  • scipy - Scientific computing (special functions)

  • numba>=0.59 - JIT compilation for physics kernels

  • intel-cmplr-lib-rt - Intel compiler runtime (optional optimization)

Troubleshooting installation:

If pip fails to install, try:

pip install --upgrade pip
pip install -r requirements.txt

If Numba fails on your platform:

  • ElectroSim will fall back to pure NumPy (slower but functional)

  • Remove numba from requirements.txt if installation is problematic

Step 4: Run ElectroSim#

python main.py

A window should open with the simulation. You’ll see:

  • Dark background

  • One particle in the center

  • FPS counter and energy display in top-left corner

First run tips:

  • Use mouse to place particles (click and drag)

  • Press E to toggle electric field visualization

  • Press P to pause/resume

  • Press F to show force vectors

  • Press V to show velocity vectors

  • See controls below for full list

Platform-Specific Notes#

Windows#

ElectroSim was developed primarily on Windows. Everything should work out of the box.

If you encounter DLL errors:

Linux#

Python 3.x is usually available via package manager:

Ubuntu/Debian:

sudo apt update
sudo apt install python3 python3-pip python3-venv

Fedora:

sudo dnf install python3 python3-pip

Then follow standard installation steps.

Note on Numba: Linux usually has excellent Numba support via LLVM.

macOS#

Use Homebrew to install Python:

brew install python@3.11

Then follow standard installation steps.

Apple Silicon (M1/M2/M3/M4): Numba may have limited support on ARM architecture. If installation fails, remove numba and intel-cmplr-lib-rt from requirements and run without JIT acceleration (slightly slower but fully functional).

Running ElectroSim Locally (Web Version)#

You can run the web version on localhost for development or offline use:

Step 1: Navigate to Web Directory#

cd web

Step 2: Start Development Server#

python server.py

You should see:

ElectroSim Web Server
Serving at http://localhost:8000
Directory: C:\path\to\ElectroSim\web
Open http://localhost:8000
Press Ctrl+C to stop

Step 3: Open in Browser#

Navigate to http://localhost:8000 in your browser.

First load:

  • Status messages show package download progress

  • Pyodide (~7 MB)

  • NumPy (~15 MB)

  • SciPy (~25 MB)

  • pygame-ce (~5 MB)

  • Total time: 30-60 seconds depending on connection

After first load:

  • Browser caches all packages

  • Subsequent loads are fast (2-5 seconds)

Step 4: Start Simulation#

Click “Start Simulation” button when it becomes active.

Stopping the Server#

Press Ctrl+C in the terminal where server.py is running.

Verifying Installation#

Desktop Version#

After python main.py, you should see:

  1. Window opens (1280×800 pixels)

  2. Default scene loads with a few particles

  3. FPS display in top-left corner (should be ~60 FPS)

  4. Particle interactions visible (particles orbiting, attracting, repelling)

Test basic functionality:

  • Click to place a particle → New particle appears at click position

  • Shift+Click → Blue (negative) particle appears

  • Press E → Electric field grid appears

  • Press P → Simulation pauses

  • Press R → Scene resets to default

If all these work, installation is successful.

Web Version#

After clicking “Start Simulation”, you should see:

  1. Canvas activates with simulation rendering

  2. Default particles visible and moving

  3. FPS display in overlay (may be lower than desktop, 30-60 FPS typical)

  4. Responsive controls (click, keyboard)

Test basic functionality:

  • Click canvas to place particle

  • Press E to toggle field (may be slow with many particles)

  • Press P to pause

  • Press R to reset

If controls work and particles interact, web version is functional.

Building Documentation (Optional)#

Full documentation is pre-built in docs/_build/html/. To rebuild from source:

Step 1: Install Documentation Dependencies#

pip install -r docs/requirements-docs.txt

This installs:

  • Sphinx - Documentation generator

  • MyST-Parser - Markdown support in Sphinx

  • Furo theme - Clean modern Sphinx theme

  • Various Sphinx extensions

Step 2: Build HTML Documentation#

python -m sphinx -b html docs docs/_build/html

Build output will be in docs/_build/html/.

Step 3: Open Documentation#

Windows:

start docs/_build/html/index.html

Linux:

xdg-open docs/_build/html/index.html

macOS:

open docs/_build/html/index.html

Or manually navigate to docs/_build/html/index.html in your file browser.

Cleaning Documentation Build#

To rebuild from scratch:

python -m sphinx -M clean docs docs/_build
python -m sphinx -b html docs docs/_build/html

Updating the Web Deployment#

If you modify the desktop code and want to update the web version:

Step 1: Run Deployment Script#

python deploy_web.py

This copies the latest electrosim/ package to web/electrosim/.

Step 2: Test Locally#

cd web
python server.py
# Open http://localhost:8000 and test

Common Issues and Solutions#

Desktop Issues#

“No module named pygame/numpy/numba”

pip install -r requirements.txt

Make sure virtual environment is activated.

Window opens but is black/frozen

  • Update graphics drivers

  • Try disabling hardware acceleration

  • Check console for error messages

“ImportError: DLL load failed” (Windows)

  • Install Visual C++ Redistributable

  • Reinstall Python with “pip” and “tcl/tk” options enabled

Numba installation fails

  • Remove numba and intel-cmplr-lib-rt from requirements.txt

  • Install remaining packages: pip install pygame numpy scipy

  • ElectroSim will detect missing Numba and fall back automatically

Simulation is very slow (< 30 FPS with few particles)

  • Enable FIELD_SAMPLER_ENABLED = True in electrosim/config.py

  • Enable NUMBA_PARALLEL_ACCEL = True if Numba is installed

  • Disable field visualization (press E) for testing

  • Check Task Manager - close other CPU-intensive programs

Web Issues#

“Failed to load Pyodide”

  • Check internet connection

  • Try different browser

  • Clear browser cache and retry

  • Check browser console (F12) for specific error

Very slow loading

  • First load downloads ~50-60 MB

  • Check network speed

  • Subsequent loads use cache (much faster)

  • Consider using desktop version if network is unreliable

Keyboard doesn’t work

  • Click the canvas to focus it (white border appears)

  • Some browsers capture certain keys (F1, F11, Ctrl+W, etc.)

  • Check browser console for “KeyboardEvent” errors

Simulation crashes/freezes

  • Reduce particle count (< 20 recommended for web)

  • Close other browser tabs to free memory

  • Refresh page to reset

  • Try desktop version for better performance

Both Platforms#

Particles behaving strangely

  • Physics is deterministic; strange behavior is usually correct

  • Periodic boundaries cause wrapping (particles reappear on opposite side)

  • Press R to reset to known-good default scene

  • Check that you haven’t accidentally created overlapping particles

Energy not conserving

  • Small energy drift is normal (numerical error accumulation)

  • Large energy changes indicate collisions or merging

  • Opposite charges merge on contact (energy changes)

  • Check overlay: E_tot should be relatively stable over time

Next Steps#

Now that ElectroSim is running:

  1. Learn the controls: See User Guide → Controls

  2. Understand visualization: See User Guide → Visualization

  3. Configure settings: See User Guide → Configuration

  4. Explore the physics: See Developer Guide → Physics Overview

  5. Read the math: See Mathematical Foundations

Getting Help#

Documentation:

  • This guide and other docs in docs/

  • README files in project root and web/

  • Code comments and docstrings

Debugging:

  • Check console output for error messages

  • Enable PROFILE_OVERLAY_ENABLED = True to see performance metrics

  • Read Developer Guide → Validation for testing approaches

Performance tuning:

Happy simulating!