MagnetSim Manual

1. Overview

MagnetSim models a grid of magnetic needles that interact with their neighbors and tend to align. Local ordering can produce domains, transitions between patterns, and other emergent behavior. Pin needles, change the grid, zoom and pan, or inject disorder and heat to explore how the field responds.

This browser version runs entirely on your device. WebAssembly or TypeScript performs the physics; the selected graphics backend draws the field. No simulation server is needed.

2. How it works

Each cell contains one needle that can rotate in two dimensions. It interacts with its eight immediate neighbors—the Moore neighborhood.

Torque changes angular velocity. Friction removes velocity each simulation step, and MIN_SPEED stops very small motions. PHYS_RND varies the friction coefficient. This is a discrete rotational model, not an energy-conserving physical integrator.

Rotation speeds are measured in degrees per simulation step. Target FPS and Steps / frame together control how quickly simulated time advances. Raising Steps / frame does more physics work before the next drawing; it does not change the size of a physics step.

Architecture

The simulation stores angles, velocities, and pin/motor flags in arrays. Configuration provides the physics, appearance and interaction parameters. A controller schedules physics and rendering and handles pause, restart and view changes. The original program used NumPy, a Config class and a Pygame event loop; the browser port preserves the discrete model while replacing those runtime components.

3. Interface

The field

Each line rotates around a small gray pivot. Stationary needles are white by default. Moving needles progress through cyan, blue, magenta, red and yellow as their speed increases. Color changes can be switched off. Active border needles can use a separate fixed color.

Status and controls

The top status strip shows Running, Paused or Settled, the step count, achieved and target FPS, steps per frame, grid dimensions and CPU timing. Desktop velocity statistics follow CPU timing in the top strip; mobile hides them. The desktop’s left pane contains playback and view controls, plus the keyboard/mouse legend. The Disorder and Heat buttons show the size of the next kick.

Configuration opens the editor. Configuration → Advanced → Compare backends runs explicit local comparisons on a separate field while preserving your simulation. Manual opens this guide and pauses the simulation until you close it.

On mobile, Pause / Resume, Step and Restart stay at the top. Open Controls for pacing, Disorder, Heat and zoom / Fit field. This pulldown overlays the field; close it with Controls, an outside tap or Escape. The two selectors below the field choose the touch tool and brush. All configuration groups remain available in portrait and landscape.

4. Controls

Keyboard and view

The original manual reversed the meanings of x/X and y/Y. The table above matches the implementation. Navigation keys repeat while held; shortcuts do not interfere with typing in configuration fields.

Mouse

• Left hold: temporarily pin needles and aim them toward the pointer. Without Option/Alt, this also unlocks user-created permanent pins.
• Option/Alt + left hold: permanently freeze needles.
• Right hold: accelerate needles clockwise. Hold Option/Alt for counter-clockwise rotation.
• Shift: enlarge the normal 3×3 brush to 5×5.
• Release: release temporary pins and motors; permanent configuration and user locks remain.

Configured borders stay protected. A border frozen by INIT_MODE cannot be unlocked or rotated with the mouse or touch tools. Change its initialization rule and restart instead.

Touch

Choose Navigate, Hold / aim, Freeze, Unfreeze, Spin clockwise or Spin counter-clockwise. Brush sizes are 1×1, 3×3 and 5×5. In Navigate mode, drag to pan. Two fingers pan and pinch to zoom; adding a second finger cancels manipulation before navigating. Interrupted touches and backgrounding release temporary interaction.

Freeze borders

Freeze borders (Freeze Brdr on mobile) holds currently rotating configured borders at their current angles while the field continues. Unfreeze restores each previous speed and direction. Stationary borders are unchanged. Restart or changing rows/columns clears the temporary freeze; it is not saved in configuration files.

Disorder and heat

D or Disorder adds random angle offsets, initially ±20° by default. R or Heat adds random velocity offsets, initially ±10 degrees/step. Repeating an action within the default two-second combo window increases the next kick, up to its configured maximum. Pins and motors are protected from these random kicks.

5. Configuration

Use the Configuration editor to change parameters. Most edits apply live; initialization rules wait for Restart. Resizing preserves overlapping state and reapplies the active border rules. Appearance-only edits leave a settled field stopped.

Save, load and files

The last committed configuration and named presets are stored in this browser’s site data. Save status and storage errors appear inside Configuration. Wait for the saved status before closing. Load & restart applies a preset. Import file accepts JSON or original-style text files; Export JSON and Export text save the current configuration. These files contain settings, not a snapshot of the running field.

