IBM · KahnR · May 12, 2026 · Apr 9, 2026 · Apr 11, 2026 · Apr 11, 2026
diff --git a/.github/ISSUE_TEMPLATE/question.yml b/.github/ISSUE_TEMPLATE/question.yml
@@ -90,5 +90,3 @@ body:
       options:
         - label: I agree to follow this project's Code of Conduct
           required: true
-
-# Made with Bob
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,91 @@ All notable changes to QBioCode will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+## [Unreleased]
+
+### Added
+- **Data Generation**: New blob dataset generator
+  - `generate_blobs_datasets()`: Create isotropic Gaussian blob datasets
+  - `generate_default_blobs_datasets()`: Quick generation with default parameters
+  - Follows QBioCode data generation patterns
+  - Useful for clustering and classification benchmarks
+
+- **Evaluation Metrics**: Added generalized `evaluation_metrics()` function to `qbiocode.evaluation.model_evaluation`
+  - Supports multiple metrics: accuracy, brier, f1, precision, recall, auc
+  - Configurable via `metrics` parameter (default: ['accuracy', 'brier'])
+  - Backward compatible: returns (accuracy, brier) tuple by default
+  - Supports both binary and multi-class classification
+  - Provides calibration quality assessment via Brier score
+  - Handles edge cases (e.g., single class in test set)
+  - Now available in main API (previously only in tutorial helpers)
+
+- **Quantum Ensemble Learning**: New unified quantum ensemble classifier
+  - `compute_qensemble()`: Quantum ensemble with configurable construction methods
+    - Implements quantum ensemble using controlled operations and superposition
+    - Two ensemble methods via `ensemble_method` parameter:
+      - `"swap"` (default): Fixed controlled-SWAP operations (faster, deterministic)
+      - `"random_unitary"`: Haar-random unitaries (more general, potentially better generalization)
+    - Three ensemble modes: balanced, unbalanced, and pair_sample
+    - Support for configurable ensemble depth (d) and operations per qubit (n_swap)
+    - Quantum cosine similarity classifier using SWAP test
+  - New utility functions in `qbiocode.utils`:
+    - `normalize_data()`: Normalize data for quantum state encoding
+    - `label_to_array()`: Convert binary labels to one-hot encoding
+    - `prepare_training_set()`: Prepare balanced training subsets
+    - `retrieve_probabilities()`: Extract probabilities from measurement counts (generic quantum utility)
+    - `execute_circuit()`: General-purpose Aer simulator execution (reusable across quantum algorithms)
+  - Based on Macaluso et al., "A variational algorithm for quantum ensemble learning" (2023)
+  - Integrated from tutorial/QEnsemble with full API compatibility
+  - Code organization: Extracted reusable functions to utils for broader applicability
+
+- **Testing Infrastructure**: Comprehensive test suite for core functionality
+  - `tests/test_data_generation.py`: Tests for data generation utilities
+  - `tests/test_file_utilities.py`: Tests for file operations and utilities
+  - `tests/test_generator_dispatch.py`: Tests for generator dispatch logic
+  - `tests/conftest.py`: Pytest configuration and fixtures
+  - Test coverage for utility modules and data generation helpers
+
+- **Code Quality Tools**: Enhanced development tooling
+  - `isort` integration for consistent import ordering
+  - Configuration in `pyproject.toml` for isort settings
+  - Added to `dev` and `all` dependency groups
+
+- **Documentation**: Testing instructions in README
+  - Added "Running Tests" section with pytest usage
+  - Instructions for installing development dependencies
+
+### Changed
+- **Code Formatting**: Applied consistent code style across entire codebase
+  - Ran `black` formatter on all Python files
+  - Ran `isort` for standardized import ordering
+  - Fixed invalid escape sequences in visualization module
+  - Improved code readability and maintainability
+
+- **CI/CD Improvements**: Stabilized continuous integration pipeline
+  - Updated GitHub Actions workflows to Node.js 24
+  - Fixed CI code quality checks for import ordering
+  - Fixed CI type-check issues
+  - Fixed documentation build process
+  - Fixed Pandoc compatibility issues
+  - Enhanced workflow reliability across all platforms
+
+- **Testing**: Improved test reliability
+  - Fixed path-order assumptions in duplicate-file tests
+  - Tests now work consistently across different file systems
+
+### Fixed
+- Invalid escape sequence in `qbiocode/visualization/visualize_correlation.py`
+- Import ordering issues throughout codebase
+- Type-check errors in CI pipeline
+- Documentation build failures
+- Path handling in cross-platform tests
+
+### Planned Features
+- Additional quantum ML algorithms
+- Enhanced meta-learning capabilities
+- More dataset complexity metrics
+- Performance optimizations
+- Extended Galaxy tool integration
 
 ## [0.1.0] - 2026-04-06
 
