trunajaya: 2D Discrete-Time Quantum Walk Engine for Caustic Art

Overview

trunajaya is a Python engine for the two-dimensional discrete-time quantum walk (DTQW) on a square lattice with a four-state coin. The evolution is exactly unitary and is computed as a fused coin-and-shift kernel compiled with Numba and parallelized across lattice rows. A single engine accepts any 4x4 coin unitary, and the four bundled cases show how the choice of coin fixes the symmetry class of the emergent pattern.

The scientific and the aesthetic content are the same object. In the long-time limit the amplitude is governed by stationary phase over the dispersion surface of the walk operator, and the bright loci where the local density diverges are catastrophe-theoretic caustics, the folds and cusps studied in the optics of the rainbow and the pool-floor web. Each run therefore produces a caustic image together with an information-theoretic reading of it.

Key features:

• One generalizable engine for any four-state coin unitary
• Four coin families spanning distinct caustic symmetry classes
• Exact unitarity, verified by machine-precision norm conservation
• Numba-accelerated kernel with user-selectable core count and a NumPy fallback
• Full field evolution and per-step diagnostics archived to NetCDF (CF-1.8)
• Probability and phase animations with physics-standard colorbars

Physics

State space and one step

The state lives on the tensor product of a position Hilbert space, the lattice, and a four-dimensional coin space indexing the lattice directions:

$$|\Psi(t)\rangle \in \mathcal{H}\mathrm{pos} \otimes \mathcal{H}\mathrm{coin}, \qquad \mathcal{H}_\mathrm{coin} = \mathrm{span}{|{+}x\rangle, |{-}x\rangle, |{+}y\rangle, |{-}y\rangle}.$$

One step of the walk is the unitary $U = S,(C \otimes I_\mathrm{pos})$, applied as a coin mixing followed by a conditional shift:

$$\phi_{c'}(\mathbf{r}) = \sum_{c} C_{c' c},\psi_c(\mathbf{r}), \qquad \psi'_{c}(\mathbf{r} + \mathbf{e}_c) = \phi_c(\mathbf{r}),$$

where $\mathbf{e}_c$ is the unit lattice vector for direction $c$. The lattice is sized as $L = 2T + 1 + 2m$ for $T$ steps and margin $m$, so the ballistic light cone never reaches the boundary and the total probability is conserved to machine precision.

Coin families

Case	Coin	Definition	Symmetry class
1	Grover	$G = \tfrac{2}{4}\mathbf{J} - \mathbf{I}$	localized four-fold
2	Fourier	$F_{jk} = \tfrac{1}{2},i^{,jk}$	delocalized cross
3	Hadamard	$H_4 = H \otimes H$	anisotropic diagonal
4	Chiral	$C = G,\mathrm{diag}(1, i, -1, -i)$	symmetry-broken pinwheel

All four share one localized initial coin state, $\psi_0 = \tfrac{1}{2}(1, i, -1, -i)$, so that differences in the resulting field are attributable to the coin alone. The Grover and chiral coins retain probability at the origin (localization), while the Fourier and Hadamard coins spread it across a broad support.

Caustics

Along the boundary of the light cone the stationary-phase condition on the dispersion surface becomes degenerate, and the amplitude piles up into sharp curves. These are the fold and cusp catastrophes of Thom, Berry, and Nye, generated here by a purely algebraic evolution with no optics present. The coin's symmetry group prints onto the pattern, which is the organizing idea behind the comparative atlas.

Diagnostics

Each step is summarized by information-theoretic quantities: the Shannon entropy $S = -\sum p \ln p$, the Renyi-2 entropy $S_2 = -\ln \sum p^2$, the inverse participation ratio and its reciprocal, the radial spread $\sigma_r$, and the origin return probability. The radial spread grows linearly in time; the fitted exponent $\alpha$ in $\sigma_r \propto t^{\alpha}$ is close to unity, confirming ballistic transport.

Installation

git clone https://github.com/sandyherho/trunajaya.git
cd trunajaya
pip install -e .

Dependencies: numpy, scipy, matplotlib, netCDF4, tqdm, numba, pandas.

Usage

Command line

trunajaya case1              # Grover coin
trunajaya case2 --cores 8    # Fourier coin on 8 threads
trunajaya --all              # all four cases plus the comparative atlas
trunajaya -c myconfig.txt    # a custom configuration

Options include --output-dir/-o, --cores, --config/-c, --all/-a, and --quiet/-q. When cores are unset the engine uses all available threads, clamped to the compiled Numba maximum.

Python API

from trunajaya_qw import QuantumWalk2D, DataHandler
from trunajaya_qw.visualization.animator import Animator

walker = QuantumWalk2D(n_cores=4)
result = walker.run(coin="chiral", steps=120)

DataHandler.save_netcdf("chiral.nc", result, {"scenario_name": "chiral"}, "outputs")
Animator.create_gif(result, "chiral.gif", "outputs")

Any 4x4 unitary can be supplied by extending COIN_REGISTRY in core/coins.py.

Output files

Each case writes the following into the output directory:

File	Content
<case>.gif	probability field animation with power-law colorbar
<case>.nc	full evolution, diagnostic series, and coin matrix (NetCDF, CF-1.8)
<case>_series.csv	per-step diagnostic time series
<case>_diagnostics.png	final field, phase field, entropy growth, spreading law
atlas.png	comparative grid of final fields (with --all)
comparison_metrics.csv	scalar summary across all cases

The NetCDF file stores the probability field probability(time, y, x) and, optionally, the phase field, so any frame can be replotted without rerunning the walk.

Project structure

trunajaya/
├── src/trunajaya_qw/
│   ├── core/
│   │   ├── walker.py         # 2D DTQW engine and Numba kernel
│   │   └── coins.py          # coin unitaries and initial states
│   ├── io/
│   │   ├── config_manager.py # configuration parsing
│   │   └── data_handler.py   # NetCDF and CSV output
│   ├── utils/
│   │   ├── logger.py
│   │   └── timer.py
│   ├── visualization/
│   │   └── animator.py       # GIF, phase, diagnostics, atlas
│   └── cli.py
├── configs/                  # case1-case4 configurations
├── tests/                    # unit tests
├── LICENSE
└── pyproject.toml

Testing

pytest tests/ -v

The suite verifies coin unitarity, probability conservation, absence of boundary leakage, ballistic spreading, the localization ordering of the coins, and agreement between the Numba and NumPy kernels.

License

MIT License. See LICENSE.

Authors

• Sandy Hardian Susanto Herho (sandyherho@itb.ac.id)
• Sito Fossy Biosa