Metadata-Version: 2.4
Name: trunajaya
Version: 0.0.1
Summary: 2D Discrete-Time Quantum Walk Engine for Caustic Art via Coin-Induced Symmetry Classes
License: MIT
License-File: LICENSE
Keywords: quantum-walk,caustics,catastrophe-optics,computational-physics,generative-art,information-theory
Author: Sandy Hardian Susanto Herho
Requires-Python: >=3.8,<4.0
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Dist: matplotlib (>=3.3.0)
Requires-Dist: netCDF4 (>=1.5.0)
Requires-Dist: numba (>=0.53.0)
Requires-Dist: numpy (>=1.20.0)
Requires-Dist: pandas (>=1.3.0)
Requires-Dist: scipy (>=1.7.0)
Requires-Dist: tqdm (>=4.60.0)
Description-Content-Type: text/markdown

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

[![DOI](https://zenodo.org/badge/1337694853.svg)](https://doi.org/10.5281/zenodo.21986484)
[![Python](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![NumPy](https://img.shields.io/badge/NumPy-%23013243.svg?logo=numpy&logoColor=white)](https://numpy.org/)
[![SciPy](https://img.shields.io/badge/SciPy-%230C55A5.svg?logo=scipy&logoColor=white)](https://scipy.org/)
[![Matplotlib](https://img.shields.io/badge/Matplotlib-%23ffffff.svg?logo=Matplotlib&logoColor=black)](https://matplotlib.org/)
[![Pandas](https://img.shields.io/badge/pandas-%23150458.svg?logo=pandas&logoColor=white)](https://pandas.pydata.org/)
[![netCDF4](https://img.shields.io/badge/netCDF4-%23004B87.svg)](https://unidata.github.io/netcdf4-python/)
[![Numba](https://img.shields.io/badge/Numba-%2300A3E0.svg?logo=numba&logoColor=white)](https://numba.pydata.org/)
[![Pillow](https://img.shields.io/badge/Pillow-%23000000.svg)](https://python-pillow.org/)
[![tqdm](https://img.shields.io/badge/tqdm-%23FFC107.svg)](https://tqdm.github.io/)


## 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

<p align="center">
  <img src=".assets/atlas.png" alt="caustic symmetry classes" width="640">
</p>

## 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

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

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

## Usage

### Command line

```bash
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

```python
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

```bash
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](LICENSE).

## Authors

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