@@ -101,57 +186,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - XGBoost for gradient boosting
 - hydra-core for configuration management
 
-## [Unreleased]
-
-### Added
-- **Testing Infrastructure**: Comprehensive test suite for core functionality
-  - `tests/test_data_generation.py`: Tests for data generation utilities
-  - `tests/test_file_utilities.py`: Tests for file operations and utilities
-  - `tests/test_generator_dispatch.py`: Tests for generator dispatch logic
-  - `tests/conftest.py`: Pytest configuration and fixtures
-  - Test coverage for utility modules and data generation helpers
-
-- **Code Quality Tools**: Enhanced development tooling
-  - `isort` integration for consistent import ordering
-  - Configuration in `pyproject.toml` for isort settings
-  - Added to `dev` and `all` dependency groups
-
-- **Documentation**: Testing instructions in README
-  - Added "Running Tests" section with pytest usage
-  - Instructions for installing development dependencies
-
-### Changed
-- **Code Formatting**: Applied consistent code style across entire codebase
-  - Ran `black` formatter on all Python files
-  - Ran `isort` for standardized import ordering
-  - Fixed invalid escape sequences in visualization module
-  - Improved code readability and maintainability
-
-- **CI/CD Improvements**: Stabilized continuous integration pipeline
-  - Updated GitHub Actions workflows to Node.js 24
-  - Fixed CI code quality checks for import ordering
-  - Fixed CI type-check issues
-  - Fixed documentation build process
-  - Fixed Pandoc compatibility issues
-  - Enhanced workflow reliability across all platforms
-
-- **Testing**: Improved test reliability
-  - Fixed path-order assumptions in duplicate-file tests
-  - Tests now work consistently across different file systems
-
-### Fixed
-- Invalid escape sequence in `qbiocode/visualization/visualize_correlation.py`
-- Import ordering issues throughout codebase
-- Type-check errors in CI pipeline
-- Documentation build failures
-- Path handling in cross-platform tests
-
-### Planned Features
-- Additional quantum ML algorithms
-- Enhanced meta-learning capabilities
-- More dataset complexity metrics
-- Performance optimizations
-- Extended Galaxy tool integration
 
 ---
 

diff --git a/README.md b/README.md
@@ -13,7 +13,7 @@ QBioCode provides tools for benchmarking quantum and classical machine learning
 - **QProfiler**: Automated ML benchmarking with data complexity analysis
 - **QSage**: Meta-learning tool for intelligent model selection
 - **Data Generation**: Create artificial datasets with controlled complexity
-- **Quantum ML Support**: QSVC, PQK, VQC, QNN implementations
+- **Quantum ML Support**: QSVC, PQK, VQC, QNN, Quantum Ensemble implementations
 - **Classical ML Baselines**: RF, SVM, LR, DT, NB, MLP, XGBoost
 - **Comprehensive Documentation**: Detailed tutorials and API reference
 
@@ -34,10 +34,10 @@ QBioCode requires Python **3.10 or higher** and has been tested with Python vers
 pip install qbiocode
 
 # Install with apps support (QProfiler, QSage)
-pip install qbiocode[apps]
+pip install 'qbiocode[apps]'
 
 # Install with all optional dependencies
-pip install qbiocode[all]
+pip install 'qbiocode[all]'
 ```
 
 #### Install with Conda
@@ -79,7 +79,7 @@ source .env/bin/activate  # On Windows: .env\Scripts\activate
 pip install -e .
 
 # Install with apps support (QProfiler, QSage)
-pip install -e ".[apps]"
+pip install -e '.[apps]'
 ```
 
 **macOS Users:** XGBoost requires OpenMP. Install it using Homebrew:
