Cirq 1.5.x to Cirq 1.6.1

.github/workflows/ci-nightly-build-test.yaml

@@ -41,7 +41,7 @@ on:
       py_version:
         description: "Python version:"
         type: string
-        default: "3.10.15"
+        default: "3.11.15"
 
       save_artifacts:
         description: Make Bazel artifacts downloadable
@@ -50,7 +50,7 @@ on:
 
 env:
   # Default Python version to use.
-  py_version: "3.10.15"
+  py_version: "3.11.15"
 
   # Additional .bazelrc options to use.
   bazelrc_additions: |

.github/workflows/ci-nightly-cirq-test.yaml

@@ -36,7 +36,7 @@ on:
       py_version:
         description: Version of Python to use
         type: string
-        default: "3.10.15"
+        default: "3.11.15"
 
       bazel_version:
         description: Version of Bazel Python to use
@@ -64,7 +64,7 @@ on:
 
 env:
   # Default Python version to use.
-  py_version: "3.10.15"
+  py_version: "3.11.15"
 
   # Bazel version. Note: this needs to match what is used in TF & TFQ.
   bazel_version: 6.5.0

CONTRIBUTING.md

@@ -65,7 +65,9 @@ Some of the important files found at the top level include the following:
 
 *   `README.md`: General introduction to the project
 *   `configure.sh`: TFQ build configuration script
-*   `requirements.txt`: Python dependencies
+*   `requirements.txt`: Primary Python 3.11 dependency lock
+*   `requirements_lock_3_10.txt`, `requirements_lock_3_11.txt`,
+    `requirements_lock_3_12.txt`: Version-specific Python dependency locks
 
 ### Coding style
 
@@ -143,7 +145,7 @@ Follow the instructions in [docs/install.md](docs/install.md) for setting up a
 development environment. After doing that, you should end up with:
 
 *   The correct version of Bazel (6.5.0)
-*   A Python virtual environment with a Python version between 3.10 and 3.12
+*   A Python virtual environment with Python 3.10, 3.11, or 3.12
 *   The TFQ Python requirements installed in that Python virtual environment
 *   The TFQ build configured by running `./configure.sh`
 

README.md

