CHANGELOG.md¶

[0.2.14] - 11-06-2026¶

Added¶

Added docs/result integrity tests for generated result links and image assets.
Added notebook extraction coverage that verifies result extraction does not modify notebook files.
Added workflow-order tests for the Tests to Publish to Pages release chain.
Added committed-notebook output checks for notebook JSON validity, saved outputs, and validation outputs that report passed when validation output blocks are present.

Changed¶

Added --stable-metadata and QML_RESULTS_STABLE_METADATA=1 support to generated result pages so release docs can avoid timestamp, commit, and runtime churn.
Documented notebook group execution commands for tutorials, real examples, and benchmarks.
Bumped package metadata to 0.2.14.

Validation¶

Verified focused docs-integrity, packaging metadata, and classical-baseline tests pass.
Verified Ruff checks pass for touched source and test files.

[0.2.13] - 11-06-2026¶

Added¶

Added a generated-result package-version consistency test so release result pages must match pyproject.toml.
Added docs/qml/release_checklist.md and linked it from the documentation index and generated Pages navigation.

Changed¶

Removed the separate Refresh results GitHub Actions verifier workflow.
Ordered release workflows so Pages deploys after successful Tests on main, and v* tag publishes wait for successful Tests and Pages runs on the same commit before uploading to PyPI.
Changed notebook-result generation to read only outputs already committed in notebooks; notebook execution now happens locally before committing notebook output changes.
Switched the SVM classical baseline probability output from deprecated SVC(probability=True) to sigmoid calibration with CalibratedClassifierCV.
Refreshed generated API, tutorial, real-example, and benchmark result pages from committed notebook outputs.
Regenerated the runtime-scaling benchmark plot asset used by the benchmark result page.
Bumped package metadata to 0.2.13.

Validation¶

Verified the focused packaging metadata and classical-baseline smoke tests.
Verified Ruff checks pass for the touched source, test, and Pages build files.

[0.2.12] - 11-06-2026¶

Added¶

Added estimator consistency coverage for fitted attributes, fitted-state errors, nested kernel/reservoir parameters, deterministic seeded behavior, and feature-count validation.
Added algorithm-truth contract tests for quantum kernel matrix use, trainable-kernel alignment traces, variational finite-shot metadata, QCNN active-wire reduction, and autoencoder postselected reconstruction.
Added QuantumKernel.get_params(...) and QuantumKernel.set_params(...) for estimator composition.
Added QuantumOneClassClassifier.score_samples(...).

Changed¶

Standardized fitted metadata across estimator-style APIs with n_features_in_, classes_ where applicable, training matrices or feature matrices, learned parameter traces, and circuit_metadata_ for circuit-backed estimators.
Added nested kernel__... and reservoir__... parameter support for composed estimator wrappers.
Updated qml.model_selection.clone_estimator(...) to clone from shallow constructor parameters so configured composed objects are preserved without passing nested keys into constructors.
Changed the Refresh results workflow from a direct-to-main artifact committer into a pull-request and push verifier for committed generated result artifacts.
Updated estimator consistency, API reference, model-selection, implementation contract, and roadmap documentation for the v0.2.12 generalization release.
Bumped package metadata to 0.2.12.

Validation¶

Verified focused estimator, algorithm-contract, model-selection, kernel, trainable-kernel, QCNN, autoencoder, and validation tests pass.
Verified Ruff formatting and lint checks pass for touched source and test files.

[0.2.11] - 11-06-2026¶

Added¶

Added qml.benchmarks.benchmark_runtime_scaling(...) for sample-size and shot-count runtime scaling diagnostics across classification and regression benchmark helpers.
Added the qml-pennylane benchmark runtime-scaling CLI preset for runtime scaling sweeps.
Added notebooks/benchmarks/08-runtime-scaling-benchmark.ipynb and refreshed generated benchmark result artifacts for the new runtime-scaling workflow.
Added model-selection scorers for balanced_accuracy, binary f1, r2, RMSE, and negative RMSE variants.
Added qml.model_selection.selection_summary_rows(...) plus qml.reporting.model_selection_table(...) and qml.reporting.print_model_selection(...) for scorer-aware model-selection reporting.
Added docs/qml/notebook_authoring.md with notebook structure, validation, plotting, and generated-result refresh conventions.

Changed¶

