Merge alias sampling / QROM state prep (#621) into the SOSSA branch

Brings feature/cyr/sossa up to yingrongchen-alias-sampling-qrom-state-prep
at 3e6053e, so #539 can be retargeted onto #621 and reviewed as the
incremental SOSSA diff rather than as SOSSA plus all of alias sampling.

The previous merge (ca88541) captured 4ab6221; the alias branch has
moved 42 commits since, including two merges of main.

Two conflicts, both add/add registration lists, both resolved as unions:

- controlled_circuit_mapper/__init__.py: each side added a different mapper
  import and its __all__ entries. Kept both; __all__ is exactly the nine
  imported names.
- registry.py: each side registered a different mapper. Kept both, preserving
  each side's relative order, since registration order is load-bearing here
  (DensePureStatePreparation must precede SparseIsometryStatePreparation).

Two further breakages had NO conflict markers and would have shipped silently
had the merge been trusted at face value:

- PhaseGradient.qs: #621 deleted MakePhaseGradientAncillaPrep in ef8f189
  under a "Dead code" heading. It is dead on that branch but live on this one:
  sossa_mapper.get_ancilla_prep_op calls it, and SOSSAWalk.qs imports it. Git
  took the deletion cleanly because this side never touched that region.
  Restored verbatim, with a note recording why it must stay.
- PrepSelPrep.qs: #621 changed PrepSelPrep's 4th parameter from
  ancillaRegister to prepareRegister and added numSelectQubits, because an
  alias-sampling PREPARE register is wider than the select index. PSPWalk on
  this side still called it with four arguments. PSPWalk keeps its own arity,
  since MakeControlledPSPWalkOp and TestPSPWalkOnBasisState both depend on it;
  only its two internal calls pass the new argument, as
  Length(ancillaRegister), which is what merge-base computed as
  numAncillaQubits and so preserves the previous semantics exactly.

Verified: Q# project compiles; all 57 distinct QSHARP_UTILS.<ns>.<name>
references from Python resolve against the compiled context, with the checker
calibrated in both directions; ruff check and ruff format clean over 326 files.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Author: YingrongChen

.devcontainer/Dockerfile

@@ -11,8 +11,7 @@ RUN apt-get update && apt-get install -y locales && \
 ENV LANG=en_US.UTF-8 \
     LANGUAGE=en_US:en \
     LC_ALL=en_US.UTF-8 \
-    QDK_UARCH=native \
-    LD_LIBRARY_PATH=/usr/local/lib:${LD_LIBRARY_PATH} \
+    LD_LIBRARY_PATH=/usr/local/lib \
     PATH=/usr/local/bin:${PATH}
 
 # Create a non-root user with sudo privileges
@@ -31,6 +30,7 @@ RUN apt-get update && \
     gnupg \
     build-essential \
     cmake \
+    ccache \
     clang \
     pkg-config \
     python3 \
@@ -45,7 +45,6 @@ RUN apt-get update && \
     libgtest-dev \
     libgmock-dev \
     libfmt-dev \
-    libecpint-dev \
     ninja-build \
     gcovr \
     patchelf \
@@ -54,6 +53,11 @@ RUN apt-get update && \
     && apt-get clean \
     && rm -rf /var/lib/apt/lists/*
 
+# Install the memory-/core-aware build parallelism helper. It is used during
+# dependency installation and may also be sourced by development scripts and
+# interactive shells.
+COPY .devcontainer/scripts/parallelism.sh /usr/local/share/qdk/parallelism.sh
+
 # Install C++ dependencies
 COPY .devcontainer/scripts/install_cpp_dependencies.sh /tmp/install_cpp_dependencies.sh
 COPY cpp/manifest/qdk-chemistry/cgmanifest.json /tmp/cpp_cgmanifest.json
@@ -62,7 +66,7 @@ COPY external/macis/manifest/cgmanifest.json /tmp/macis_cgmanifest.json
 # Delete build directory after installation
 ENV KEEP_BUILD_DIR=0
 RUN bash /tmp/install_cpp_dependencies.sh /tmp/cpp_cgmanifest.json /tmp/macis_cgmanifest.json && \
-     rm /tmp/install_cpp_dependencies.sh /tmp/cpp_cgmanifest.json /tmp/macis_cgmanifest.json
+    rm /tmp/install_cpp_dependencies.sh /tmp/cpp_cgmanifest.json /tmp/macis_cgmanifest.json
 
 # Create/align the non-root user and group (safe for repeated builds)
 RUN if getent group "$USER_GID" >/dev/null; then \
@@ -89,3 +93,38 @@ USER $USERNAME
 
 # Setup bash prompt
 RUN echo 'export PS1="\[\033[1;34m\]\u@qdk-dev:\w$ \[\033[0m\]"' >> ~/.bashrc
+
+# Use Microsoft's public package proxies by default. Override these build
+# arguments to use different registries.
+ARG NPM_CONFIG_REGISTRY=https://packagefeedproxy.microsoft.io/npm/
+ENV NPM_CONFIG_REGISTRY=${NPM_CONFIG_REGISTRY}
+
+ARG PIP_INDEX_URL=https://packagefeedproxy.microsoft.io/pypi/simple
+ENV PIP_INDEX_URL=${PIP_INDEX_URL}
+
+# Create the Python virtual environment.
+ENV VIRTUAL_ENV=/home/$USERNAME/qdk_chemistry_venv \
+    PATH=/home/$USERNAME/qdk_chemistry_venv/bin:$PATH
+
+# The post-create editable install disables build isolation so its persistent
+# CMake cache uses stable tool paths. Preinstall python/pyproject.toml's
+# [build-system].requires here; --check-build-dependencies detects any drift.
+RUN python -m venv "$VIRTUAL_ENV" \
+    && python -m pip install --no-cache-dir --upgrade pip setuptools wheel \
+    && python -m pip install --no-cache-dir \
+    "scikit-build-core>=0.10.0" \
+    "pybind11>=2.13.6" \
+    "numpy>=2.0.0,<2.4.0" \
+    && echo "source $VIRTUAL_ENV/bin/activate" >> ~/.bashrc
+
+# Set the safe CMAKE_BUILD_PARALLEL_LEVEL for interactive shells
+RUN echo "source /usr/local/share/qdk/parallelism.sh" >> ~/.bashrc
+
+# Set ENV variables for the container environment.
+# Override in shell (per-session) or devcontainer.json (persistent), if needed.
+#   CMAKE_PREFIX_PATH - Make user-local C++ installations discoverable
+#   QDK_UARCH         - default to native architecture for QDK builds
+#   CMAKE_BUILD_TYPE  - default CMake build type
+ENV CMAKE_PREFIX_PATH=/home/$USERNAME/.local \
+    QDK_UARCH=native \
+    CMAKE_BUILD_TYPE=RelWithDebInfo

.devcontainer/devcontainer-lock.json

@@ -0,0 +1,19 @@
+{
+  "features": {
+    "ghcr.io/devcontainers/features/git:1": {
+      "version": "1.3.8",
+      "resolved": "ghcr.io/devcontainers/features/git@sha256:fd75977de13a9979000e0e78baf949adb0ca71d2398995fa22e0a36d7e7e7fe2",
+      "integrity": "sha256:fd75977de13a9979000e0e78baf949adb0ca71d2398995fa22e0a36d7e7e7fe2"
+    },
+    "ghcr.io/devcontainers/features/node:2": {
+      "version": "2.1.0",
+      "resolved": "ghcr.io/devcontainers/features/node@sha256:586c9a6f7dd40bd3ba2cd41e7f2f88dcc31fbe5d1442afcbf07ffbc66b686857",
+      "integrity": "sha256:586c9a6f7dd40bd3ba2cd41e7f2f88dcc31fbe5d1442afcbf07ffbc66b686857"
+    },
+    "ghcr.io/devcontainers/features/rust:1": {
+      "version": "1.5.1",
+      "resolved": "ghcr.io/devcontainers/features/rust@sha256:f7afd923fd283db88ca961342ae65ea63a8c95bcf86e42c4c363f43bc4ba26a5",
+      "integrity": "sha256:f7afd923fd283db88ca961342ae65ea63a8c95bcf86e42c4c363f43bc4ba26a5"
+    }
+  }
+}

.devcontainer/devcontainer.json

@@ -20,15 +20,12 @@
                 "ms-toolsai.jupyter"
             ],
             "settings": {
-                "python.defaultInterpreterPath": "/usr/local/bin/python",
-                "python.formatting.provider": "none",
+                "python.defaultInterpreterPath": "${containerEnv:VIRTUAL_ENV}/bin/python",
                 "editor.formatOnSave": true,
                 "editor.codeActionsOnSave": {
-                    "source.fixAll.ruff": true,
-                    "source.organizeImports.ruff": true
+                    "source.fixAll.ruff": "explicit",
+                    "source.organizeImports.ruff": "explicit"
                 },
-                "python.linting.enabled": true,
-                "python.linting.lintOnSave": true,
                 "[python]": {
                     "editor.defaultFormatter": "charliermarsh.ruff",
                     "editor.formatOnSave": true,
@@ -55,16 +52,25 @@
                 "C_Cpp.codeAnalysis.clangTidy.runAutomatically": true,
                 "C_Cpp.formatting": "clangFormat",
                 "C_Cpp.clang_format_style": "file",
-                "C_Cpp.clang_format_fallbackStyle": "Google"
+                "C_Cpp.clang_format_fallbackStyle": "Google",
+                "C_Cpp.default.cppStandard": "c++20",
+                "cmake.buildType": "RelWithDebInfo"
             }
         }
     },
     "features": {
-        "ghcr.io/devcontainers/features/git:1": {}
+        "ghcr.io/devcontainers/features/git:1": {},
+        "ghcr.io/devcontainers/features/node:2": {
+            "version": "lts"
+        },
+        "ghcr.io/devcontainers/features/rust:1": {
+            "version": "stable",
+            "profile": "default"
+        }
     },
     "remoteEnv": {
-        "CPATH": "${containerEnv:CPATH}:/usr/include/hdf5/serial:/usr/include/eigen3"
+        "CPATH": "/usr/include/hdf5/serial:/usr/include/eigen3"
     },
-    "postCreateCommand": "bash .devcontainer/scripts/venv.sh",
+    "postCreateCommand": "bash .devcontainer/scripts/post_create.sh",
     "remoteUser": "vscode"
 }

.devcontainer/scripts/install_cpp_dependencies.sh

@@ -37,13 +37,30 @@ BUILD_DIR="${BUILD_DIR:-/tmp/qdk_deps_build}"
 INSTALL_PREFIX="${INSTALL_PREFIX:-/usr/local}"
 BUILD_TYPE="${BUILD_TYPE:-Release}"
 BUILD_SHARED_LIBS="${BUILD_SHARED_LIBS:-OFF}"  # Default to static
-LIBINT_JOBS=${LIBINT_JOBS:-4}  # Limit libint build jobs to 4 due to high memory usage
+
 KEEP_BUILD_DIR="${KEEP_BUILD_DIR:-0}"
-if command -v nproc >/dev/null 2>&1; then
-    JOBS=$(nproc) # Linux
+
+PARALLELISM_HELPER="/usr/local/share/qdk/parallelism.sh"
+if [ -f "$PARALLELISM_HELPER" ]; then
+    # shellcheck source=/dev/null
+    source "$PARALLELISM_HELPER"
+fi
+
+if command -v parallel_jobs_for_memory >/dev/null 2>&1; then
+    # Use the parallelism helper to determine job counts based on memory
+    JOBS="${JOBS:-$(parallel_jobs_for_memory 1)}"
+    LIBINT_JOBS="${LIBINT_JOBS:-$(parallel_jobs_for_memory 4)}"
 else
-    JOBS=$(sysctl -n hw.logicalcpu) # macOS
+    # Fallback when helper is unavailable
+    if command -v nproc >/dev/null 2>&1; then
+        DEFAULT_JOBS=$(nproc) # Linux
+    else
+        DEFAULT_JOBS=$(sysctl -n hw.logicalcpu) # macOS
+    fi
+    JOBS="${JOBS:-$DEFAULT_JOBS}"
+    LIBINT_JOBS="${LIBINT_JOBS:-4}"
 fi
+
 MAC_BUILD="OFF"
 if [[ "$OSTYPE" == "darwin"* ]]; then
     MAC_BUILD="ON"
@@ -224,7 +241,6 @@ cmake .. -DCMAKE_BUILD_TYPE="$BUILD_TYPE" \
          -DCMAKE_INSTALL_PREFIX="$INSTALL_PREFIX" \
          -DCMAKE_POSITION_INDEPENDENT_CODE=ON \
          -DBUILD_SHARED_LIBS="$BUILD_SHARED_LIBS"
-# libint's compilation is memory intensive so parallel jobs are limited to 4 to prevent OOM errors
 make -j"$LIBINT_JOBS"
 make install
 cd "$BUILD_DIR"

.devcontainer/scripts/parallelism.sh

@@ -0,0 +1,53 @@
+# shellcheck shell=bash
+#
+# This file is intended to be sourced.
+#
+# It provides:
+# - parallel_jobs_for_memory()
+# - a default CMAKE_BUILD_PARALLEL_LEVEL (unless already set)
+#
+# parallel_jobs_for_memory <memory_per_job_gb>
+#
+# Compute a safe parallel job count based on available RAM and CPU cores.
+#
+# Result:
+#   min(cpu_cores, floor(total_ram_gb / memory_per_job_gb))
+#
+# with a minimum value of 1.
+#
+parallel_jobs_for_memory() {
+    local memory_per_job_gb="$1"
+    local cores mem_bytes jobs
+
+    if [ -r /proc/meminfo ] && command -v nproc >/dev/null 2>&1; then
+        # Linux
+        cores=$(nproc)
+        mem_bytes=$(awk '/MemTotal/ {print $2 * 1024}' /proc/meminfo)
+    else
+        # macOS (or other non-/proc environments)
+        cores=$(sysctl -n hw.logicalcpu)
+        mem_bytes=$(sysctl -n hw.memsize)
+    fi
+
+    # If running inside a cgroup with a memory limit, respect it.
+    local cgroup_limit_bytes=""
+    if [ -r /sys/fs/cgroup/memory.max ]; then
+        cgroup_limit_bytes="$(cat /sys/fs/cgroup/memory.max)"                    # cgroup v2
+    elif [ -r /sys/fs/cgroup/memory/memory.limit_in_bytes ]; then
+        cgroup_limit_bytes="$(cat /sys/fs/cgroup/memory/memory.limit_in_bytes)"  # cgroup v1
+    fi
+    if [[ "$cgroup_limit_bytes" =~ ^[0-9]+$ ]] && (( cgroup_limit_bytes > 0 )) && (( cgroup_limit_bytes < mem_bytes )); then
+        mem_bytes="$cgroup_limit_bytes"
+    fi
+
+    jobs=$(( mem_bytes / (memory_per_job_gb * 1024 * 1024 * 1024) ))
+
+    (( jobs < 1 )) && jobs=1
+    (( jobs > cores )) && jobs=$cores
+
+    echo "$jobs"
+}
+
+if [ -z "${CMAKE_BUILD_PARALLEL_LEVEL:-}" ]; then
+    export CMAKE_BUILD_PARALLEL_LEVEL="$(parallel_jobs_for_memory 8)"
+fi

.devcontainer/scripts/post_create.sh

@@ -0,0 +1,27 @@
+#!/bin/bash
+# Post-create step: install QDK Chemistry from the mounted source.
+set -euo pipefail
+source "${VIRTUAL_ENV:?}/bin/activate"
+
+# Set a memory-/core-aware CMAKE_BUILD_PARALLEL_LEVEL (unless already set) so the
+# initial build below does not oversubscribe CPU or OOM on constrained machines.
+source /usr/local/share/qdk/parallelism.sh
+
+# Build C++ and install to a user-local prefix.
+# Use the in-tree macis (external/macis) per INSTALL.md; prevents a
+# full rebuild on reconfigure.
+cmake -S cpp -B cpp/build -G Ninja \
+    -DCMAKE_INSTALL_PREFIX="$HOME/.local" \
+    -DCMAKE_BUILD_TYPE="${CMAKE_BUILD_TYPE:-RelWithDebInfo}" \
+    -DCMAKE_CXX_COMPILER_LAUNCHER=ccache \
+    -DCMAKE_DISABLE_FIND_PACKAGE_macis=ON
+cmake --build cpp/build
+cmake --install cpp/build
+
+# Install python library
+cd ./python
+pip install -v \
+    --no-build-isolation \
+    --check-build-dependencies \
+    -C build-dir="build/{wheel_tag}" \
+    -e '.[all]'

.devcontainer/scripts/venv.sh

@@ -19,17 +19,17 @@ job. Limit build parallelism by both the available memory and the CPU count.
    including builds started indirectly by `pip`.
 
 For example, a machine with 32 GB of available RAM and 16 logical CPUs should
-compile with at most six jobs:
+compile with at most four jobs:
 
 ```bash
-export CMAKE_BUILD_PARALLEL_LEVEL=6
+export CMAKE_BUILD_PARALLEL_LEVEL=4
 cmake --build cpp/build
 ```
 
 For a Python package build, apply the same limit:
 
 ```bash
-CMAKE_BUILD_PARALLEL_LEVEL=6 python -m pip install ./python
+CMAKE_BUILD_PARALLEL_LEVEL=4 python -m pip install ./python
 ```
 
 If a build is killed or reports an out-of-memory error, reduce

.github/skills/memory-aware-build/SKILL.md

@@ -130,6 +130,31 @@ Alternatively, click the green button in the bottom-left corner of VS Code and s
 
 After the initial build, restart VS Code and reopen in the container to ensure the Python virtual environment is properly loaded.
 
+### Step 4: Develop
+
+The dev container installs the Python package in editable mode, so changes to pure Python files are available immediately. After changing pybind11 sources, rebuild the Python package:
+
+```bash
+python -m pip install --no-build-isolation --check-build-dependencies --no-deps \
+  -C build-dir="build/{wheel_tag}" -e ./python
+```
+
+After changing the C++ library, build and install it before rebuilding the Python bindings:
+
+```bash
+cmake --build cpp/build --target chemistry
+cmake --install cpp/build
+python -m pip install --no-build-isolation --check-build-dependencies --no-deps \
+  -C build-dir="build/{wheel_tag}" -e ./python
+```
+
+Build only the relevant C++ test target during development, then run its tests from the directory where CTest registers them. For example:
+
+```bash
+cmake --build cpp/build --target test_algorithm_hash
+ctest --test-dir cpp/build/tests --output-on-failure -R AlgorithmHash
+```
+
 **NOTE:**
 
 - The first build can take up to two hours on slower systems.