Text files use NAME = VALUE with # comments. Export text always includes hardcoded comments from the original config.txt; imported comments are ignored. Some historical comments describe the original desktop window or use older units; this guide describes browser behavior. Mobile uses the system share sheet when available, otherwise a file download. Clearing site data removes browser saves.

The original command python3 magnet-sim.py -c my_settings.txt belongs to the Python application. In the browser, use Import file instead.

Grid and physics

ROWS · COLS

Grid height and width, in needles.

DX · DY

Physical spacing. Changes the distance-dependent interaction strength.

COUPLING_CONSTANT

Master interaction strength. Larger values produce stronger, faster alignment; lower values allow weaker ordering. Its effect depends on spacing and DISTANCE_EXPONENT.

FRICTION · MIN_SPEED

Velocity removed per step and the threshold below which motion stops.

DISTANCE_EXPONENT

Power-law decay with distance; default 3.

PHYS_RND

Friction randomness, from 0 to 100 percent.

Appearance and pacing

USE_GUI

Draw the field. When disabled, physics and status continue.

NEEDLE_LENGTH

Needle half-length; 0 uses one third of the smaller grid spacing.

SCALE

Explicit zoom value. Automatic fitting overrides the view at the triggers listed above.

FPS · SIM_STEPS_PER_FRAME

Target frame rate and physics steps per frame. FPS 0 pauses.

COLOR_CHANGES · ZERO_SPEED_COLOR

Enable speed colors and choose the stationary/fixed needle color.

COLOR_RANGE

Speed corresponding to the top of the color gradient. 0 automatically uses the maximum speed in the field.

SHOW_BORDER_COLOR · BORDER_COLOR

Give active pinned/motorized border needles a fixed color.

Interaction and randomization

SCROLL_FRACTION · KEY_REPEAT_RATE

Viewport fraction moved per pan action and repeats per second for held keys.

MOUSE_ROTATE_SPEED

Legacy right-button acceleration: each frame adds speed × (1 / FPS) / steps per frame. The paused fallback uses 0.033 seconds.

MOUSE_ROTATE_START_ANGLE

Math angle measured from the right when a temporary motor starts. Use −1 to preserve the existing angle.

RND_ANGLE_DEFAULT · RND_VEL_DEFAULT

First Disorder and Heat kick sizes.

RND_ANGLE_MAX · RND_VEL_MAX

Maximum kick sizes.

RND_ANGLE_MULT · RND_VEL_MULT

Multipliers for repeated kicks.

COMBO_WINDOW

Seconds allowed between combined kicks.

Advanced

At the bottom of Configuration, expand Advanced for Renderer, Physics engine, Rendering quality and Compare backends. Switch renderers or CPU physics backends without restarting the field. WebGL2 and WebAssembly are the initial choices where supported; Canvas 2D and TypeScript provide fallbacks. Explicit quality settings control framebuffer resolution. Desktop and mobile backend/quality preferences are stored separately. Experimental backends and CPU/GPU timing results are labeled; timing alone is not a power measurement.

6. Initialization rules

INIT_MODE is an ordered, comma-separated list. Edit and reorder its rules in Configuration, then Restart to apply them. The Example dropdown beside Advanced text rules contains the six original config.txt examples. Selecting one fills the text and rule controls without restarting. Other values display Custom. Later rules can override earlier border settings, including corners.

Use top, bottom, left, right or all for LOCATION. Combine names with underscores, such as left_top. Positive angles/speeds are clockwise, negative values counter-clockwise. The optional _rnd suffix chooses values between 0 and X.

Examples

1. Original · frozen left

angle_90, border_freeze_left_0, rotate_-10

2. Tilted · driven top

angle_-45, rotate_+5, border_rotate_top_2, border_freeze_left_90

3. Driven left and top

border_rotate_left_top_5

4. Random opposing borders

angle_360_rnd, border_rotate_left_3_rnd, border_rotate_top_-3_rnd, border_rotate_right_-3_rnd, border_rotate_bottom_+3

5. Horizontal · driven top/bottom

angle_90, border_rotate_left_0,border_rotate_top_5, border_rotate_bottom_5, border_rotate_right_0

6. Frozen sides · slow borders

angle_90,border_freeze_left_right_0,border_freeze_top_90,border_rotate_top_bottom_0.1