Updated API, benchmark, model-selection, algorithm-coverage, and notebook index documentation for runtime scaling, expanded scoring, and notebook authoring guidance.
Refreshed generated API, tutorial, real-example, and benchmark result pages and notebook image assets.

Validation¶

Verified the full pytest suite passes.
Verified Ruff checks pass for src/qml and tests.
Verified the static Pages build succeeds locally.
Executed the runtime-scaling benchmark notebook through the result generator.

[0.2.10] - 01-06-2026¶

Added¶

Added a dedicated Refresh results GitHub Actions workflow for generated documentation artifacts. It executes notebooks only when notebook, QML source, result-generation, dependency, or workflow changes require refreshed outputs.
Added --execute-notebook support to docs/pages/generate_results.py so notebook-only refreshes can execute just the notebooks changed in a commit before regenerating the notebook result pages.
Added notebooks/benchmarks/07-noise-model-benchmark.ipynb comparing noiseless, depolarizing, amplitude-damping, readout-error, and combined-noise execution for representative classification and regression QML workflows.
Added an algorithm documentation coverage page mapping public QML implementations to theory notes, tutorials, benchmarks, and generated web pages.
Added deterministic mini-batch training support for VQC/VQR workflows and variational estimator wrappers via batch_size.

Changed¶

Reduced the GitHub Pages workflow to a static-site build and deploy path using committed Markdown and generated assets, avoiding notebook execution and API result recomputation during normal Pages deployments.
Narrowed Pages workflow path filters so source and notebook changes flow through the result-refresh workflow first, while docs/site-only changes deploy directly.
Narrowed result-refresh triggers to notebook files, top-level QML source modules, result-generation tooling, dependency files, and the refresh workflow itself.
Updated Pages tooling documentation to describe the split between fast static deployment and explicit generated-result refreshes.
Expanded kernel documentation for quantum kernel regression and trainable quantum kernel classification theory coverage.
Clarified variable and parameter definitions across QML theory and support documentation pages.

Validation¶

Verified the updated workflow YAML parses successfully.
Verified docs/pages/generate_results.py and docs/pages/build_site.py compile successfully.
Verified the static Pages build succeeds locally.
Added focused tests for mini-batch index generation, VQC/VQR mini-batch workflows, and estimator parameter plumbing.

[0.2.9] - 01-06-2026¶

Added¶

Added qml.model_selection helpers for estimator-style workflows:
cross_validate_estimator(...)
train_test_evaluate(...)
select_best_model(...)
Added notebooks/tutorials/13-model-selection-and-cross-validation.ipynb demonstrating deterministic model comparison with package estimators.
Added qml.circuit_metadata helpers for trainable-parameter counts and estimated package-template circuit depth.
Added circuit_metadata fields to circuit-backed workflow results where applicable.

Changed¶

Moved generated result reports from root-level RESULTS*.md files into docs/results/ and updated Pages generation/build tooling accordingly.
Updated benchmark aggregation to carry trainable_parameters and estimated_depth into run records and per-model summaries.
Updated benchmark notebooks and generated benchmark result pages to include circuit metadata columns and depth-aware runtime scatter markers.
Updated roadmap, API docs, benchmark docs, implementation contracts, and notebook indexes for the new model-selection and circuit-metadata surfaces.
Bumped package metadata to 0.2.9.

Validation¶

Added focused tests for model-selection helpers, circuit metadata helpers, benchmark metadata aggregation, and imports.
Executed the new model-selection tutorial and refreshed generated tutorial result assets.
Executed the updated classification and regression benchmark notebooks and refreshed generated benchmark result assets.

[0.2.8] - 25-05-2026¶

Added¶

Added qml.noise helpers for validated depolarizing, amplitude-damping, and readout-error channel specifications.
Added opt-in noise_model support for variational estimators, quantum kernels, trainable quantum kernels, QCNN workflows, reservoir feature maps, and the VQC/VQR/kernel workflow functions.
Added CLI noise-model flags for circuit-backed workflows and benchmark commands:
--depolarizing
--amplitude-damping
--readout-error

Changed¶

Switched noisy circuit execution to PennyLane default.mixed only when a nonzero noise model is supplied, preserving existing noiseless defaults.
Included canonical noise_model metadata in noisy workflow and benchmark outputs.
Bumped package metadata to 0.2.8.

