[SripriyaDevarapalli]

Description

This pull request addresses the documentation issue in #899 regarding the behavior of tf.keras.Model.save() versus save_weights() for TensorFlow Quantum (TFQ) layers.

Summary of changes

• Documents the reported serialization issue when saving complete Keras models containing TFQ layers that may not support configuration serialization.
• Explains save_weights() as an alternative when complete model serialization fails.
• Provides a Python example showing how to save weights and load them into a recreated model architecture.

Related to #899 and #56.

How Has This Been Tested?

• Ran git diff --cached --check successfully.
• Reviewed the documentation changes.
• • A TFQ runtime save/load test could not be completed because the local checkout lacks the compiled native operation library required to import TFQ.
• This is a documentation-only change; no source code or tests were modified.

Test Configuration:

• Python version: 3.11
• Operating system: Windows
• TensorFlow version: 2.19.1
• tf-keras version: 2.19.0

AI use

• No AI tool was used.
• AI-assisted: I did the research and wrote the change, and used an AI tool for parts of it (for example completion, editing or review).
• AI-generated: an AI tool did most of the research or wrote most of the change. I have read all of it and can explain it.
• Translated into English with an AI tool.

Checklist

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new errors or warnings
• My code and tests pass locally and have at least 80% line coverage
• Any dependent changes have been merged and published in downstream modules

[gemini-code-assist]

Code Review

This pull request updates the design documentation in docs/design.md to include a new section on saving Keras models. It explains why saving a complete model with tf.keras.Model.save() can fail for certain layers and provides a code example demonstrating how to use save_weights() and load_weights() as a workaround. There are no review comments, so there is no feedback to provide.

[SripriyaDevarapalli]

Hey @mhucka I've created a PR #1120 addressing the documentation issue regarding the behavior of save() versus save_weights() for TensorFlow Quantum layers.

The changes explain the reported serialization issue, document save_weights() as an alternative, and include a usage example, and if you have any suggestions for improvement please do let me know .

Thank you!

[SripriyaDevarapalli]

I also noticed that the CI run failed in the Tutorial tests job.

The logs show an ImportError indicating that pydot and/or Graphviz are missing when tf.keras.utils.plot_model() is called. The file format and lint checks, wheel test, and library tests all passed.

This appears to be a missing dependency in the tutorial test environment rather than an issue caused by my documentation changes. I wanted to bring this to your attention for investigation.

Thank you!

[mhucka]

Thanks for working on this. A few adjustments are needed to make the section accurate and fit the structure of docs/design.md:

1. In docs/design.md, the ### headings under ## TensorFlow Quantum primitives (Fundamental ops, Layers, Differentiators, Datasets) correspond to the four main component types in TFQ. Since model saving applies specifically to tfq.layers, please make this a #### Saving and loading models subsection under ### Layers rather than a sibling ### section.

2. This limitation is not specific to TFQ 0.7.2, and it does not depend on the TensorFlow/Keras version. None of the layers in tfq.layers implement get_config(), because they accept non-JSON-serializable quantum objects (such as cirq.Circuit, cirq.PauliSum, and sympy.Symbol). Please state directly that saving a complete model with model.save() is not supported for models containing TFQ layers, and mention tfq.layers.PQC as well as tfq.layers.ControlledPQC.

3. Calling model.save() raises a NotImplementedError (stating 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).

4. The tf-keras environment variable is unrelated to why model.save() fails on TFQ layers, so linking to install.md here can confuse readers. Remove the final paragraph about install.md and TF_USE_LEGACY_KERAS=1.

[SripriyaDevarapalli]

@mhucka Thank you for the feedback! I've updated docs/design.md to address all the requested changes.
I've committed and pushed the updates to the existing PR. All six checks are passing. Could you please take a look and review it ?
Thanks again for your guidance!

[SripriyaDevarapalli]

@mhucka Thanks for the feedback , I have made the required changes , can you review it now .

…

On Sun, 18 Oct 2026 at 08:41, Michael Hucka, Ph.D. ***@***.***> wrote: ***@***.**** requested changes on this pull request. Thanks for working on this. A few adjustments are needed to make the section accurate and fit the structure of docs/design.md: 1. In docs/design.md, the ### headings under ## TensorFlow Quantum primitives (Fundamental ops, Layers, Differentiators, Datasets) correspond to the four main component types in TFQ. Since model saving applies specifically to tfq.layers, please make this a #### Saving and loading models subsection under ### Layers rather than a sibling ### section. 2. This limitation is not specific to TFQ 0.7.2, and it does not depend on the TensorFlow/Keras version. None of the layers in tfq.layers implement get_config(), because they accept non-JSON-serializable quantum objects (such as cirq.Circuit, cirq.PauliSum, and sympy.Symbol). Please state directly that saving a complete model with model.save() is not supported for models containing TFQ layers, and mention tfq.layers.PQC as well as tfq.layers.ControlledPQC. 3. Calling model.save() raises a NotImplementedError (stating 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). 4. The tf-keras environment variable is unrelated to why model.save() fails on TFQ layers, so linking to install.md here can confuse readers. Remove the final paragraph about install.md and TF_USE_LEGACY_KERAS=1. — Reply to this email directly, view it on GitHub <#1120?email_source=notifications&email_token=BR4HQ76GF6ADNFIHLOKJXKD5UQYELA5CNFSNUABKM5UWIORPF5TWS5BNNB2WEL2QOVWGYUTFOF2WK43UKJSXM2LFO4XTKNJWGEZDEMBZG4ZKM4TFMFZW63VGMF2XI2DPOKSWK5TFNZ2KYZTPN52GK4S7MNWGSY3L#pullrequestreview-5561220972>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/BR4HQ77XWCER3ETDDQLERLL5UQYELAVCNFSNUABFKJSXA33TNF2G64TZHMZDGOBXG4ZDONRSHNEXG43VMU5TKOBTGMZTKNJXHE3KC5QC> . You are receiving this because you authored the thread.Message ID: ***@***.***>

[mhucka]

Thanks for the update. Some further comments are below.

In addition, the PR description still contains the bullet "Links to the TFQ installation guide and notes that saving and loading behavior may depend on the TensorFlow and Keras versions in use" from the initial commit.

[mhucka]

Please wrap to 80 columns, per .editorconfig and .markdownlintrc settings.

[mhucka]

build_model() is never defined in the example. Readers have to guess what it should contain. At minimum, add a sentence saying the recreated model must be built (its variables created) before calling load_weights(). With the HDF5 format in tf-keras, loading weights into an unbuilt subclassed model raises a ValueError.

[SripriyaDevarapalli]

Hi @mhucka,

Thank you for your valuable feedback and guidance. I've addressed all the requested changes, updated the PR description, and pushed the latest commit (2332f71) to the existing PR.

All six automated checks are passing.

Could you please review the latest updates when you have a chance?

Thank you for your time and support!