# MLiglon IGL Laboratory 2.0.1 — user guide

The laboratory is an interactive demonstration of **one two-input IGL node**. Load a Boolean function, vary the weights and inputs, and watch the arithmetic, activation curve, truth table and response surface agree. All calculations run in your browser.

The 2.0 interface uses the browser viewport directly. It does not inherit a WordPress theme's content width. On larger screens, parameters, the visualization and the inspector sit side by side; on smaller screens, the layout adapts so each control remains reachable.

## A five-minute first experiment

1. In **Choose a starting point**, choose **XOR**. The four Boolean outputs should read `0, 1, 1, 0`, ordered `00, 01, 10, 11`.
2. Drag the response surface to orbit around it. Try the top camera view to see how the response varies across the input square.
3. Move both inputs in **Probe the inputs** away from the corners, or select a point on the surface. Watch **Inspect** update the weighted sum, activation region and normalized output.
4. Select the **Activation** diagnostic. Its markers show why different input pairs end up on different segments of the same five-region function.
5. Choose **INT** (Fixed INT arithmetic), then try `P = 4`, `16`, `128` and `1024`. Keep proportional parameter rescaling enabled when you want to compare the same normalized model.
6. Open **Precision map** to compare quantized output against the real-valued reference. Change inputs as well as scale; exact Boolean corners alone do not reveal behavior between the corners.
7. Open **Train**, choose a different target and click **Randomize start**, then **Run search**. Watch the best error fall. Use **Restore start** to return to the start of that run.

## Interface regions

| Region | Purpose |
| --- | --- |
| Choose a starting point | All 16 two-input Boolean functions, plus graded examples |
| Shape the response | Weights, bias, activation scale, arithmetic mode and parameter rescaling |
| Probe the inputs | Choose a point in the input square without changing the four training examples |
| Response surface | Explore the response over the complete normalized input domain |
| Activation | Relate the weighted sum to the five activation regions |
| Cross-section | Inspect a one-dimensional slice through the surface at a selected live input |
| Precision map | Inspect the difference between fixed-integer evaluation and the real-valued reference |
| Inspect | Truth table, closest Boolean function and live arithmetic trace |
| Train | Bounded educational optimization of this one node against four examples |
| Guide | Explanations, controls and a walkthrough |

**Focus view** gives more of the viewport to the visualization. **Fullscreen** asks the browser to hide its surrounding UI; the browser can decline. The laboratory already fills its own tab without fullscreen permission.

## Node mathematics

Let the normalized input coordinates be `x₁, x₂ ∈ [0,1]`. The adjustable parameters are `W₁`, `W₂`, bias `B`, and positive scale `P`.

### Real mode

The weighted sum is:

```text
S = W₁x₁ + W₂x₂ + B
Y = f(S; P)
normalized output = Y / P
```

The activation is exactly the five-region function inherited from version 1.3.0:

| Weighted sum | Output | Region |
| --- | --- | --- |
| `S ≤ 0` | `0` | I — zero |
| `0 < S ≤ P` | `S` | II — rising |
| `P < S ≤ 2P` | `2P − S` | III — falling |
| `2P < S ≤ 3P` | `S − 2P` | IV — rising |
| `S > 3P` | `P` | V — plateau |

The output remains between `0` and `P`, so `Y/P` remains between `0` and `1`. The falling region lets a single node produce a non-monotonic response, which is central to the XOR and XNOR examples.

For XOR at `P = 16`, the preset uses `W₁ = 16`, `W₂ = 16`, `B = 0`. The four Boolean weighted sums are `0`, `16`, `16`, `32`. Applying the activation produces `0`, `16`, `16`, `0`, or normalized outputs `0,1,1,0`.

### Fixed INT mode

The demo quantizes input values and rounds the parameters:

```text
X₁ = round(clamp(x₁, 0, 1) × P)
X₂ = round(clamp(x₂, 0, 1) × P)
W₁, W₂, B = rounded parameter values
D = W₁X₁ + W₂X₂
S = round(D / P) + B
Y = f(S; P)
```

The trace displays the quantized inputs, products, normalization and activation. JavaScript `Math.round` is retained from version 1.3.0: exact halfway values round toward positive infinity, including negative ties. This is an explicit demo convention; a hardware implementation must use a matching rule if bit-for-bit agreement is required.

The browser uses JavaScript numbers for reference evaluation. The demonstration does not measure native integer SIMD instructions, C7x latency, energy, or physical memory traffic.

## What P means

Available values are **1, 2, 4, 8, 16, 32, 64, 128, 256, 512 and 1024**. P sets the activation breakpoints and the fixed-integer input/output scale. At `P = 1024`, each normalized input can take 1025 quantized values, including both endpoints.

With proportional rescaling enabled, changing P multiplies `W₁`, `W₂` and `B` by the new-to-old scale ratio. In Real mode, this preserves the normalized response mathematically. In Fixed INT mode, rounding and the new input lattice can change intermediate responses. With rescaling disabled, the numerical weights and bias remain fixed except where the allowed bounds require clamping, so changing P also changes the shape of the model.

