# IPT illustrative Python tools

Maintenance refresh: 21 November 2026.

These small examples explore prescribed diffusion rules, normalized field
entropy, and a fixed six-qubit graph state. They illustrate concepts discussed
by the Informational Projection Theory project. They do not derive physical
spacetime, establish the theory, or constitute empirical validation.

## Install

Python 3.11 or 3.12 is recommended. Use a virtual environment and install the
requirements from the extracted toolkit directory.

Linux/macOS:

```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
```

Windows, without requiring environment activation:

```powershell
py -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
```

In the commands below, use your environment's Python interpreter. On Windows
without activation, replace `python` with `.\.venv\Scripts\python.exe`.

The GUI requires Tkinter and a graphical desktop. Tkinter is supplied by many
desktop Python installations; Linux distributions may package it separately,
often as `python3-tk`. It is not installed through this requirements file.
The command-line examples can save their figures without a desktop.

The diffusion tools need NumPy, Matplotlib, and Pillow. Qiskit is needed only
for the six-qubit example. Neither Qiskit Aer nor a cloud account/API key is
needed. SciPy, NetworkX, and pandas are no longer imported by these scripts.

## 1. Whole-grid and observer-window Shannon entropy

```bash
python ipt_entropy_simulator.py --init spike --grid 60 --steps 150 --alpha 0.2 --obs 30 30 8 --no-show --output-dir results/spike
python ipt_entropy_simulator.py --init noise --seed 42 --grid 24 --steps 40 --no-show --output-dir results/noise
```

This example starts with a nonnegative scalar field on an already specified
square grid. Each update mixes a cell with its four neighbors, with periodic
boundaries. For a diffusion coefficient from 0 through 0.25 inclusive, the
update preserves total field weight and nonnegativity up to floating-point
roundoff. Negative, non-finite, and larger coefficients are rejected.

Initialization choices are `spike`, `stripe`, `noise`, and `gradient`.
The grid must be at least 2 by 2, with at least one frame. Observer coordinates
must lie within the grid; its integer radius must be nonnegative. If
`--obs` is omitted, the window is centered in the grid with radius at most 8.
A large radius is allowed and can include the whole grid.

The reported quantity is Shannon entropy in **nats**, using the natural
logarithm after normalizing the field weights to sum to one. The observer
window is a Euclidean disk that does not wrap at the grid boundary; its
weights are normalized separately. Its entropy is therefore not an additive
part of the whole-grid entropy. An empty or zero-weight window is assigned
entropy zero by convention.

`--seed` makes a noise initialization reproducible. The initial state counts
as the first frame. The script saves `entropy_trend.png` and
`entropy_evolution.gif` in the output directory. Existing files with those
names are overwritten; use a separate directory to preserve another run.
Omit `--no-show` to show the entropy plot after the animation has been saved.

## 2. Desktop launcher

```bash
python ipt_gui_runner.py
```

The launcher exposes the same four initialization choices and optional seed.
It uses the Python interpreter running the GUI and locates its companion
script relative to itself. Simulations run in a child process while the
window stays responsive. Parameter or dependency failures appear in the
window and an error dialog. The Cancel button stops a running simulation;
partial files may remain.

The default output folder is `results` beside the scripts. Select another
folder with Browse. Relative output paths are resolved against the toolkit
directory. Result images can be opened using the system's default viewer on
Windows, macOS, or a Linux desktop that supplies `xdg-open`.

## 3. Scalar-field diffusion and decay

```bash
python entropy_simulation.py --init local_spike --output spike --output-dir results/field
python entropy_simulation.py --init local_noise --noise 0.1 --seed 42 --output noise --output-dir results/field
```

This older illustration keeps its original filename and valid default
numerical rule. It updates interior cells toward the average of four
neighbors, subtracts a prescribed decay, and clips negative values after
each update. Boundaries do not receive the interior diffusion update.
Its alpha is a mixing rate toward the neighbor average, so its meaning
differs by a factor of four from the coefficient in the first example.
This maintenance version accepts alpha from 0 through 0.25 in both CLIs.

The trend is labeled **total field amplitude**, the sum of the scalar grid
in arbitrary units. It is not Shannon entropy or measured thermodynamic
entropy. Its change reflects the prescribed boundary, decay, and clipping
rules; total field weight need not be conserved. The `local_noise`
initialization remains a signed Gaussian field, followed by clipping at
the first update. With the default noise scale of zero it starts empty.
Choose a positive `--noise` value to explore this initialization.

Outputs are a GIF and a trend PNG named from `--output`. Figure creation is
headless, and an optional seed makes noise reproducible.

## 4. Six-qubit graph-state example

```bash
python mera_entropy_simulation.py
```

The existing filename is retained. The program applies Hadamard gates to
six qubits, then controlled-Z gates on a fixed graph, and calculates
von Neumann entropies of three reduced states in **bits**. The circuit has
not changed. It is inspired by a MERA-like drawing, but is not a full
MERA optimization or a demonstrated emergence of spacetime.

Qiskit's built-in Statevector calculation runs locally. The output lists
the root, two intermediate qubits, and the upper three-qubit subsystem.

## Reproducibility and scope

The package contains exactly four Python scripts, this README, and
requirements.txt. The dependency ranges describe compatible API families;
they are not a lockfile. Record your installed package versions when sharing
a result, and keep the parameters and seed with your output.

The 2026 maintenance changes repair invocation, validation, packaging, and
labels. The periodic diffusion update is algebraically equivalent to the
older rule within the supported coefficient range. None of these scripts
fits observational data or compares IPT with competing physical models.

## Maintenance verification

The repaired diffusion tools were smoke-tested with Python 3.12.14 and NumPy
2.3.5. All four Shannon-entropy modes and all three scalar-field modes produced
PNG and GIF outputs. Stable periodic updates matched the previous numerical
results within floating-point roundoff; invalid coefficients and observer
inputs were rejected. The Tkinter launcher was checked for importability and
matching choices, but native GUI interaction and system viewers were not
exercised. Qiskit was unavailable in the maintenance environment, so the
six-qubit example has not been runtime-tested in this refresh.
