electrosim.simulation.engine#

Classes

Particle(id, pos_m, vel_mps, mass_kg, ...[, ...])

Simulated charged particle in a 2D periodic domain.

Simulation()

Simulation orchestrator for N-body Coulomb dynamics.
class Particle(id, pos_m, vel_mps, mass_kg, charge_c, radius_m, fixed=False, color_rgb=(255, 255, 255), history=<factory>)[source]#

Bases: object

Simulated charged particle in a 2D periodic domain.

Parameters:

  • id (int)

  • pos_m (ndarray)

  • vel_mps (ndarray)

  • mass_kg (float)

  • charge_c (float)

  • radius_m (float)

  • fixed (bool)

  • color_rgb (Tuple[int, int, int])

  • history (Deque[Tuple[float, Tuple[float, float]]])

id#

Unique identifier within the current particle list.

Type:

int

pos_m#

Position in meters.

Type:

numpy.ndarray shape (2,)

vel_mps#

Velocity in meters per second.

Type:

numpy.ndarray shape (2,)

mass_kg#

Mass in kilograms.

Type:

float

charge_c#

Charge in Coulombs.

Type:

float

radius_m#

Collision/visual radius in meters.

Type:

float

fixed#

If True, particle does not move (treated as infinite mass during collisions).

Type:

bool

color_rgb#

Display color based on charge sign or neutrality.

Type:

tuple[int, int, int]

history#

Time-stamped positions for trajectory rendering.

Type:

collections.deque[(float, (float, float))]

id: int#
pos_m: ndarray#
vel_mps: ndarray#
mass_kg: float#
charge_c: float#
radius_m: float#
fixed: bool = False#
color_rgb: Tuple[int, int, int] = (255, 255, 255)#
history: Deque[Tuple[float, Tuple[float, float]]]#
class Simulation[source]#

Bases: object

Simulation orchestrator for N-body Coulomb dynamics.

Drives particles and world parameters, advances time, computes energies, maintains selection and visualization state, and exposes frame/substep stepping consistent with the rendering loop.

reset_to_default_scene()[source]#

Reset to a single particle at world center with default properties.

Side effects: clears particles and timers, adds a new particle with default charge/mass/radius, recomputes energies, and resets selection.

Return type:

None

clear()[source]#

Remove all particles and reset timers, energies, selection, and forces.

Return type:

None

add_particle(pos_m, vel_mps, charge_c, mass_kg, radius_m, fixed)[source]#

Create and append a particle with clamped properties and charge-derived color.

Parameters:

  • pos_m (numpy.ndarray shape (2,)) – Initial position (m).

  • vel_mps (numpy.ndarray shape (2,)) – Initial velocity (m/s).

  • charge_c (float) – Charge (C), clamped to [MIN_CHARGE_C, MAX_CHARGE_C].

  • mass_kg (float) – Mass (kg), clamped to [MIN_MASS_KG, MAX_MASS_KG].

  • radius_m (float) – Radius (m), clamped to [MIN_RADIUS_M, MAX_RADIUS_M].

  • fixed (bool) – If True, particle starts fixed.

Return type:

None

select_particle_at_screen_pos(px, py)[source]#

Select the nearest particle under a screen pixel within a small radius.

Parameters:

  • px (int) – Screen pixel coordinates.

  • py (int) – Screen pixel coordinates.

Return type:

None

adjust_selected_charge(delta_c)[source]#

Adjust charge of selected particle by delta_c (C), clamped to config range.

Parameters:

delta_c (float)

Return type:

None

adjust_selected_mass(delta_kg)[source]#

Adjust mass of selected particle by delta_kg (kg), clamped to config range.

Parameters:

delta_kg (float)

Return type:

None

adjust_selected_radius(delta_m)[source]#

Adjust radius of selected particle by delta_m (m), clamped to config range.

Parameters:

delta_m (float)

Return type:

None

toggle_selected_fixed()[source]#

Toggle fixed/mobile state of the currently selected particle (if any).

Return type:

None

remove_selected_particle()[source]#

Remove the selected particle and reassign sequential `id`s to the remainder.

Return type:

None

recompute_energies()[source]#

Recompute kinetic, potential, and total energies from current state.

Return type:

None

update_trails(sample_interval_s)[source]#

Append particle positions to trails if sample_interval_s has elapsed.

Old entries older than TRAJECTORY_HISTORY_SECONDS are pruned.

Parameters:

sample_interval_s (float)

Return type:

None

step_substep(dt_s)[source]#

Advance the simulation by one substep of duration dt_s.

Performs RK4 integration, wraps positions, resolves collisions, wraps again, and validates selection index.

Parameters:

dt_s (float)

Return type:

None

step_frame()[source]#

Advance the simulation by a frame worth of substeps based on speed.

Runs physics integration per substep, then once-per-frame visual-only work: trails, energies, and force caching (optional). t_sim accumulates substep time.

Return type:

None

start_uniform_field_validation()[source]#

Set up and launch the uniform-field validation scenario.

Creates a single particle at the world center with zero initial velocity, enables a constant uniform field for both physics and visualization, precomputes the analytical trajectory, and prints a summary table. Runtime errors vs analytical are updated each frame.

Return type:

None

stop_validation()[source]#

Disable uniform-field validation and restore defaults.

Return type:

None