Metadata-Version: 2.4
Name: bilinear-quantum
Version: 1.0.1
Summary: TensorFlow Quantum implementation of Bilinear and Hirota Quantum Bilinear Learning
Author-email: Nguyen Minh Tuan <minhtuan@ptit.edu.vn>, Bui Phi Hung <n23dcat028@student.ptithcm.edu.vn>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/Thien-y1502/bilinear-quantum
Project-URL: Documentation, https://github.com/Thien-y1502/bilinear-quantum/tree/main/docs
Project-URL: Repository, https://github.com/Thien-y1502/bilinear-quantum
Project-URL: Issues, https://github.com/Thien-y1502/bilinear-quantum/issues
Project-URL: Changelog, https://github.com/Thien-y1502/bilinear-quantum/blob/main/CHANGELOG.md
Project-URL: PyPI, https://pypi.org/project/bilinear-quantum/
Keywords: bilinear learning,Hirota bilinear operator,quantum machine learning,TensorFlow Quantum
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: <3.13,>=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy==2.0.2
Requires-Dist: scipy==1.15.3
Requires-Dist: sympy==1.14.0
Requires-Dist: tensorflow==2.18.1
Requires-Dist: tf-keras==2.18.0
Requires-Dist: tensorflow-quantum==0.7.6
Requires-Dist: cirq-core==1.5.0
Requires-Dist: cirq-google==1.5.0
Requires-Dist: pandas<3,>=2.2
Requires-Dist: scikit-learn<2,>=1.5
Requires-Dist: matplotlib<4,>=3.9
Requires-Dist: seaborn<1,>=0.13
Requires-Dist: statsmodels<1,>=0.14
Requires-Dist: PyYAML<7,>=6
Requires-Dist: psutil<8,>=6
Provides-Extra: dev
Requires-Dist: build<2,>=1.2; extra == "dev"
Requires-Dist: pytest==8.3.5; extra == "dev"
Requires-Dist: pytest-cov<7,>=6; extra == "dev"
Requires-Dist: ruff<1,>=0.12; extra == "dev"
Dynamic: license-file

# Bilinear Quantum Learning

