Metadata-Version: 2.4
Name: bilinear-quantum
Version: 1.0.0
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://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 / Hirota Quantum Bilinear Learning

This repository is the canonical implementation and evidence package for a
gate-based Bilinear Quantum Learning (BQL) foundation and its Hirota Quantum
Bilinear Learning (HQBL) hierarchy.

The project is governed by falsification-first gates:

1. no backend skip is promoted to a pass;
2. no learning experiment opens before exact mathematical invariants pass;
3. classical, quantum, ordinary-bilinear, and Hirota comparisons are matched;
4. negative results remain part of the evidence package;
5. quantum advantage is not an assumed contribution.

## Canonical runtime

The reproducible binary runtime is Linux x86-64, CPython 3.12, TensorFlow
2.18.1, TF-Keras 2.18, TensorFlow Quantum 0.7.6, Cirq 1.5, NumPy 2.0,
SciPy 1.15, and SymPy 1.14. The exact environment is verified by
`scripts/verify_environment.py`; version drift is a hard failure.

## Repository map

- `src/bilinear_quantum`: installable TensorFlow/TFQ library;
- `tests`: mathematical, backend, layer, serialization, and gate tests;
- `configs`: immutable experiment specifications;
- `scripts`: environment, gate, experiment, analysis, and release entrypoints;
- `docs`: master specification, traceability, and library documentation;
- `manuscript`: submission manuscript and supplementary material;
- `references`: immutable source packages supplied for the project;
- `artifacts`: generated evidence, reports, figures, and tables.
- `manuscript`: editable publication sources and bibliography;
- `output`: generated DOCX/PDF manuscripts, packages, and release bundle.

## Current status

Work is accepted only through machine-readable gate reports. See
`artifacts/gates/` after executing the canonical gate runner.

## Install and verify

Install the immutable public release on Linux x86-64 with CPython 3.12:

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

Run a packaged smoke experiment without a repository checkout:

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

For development and full-profile evidence reproduction from a clean source
release:

```bash
python -m pip install -r requirements-lock.txt
python -m pip install --no-deps -e .
export TF_USE_LEGACY_KERAS=1
bq-run-gates --project-root .
```

To reproduce into a fresh immutable destination without touching the evidence
shipped with the release:

```bash
python scripts/run_reproduction.py \
  --profile full \
  --artifact-root reproduced/full-20260825
```

The exact API contract is documented in `docs/API.md`; the end-to-end data and
evidence procedure is in `docs/REPRODUCIBILITY.md`. Full-profile experiments
refuse an uncommitted or dirty source tree, and completed output directories
cannot be overwritten.

## Authors and citation

The software release is authored by Nguyen Minh Tuan and Bui Phi Hung,
Faculty of Information Technology, Posts and Telecommunications Institute of
Technology, Ho Chi Minh City, Vietnam. Citation metadata is provided in
`CITATION.cff`.

## License and third-party software

Original project code is released under the Apache License 2.0. Runtime
dependencies remain governed by their respective licenses and are installed
separately; no Elsevier template or third-party research document is bundled
in the Python distribution.
