ElectroSim

Welcome to the ElectroSim documentation. This site provides:

• A user guide to run and operate the simulation

• A developer guide focused on architecture, physics, and performance

• A complete API reference generated from source

• Mathematical foundations with LaTeX derivations

• Annotated, line-by-line explanations for each function

User Guide

• Getting Started
  • System Requirements
  • Quick Start (Choose Your Platform)
  • Platform-Specific Notes
  • Running ElectroSim Locally (Web Version)
  • Verifying Installation
  • Building Documentation (Optional)
  • Updating the Web Deployment
  • Common Issues and Solutions
  • Next Steps
  • Getting Help
• Running the Simulation
  • Basic Launch
  • Window Configuration
  • Time Integration
  • Default Scene
  • Performance Monitoring
  • Related Documentation
• Controls
  • Mouse
  • Keyboard
• Visualization
  • Particle Rendering
  • Electric Field Visualization
  • Force Vectors
  • Velocity Vectors
  • Particle Trajectories
  • Metric Grid
  • Overlay Information
  • Background and Theme
  • Performance Considerations
  • Related Documentation
• Configuration
  • Window and Display
  • Physics Parameters
  • Particle Defaults and Limits
  • Visualization Settings
  • Performance Options
  • Interaction Settings
  • Validation Settings
  • Configuration Workflow
  • Web Version Overrides
  • Performance Tuning Guide
  • Related Documentation
• Running ElectroSim on the Web
  • Quick Start
  • What Runs in the Browser
  • Keyboard and Mouse Controls
  • Differences vs Desktop
  • Troubleshooting

Developer Guide

• Architecture
  • Overview
  • Modules and responsibilities
  • Dependency diagram
  • Data Flow
  • Design Patterns
  • Extension Points
  • Error Handling
  • Platform-Specific Adaptations
  • Testing Strategy
  • Related Documentation
• Physics Overview
  • Units and Domain
  • Force Model
  • Time Integration Pipeline
  • Collisions and Merging
  • Boundary Handling
  • Energy Accounting
  • Field Evaluation and Visualization
  • Validation Hooks
  • Related Modules
• Performance Notes
  • Built-in Profiling
  • Cost Drivers
  • Tuning Workflow
  • Batch Experiments
  • Browser Considerations
• Validation
  • Uniform Field Scenario
  • How to Run It
  • Reading the Overlay
  • Customising the Scenario
  • Automating from Code
• Web Integration (Pyodide + pygame-ce)
  • Components and Data Sources
  • Keyboard Input Bridging
  • Field Sampling Fallback
  • Expected Behavior (Web)
  • Limitations
  • Debugging Tips

API Reference

• API Reference
  • electrosim
  • electrosim.config
  • electrosim.simulation.engine
  • electrosim.simulation.physics
  • electrosim.rendering.primitives
  • electrosim.rendering.particles
  • electrosim.rendering.field
  • electrosim.rendering.field_sampler
  • electrosim.rendering.trails
  • electrosim.rendering.overlay
  • electrosim.rendering.draw
  • electrosim.ui.controls
  • main

Mathematical Foundations

• Coulomb Force with Periodic Boundary Conditions
• Plummer-like Softening
• RK4 Derivation
• Elastic Collision Impulse
• Potential Energy Modeling
• Field Visualization Mapping
  • Brightness mode
  • Length mode

Annotated Source (Line-by-line)

• Annotated: electrosim.simulation.physics
  • minimum_image_displacement
  • electric_force_pair
  • compute_accelerations (Numba path shape and algorithm)
  • total_potential_energy
  • rk4_integrate (stages and state policy)
  • resolve_collisions (merge and elastic phases)
• Annotated: electrosim.simulation.engine
  • Particle dataclass
  • Simulation.init
  • reset_to_default_scene
  • clear
  • add_particle
  • _update_color
  • select_particle_at_screen_pos
  • adjust_selected_charge/mass/radius
  • toggle_selected_fixed
  • remove_selected_particle
  • recompute_energies
  • _wrap_all_positions
  • _ensure_selected_valid
  • _compute_last_forces
  • update_trails / _advance_time_and_trails
  • step_substep
  • step_frame
• Annotated: electrosim.rendering.primitives
  • world_vector_to_screen / screen_vector_to_world
  • _draw_arrow
  • draw_meter_grid
  • draw_glow_at_screen_pos
• Annotated: electrosim.rendering.field
  • _get_sampler
  • draw_field_grid
• Annotated: electrosim.rendering.field_sampler
  • ElectricFieldSampler
  • _grid_dims
  • recompute
  • iter_centers_and_vectors_px
• Annotated: electrosim.rendering.particles
  • draw_particles
  • draw_velocity_vectors
  • draw_force_vectors
  • draw_particle_glows
• Annotated: electrosim.rendering.trails
  • draw_trails
• Annotated: electrosim.rendering.overlay
  • draw_overlay
• Annotated: electrosim.ui.controls
  • InputState
  • handle_events
  • render_placement_preview
  • render_hover_tooltip
• Annotated: main.py
  • main