From 4219603b6b39589eb664920c333b4cbdab9e8fcc Mon Sep 17 00:00:00 2001 From: Devarapalli Sripriya Reddy Date: Tue, 13 Oct 2026 19:28:45 +0530 Subject: [PATCH 1/3] docs: explain save vs save_weights for TFQ layers --- docs/design.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/docs/design.md b/docs/design.md index a82bc9716..ede294cc2 100644 --- a/docs/design.md +++ b/docs/design.md @@ -87,6 +87,33 @@ operations. Additionally, you can create a layer with a high degree of complexity supporting batch circuit, batch control parameter value, and perform batch readout operations. See `tfq.layers.Sample` for an example. +### Saving Keras models + +Saving a complete model with `tf.keras.Model.save()` can fail when a layer +was created with arguments that Keras cannot serialize and the layer does not +override `get_config()`. For example, a model containing +`tfq.layers.ControlledPQC` fails to save in TFQ 0.7.2. Depending on the +format, the error is a `NotEncodableError` or a `NotImplementedError` saying +the layer must override `get_config()`. The message does not always make +clear that the layer is the cause. + +As an alternative, `tf.keras.Model.save_weights()` saves only the model +weights, without the complete model configuration. Recreate the model +architecture before loading the saved weights: + +```python +model.save_weights("my_model.weights.h5") + +new_model = build_model() # Recreate the same model architecture. +new_model.load_weights("my_model.weights.h5") +``` + +For details about the project's Keras setup, see the +[installation guide](install.md). TensorFlow Quantum's installation +instructions use the legacy `tf-keras` package via +`TF_USE_LEGACY_KERAS=1`. Saving and loading behavior may depend on the +TensorFlow and Keras versions in use. + ### Differentiators Unlike many TensorFlow operations, observables in quantum circuits do not have From 252fbe10f097aa3792c4e1805d4bba116d28c28f Mon Sep 17 00:00:00 2001 From: Devarapalli Sripriya Reddy Date: Sun, 18 Oct 2026 12:50:07 +0530 Subject: [PATCH 2/3] docs: clarify saving TFQ layers --- docs/design.md | 25 ++++++++----------------- 1 file changed, 8 insertions(+), 17 deletions(-) diff --git a/docs/design.md b/docs/design.md index ede294cc2..e8e6e0091 100644 --- a/docs/design.md +++ b/docs/design.md @@ -87,19 +87,16 @@ operations. Additionally, you can create a layer with a high degree of complexity supporting batch circuit, batch control parameter value, and perform batch readout operations. See `tfq.layers.Sample` for an example. -### Saving Keras models +#### Saving and loading models -Saving a complete model with `tf.keras.Model.save()` can fail when a layer -was created with arguments that Keras cannot serialize and the layer does not -override `get_config()`. For example, a model containing -`tfq.layers.ControlledPQC` fails to save in TFQ 0.7.2. Depending on the -format, the error is a `NotEncodableError` or a `NotImplementedError` saying -the layer must override `get_config()`. The message does not always make -clear that the layer is the cause. +Saving a complete Keras model with `model.save()` is not supported for models containing TFQ layers, including `tfq.layers.PQC` and `tfq.layers.ControlledPQC`. These layers accept quantum objects, such as `cirq.Circuit`, `cirq.PauliSum`, and `sympy.Symbol`, that are not +JSON-serializable, and the layers do not implement `get_config()` to serialize their configurations. -As an alternative, `tf.keras.Model.save_weights()` saves only the model -weights, without the complete model configuration. Recreate the model -architecture before loading the saved weights: +Depending on the serialization path, calling `model.save()` may raise a `NotImplementedError` indicating that the layer must override +`get_config()`, a `TypeError` for non-JSON-serializable `call()` +arguments such as `sympy.Symbol` or `cirq.PauliSum`, or a `NotEncodableError` when tracing layer `call` defaults for `SavedModel` export. This limitation is not specific to a particular TFQ, TensorFlow, or Keras version. + +As an alternative, `model.save_weights()` saves the model's weights without saving the complete model configuration. Recreate the same model architecture before loading the saved weights: ```python model.save_weights("my_model.weights.h5") @@ -108,12 +105,6 @@ new_model = build_model() # Recreate the same model architecture. new_model.load_weights("my_model.weights.h5") ``` -For details about the project's Keras setup, see the -[installation guide](install.md). TensorFlow Quantum's installation -instructions use the legacy `tf-keras` package via -`TF_USE_LEGACY_KERAS=1`. Saving and loading behavior may depend on the -TensorFlow and Keras versions in use. - ### Differentiators Unlike many TensorFlow operations, observables in quantum circuits do not have From 2332f7155c1c2ec1d55b93994ecba33614f76186 Mon Sep 17 00:00:00 2001 From: Devarapalli Sripriya Reddy Date: Fri, 6 Nov 2026 23:35:57 +0530 Subject: [PATCH 3/3] docs: address review feedback --- docs/design.md | 26 ++++++++++++++++++-------- 1 file changed, 18 insertions(+), 8 deletions(-) diff --git a/docs/design.md b/docs/design.md index e8e6e0091..9e83c817d 100644 --- a/docs/design.md +++ b/docs/design.md @@ -89,14 +89,24 @@ batch readout operations. See `tfq.layers.Sample` for an example. #### Saving and loading models -Saving a complete Keras model with `model.save()` is not supported for models containing TFQ layers, including `tfq.layers.PQC` and `tfq.layers.ControlledPQC`. These layers accept quantum objects, such as `cirq.Circuit`, `cirq.PauliSum`, and `sympy.Symbol`, that are not -JSON-serializable, and the layers do not implement `get_config()` to serialize their configurations. - -Depending on the serialization path, calling `model.save()` may raise a `NotImplementedError` indicating that the layer must override -`get_config()`, a `TypeError` for non-JSON-serializable `call()` -arguments such as `sympy.Symbol` or `cirq.PauliSum`, or a `NotEncodableError` when tracing layer `call` defaults for `SavedModel` export. This limitation is not specific to a particular TFQ, TensorFlow, or Keras version. - -As an alternative, `model.save_weights()` saves the model's weights without saving the complete model configuration. Recreate the same model architecture before loading the saved weights: +Saving a complete Keras model with `model.save()` is not supported for +models containing TFQ layers, including `tfq.layers.PQC` and +`tfq.layers.ControlledPQC`. These layers accept quantum objects, such as +`cirq.Circuit`, `cirq.PauliSum`, and `sympy.Symbol`, that are not +JSON-serializable, and the layers do not implement `get_config()` to +serialize their configurations. + +Depending on the serialization path, calling `model.save()` may raise a +`NotImplementedError` indicating that the layer must override +`get_config()`, a `TypeError` for non-JSON-serializable `call()` arguments +such as `sympy.Symbol` or `cirq.PauliSum`, or a `NotEncodableError` when +tracing layer `call` defaults for `SavedModel` export. This limitation is +not specific to a particular TFQ, TensorFlow, or Keras version. + +As an alternative, `model.save_weights()` saves the model's weights without +saving the complete model configuration. Recreate the same model +architecture before loading the saved weights. The recreated model must +be built (its variables must be created) before calling `load_weights()`: ```python model.save_weights("my_model.weights.h5")