Validation¶

Added focused tests for noise-model validation, noisy quantum kernels, noisy variational estimators, and noisy reservoir features.
Verified focused noise, validation, estimator API, and Ruff checks pass.

[0.2.7] - 25-05-2026¶

Added¶

Added a benchmark interpretation guide covering confidence intervals, paired classical deltas, generalization gaps, runtime tradeoffs, finite-shot results, tuning fairness, and release-note wording.
Added a model-selection guide for choosing QML APIs, estimator classes, embeddings, finite-shot settings, and classical baselines by task type.

Changed¶

Added the new release-hardening guides to the generated Pages documentation navigation and README documentation index.
Expanded README algorithm-note links to include advanced kernels, reservoirs, embeddings, classical baselines, and benchmark documentation.

[0.2.6] - 25-05-2026¶

Added¶

Added benchmark coverage for newer quantum models:
quantum_reservoir
quantum_kernel_regressor
trainable_quantum_kernel_regressor
quantum_gaussian_process_regressor
quantum_reservoir_regressor
Added a benchmark finite-shots CLI preset for analytic versus finite-shot comparisons across classification and regression workflows.
Added benchmark notebook result-page generation through RESULTS_BENCHMARKS.md and the generated Pages site.
Added ROADMAP.md

Changed¶

Expanded the finite-shot benchmark notebook to compare analytic, 64-shot, 128-shot, and 512-shot execution with metric deltas versus analytic baselines.
Added local pre-commit quality hooks for Ruff, formatting, YAML, TOML, and whitespace checks.
Refactored shared classical-baseline fitting, result assembly, naming, and dataset helpers into a private utility module while preserving public workflow APIs.
Refactored benchmark summary-statistics, timing, and metadata helpers into a private utility module while preserving public benchmark APIs.
Updated packaging metadata tests to validate the next release version without pinning stale package metadata.

Validation¶

Added focused tests for package release metadata, shared classical baseline helper behavior, and benchmark aggregation helpers.
Verified pre-commit run --all-files, ruff check ., and the full pytest suite pass after formatting and whitespace cleanup.

[0.2.5] - 25-05-2026¶

Changed¶

Added local pre-commit quality hooks for Ruff, formatting, YAML, TOML, and whitespace checks.
Refactored shared classical-baseline fitting, result assembly, naming, and dataset helpers into a private utility module while preserving public workflow APIs.
Refactored benchmark summary-statistics, timing, and metadata helpers into a private utility module while preserving public benchmark APIs.
Updated packaging metadata tests to validate the next release version without pinning stale package metadata.

Validation¶

Added focused tests for package release metadata, shared classical baseline helper behavior, and benchmark aggregation helpers.
Verified pre-commit run --all-files, ruff check ., and the full pytest suite pass after formatting and whitespace cleanup.

[0.2.4] - 25-05-2026¶

Added¶

Added general-purpose advanced quantum-kernel estimators:
qml.kernels.QuantumKernelPCA
qml.kernels.QuantumOneClassClassifier
qml.kernels.QuantumGaussianProcessRegressor
Added trainable quantum-kernel regression:
qml.trainable_kernels.TrainableQuantumKernelRegressor
qml.trainable_kernels.run_trainable_quantum_kernel_regressor(...)
Added fixed quantum-reservoir feature models:
qml.reservoir.QuantumReservoirFeatures
qml.reservoir.QuantumReservoirClassifier
qml.reservoir.QuantumReservoirRegressor
Added additional reusable feature maps and ansatz helpers:
amplitude embedding
ZZ feature map
IQP feature map
strongly entangling ansatz helper
Added tutorial notebook notebooks/tutorials/12-advanced-quantum-kernel-and-reservoir-models.ipynb.
Added real-example notebooks that keep physics/math simulation code local to notebooks/real_examples/ while using package-level QML estimators:
07-tfim-hamiltonian-parameter-inference.ipynb
08-quantum-kernel-phase-discovery.ipynb
09-potential-energy-curve-interpolation.ipynb
10-lorenz-quantum-reservoir-regime-classifier.ipynb
11-noisy-oscillator-quantum-reservoir-inference.ipynb
Added documentation pages for advanced kernel models, quantum reservoirs, and reusable embeddings/ansatz helpers.

Changed¶