@@ -94,7 +94,7 @@ For detailed installation instructions, see the [Installation Guide](https://ibm
 
 ```bash
 # Install the package with development dependencies
-pip install -e ".[dev]"
+pip install -e '.[dev]'
 
 # Run the test suite
 python -m pytest
@@ -117,7 +117,7 @@ qbc.generate_data(
 )
 
 # Run QProfiler
-from apps.qprofiler import qprofiler
+from qbiocode.apps.qprofiler import qprofiler
 import yaml
 
 config = yaml.safe_load(open('configs/config.yaml'))
@@ -142,7 +142,7 @@ QProfiler provides a comprehensive benchmarking pipeline that:
 qprofiler --config configs/config.yaml
 
 # Python API
-from apps.qprofiler import qprofiler
+from qbiocode.apps.qprofiler import qprofiler
 qprofiler.main(config)
 ```
 
@@ -164,7 +164,7 @@ QSage uses surrogate models trained on extensive benchmarking data to:
 qsage --data your_data.csv --output predictions.csv
 
 # Python API
-from apps.sage.sage import QuantumSage
+from qbiocode.apps.sage.sage import QuantumSage
 sage = QuantumSage(data=benchmark_df, features=features, metrics=metrics)
 predictions = sage.predict(new_dataset_features)
 ```
@@ -197,7 +197,14 @@ Learn to use meta-learning for model selection:
 - Analyzing prediction accuracy
 - Understanding feature importance
 
-### 4. [Quantum Projection Learning](tutorial/Quantum_Projection_Learning/QPL_example.ipynb)
+### 4. [Quantum Ensemble Learning](tutorial/QEnsemble/QEnsemble_example_blobs.ipynb)
+Learn quantum ensemble methods for improved classification:
+- Fixed swap-based ensemble approach
+- Random unitary-based ensemble approach
+- Quantum superposition for evaluating multiple training configurations
+- Comparison with classical ensemble methods
+
+### 5. [Quantum Projection Learning](tutorial/Quantum_Projection_Learning/QPL_example.ipynb)
 Advanced quantum ML techniques with classical baselines.
 
 ## 🔧 Core Modules
@@ -228,6 +235,34 @@ qbc.generate_data(type_of_data='classes', ...)
 - Projected Quantum Kernel (PQK)
 - Variational Quantum Classifier (VQC)
 - Quantum Neural Network (QNN)
+- Quantum Ensemble (QEnsemble) - swap and random unitary methods
+
+**Quantum Ensemble Usage:**
+```python
+from qbiocode.learning import compute_qensemble
+from sklearn.datasets import make_blobs
+from sklearn.model_selection import train_test_split
+
+# Generate data
+X, y = make_blobs(n_samples=100, n_features=2, centers=2, random_state=42)
+X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.3)
+
+# Run quantum ensemble with swap method
+results_swap = compute_qensemble(
+    X_train, X_test, y_train, y_test,
+    ensemble_method='swap',
+    n_ensemble=4,
+    seed=42
+)
+
+# Run quantum ensemble with random unitary method
+results_random = compute_qensemble(
+    X_train, X_test, y_train, y_test,
+    ensemble_method='random_unitary',
+    n_ensemble=4,
+    seed=42
+)
+```
 
 ### Embeddings
 - PCA, LLE, Isomap, Spectral Embedding

diff --git a/docs/source/api/qbiocode.data_generation.rst b/docs/source/api/qbiocode.data_generation.rst
@@ -12,6 +12,14 @@ qbiocode.data\_generation.generator module
    :show-inheritance:
    :undoc-members:
 
+qbiocode.data\_generation.make\_blobs module
+--------------------------------------------
+
+.. automodule:: qbiocode.data_generation.make_blobs
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
 qbiocode.data\_generation.make\_circles module
 ----------------------------------------------
 

diff --git a/docs/source/api/qbiocode.learning.rst b/docs/source/api/qbiocode.learning.rst
@@ -44,6 +44,14 @@ qbiocode.learning.compute\_pqk module
    :show-inheritance:
    :undoc-members:
 
+qbiocode.learning.compute\_qensemble module
+-------------------------------------------
+
+.. automodule:: qbiocode.learning.compute_qensemble
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
 qbiocode.learning.compute\_qnn module
 -------------------------------------
 

diff --git a/docs/source/api/qbiocode.utils.rst b/docs/source/api/qbiocode.utils.rst
@@ -20,6 +20,14 @@ qbiocode.utils.dataset\_checkpoint module
    :show-inheritance:
    :undoc-members:
 
+qbiocode.utils.data\_encoding module
+------------------------------------
+
+.. automodule:: qbiocode.utils.data_encoding
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
 qbiocode.utils.find\_duplicates module
 --------------------------------------
 

diff --git a/docs/source/installation.md b/docs/source/installation.md
@@ -20,13 +20,17 @@ pip install qbiocode
 Install with apps support (QProfiler, QSage):
 
 ```bash