**P and mesh density are separate controls.** A 64-by-64 visualization mesh samples a surface; P may still be 1024. Increasing P does not automatically create a 1024-by-1024 GPU mesh or a million training examples.

The **Precision map** evaluates 65 × 65 cell midpoints. Sampling midpoints avoids aligning every probe with the power-of-two input lattice at high P. Its blue-to-gold scale is relative to the maximum difference found in the current sample: compare the numerical mean and maximum when comparing P values. The displayed maximum is a sampled maximum, not a proven worst-case bound over all possible real inputs.

## Presets and truth tables

The 16 Boolean presets cover every two-input Boolean truth table. The four original graded examples explore partial and asymmetric responses between Boolean values. Presets are starting points; adjusting a parameter changes the model immediately.

The truth table always evaluates the four corners `(0,0)`, `(0,1)`, `(1,0)`, `(1,1)`. Moving the live input does not alter this table's evaluation coordinates. Select a table row to move the live input to that corner.

An **Exact** classification means all four normalized outputs match a Boolean truth table within numerical tolerance. A **Nearest** classification describes the closest Boolean table by average absolute error; it is not a probability, a confidence estimate or a test-set accuracy claim. Interior points may be graded even when the four corners are exactly Boolean.

## 3D controls

| Control | Action |
| --- | --- |
| Drag with a mouse or one touch | Orbit the camera |
| Mouse wheel or two-finger pinch | Zoom |
| Shift + drag | Pan |
| Hover over the surface | Inspect a sample |
| Click a surface point | Select its inputs for the live node |
| Arrow keys with the canvas focused | Orbit using the keyboard |
| `+` / `−` with canvas focus | Zoom using the keyboard |
| Reset camera / Home with canvas focus | Restore the initial view |
| Camera presets | Jump to a standard orientation |
| Auto orbit | Animate rotation until disabled |

The toolbar and **View options** provide orthographic/perspective projection, six color palettes, mesh densities through 192, wireframe, shading, floor grid, coordinate axes and labels, a live marker and cross-sections. The optional **Real reference mesh** overlays the same stored parameters evaluated without integer rounding. Color encodes normalized output; the legend remains tied to `Y/P` from 0 to 1.

The mesh joins sampled values with triangles. Fixed-integer evaluation contains jumps that a finite mesh can display as short sloping faces. Exact inspected values are computed by the reference core, not inferred from a rendered color or an interpolated triangle. For precision comparisons, use the numerical trace and the precision diagnostic alongside the surface.

The renderer uses native WebGL with no external 3D library dependency. If WebGL is unavailable, the application presents a Canvas fallback and retains the mathematical controls. WebGL may be implemented in hardware or software by the browser; the demo does not infer hardware performance from rendering success.

## Enhanced single-node training

Training operates on **three parameters** (`W₁`, `W₂`, `B`) and **four Boolean examples**. P and the arithmetic mode stay fixed during a run. The target is one of the 16 Boolean functions, and the objective is mean squared error:

```text
MSE = ((y₀₀ − t₀₀)² + (y₀₁ − t₀₁)²
     + (y₁₀ − t₁₀)² + (y₁₁ − t₁₁)²) / 4
```

Here each `y` is the normalized output `Y/P` and each target `t` is 0 or 1. The evaluation counter counts parameter candidates; each candidate is scored on all four rows.

### Local search

Local search tries the positive and negative direction of each parameter, up to six in-range candidates. It accepts the best strict improvement. The default step is one integer in Fixed INT mode and `P/4` in Real mode. **Step** and **×10** always use this local six-neighbor method, regardless of which method is selected for **Run search**. Each button starts a new displayed batch; ×10 stops early when it finds no improvement or solves the target.

A local plateau means none of the tested changes improved the objective. It does not establish that the requested Boolean function is impossible. The non-monotonic activation and saturation regions can make small coordinate moves ineffective.

### Multiscale search

The extended search tests joint three-parameter changes, up to 26 neighbors in a poll. It begins with a step of P and reduces the step when needed, down to 1 in Fixed INT mode or `P/256` in Real mode. Seeded coarse-lattice restarts let it explore a different part of the allowed parameter range after a stall. It retains the best candidate found so far.

A run is bounded by the selected candidate budget and a restart limit. The default restart limit is 32; a validated imported experiment may supply a different bounded limit, which is retained with the saved search settings. Repeating the same starting node, target, seed, algorithm and limits reproduces the search sequence. The algorithm evaluates candidates; it does not silently substitute the target preset.

**Run search** executes bounded work in a Web Worker where available so camera interaction and controls can remain responsive. A time-sliced fallback is used if a worker cannot run. **Stop** ends the active search and retains the best result received so far. Switching to a different browser tab or otherwise hiding this page also stops an active search. Returning to the page does not resume it automatically; use Run search to begin a new run. **Restore start** returns to the node saved at the beginning of the last run or local-step batch. The progress chart shows the best objective reached, so it should not rise as exploratory restarts occur.

