Bilinear Quantum Learning

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:

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:

python -m pip install bilinear-quantum==1.0.1

Set the TensorFlow Quantum compatibility flag before importing TensorFlow:

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

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:

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 for the data contract.

Public project resources

• PyPI package
• Source repository
• Colab quickstart
• API guide
• Reproducibility protocol
• Dataset provenance
• Release history
• Issue tracker

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 and traceability matrix.

Citation

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

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. 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. Contributions are governed by CONTRIBUTING.md and CODE_OF_CONDUCT.md.