-pip install qbiocode[apps]
+pip install 'qbiocode[apps]'
 ```
 
 Install with all optional dependencies:
 
 ```bash
-pip install qbiocode[all]
+pip install 'qbiocode[all]'
+```
+
+```{note}
+**For zsh users:** The quotes around `'qbiocode[apps]'` are required because zsh interprets square brackets as glob patterns. Bash users can omit quotes, but using them works in both shells.
 ```
 
 ## Install with Conda
@@ -60,7 +64,7 @@ conda activate qbiocode
 pip install qbiocode
 
 # Or with apps support
-pip install qbiocode[apps]
+pip install 'qbiocode[apps]'
 ```
 
 **Note**: See [docs/CONDA_SUBMISSION.md](../CONDA_SUBMISSION.md) for information about the conda submission process.

diff --git a/docs/source/tutorials.md b/docs/source/tutorials.md
@@ -50,7 +50,40 @@ Explore QSage, an intelligent meta-learning system that predicts which machine l
 
 ---
 
-### 4. Quantum Projection Learning (QPL)
+### 4. Quantum Ensemble Learning
+
+Learn how to use quantum ensemble methods to improve classification performance by leveraging quantum superposition to evaluate multiple training set configurations simultaneously. This tutorial demonstrates two quantum ensemble approaches.
+
+<a href="tutorials/QEnsemble/QEnsemble_example_blobs.html">📓 <strong>View Tutorial Notebook</strong></a>
+
+**What You'll Learn:**
+- Generate blob datasets for binary classification
+- Implement fixed swap-based quantum ensemble method
+- Implement random unitary-based quantum ensemble method
+- Use quantum SWAP test for cosine similarity measurement
+- Compare quantum ensemble with classical baselines (Random Forest, XGBoost)
+- Evaluate performance using accuracy and Brier score metrics
+- Understand quantum superposition for ensemble learning
+
+**Key Concepts:**
+- Quantum ensemble learning via superposition
+- SWAP test for quantum state comparison
+- Controlled-SWAP operations for deterministic data rearrangement
+- Haar-random unitaries for general mixing
+- One-hot encoding for quantum state preparation
+- Quantum advantage in ensemble methods
+
+**Methods:**
+1. **Swap Method**: Uses fixed controlled-SWAP operations to create deterministic permutations of training data
+2. **Random Unitary Method**: Applies Haar-random unitary transformations for more general data mixing
+
+**References:**
+- Macaluso et al. (2023) - "A variational algorithm for quantum neural networks"
+- Rhrissorrakrai et al. (2025) - "Quantum Ensemble Learning" (arXiv:2506.02213)
+
+---
+
+### 5. Quantum Projection Learning (QPL)
 
 Learn about Quantum Projection Learning (QPL), a technique that combines quantum feature maps with multiple classical machine learning algorithms. This comprehensive tutorial demonstrates how to systematically evaluate quantum-enhanced features across different learners.
 
@@ -82,7 +115,7 @@ Learn about Quantum Projection Learning (QPL), a technique that combines quantum
 
 ---
 
-### 5. Projected Quantum Kernel (PQK) - Ovarian Cancer Survival Prediction
+### 6. Projected Quantum Kernel (PQK) - Ovarian Cancer Survival Prediction
 
 Learn how to apply Projected Quantum Kernels (PQK) to real-world cancer genomics data for survival prediction. This advanced tutorial demonstrates quantum-enhanced machine learning on multi-omics ovarian cancer data from the Multi-Omics Cancer Benchmark (TCGA preprocessed data).