A solved four-row truth table is the educational goal. The laboratory has no multilevel network, no dataset upload, no general-purpose model training, and no train/test generalization claim. WebGL accelerates the display; this release uses the JavaScript reference arithmetic for search scoring rather than presenting GPU scoring as an assumed speed improvement for four examples.

## Appearance and accessibility

**Appearance** contains the original light and dark themes plus additional choices, a broader font selection and text-size controls. Noto Sans, Noto Serif and Noto Sans Mono are bundled for offline use. Named IBM Plex/system font choices use local font matching with fallbacks if that specific family is not installed.

Preferences are remembered in this browser when local storage is allowed. Private browsing settings, cleared site data or browser policies can remove or block persistence. Use configuration export when you need a portable experiment.

Ordinary controls retain native keyboard behavior. Contextual help buttons and the Guide explain the mathematics and display options. Motion is optional; auto orbit is disabled by default. If large text leaves less room for panels, use Focus view or a taller window and scroll the controls as needed.

## Save, share and export

Use **Save / share** for the supported experiment outputs:

- **Configuration JSON:** save node parameters, live inputs, target, rescaling preference, view options, appearance/layout preferences, and the current algorithm, budget, seed and restart limit. Imports validate recognized fields before applying them. The JSON does not save camera rotation/zoom, a pinned baseline, undo history or the completed search history.
- **Truth-table CSV:** export the four Boolean rows, P, mode, weights, bias, weighted products, S, raw Y, normalized output, activation region and selected target values.
- **Sampled surface CSV:** export 4,225 rows on a 65 × 65 grid including the endpoints. Each row records requested coordinates, the effective evaluated coordinates, model parameters, S, Y, normalized output and region. In INT mode several requested coordinates can snap to the same effective coordinates. This endpoint grid differs deliberately from the midpoint sampling in Precision map; neither export enumerates every possible real input.
- **PNG:** save the response visualization as an image.
- **Search history CSV:** export candidate-evaluation counts and best MSE. Multiscale runs record the initial result and improvements, rather than logging every rejected candidate; local-step batches record their iteration results.
- **Copy configuration and table:** obtain a readable record for a document or discussion.
- **Copy experiment link:** encode numerical node settings, live inputs, target and rescaling preference in the URL fragment for another tab or another person to open. Appearance, view options, camera position, search controls and history are not included in this compact link. A copied link is not sent automatically.
- **Save to browser / Restore:** keep an experiment in the current browser's local storage when permitted.

Downloads, clipboard actions and browser persistence can be limited by browser policy. The interface reports failures it can detect. A download request means the browser was asked to save the file; browser policy still controls its final destination and completion. An imported JSON file is read locally; the demo does not upload its contents to a training server.

## Compare and undo

The toolbar offers **Undo** and **Redo** for model changes. In **Inspect**, use **Pin current as baseline** to retain a numerical snapshot, edit the live model, and compare the four outputs and target error. **Restore baseline** reapplies that snapshot. A pinned comparison is separate from the current live input marker on the 3D surface.

## Useful demonstrations

### Find XOR's falling region

Load XOR and compare `(1,0)`, `(0,1)` and `(1,1)`. All use the same activation. The first two land on its peak; the last reaches the falling segment's endpoint. Follow the markers on the Activation plot.

### Show quantization at small P

Load a graded example, use Fixed INT, and choose `P = 2` or `4`. Move the inputs slowly. The effective inputs and outputs change in discrete jumps. Repeat at P1024 and inspect the numeric trace rather than assuming every visual jump remains large enough to see.

### Compare a plateau with a restart

Choose a target unlike the starting node. First attempt local steps; when no strict improvement is available, restore the starting model and run multiscale search with a fixed seed. Compare the candidate counts and objective history. A faster result here is a property of this small example, not a general hardware or training-speed benchmark.

## Scope and references

The implementation preserves the mathematical node demo supplied in version 1.3.0, including its five-region activation and fixed-integer convention. The user interface identifies the cited MLiglon patent numbers for context. This browser application is not the complete patented IGL training system, a patent claim interpretation, or a reproduction of an embedded deployment.

For installation and WordPress linking, see [INSTALL.md](INSTALL.md). For feature migration details, see [PARITY-REVIEW.md](PARITY-REVIEW.md). For measured checks of this release, read the packaged test report.

## Additional search and probe controls

**Maximum restarts** in Train sets the cap for multiscale restarts (0, 4, 8, 16, 32, 64 or 128). Local search does not restart. A bounded custom limit or budget in an imported JSON file is retained and shown in its selector.

**Clear pinned probe** in View options removes the selected surface highlight while retaining the current live input coordinates. Reset display options also clears the pin.

Surface PNG exports include the version, parameters, arithmetic mode, effective live inputs, output, mesh dimensions and an interpolation note.