Optimized qpp::sample()

Signed-off-by: Vlad Gheorghiu <vsoftco@gmail.com>

Author: vsoftco

.gitignore

@@ -66,6 +66,7 @@ mat.txt
 examples/_*.cpp
 out.tmp
 TODO.txt
+NOTES.txt
 test
 
 # pyqpp

CHANGES.md

@@ -1,15 +1,15 @@
-# Version 7.0.0 - xx December 2025
+# Version 7.0.0 - xx March 2026
 
 - Significant performance improvements (10x to 1000x) for qubit state
   manipulation and qubit circuit execution through extensive optimizations of
-  `qpp::apply()` and `qpp::applyCTRL()`
+  `qpp::apply()`, `qpp::applyCTRL()`, and `qpp::measure_seq()`.
 - **pyqpp** is now feature complete, providing Python users with
   complete access to the full **Quantum++** API
-- Switched back to MAJOR.MINOR.PATCH release versioning system:
+- Switched to MAJOR.MINOR.PATCH release versioning system:
   - MAJOR -- introduces significant changes that break backward compatibility
   - MINOR -- may include limited or minor compatibility breaks
   - PATCH -- fully backward compatible fixes and improvements
-- Renamed the `qpp::Bit_circuit` to `qpp::BitCircuit` and
+- Renamed the class `qpp::Bit_circuit` to `qpp::BitCircuit` and the class
   `qpp::Dynamic_bitset` to `qpp::DynamicBitset` in ["qpp/classes/reversible.hpp"]
 - Renamed the class `internal::QCircuitConditionalStep` to
   `internal::QCircuitRuntimeStep`, and the corresponding
@@ -22,14 +22,16 @@
   `qpp::QCircuit::set_dits_runtime(mutable_dits_functor_t dits)`. Here
   `mutable_dits_functor_t` is an alias to an internal mutable functor defined
   in ["qpp/internal/classes/qcircuit_runtime_step.hpp"]
-- Changed `cond_func_t` type alias to `cond_pred_t` for
-  Boolean predicates in conditional statements and moved the type alias from
+- Changed `cond_func_t` type alias to `cond_pred_t` for Boolean predicates in
+  conditional statements and moved the type alias from
   ["qpp/types.hpp"] to
   ["qpp/internal/classes/qcircuit_runtime_step.hpp"]; alias to an internal type.
 - Added
   ["examples/circuits/runtime_set_dits.cpp"](https://github.com/softwareQinc/qpp/blob/main/examples/circuits/runtime_set_dits.cpp)
 - Conditional statements are now indented with tabs when displaying
-  qpp::QCircuit instances
+  `qpp::QCircuit` instances
+- API change in `qpp::sample(A, target, dims)` overload, added the overall
+  outcome probability to its return type `std::tuple<std::vector<idx>, realT>`
 - Bumped Eigen3 minimum required version to 5.0.0
 - Bumped CMake minimum required version to 3.20
 - Modernized CMake configuration files
@@ -40,9 +42,9 @@
   in ["benchmarks"](https://github.com/softwareQinc/qpp/blob/main/benchmarks)
 - Bugfixes for `qpp::QFT()` and `qpp::TFQ()`
 - Added `pyqpp.QEngine.get_stats_to_JSON()` to display the measurement
-  statistics in JSON format from `pyqpp`
-- Finalized pyqpp, now all Quantum++ functions have corresponding bindings in
-  Python
+  statistics in JSON format from **pyqpp**
+- **pyqpp** is feature-complete, now all Quantum++ functions have corresponding
+  bindings in Python
 
 # Version 6.0 - 14 April 2025
 

docker/Dockerfile

@@ -1,36 +1,35 @@
-FROM ubuntu:latest
-ENV TZ="America/Toronto"
-RUN apt-get update && \
-    apt-get -y update && \
-    apt-get install -yq tzdata && \
-    ln -fs /usr/share/zoneinfo/America/Toronto /etc/localtime && \
-    dpkg-reconfigure -f noninteractive tzdata
+FROM python:3.11-slim-bookworm
 
-RUN apt-get install -y build-essential python3 python3-pip python3-dev \
-    python3-venv libeigen3-dev cmake sudo git vim
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    cmake \
+    libeigen3-dev \
+    git \
+    vim \
+    sudo
 
-# Enable a normal user with sudo access
-RUN useradd -m -c "softwareQ" sq
-RUN echo '%sq ALL=(ALL) NOPASSWD:ALL' >> /etc/sudoers
+# Create user with sudo access in one go
+RUN useradd -m -c "softwareQ" sq && \
+    echo 'sq ALL=(ALL) NOPASSWD:ALL' >> /etc/sudoers
 
-# Create a Python 3 virtual environment
 USER sq
 WORKDIR /home/sq
-RUN python3 -m venv venv
 
-# Install Jupyter and other dependencies, followed by pyqpp
-COPY requirements.txt ./
-RUN . venv/bin/activate && pip install --no-cache-dir --upgrade pip && \
-    pip install --no-cache-dir -r requirements.txt && \
-    pip install --no-cache-dir git+https://github.com/softwareqinc/qpp
+COPY --chown=sq:sq requirements.txt ./
+RUN python3 -m venv venv && \
+    ./venv/bin/pip install --no-cache-dir --upgrade pip && \
+    ./venv/bin/pip install --no-cache-dir -r requirements.txt && \
+    ./venv/bin/pip install --no-cache-dir git+https://github.com/softwareqinc/qpp@v7.0.0
 
-# Clone and install Quantum++ and qpp_qasm
-RUN git clone --depth 1 --branch main https://github.com/softwareqinc/qpp
-WORKDIR /home/sq/qpp
-RUN cmake -B build && \
-    cmake --build build --target qpp_qasm && \
-    sudo cmake --build build --target install && \
-    sudo cp build/qpp_qasm /usr/local/bin
+# Clone Quantum++ and build qpp_qasm
+RUN git clone --depth 1 --branch main https://github.com/softwareqinc/qpp && \
+    cmake -S qpp -B qpp/build && \
+    cmake --build qpp/build --target qpp_qasm && \
+    sudo cmake --build qpp/build --target install && \
+    sudo cp qpp/build/qpp_qasm /usr/local/bin && \
+    rm -rf qpp/build  # Clean up build artifacts
 
 # Create a notebook directory for Jupyter
 RUN mkdir notebooks
+ENV PATH="/home/sq/venv/bin:$PATH"
+# CMD ["jupyter", "notebook", "--ip=0.0.0.0", "--notebook-dir=./notebooks"]

include/qpp/MATLAB/matlab.hpp

@@ -57,7 +57,7 @@ namespace qpp {
  * // loads a previously saved Eigen ket
  * // from the MATLAB file "input.mat"
  * ket psi = load_MATLAB<ket>("input.mat");
- * \endcode
+ * @endcode
  *
  * @tparam Derived Complex Eigen type
  * @param mat_file MATLAB .mat file
@@ -140,7 +140,7 @@ load_MATLAB(const std::string& mat_file, const std::string& var_name) {
  * // loads a previously saved Eigen dynamic double matrix
  * // from the MATLAB file "input.mat"
  * rmat mat = load_MATLAB<rmat>("input.mat");
- * \endcode
+ * @endcode
  *
  * @tparam Derived Non-complex Eigen type
  * @param mat_file MATLAB .mat file

include/qpp/classes/exception.hpp

@@ -71,7 +71,7 @@ namespace exception {
  *     };
  * } // namespace exception
  * } // namespace qpp
- * \endcode
+ * @endcode
  */
 class Exception : public std::exception {
   protected: