- This release takes inspiration from the distinction between model and inference to further modularize and simplify the structure of the code. Given some problem to solve in machine learning, here is how we think about the distinction:
- **model:** a representation of some structure assumed to be present in the problem. For example, when trying to learn a probability distribution, an energy function is a model: the structure it represents is the relative probabilities of samples from the probability distribution you are trying to learn. Models are typically parameterized so that they can be updated to better represent the actual structure present in the problem.
- **inference:** a process for obtaining results from a model. For example, MCMC is a process which obtains samples from the probability distribution corresponding to an energy function.
- To support this distinction, we now provide a `models` subpackage for defining energy functions and quantum circuits. Separately, we now provide an `inference` subpackage for defining EBMs (classes for sampling according to an energy function) and QNNs (classes for measuring observables at the output of a given quantum circuit).
- Further theoretical analysis revealed to us that the derivatives of VQT and QMHL losses could be composed from more general derivatives of the underlying computations. This means the VQT and QMHL functions do not need to define their own custom gradients anymore. Instead, the more general derivatives of log partition functions and EBM expectation values are implemented.
New features
Below we list in finer granularity some of the improvements made in this release.
- `models` subpackage
- Classical models
- `BitstringEnergy` class, for defining an energy function as a stack of `tf.keras.layers.Layer` instances.
- Two hardcoded subclasses, `BernoulliEnergy` for representing a tensor product of Bernoullis and `KOBE` for representing Kth order binary energy functions.
- Quantum models
- `QuantumCircuit` class, for defining unitary transformations. This is an abstraction layer on top of TensorFlow Quantum. As a benefit of this abstraction, users are able to add and invert circuits, while the underlying class manages tracking all associated variables, symbols, and circuit tensors. Sort of like a generalization of the [PQC layer in TFQ](https://www.tensorflow.org/quantum/api_docs/python/tfq/layers/PQC).
- `DirectQuantumCircuit` class, for automatically upgrading a parameterized `cirq.Circuit` into a `QuantumCircuit`.
- Hybrid models
- `Hamiltonian` class for representing general observables. This class accepts a `BitstringEnergy` to represent eigenvalues, and a `QuantumCircuit` to represent eigenvectors.
- `inference` subpackage
- Classical inference
- `EnergyInference` is a base class for working with probability distributions corresponding to `BitstringEnergy` models. In other words, this class is an EBM. A critical feature is its ability to take derivatives: given a function `f` acting on samples `x` from the EBM, this class can take the derivative of `f(x)` with respect to both the variables of `f` and the variables of the `BitstringEnergy` defining this EBM.
- `AnalyticEnergyInference` class for exact sampling from any `BitstringEnergy` (subject to memory constraints on the number of bits). Works by calculating the probability of every bitstring, then sampling them as a categorical distribution.
- `BernoulliEnergyInference` class for exact sampling from `BernoulliEnergy` models.
- `probabilities` function for calculating the vector of probabilities corresponding to a given `BitstringEnergy` model.
- Quantum inference
- `QuantumInference` class for encapsulating the circuit, symbol name, symbol value, and observable management required for expectation calculation with TFQ. Enables measuring some kinds of `Hamiltonian`s beyond simple `cirq.PauliSum`s.
- `unitary` function for calculating the unitary matrix represented by a given `QuantumCircuit`.
- Hybrid inference
- `QHBM` class. Here is where all the pieces come together. It is initialized with an `EnergyInference` and `QuantumCircuit` instance. It enables measuring the expectation values of observables against QHBMs. The modular Hamiltonian corresponding to the QHBM is an property of `QHBM` returned as a `Hamiltonian` class.
- `density_matrix` function for calculating the matrix corresponding to a given `QHBM`, useful for numerics when the number of qubits is small enough.
- `fidelity` function for calculating the fidelity between a `QHBM` and a density matrix. Again, useful for numerics when the number of qubits is small enough.
- Losses
- `vqt` function for calculating the VQT loss given a `QHBM`, a hamiltonian, and an inverse temperature. Fully differentiable in `tf.GradientTape()` contexts.
- `qmhl` function for calculating the QMHL loss between a `QuantumData` and a `QHBM`. Fully differentiable in `tf.GradientTape()` contexts.
- `data` subpackage
- `QuantumData` class for encapsulating any sources of data to which we have quantum processing access.
- `QHBMData` class for defining a source of quantum data as the output from a QHBM.
- Other improvements
- Enabled `yapf` lint checks for pull requests.
- Added a nightly build publisher, triggered on merges into the `main` branch.
- updated TFQ dependency to latest version, 0.6.1
Breaking changes
Note that almost all APIs have been changed and simplified. See the test cases for examples of usage. As well, keep an eye out for our upcoming `baselines` release (issue 197), where we will showcase some of our research code.
Further details
Full commit list
* Enable differentiation through hypernetworks by sahilpatelsp in https://github.com/google/qhbm-library/pull/96
* Utilities for modular Hamiltonian expectation by zaqqwerty in https://github.com/google/qhbm-library/pull/97
* Fix the internal test error. by jaeyoo in https://github.com/google/qhbm-library/pull/98
* Updated links in documentation + instructions on how to add reviewers by thubregtsen in https://github.com/google/qhbm-library/pull/103
* Added two examples: qmhl and vqt by thubregtsen in https://github.com/google/qhbm-library/pull/102
* Reverts erroneous changes by farice in https://github.com/google/qhbm-library/pull/107
* Add automatic dev version publisher by zaqqwerty in https://github.com/google/qhbm-library/pull/108
* Separate EBM by zaqqwerty in https://github.com/google/qhbm-library/pull/111
* Add yapf linter step and make CI explicit by jaeyoo in https://github.com/google/qhbm-library/pull/116
* Fix lint error for loss function argument by jaeyoo in https://github.com/google/qhbm-library/pull/118
* Remove lint from energy files by zaqqwerty in https://github.com/google/qhbm-library/pull/121
* Separate QNN by zaqqwerty in https://github.com/google/qhbm-library/pull/113
* QuantumCircuit addition and inversion by zaqqwerty in https://github.com/google/qhbm-library/pull/122
* Make models arguments to inference engines by zaqqwerty in https://github.com/google/qhbm-library/pull/124
* Hamiltonian tracing by zaqqwerty in https://github.com/google/qhbm-library/pull/156
* EnergyInference expectation method derivative by zaqqwerty in https://github.com/google/qhbm-library/pull/151
* Upgrade TFQ version to 0.6.1 by zaqqwerty in https://github.com/google/qhbm-library/pull/160
* Generalize EnergyInfer expectation by zaqqwerty in https://github.com/google/qhbm-library/pull/169
* VQT by zaqqwerty in https://github.com/google/qhbm-library/pull/163
* Add inverse to unique_bitstrings_with_counts by zaqqwerty in https://github.com/google/qhbm-library/pull/177
* Energy inference cleanup by zaqqwerty in https://github.com/google/qhbm-library/pull/174
* Remove counts argument from inference calls by zaqqwerty in https://github.com/google/qhbm-library/pull/175
* Log partition estimator and derivative by zaqqwerty in https://github.com/google/qhbm-library/pull/180
* Move operator expectations to QuantumInference by zaqqwerty in https://github.com/google/qhbm-library/pull/179
* Automate inference and make models arguments to inference engines by zaqqwerty in https://github.com/google/qhbm-library/pull/181
* Fidelity for new style QHBMs by zaqqwerty in https://github.com/google/qhbm-library/pull/187
* Add derivative tests to circuit by zaqqwerty in https://github.com/google/qhbm-library/pull/188
* QMHL by zaqqwerty in https://github.com/google/qhbm-library/pull/189
* Architecture refresh by zaqqwerty in https://github.com/google/qhbm-library/pull/191
* Remove old code, bump working version by zaqqwerty in https://github.com/google/qhbm-library/pull/192
* Update docs by zaqqwerty in https://github.com/google/qhbm-library/pull/193
* Organize into submodules by zaqqwerty in https://github.com/google/qhbm-library/pull/196
New Contributors
* thubregtsen made their first contribution in https://github.com/google/qhbm-library/pull/103
Link to changelog
https://github.com/google/qhbm-library/compare/v0.2.1...v0.3.0