Expanded the public API reference and implementation contracts for the new estimators, feature maps, and reservoir models.
Updated generated tutorial and real-example result pages to include the new tutorial and notebooks.
Added trainable quantum-kernel regression to deterministic API reference results.
Updated the generated Pages site navigation and algorithm cards for advanced kernel and quantum-reservoir documentation.
Bumped package metadata to 0.2.4.

Validation¶

Executed the new tutorial notebook and the new real-example notebooks.
Verified all new notebook validation blocks report passed: True.
Verified the generated documentation site builds successfully.
Verified Ruff passes on the updated package and docs scripts.
Verified the full test suite passes with 68 tests.

[0.2.3] - 22-05-2026¶

Changed¶

Added rendered diagnostic plot outputs across the tutorial notebooks so the generated tutorial result page now includes dataset, loss, prediction, kernel-matrix, embedding, and forecasting figures where relevant.
Expanded the quantum metric-learning tutorial with loss-history and dataset-comparison plots.
Removed the archived QAOA notebook and dropped the notebooks/archive/ workflow from generated result pages and GitHub Pages navigation.
Bumped package metadata to 0.2.3.

Removed¶

Removed notebooks/archive/01-qaoa-max-cut.ipynb.
Removed RESULTS_ARCHIVE.md and the extracted archive plot assets.

Validation¶

Executed all tutorial notebooks from notebooks/tutorials/.
Regenerated RESULTS_TUTORIALS.md and extracted tutorial plot assets.
Verified generated Pages site builds from the project virtualenv.

[0.2.2] - 22-05-2026¶

Added¶

Added docs/qml/api_reference.md as a compact public API reference for top-level imports, workflow functions, estimator APIs, benchmark helpers, classical baselines, reporting helpers, and version access.
Added benchmark runtime tracking to classification and regression benchmark run records and aggregate summaries.
Added benchmark train/test generalization-gap tracking:
classification gap is train_accuracy - test_accuracy
regression gap is test_mse - train_mse
Added a best_model summary field to benchmark outputs:
classification selects the highest mean test_accuracy
regression selects the lowest mean test_mse

Changed¶

Updated benchmark documentation to match the current model registry, including trainable quantum kernels and quantum metric learning.
Expanded benchmark guidance to require classical baselines, explicit seed lists, runtime reporting, train/test gap reporting, and clear non-advantage framing for release-quality comparisons.
Wired the API reference into the generated GitHub Pages site and primary navigation.
Updated README.md and USAGE.md to describe the stronger benchmark output contract and interpretation limits.
Bumped package metadata to 0.2.2.

Validation¶

Added benchmark smoke-test assertions for runtime summaries, generalization-gap summaries, and best_model metadata.

[0.2.1] - 22-05-2026¶

Fixed¶

Fixed packaging metadata tests on Python 3.10 by falling back from the standard-library tomllib module to tomli.

Maintenance¶

Added the conditional development dependency tomli>=2; python_version < '3.11'.
Marked the finite-shot trainable-kernel dataset smoke test as slow so pytest -m "not slow" remains focused on the fast CI subset.

Validation¶

Verified pytest -m "not slow" passes with 58 tests selected and 4 slow tests deselected.

[0.2.0] - 21-05-2026¶

Added¶

Added implementation contracts documenting the model family, objective, metric semantics, and behavioral checks expected for each advertised algorithm.
Added dataset-agnostic estimator APIs:
qml.estimators.QuantumClassifier
qml.estimators.QuantumRegressor
qml.kernels.QuantumKernel
qml.kernels.QuantumKernelClassifier
qml.kernels.QuantumKernelRegressor
qml.preprocessing.make_sequence_windows
Added qml.reporting helpers for human-readable notebook and CLI tables:
format_table(...)
print_table(...)
print_section(...)
Added tutorial notebooks for the new estimator and preprocessing APIs:
notebooks/tutorials/06-quantum-kernel-estimators.ipynb
notebooks/tutorials/07-variational-quantum-estimators.ipynb
notebooks/tutorials/08-sequence-window-quantum-forecasting.ipynb
Added real-example notebooks for small reproducible physics and dynamical-system tasks:
notebooks/real_examples/01-rabi-oscillation-parameter-inference.ipynb
notebooks/real_examples/02-ising-correlation-temperature-classifier.ipynb
notebooks/real_examples/03-lorenz-regime-classifier.ipynb
notebooks/real_examples/04-condensed-matter-tfim-phase-classifier.ipynb
notebooks/real_examples/05-pendulum-trajectory-surrogate.ipynb
notebooks/real_examples/06-damped-oscillator-parameter-inference.ipynb
Added notebooks/README.md to document tutorial and real-example notebooks.
Added generated notebook result pages:
RESULTS_TUTORIALS.md
RESULTS_REAL_EXAMPLES.md

