IsingForge Engine

IsingForge Engine is a GPU-accelerated, continuous-time heuristic solver for combinatorial optimization problems, specifically targeting Max-Cut and Quadratic Unconstrained Binary Optimization (QUBO) formulations.

Built with Rust, wgpu, and egui, the engine executes massively parallel phase-relaxation dynamics directly on the GPU via Compute Shaders (WGSL), offering real-time visualization and high-throughput computation directly in the browser or natively.

Algorithmic Architecture

The algorithm is a deterministic, physics-inspired heuristic. It utilizes a continuous-time relaxation method with custom variables (such as local stress, confidence bounds, and inelastic collision penalties) to escape local minima and navigate complex graph topologies.

The engine represents each node as a continuous phase bounded between [-1.0, 1.0]. The state update logic per tick follows these principles:

1. Local Field Calculation: Evaluates the aggregate force exerted by neighboring nodes and local QUBO biases.
2. Stress Building: Nodes accrue frustration proportional to the Hamiltonian energy penalty of their current state.
3. Phase Update: An acceleration vector is calculated based on the local field, a bifurcation pull, and injected thermal noise.
4. Inelastic Boundaries: Nodes lose kinetic energy upon hitting the strict phase boundaries (-1.0 or 1.0), preventing unbounded oscillations and dampening artificial volatility.

Key Features

• GPGPU Acceleration: The core solver is written in WGSL, executing compute passes in parallel across graph nodes using ping-pong memory buffers to eliminate data transfer bottlenecks.
• Max-Cut & QUBO Support: Native parsing of standard formats with an integrated translation layer that maps QUBO matrices into local magnetic fields for the Ising model.
• Real-Time Telemetry: The UI provides live monitoring of the system temperature, kinetic agitation, and graph cut optimization progress.
• Cross-Platform: Compiles to native desktop applications and WebAssembly (WASM) for execution in modern WebGPU-enabled browsers.

Installation & Usage

Prerequisites

• Rust toolchain (cargo)
• A system with Vulkan, Metal, or DX12 support (for native builds), or a WebGPU-compatible browser (e.g., Chrome, Edge).

Running in the Browser (WebAssembly)

The recommended way to run IsingForge is through the browser using Trunk.

1. Install the WASM target and Trunk:

rustup target add wasm32-unknown-unknown
cargo install trunk

2. Serve the application locally:

trunk serve --release

Open the provided localhost URL in a WebGPU-enabled browser. (Note: --release is required for the heuristic engine to run at a stable framerate).

Datasets and Interaction

You can test the engine using standard Max-Cut datasets. The Stanford G-Set is a recognized benchmark and is highly recommended for evaluating the solver's performance. You can download the G-Set datasets here: Stanford G-Set Repository

1. Load Data: Use the UI to import a .txt file (e.g., G1.txt from the Stanford repository) or a QUBO matrix.
2. Tune Hyperparameters: Adjust Base Friction, Inhibition Weight, and Noise Multiplier in the control panel to control the annealing schedule.
3. Export: Once the graph reaches a stable low-energy state, export the separated phase groups directly to your clipboard or a text file.

License

This project is licensed under the GNU General Public License v3.0.

You are free to use, modify, and distribute this software, provided that any derivative works are also made open-source under the same GPLv3 license.