Metadata-Version: 2.4
Name: qiu-hamiltonian-simulation
Version: 0.1.0
Summary: Qiskit circuits of the time evolution under potentials and kinetic energies given as sampled signals.
Keywords: hamiltonian simulation,qiskit,quantum circuits,quantum computing,time evolution
Author: Siavash Davani
Author-email: Siavash Davani <siavash.davani@gmail.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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: Typing :: Typed
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Quantum Computing
Requires-Dist: qiskit>=2.2.1
Requires-Dist: qiu-qiskit-encore
Requires-Dist: qiu-quantum-computing
Requires-Dist: qiu-signals
Maintainer: Siavash Davani
Maintainer-email: Siavash Davani <siavash.davani@gmail.com>
Requires-Python: >=3.11
Project-URL: Homepage, https://github.com/BlackWild/qiu/tree/master/packages/qiu-hamiltonian-simulation
Project-URL: Documentation, https://blackwild.github.io/qiu/qiu-hamiltonian-simulation/
Project-URL: Repository, https://github.com/BlackWild/qiu
Project-URL: Issues, https://github.com/BlackWild/qiu/issues
Project-URL: Changelog, https://github.com/BlackWild/qiu/blob/master/packages/qiu-hamiltonian-simulation/CHANGELOG.md
Description-Content-Type: text/markdown

# Qiskit Hamiltonian Simulation

[![PyPI](https://img.shields.io/pypi/v/qiu-hamiltonian-simulation)](https://pypi.org/project/qiu-hamiltonian-simulation/) [![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue)](https://www.python.org/) [![License: MIT](https://img.shields.io/badge/license-MIT-green)](https://github.com/BlackWild/qiu/blob/master/LICENSE) [![CI](https://github.com/BlackWild/qiu/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/BlackWild/qiu/actions/workflows/ci.yml) [![Docs](https://img.shields.io/badge/docs-mkdocs-blue)](https://blackwild.github.io/qiu/qiu-hamiltonian-simulation/)

Time evolution `e^(-i t H / hbar)` under potentials `V(x)` and kinetic energies `T(p)`, given as [`qiu-signals`](https://github.com/BlackWild/qiu/blob/master/packages/qiu-signals/README.md) signals, built on the phase circuits of [`qiu-quantum-computing`](https://github.com/BlackWild/qiu/blob/master/packages/qiu-quantum-computing/README.md).

## Installation

```sh
pip install qiu-hamiltonian-simulation
```

## Position and momentum domain

A potential acts diagonally on the position amplitudes. A kinetic energy acts diagonally on the momentum amplitudes, the orthonormal DFT `numpy.fft.fft(psi, norm="ortho")`, which is Qiskit's **inverse** QFT (`time_independent.fourier`). The momentum-domain evolutions thus apply the inverse QFT, the phase and the QFT, in this order.

The momentum signal must live on a Fourier domain axis (e.g. `MomentumAxis` or `AngularWavenumberAxis`) in the `FFT` ordering, whose sample `k` is the momentum of the Fourier basis state `|k>`. Other orderings, and signals on axes of the wrong domain, are rejected.

## Evolutions

`time_independent.direct`, exact for quadratic signals `f`, i.e. `e^(i f)`:

- `PositionDomainEvolutionQuadratic(f)` for `f` on a position axis.
- `MomentumDomainEvolutionQuadratic(f, fourier_method)` for `f` on a momentum axis.

For the evolution under `V` or `T` over the time `t`, pass `f = (-t / hbar) * V`; scaling a `QuadraticSignal` keeps it quadratic.

`time_independent.sample_based`, for arbitrary real signals of one sign, sampled or algebraic:

- `PotentialEvolutionSampleBased(V, t, hbar, max_delta, state_preparation_method)`
- `KineticEvolutionSampleBased(T, t, hbar, max_delta, state_preparation_method, fourier_method)`

Both apply `e^(-i t V / hbar)` or `e^(-i t T / hbar)` with the sample-based phase propagator, sliced into phases of at most `max_delta`, and expose its `num_of_cycles`.

All synthesis methods default to `GATE`, leaving the synthesis to Qiskit when transpiling; see the caveat on the state preparation in [`qiu-quantum-computing`](https://github.com/BlackWild/qiu/blob/master/packages/qiu-quantum-computing/README.md#sample-based-phases).

## Usage

```python
import numpy as np
from qiu_signals.algebraic_signal import QuadraticSignal
from qiu_signals.integer_axis import IndexOrdering
from qiu_signals.physical_axis import MomentumAxis, PositionAxis
from qiskit.quantum_info import Statevector
from qiu_hamiltonian_simulation.time_independent.direct import (
    MomentumDomainEvolutionQuadratic,
)

x_axis = PositionAxis(size=16, delta_x=0.5, ordering=IndexOrdering.CENTERED)
p_axis = MomentumAxis.from_position_axis(x_axis, hbar=1.0)  # FFT ordering

# free evolution of a particle of mass 1 over the time t = 0.2
t, mass = 0.2, 1.0
kinetic = QuadraticSignal(p_axis, alpha=1 / (2 * mass))
evolution = MomentumDomainEvolutionQuadratic((-t / 1.0) * kinetic)

psi = Statevector(
    np.exp(-(x_axis.values**2)) / np.linalg.norm(np.exp(-(x_axis.values**2)))
)
out = psi.evolve(evolution)
expected = np.fft.ifft(
    np.exp(-1j * t * kinetic.data) * np.fft.fft(psi.data, norm="ortho"), norm="ortho"
)
assert np.allclose(out.data, expected)
```

## Examples

- `examples/free_space_double_slit.py`: The paraxial diffraction of a double slit over 1 km, with the direct propagator on 10 qubits, checked against NumPy's FFT.

## Documentation

The documentation, with the API reference from the docstrings, is built from `docs/` with MkDocs and published at <https://blackwild.github.io/qiu/qiu-hamiltonian-simulation/>. To serve it locally, from the repository root:

```sh
uv run mkdocs serve -f packages/qiu-hamiltonian-simulation/mkdocs.yml
```

## Tests

From the repository root:

```sh
uv run pytest packages/qiu-hamiltonian-simulation
```