Changed¶

Moved importable package code from root-level qml/ to src/qml/.
Updated packaging and local test configuration for the src/ layout.
Reworked the QCNN workflow into a defensible four-qubit QCNN with trainable convolution blocks, trainable pooling blocks, and active-wire reduction from four to two to one wire.
Consolidated the quantum-kernel classifier workflow onto the reusable qml.kernels.QuantumKernel implementation.
Added sklearn-style get_params and set_params methods to variational and quantum-kernel estimators.
Updated classical baselines and benchmark helpers so selected datasets are propagated consistently across quantum and classical models.
Moved algorithm walkthrough notebooks into notebooks/tutorials/.
Renamed notebooks to numbered kebab-case names for stable file-browser ordering.
Converted repeated notebook print_section helper code to use qml.reporting.print_section.
Updated notebook bootstrap cells so tutorials and real examples run from the repository root, notebooks/, or their own subdirectories.
Updated Pages workflow triggers so documentation is rebuilt when src/** changes.
Updated Pages result generation to execute notebooks and publish tutorial and real-example result pages with extracted tables and plots.
Excluded notebooks from Ruff and Black because executable notebook bootstrap cells intentionally adjust import paths before importing project modules.

Fixed¶

Corrected qml.io_utils repository-root detection after the src/ layout migration.
Updated markdown references to the renamed tutorial notebook paths.
Corrected quantum-autoencoder reconstruction fidelity so it is evaluated after compression loss via trash-zero postselection and tied decoding, rather than by applying an encoder immediately followed by its inverse.

Validation¶

Executed all tutorial notebooks from notebooks/tutorials/.
Executed the affected real-example notebooks after adopting qml.reporting.
Verified package imports, reporting helpers, estimator APIs, and notebook parsing.
Added behavioral test coverage for autoencoder reconstruction, QCNN pooling structure, analytic kernel positive semidefiniteness, estimator parameter APIs, and benchmark dataset consistency.

[0.1.12] - 06-05-2026¶

Added¶

Implemented a first-class quantum autoencoder workflow in qml.autoencoder
Added autoencoder CLI support via python -m qml autoencoder
Added smoke, artifact, CLI, and import coverage for the quantum autoencoder
Added autoencoder documentation and example notebook support
Added a GitHub Pages workflow for publishing a custom static documentation site
Added a Pages site generator and stylesheet matched to the root portfolio site
Added generated RESULTS.md reference outputs and a Results web page
Added generated result images to RESULTS.md and the Results web page
Added a Pages workflow status badge to README.md
Added documentation for the Pages tooling in docs/pages/README.md
Added README and usage-documentation links to the published Pages site

Maintenance¶

Ignored local static-site build output directories (_site/ and site_docs/)
Configured pytest to include the repository root on the import path for local test runs
Regenerate reference results during the Pages workflow before building the site

Summary¶

New core QML capability:

variational quantum classification (VQC)
variational quantum regression (VQR)
quantum convolutional neural networks (QCNN)
quantum autoencoders
quantum kernel methods
trainable quantum kernels
quantum metric learning

[0.1.11] - 10-04-2026¶

Added¶

Implemented a first-class QCNN workflow in qml.qcnn
Added qcnn CLI support via python -m qml qcnn
Added QCNN benchmark support in classification benchmarks
Added QCNN smoke, CLI, benchmark, and import coverage
Added QCNN documentation across README, usage docs, theory notes, and a dedicated algorithm page
Added QCNN example notebook: notebooks/tutorials/10-quantum-convolutional-neural-network.ipynb

Summary¶

New core QML capability:

variational quantum classification (VQC)
variational quantum regression (VQR)
quantum convolutional neural networks (QCNN)
quantum kernel methods
trainable quantum kernels
quantum metric learning

[0.1.10] - 10-04-2026¶

Fixed¶

metric-learning now honors --save in the CLI and API
Added JSON/plot artifact saving for quantum metric learning
Normalised VQR artifact output paths to results/vqr/ and images/vqr/
Updated API docs to reflect that metric learning returns a dataclass result

Added¶

Regression tests for metric-learning artifact saving
Regression tests for VQR default artifact path selection

Maintenance¶

Ignored local .codex file and .codex/ directory
Removed stale local build artifacts before the next release cut

[0.1.9] - 06-04-2026¶

Added¶

Quantum metric learning¶

Implemented supervised quantum metric learning using contrastive loss
Trainable data re-uploading embedding circuits
Nearest-centroid classification in learned quantum feature space
CLI workflow:

python -m qml metric-learning --samples 200 --layers 2 --steps 50 --plot

Notebook:

notebooks/tutorials/09-quantum-metric-learning.ipynb

Documentation:

docs/qml/metric_learning.md

Visualisation support¶

Added plot_metric_learning_embeddings(...) to qml.visualize
Standardised plotting via shared visualisation utilities
Automatic embedding plots when plot=True

Benchmark integration¶

Added quantum_metric_learning to classification benchmark framework
Supports multi-seed comparison with VQC, quantum kernel, and classical baselines
Compatible with per-model hyperparameter overrides

CLI integration¶

Added metric-learning subcommand
Consistent interface with other QML workflows

Testing¶

Added smoke tests for:
API workflow
CLI execution
Ensures reproducibility with small-step configurations

Documentation updates¶

README feature list updated
USAGE.md includes API and CLI usage examples
THEORY.md extended with contrastive learning formulation
Added dedicated docs page:

docs/qml/metric_learning.md

Internal improvements¶

Unified plotting interface across models
Improved result dataclass structure for embedding-based workflows
Added label outputs (y_train, y_test) to metric learning results
Improved compatibility of benchmark framework with dataclass-based outputs

Summary¶

New core QML capability:

variational quantum classification (VQC)
variational quantum regression (VQR)
quantum kernel methods
trainable quantum kernels
quantum metric learning

Metric learning provides a flexible representation-learning approach compatible with classical classifiers and similarity-based workflows.

[0.1.7] - 06-04-2026¶

Added¶

unified training loop via qml.training.run_training_loop
shared utilities in qml.utils
centralised path handling via qml.io_utils.ensure_dir

Refactored¶

removed duplicated optimisation loops across VQC, VQR, and kernel workflows
improved package modularity and internal consistency
simplified experiment output handling

Removed¶

deprecated qml.datasets
redundant local helper functions

[0.1.5] - 06-04-2026¶

Added¶

Multiple dataset support via qml.data
classification datasets:
- moons
- circles
- blobs
- xor
- regression datasets:
- linear
- sine
- polynomial
- Dataset selection exposed across public APIs:
run_vqc(dataset=...)
run_vqr(dataset=...)
run_quantum_kernel_classifier(dataset=...)
run_trainable_quantum_kernel_classifier(dataset=...)
compare_classification_models(dataset=...)
compare_regression_models(dataset=...)
CLI support for dataset selection:

bash python -m qml vqc --dataset circles python -m qml regression --dataset sine python -m qml benchmark classification --dataset xor - Dataset smoke tests ensuring end-to-end compatibility - Deterministic dataset generation with seeded NumPy RNG

Changed¶

Benchmark framework updated to support model-specific kwargs alongside dataset selection
Classification and regression runners now return consistent "dataset" metadata
Improved separation between dataset specification and data tensors
Benchmark dispatch filters unsupported kwargs for classical baselines

Fixed¶

Finite-shot determinism preserved across datasets
Regression benchmark default dataset corrected to "linear"
Removed dataset shadowing bug where dataset dict replaced dataset name
CLI dataset argument now correctly propagates to runners

0.1.4 - 06-04-2026¶

Added¶

Noise-aware benchmark support via per-model model_kwargs
Finite-shot benchmark smoke tests
Deterministic finite-shot benchmark execution with fixed seeds
Extended dataset utilities for multiple classification and regression dataset types

Changed¶

Updated benchmark dispatch to support model-specific kwargs cleanly
Refined README, USAGE, and THEORY documentation to reflect current package capabilities
Generalised qml.data dataset generation with lightweight dispatch helpers