[![PyPI](https://img.shields.io/pypi/v/bilinear-quantum.svg)](https://pypi.org/project/bilinear-quantum/)
[![Python 3.12](https://img.shields.io/badge/python-3.12-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-Apache--2.0-green.svg)](LICENSE)
[![CI](https://github.com/Thien-y1502/bilinear-quantum/actions/workflows/ci.yml/badge.svg)](https://github.com/Thien-y1502/bilinear-quantum/actions/workflows/ci.yml)
[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/Thien-y1502/bilinear-quantum/blob/main/notebooks/Bilinear_Quantum_Colab_Quickstart.ipynb)

`bilinear-quantum` is the public TensorFlow/TensorFlow Quantum reference
implementation of Bilinear Quantum Learning (BQL) and Hirota Quantum
Bilinear Learning (HQBL). It separates exact mathematical identities,
trainable TensorFlow layers, circuit backends, statistical comparisons, and
reproducible experiment runners.

The project follows a falsification-first policy: exact backend checks must
pass before learning experiments run; classical and quantum comparators use
matched data splits; and negative results remain part of the evidence. The
package does **not** assume or claim generic computational quantum advantage.

## Start in Google Colab

Open the maintained notebook:

[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/Thien-y1502/bilinear-quantum/blob/main/notebooks/Bilinear_Quantum_Colab_Quickstart.ipynb)

The notebook installs the public PyPI release, verifies the exact BQL identity,
runs a packaged benchmark, and demonstrates a quantum-circuit dataset against
classical baselines. It is an educational smoke test, not paper evidence.

## Install

The verified lane is Linux x86-64 with CPython 3.12:

```bash
python -m pip install bilinear-quantum==1.0.1
```

Set the TensorFlow Quantum compatibility flag before importing TensorFlow:

```python
import os
os.environ.setdefault("TF_USE_LEGACY_KERAS", "1")

from bilinear_quantum.layers import BilinearQuantumLayer, HirotaBilinearLayer
from bilinear_quantum.models import BilinearRidge, LowRankBilinearRidge
```

The canonical binary runtime uses TensorFlow 2.18.1, TF-Keras 2.18.0,
TensorFlow Quantum 0.7.6, Cirq 1.5.0, NumPy 2.0.2, SciPy 1.15.3, and SymPy
1.14.0. Google Colab may request one runtime restart after installation.

## Minimal exact check

```python
import numpy as np
from bilinear_quantum import (
    Calibration,
    bql_exact_numpy,
    classical_bilinear,
    factorize_bilinear_matrix,
    projection_radii,
)

W = np.array([[1.0, -0.2], [0.3, 0.7]])
f_train = np.array([[0.2, 0.1], [-0.4, 0.3]])
g_train = np.array([[0.1, -0.2], [0.2, 0.4]])
factorization = factorize_bilinear_matrix(W)
r_f, r_g = projection_radii(factorization, f_train, g_train)

quantum = bql_exact_numpy(
    f_train[0],
    g_train[0],
    factorization,
    r_f,
    r_g,
    calibration=Calibration.READOUT,
)
classical = classical_bilinear(f_train[0], W, g_train[0])
np.testing.assert_allclose(quantum, classical, atol=1e-12)
```

## Packaged experiments

Run a quick public smoke benchmark without cloning the repository:

```bash
bq-run-experiment E1 --profile smoke --output-root reproduced/smoke
```

Registered experiments cover controlled bilinear rank, true Hirota Fourier
tasks, KdV operator residuals, subject-disjoint human activity recognition,
order/resource/shot/noise/trainability sweeps, and a dequantization challenge.
Experiments E4 and E4Q require the separately prepared UCI HAR dataset.

For a custom quantum dataset, first convert circuits, statevectors, density
matrices, or hardware measurements into two bounded numerical branches
`f` and `g`, then evaluate BQL/HQBL and every baseline on the same immutable
split. See [the Colab guide](docs/COLAB.md) for the data contract.

## Public project resources

- [PyPI package](https://pypi.org/project/bilinear-quantum/)
- [Source repository](https://github.com/Thien-y1502/bilinear-quantum)
- [Colab quickstart](https://colab.research.google.com/github/Thien-y1502/bilinear-quantum/blob/main/notebooks/Bilinear_Quantum_Colab_Quickstart.ipynb)
- [API guide](docs/API.md)
- [Reproducibility protocol](docs/REPRODUCIBILITY.md)
- [Dataset provenance](docs/DATASETS.md)
- [Release history](CHANGELOG.md)
- [Issue tracker](https://github.com/Thien-y1502/bilinear-quantum/issues)

## Scientific scope

The exact BQL/HQBL core is deliberately auditable and classically
dequantizable. Circuit, finite-shot, noise, trainability, and learned-feature
experiments are reported separately from exact algebraic identities. Simulator
accuracy, a quantum implementation, or fewer trainable parameters alone is not
evidence of computational quantum advantage.

Full-profile evidence is accepted only through machine-readable gate reports.
Each completed run records the source commit, registry checksum, dependency
versions, command, runtime, outputs, and SHA-256 manifest. See
[the master specification](docs/MASTER_SPECIFICATION.md) and
[traceability matrix](docs/TRACEABILITY.md).

## Citation

Citation metadata is provided in [`CITATION.cff`](CITATION.cff). Until an
archival DOI is assigned, cite the exact software version and both canonical
links:

```text
Nguyen Minh Tuan and Bui Phi Hung. Bilinear Quantum Learning and Hirota
Quantum Bilinear Learning, software version 1.0.1, 2026.
https://pypi.org/project/bilinear-quantum/
https://github.com/Thien-y1502/bilinear-quantum
```

## License and third-party software

Original project code is released under the [Apache License 2.0](LICENSE).
Dependencies are installed separately and retain their own licenses. The public
repository and Python distributions do not contain the Elsevier template,
private reference packages, restricted datasets, or unpublished manuscript
files.

Security reports should follow [SECURITY.md](SECURITY.md). Contributions are
governed by [CONTRIBUTING.md](CONTRIBUTING.md) and
[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