@@ -8,8 +8,8 @@ High-performance Python framework for hybrid quantum-classical machine learning
 
 [![Licensed under the Apache 2.0
 license](https://img.shields.io/badge/License-Apache%202.0-3c60b1.svg?logo=opensourceinitiative&logoColor=white&style=flat-square)](https://github.com/tensorflow/quantum/blob/master/LICENSE)
-[![Compatible with Python versions 3.10 and
-higher](https://img.shields.io/badge/Python-3.10+-fcbc2c.svg?style=flat-square&logo=python&logoColor=white)](https://www.python.org/downloads/)
+[![Compatible with Python versions 3.11 and
+3.12](https://img.shields.io/badge/Python-3.11--3.12-fcbc2c.svg?style=flat-square&logo=python&logoColor=white)](https://www.python.org/downloads/)
 [![TensorFlow Quantum project on
 PyPI](https://img.shields.io/pypi/v/TensorFlow_Quantum.svg?logo=python&logoColor=white&label=PyPI&style=flat-square&color=fcbc2c)](https://pypi.org/project/tensorflow-quantum)
 
@@ -42,14 +42,14 @@ from [TensorFlow](https://tensorflow.org). Here are some of TFQ's features:
     adjoint methods
 *   Implements operations as C++ TensorFlow Ops, making them 1<sup>st</sup>-class
     citizens in the TF compute graph
-*   Harnesses TensorFlow’s computational machinery to provide exceptional
+*   Harnesses TensorFlow's computational machinery to provide exceptional
     performance and scalability
 
 TensorFlow Quantum empowers quantum algorithms and machine learning researchers
 to pursue questions whose answers can only be obtained through fast simulation
 of many millions of moderately-sized circuits. It has already been instrumental
 in enabling ground-breaking research in QML by providing a seamless workflow for
-leveraging Google’s quantum computing offerings.
+leveraging Google's quantum computing offerings.
 
 ## Installation
 
@@ -59,11 +59,15 @@ instructions](https://www.tensorflow.org/quantum/install) in the documentation.
 _Compatibility_: At this time, TensorFlow Quantum is built and
 tested on Linux with the following systems and software:
 
-* Python 3.10–3.12
+* Python 3.10-3.12
 * TensorFlow 2.19.1
 * TF-Keras 2.19.0
-* NumPy 2.0
-* Cirq 1.5.0
+* NumPy 2.1
+* Cirq 1.5.0-1.6.1
+
+Python 3.13 is not supported yet because TensorFlow 2.19.1 does not publish
+Python 3.13 wheels. Python 3.10 uses Cirq 1.5.0, while Python 3.11-3.12 use
+Cirq 1.6.1.
 
 ## Quick start
 

WORKSPACE

@@ -34,16 +34,25 @@ load("@local_config_python//:defs.bzl", "interpreter")
 
 register_toolchains("@local_config_python//:py_toolchain")
 
+load("//third_party:select_requirements_lock.bzl", "select_requirements_lock")
 load("@rules_python//python:pip.bzl", "pip_parse")
 
+select_requirements_lock(
+    name = "tfq_active_requirements_lock",
+    python_bin_path = interpreter,
+    requirements_lock_3_10 = "//:requirements_lock_3_10.txt",
+    requirements_lock_3_11 = "//:requirements_lock_3_11.txt",
+    requirements_lock_3_12 = "//:requirements_lock_3_12.txt",
+)
+
 pip_parse(
     name = "pypi",
     extra_pip_args = [
         "--index-url",
         "https://pypi.org/simple/",
     ],
     python_interpreter = interpreter,
-    requirements_lock = "//:requirements.txt",
+    requirements_lock = "@tfq_active_requirements_lock//:requirements.txt",
 )
 
 load("@pypi//:requirements.bzl", "install_deps")
@@ -93,8 +102,7 @@ http_archive(
 load("@org_tensorflow//third_party/py:python_repo.bzl", "python_repository")
 
 # TensorFlow 2.19 expects @python_version_repo to exist even when TFQ manages
-# its own pip_parse setup. Reuse the single lockfile across the supported
-# interpreter versions.
+# its own pip_parse setup. Provide lockfiles for each supported interpreter.
 python_repository(
     name = "python_version_repo",
     default_python_version = "system",

configure.sh

@@ -41,6 +41,20 @@ function is_windows() {
   [[ "${PLATFORM}" =~ msys_nt*|mingw*|cygwin*|uwin* ]]
 }
 
+function require_supported_python() {
+  local py_bin="$1"
+
+  if ! "${py_bin}" - <<'PY'
+import sys
+raise SystemExit(0 if (3, 10) <= sys.version_info[:2] < (3, 13) else 1)
+PY
+  then
+    die "Python 3.10, 3.11, or 3.12 required for TensorFlow Quantum, but found " \
+      "$("${py_bin}" -V 2>&1). Pass --python=/path/to/python3.10-3.12 " \
+      "or set PYTHON_BIN_PATH."
+  fi
+}
+
 function inside_docker() {
   if [[ -f /.dockerenv ]]; then
     return 1
@@ -53,10 +67,13 @@ function inside_docker() {
 
 # --- parse args ------------------------------------------------------------
 USER_PY=""
+BUILD_BACKEND="cpu"
 for arg in "$@"; do
   case "$arg" in
     --python=*) USER_PY="${arg#--python=}" ;;
-    *) echo "Unknown arg: $arg" ;;
+    --cpu) BUILD_BACKEND="cpu" ;;
+    --gpu) BUILD_BACKEND="gpu" ;;
+    *) die "Unknown arg: $arg" ;;
   esac
 done
 
@@ -71,23 +88,16 @@ elif [[ -n "${CONDA_PREFIX:-}" && -x "${CONDA_PREFIX}/bin/python" ]]; then
   # 3) Conda environment python, if available
   PY="${CONDA_PREFIX}/bin/python"
 else
-  # 4) Fallback: system python3, but require >= 3.10
+  # 4) Fallback: system python3, but require Python 3.10-3.12.
   if ! command -v python3 >/dev/null 2>&1; then
-    die "python3 not found. Pass --python=/path/to/python3.10+ or set PYTHON_BIN_PATH."
-  fi
-
-  if ! python3 - <<'PY'
-import sys
-raise SystemExit(0 if sys.version_info[:2] >= (3, 10) else 1)
-PY
-  then
-    die "Python 3.10+ required for TensorFlow Quantum, but found " \
-      "$(python3 -V 2>&1). Pass --python=/path/to/python3.10+ or set PYTHON_BIN_PATH."
+    die "python3 not found. Pass --python=/path/to/python3.10-3.12 or set PYTHON_BIN_PATH."
   fi
 
   PY="$(command -v python3)"
 fi
 
+require_supported_python "${PY}"
+
 # Normalize to an absolute path. Use Python to print sys.executable because
 # tools like pyenv use shim scripts that readlink would resolve to the script
 # itself, not the actual interpreter binary.
@@ -101,16 +111,13 @@ inside_docker && echo "${info_string}." || echo "${info_string} inside Docker."
 echo
 
 # --- choose CPU/GPU like upstream script (default CPU) ---------------------
-TF_NEED_CUDA=""
-y_for_cpu='Build against TensorFlow CPU backend? (Type n to use GPU) [Y/n] '
-while [[ -z "${TF_NEED_CUDA}" ]]; do
-  read -p "${y_for_cpu}" INPUT || true
-  case "${INPUT:-Y}" in
-    [Yy]* ) echo "CPU build selected."; TF_NEED_CUDA=0;;
-    [Nn]* ) echo "GPU build selected."; TF_NEED_CUDA=1;;
-    * ) echo "Please answer y or n.";;
-  esac
-done
+TF_NEED_CUDA=0
+if [[ "${BUILD_BACKEND}" == "gpu" ]]; then
+  TF_NEED_CUDA=1
+  echo "GPU build selected via --gpu."
+else
+  echo "CPU build selected."
+fi
 
 # For TF >= 2.1 this value isn’t actually consulted by TFQ,
 # but we keep a compatible prompt/flag.

docs/install.md

@@ -10,7 +10,10 @@ There are a few ways to set up your environment to use TensorFlow Quantum (TFQ):
   Python's pip package manager.
 * Or build TensorFlow Quantum from source.
 
-TensorFlow Quantum is supported on Python version 3.10 through 3.12 and depends directly on [Cirq](https://github.com/quantumlib/Cirq).
+TensorFlow Quantum is supported on Python versions 3.10, 3.11, and 3.12 and
+depends directly on [Cirq](https://github.com/quantumlib/Cirq). Python 3.10
+uses Cirq 1.5.0, while Python 3.11-3.12 use Cirq 1.6.1. Python 3.13 is not
+supported yet because TensorFlow 2.19.1 does not publish Python 3.13 wheels.
 
 ## Pip package
 
@@ -57,13 +60,13 @@ The following steps are tested for Ubuntu-like systems.
 
 ### 1. Set up a Python 3 development environment
 
-We will use Python 3.10 as an example. First, we need the Python 3.10 development tools.
+We will use Python 3.11 as an example. First, we need the Python 3.11 development tools.
 <!-- common_typos_disable -->
 <pre class="devsite-click-to-copy">
   <code class="devsite-terminal">sudo apt update</code>
-  <code class="devsite-terminal">sudo apt-get install pkg-config zip g++ zlib1g-dev unzip python3.10</code>
-  <code class="devsite-terminal">sudo apt install python3.10 python3.10-dev python3.10-venv python3-pip</code>
-  <code class="devsite-terminal">python3.10 -m pip install --upgrade pip</code>
+  <code class="devsite-terminal">sudo apt-get install pkg-config zip g++ zlib1g-dev unzip python3.11</code>
+  <code class="devsite-terminal">sudo apt install python3.11 python3.11-dev python3.11-venv python3-pip</code>
+  <code class="devsite-terminal">python3.11 -m pip install --upgrade pip</code>
 </pre>
 <!-- common_typos_enable -->
 
@@ -72,7 +75,7 @@ We will use Python 3.10 as an example. First, we need the Python 3.10 developmen
 Go to your workspace directory and make a virtual environment for TFQ development.
 <!-- common_typos_disable -->
 <pre class="devsite-click-to-copy">
-  <code class="devsite-terminal">python3.10 -m venv quantum_env</code>
+  <code class="devsite-terminal">python3.11 -m venv quantum_env</code>
   <code class="devsite-terminal">source quantum_env/bin/activate</code>
 </pre>
 <!-- common_typos_enable -->
@@ -161,7 +164,7 @@ We use the standard [fork and pull request workflow](https://guides.github.com/a
 <pre class="devsite-click-to-copy">
   <code class="devsite-terminal">git clone https://github.com/<var>username</var>/quantum.git</code>
   <code class="devsite-terminal">cd quantum</code>
-  <code class="devsite-terminal">pip install -r requirements.txt</code>
+  <code class="devsite-terminal">pip install -r "$(bash ./scripts/select_requirements_lock.sh)"</code>
 </pre>
 <!-- common_typos_enable -->
 
@@ -172,7 +175,7 @@ the command below to install the TensorFlow Quantum dependencies:
 
 <!-- common_typos_disable -->
 <pre class="devsite-click-to-copy">
-  <code class="devsite-terminal">pip install -r requirements.txt</code>
+  <code class="devsite-terminal">pip install -r "$(bash ./scripts/select_requirements_lock.sh)"</code>
 </pre>
 <!-- common_typos_enable -->
 

release/README.md

@@ -68,7 +68,7 @@ into the upstream repository before proceeding further.
 
 3.  `cd` into that directory in a Bash shell.
 
-### Rebuild the `requirements.txt` file
+### Rebuild the requirements lock files
 
 1.  Create a Python virtual environment using the lowest version of Python
     supported by TFQ. (Currently this is Python 3.10.)
@@ -80,10 +80,12 @@ into the upstream repository before proceeding further.
     ./scripts/generate_requirements.sh
     ```
 
-    This will update the dependency versions in the file `requirements.txt` to
-    the latest versions based on `requirements.in`. If this process fails, you
-    may have to iterate on adjusting the constraints in `requirements.in`
-    followed by running `generate_requirements.sh` again until it succeeds.
+    This will update the dependency versions in the version-specific lock file
+    for the Python interpreter you used to run the script. When run under
+    Python 3.11, it also refreshes `requirements.txt` as the primary dev lock.
+    If this process fails, you may have to iterate on adjusting the constraints
+    in `requirements.in` followed by running `generate_requirements.sh` again
+    until it succeeds.
 
 3.  If any changes were made to `requirements.in`, check the requirements listed
     inside `release/setup.py` and make corresponding changes if the changes to
@@ -101,7 +103,7 @@ the following:
     *   Important: if solving the problem requires changes to the versions of
         dependency packages, make sure to update both `requirements.in` and
         `release/setup.py` (if applicable), and then **go back to the previous
-        subsection on rebuilding `requirements.txt`** and do it over.
+        subsection on rebuilding the requirements lock files** and do it over.
 
 3.  If `build_release.sh` succeeds without error, it should leave a new `.whl`
     file in the subdirectory `wheelhouse/`. Verify that it is there.

release/build_distribution.sh

@@ -94,7 +94,8 @@ exec 2> >(sed "s/^/[DOCKER] /" >&2)
 
 printf ":::::::: Configuring Python environment ::::::::\n\n"
 python3 -m pip install --upgrade pip --root-user-action ignore
-python3 -m pip install -r requirements.txt --root-user-action ignore
+requirements_file="\$(bash ./scripts/select_requirements_lock.sh --python=\$(command -v python3))"
+python3 -m pip install -r "\${requirements_file}" --root-user-action ignore
 
 printf "\n\n:::::::: Configuring TFQ build ::::::::\n\n"
 printf "Y\n" | ./configure.sh

release/build_pip_package.sh

@@ -17,26 +17,27 @@
 set -e
 
 # Pick the Python that TFQ/TensorFlow used during configure/build.
-# Order: explicit env -> python3 (>= 3.10)
+# Order: explicit env -> python3 (3.10-3.12)
 PY="${PYTHON_BIN_PATH:-}"
 if [[ -z "${PY}" ]]; then
   if ! command -v python3 >/dev/null 2>&1; then
-    echo "ERROR: python3 not found. Set PYTHON_BIN_PATH to a Python 3.10+ interpreter." >&2
+    echo "ERROR: python3 not found. Set PYTHON_BIN_PATH to a Python 3.10, 3.11, or 3.12 interpreter." >&2
     exit 2
   fi
 
-  # Require Python >= 3.10 for TFQ.
-  if ! python3 - <<'PY'
+  PY="$(command -v python3)"
+fi
+
+# Require Python 3.10-3.12 for TFQ.
+if ! "${PY}" - <<'PY'
 import sys
-sys.exit(0 if sys.version_info[:2] >= (3, 10) else 1)
+sys.exit(0 if (3, 10) <= sys.version_info[:2] < (3, 13) else 1)
 PY
-  then
-    echo "ERROR: Python 3.10+ required for TensorFlow Quantum; found $(python3 -V 2>&1)." >&2
-    exit 2
-  fi
-
-  PY="$(command -v python3)"
+then
+  echo "ERROR: Python 3.10, 3.11, or 3.12 required for TensorFlow Quantum; found $("${PY}" -V 2>&1)." >&2
+  exit 2
 fi
+
 echo "Using Python: ${PY}"
 
 # Ensure packaging tools are present in THIS interpreter.