default optimal stepsize per optimizer, v0.3.13

Author: SidRichardsQuantum

CHANGELOG.md

@@ -4,6 +4,27 @@ All notable changes to this project will be documented in this file.
 
 ---
 
+## [0.3.13] - April 13, 2026
+
+### Changed
+
+- **VQE CLI now matches calibrated optimizer-default behaviour**
+
+  `vqe --stepsize` is now optional. When omitted, the CLI preserves the same
+  calibrated per-optimizer default stepsize behaviour as the Python APIs
+  instead of forcing a legacy fixed `0.2` learning rate.
+
+### Fixed
+
+- Fixed stale VQE CLI argument forwarding that still cast `stepsize` eagerly in
+  standard VQE, compare-noise, and post-VQE excited-state workflows, preventing
+  the new optimizer-default resolution path from taking effect.
+- Fixed optimizer documentation to reflect the canonical
+  `NesterovMomentum` registry entry, the alias model, and the current
+  calibrated default-stepsize registry layout.
+- Fixed notebook and documentation path references so the renumbered
+  `getting_started/` notebook names are referenced consistently.
+
 ## [0.3.12] - April 13, 2026
 
 ### Added
@@ -156,7 +177,7 @@ All notable changes to this project will be documented in this file.
 
 - **New VarQRTE notebooks**
 
-  - `notebooks/getting_started/13_getting_started_qrte_h2.ipynb` — prepared-state VarQRTE usage demo
+  - `notebooks/getting_started/11_getting_started_qrte_h2.ipynb` — prepared-state VarQRTE usage demo
   - `notebooks/qite/H2/Real_Time.ipynb` — package-client VarQRTE workflow
   - `notebooks/benchmarks/qite/H2/Exact_QRTE_Benchmark.ipynb` — exact-vs-VarQRTE H2 quench benchmark
 

README.md

@@ -115,6 +115,9 @@ model_res = run_vqe(
 print("Model VQE:", model_res["energy"])
 ```
 
+`run_vqe()` uses the calibrated default stepsize for the selected optimizer when `stepsize` is omitted.
+The `vqe` CLI does the same when `--stepsize` is omitted.
+
 CLI:
 
 ```bash
@@ -274,9 +277,9 @@ Layout:
 
 Recommended starting points:
 
-- [`notebooks/getting_started/vqe_vs_qpe_from_scratch_h2.ipynb`](notebooks/getting_started/vqe_vs_qpe_from_scratch_h2.ipynb)
-- [`notebooks/getting_started/06_getting_started_qite_h2.ipynb`](notebooks/getting_started/06_getting_started_qite_h2.ipynb)
-- [`notebooks/getting_started/13_getting_started_qrte_h2.ipynb`](notebooks/getting_started/13_getting_started_qrte_h2.ipynb)
+- [`notebooks/getting_started/01_vqe_vs_qpe_from_scratch_h2.ipynb`](notebooks/getting_started/01_vqe_vs_qpe_from_scratch_h2.ipynb)
+- [`notebooks/getting_started/07_getting_started_qite_h2.ipynb`](notebooks/getting_started/07_getting_started_qite_h2.ipynb)
+- [`notebooks/getting_started/11_getting_started_qrte_h2.ipynb`](notebooks/getting_started/11_getting_started_qrte_h2.ipynb)
 - [`notebooks/benchmarks/qite/H2/Exact_QRTE_Benchmark.ipynb`](notebooks/benchmarks/qite/H2/Exact_QRTE_Benchmark.ipynb)
 
 ## Documentation

THEORY.md

@@ -273,7 +273,7 @@ Supported optimizers:
 - Gradient Descent
 - RMSProp
 - Adagrad
-- Momentum / Nesterov
+- Momentum / NesterovMomentum
 
 Differences:
 

USAGE.md

@@ -285,6 +285,9 @@ Guidance:
 | GradientDescent  | baseline                                |
 | NesterovMomentum | faster convergence on smooth landscapes |
 
+If `stepsize` / `--stepsize` is omitted for VQE workflows, the calibrated
+default for the selected optimizer is used.
+
 See:
 
 ```

more_docs/vqe/optimizers.md

@@ -7,14 +7,31 @@ The implemented optimizer names are:
 - `Adam`
 - `GradientDescent`
 - `Momentum`
-- `Nesterov`
+- `NesterovMomentum`
 - `RMSProp`
 - `Adagrad`
 
-These are exposed through the factory:
+These are exposed through the registry `OPTIMIZERS`, where each canonical name maps
+to:
+
+- the PennyLane optimizer factory
+- a calibrated default `stepsize`
+- accepted aliases
+
+The calibrated defaults currently used by `run_vqe()` when `stepsize` is omitted are:
+
+- `Adam`: `0.15`
+- `GradientDescent`: `0.10`
+- `Momentum`: `0.10`
+- `NesterovMomentum`: `0.20`
+- `RMSProp`: `0.01`
+- `Adagrad`: `0.10`
+
+The main helpers are:
 
 ```python
-get_optimizer(name: str = "Adam", stepsize: float = 0.2)
+get_optimizer(name: str = "Adam", stepsize: float | None = None)
+get_optimizer_stepsize(name: str = "Adam") -> float
 ```
 
 and are used inside the main VQE loop via a unified PennyLane interface.
@@ -64,7 +81,12 @@ where the update $\Delta \theta_t$ depends on the optimizer-specific rule.
 In `vqe.core.run_vqe`, the optimizer is constructed as
 
 ```python
-opt = engine_build_optimizer(str(optimizer_name), stepsize=float(stepsize))
+resolved_stepsize = (
+    get_optimizer_stepsize(str(optimizer_name))
+    if stepsize is None
+    else float(stepsize)
+)
+opt = engine_build_optimizer(str(optimizer_name), stepsize=resolved_stepsize)
 ```
 
 and then applied through either
@@ -243,7 +265,7 @@ Instead of evaluating the gradient exactly at the current point, Nesterov moment
 
 ### Typical use in this repo
 
-Nesterov is a useful intermediate option between simple momentum methods and more adaptive optimizers such as Adam.
+`NesterovMomentum` is a useful intermediate option between simple momentum methods and more adaptive optimizers such as Adam.
 
 ---
 
@@ -412,7 +434,7 @@ The optimizers in this repository can be grouped roughly as follows.
 
 - `GradientDescent`
 - `Momentum`
-- `Nesterov`
+- `NesterovMomentum`
 
 These methods use a global learning rate $\eta$ without adaptive per-parameter normalization. They are simple and interpretable, but usually more sensitive to hyperparameter tuning.
 
@@ -432,14 +454,14 @@ For most standard VQE experiments in this repository:
 
 1. start with `Adam`
 2. use `GradientDescent` as a baseline if you want a clean reference
-3. try `Momentum` or `Nesterov` if you want simple inertial alternatives
+3. try `Momentum` or `NesterovMomentum` if you want simple inertial alternatives
 4. try `RMSProp` or `Adagrad` when parameter scales appear uneven
 
 A practical rule of thumb is:
 
 - **Adam** for general-purpose default use
 - **GradientDescent** for interpretability and baseline studies
-- **Momentum / Nesterov** for simple acceleration over GD
+- **Momentum / NesterovMomentum** for simple acceleration over GD
 - **RMSProp / Adagrad** for stronger per-parameter adaptation
 
 ---
@@ -487,29 +509,43 @@ So:
 The current optimizer registry is:
 
 ```python
-_OPTIMIZERS = {
-    "Adam": qml.AdamOptimizer,
-    "adam": qml.AdamOptimizer,
-    "GradientDescent": qml.GradientDescentOptimizer,
-    "gd": qml.GradientDescentOptimizer,
-    "Momentum": qml.MomentumOptimizer,
-    "Nesterov": qml.NesterovMomentumOptimizer,
-    "RMSProp": qml.RMSPropOptimizer,
-    "Adagrad": qml.AdagradOptimizer,
+OPTIMIZERS = {
+    "Adam": {"factory": qml.AdamOptimizer, "stepsize": 0.15, "aliases": ("adam",)},
+    "GradientDescent": {
+        "factory": qml.GradientDescentOptimizer,
+        "stepsize": 0.10,
+        "aliases": ("gradientdescent", "gradient_descent", "gd"),
+    },
+    "Momentum": {
+        "factory": qml.MomentumOptimizer,
+        "stepsize": 0.10,
+        "aliases": ("momentum",),
+    },
+    "NesterovMomentum": {
+        "factory": qml.NesterovMomentumOptimizer,
+        "stepsize": 0.20,
+        "aliases": ("nesterov", "nesterovmomentum"),
+    },
+    "RMSProp": {"factory": qml.RMSPropOptimizer, "stepsize": 0.01, "aliases": ("rmsprop",)},
+    "Adagrad": {"factory": qml.AdagradOptimizer, "stepsize": 0.10, "aliases": ("adagrad",)},
 }
 ```
 
-So the accepted user-facing names are:
+So the canonical user-facing names are:
 
 - `Adam`
-- `adam`
 - `GradientDescent`
-- `gd`
 - `Momentum`
-- `Nesterov`
+- `NesterovMomentum`
 - `RMSProp`
 - `Adagrad`
 
+Accepted aliases also include:
+
+- `adam`
+- `gd`
+- `nesterov`
+
 ---
 
 ## Summary Table
@@ -518,7 +554,7 @@ So the accepted user-facing names are:
 | ----------------- | --------------------------------------------------- | -------------: | ------------------------------: | ----------------------------------------------------- |
 | `GradientDescent` | direct negative-gradient update                     |             No |                              No | simple but stepsize-sensitive                         |
 | `Momentum`        | gradient descent with velocity accumulation         |            Yes |                              No | faster than GD, can overshoot                         |
-| `Nesterov`        | momentum with look-ahead gradient                   |            Yes |                              No | often sharper updates, still tuning-sensitive         |
+| `NesterovMomentum` | momentum with look-ahead gradient                  |            Yes |                              No | often sharper updates, still tuning-sensitive         |
 | `Adagrad`         | cumulative squared-gradient scaling                 |             No |                             Yes | adapts well early, can become too conservative        |
 | `RMSProp`         | moving-average squared-gradient scaling             |             No |                             Yes | adaptive and stable, but less full-featured than Adam |
 | `Adam`            | momentum + adaptive second moment + bias correction |            Yes |                             Yes | robust default, but more complex                      |

notebooks/README_notebooks.md

@@ -55,8 +55,8 @@ notebooks/
 │   └── vqe/
 │
 ├── getting_started/
-│   ├── vqe_vs_qpe_from_scratch_h2.ipynb
-│   └── 13_getting_started_qrte_h2.ipynb
+│   ├── 01_vqe_vs_qpe_from_scratch_h2.ipynb
+│   └── 11_getting_started_qrte_h2.ipynb
 │
 ├── vqe/
 │   ├── H2/
@@ -72,15 +72,15 @@ notebooks/
 
 If you are new to the repository, begin with:
 
-`notebooks/getting_started/vqe_vs_qpe_from_scratch_h2.ipynb`
+`notebooks/getting_started/01_vqe_vs_qpe_from_scratch_h2.ipynb`
 
 This notebook provides compact, conceptual implementations of **VQE** and **QPE** before moving to the packaged workflows used elsewhere in the repository.
 
 Fast path:
 
-- start with `getting_started/01_getting_started_vqe_h2.ipynb` for the basic VQE API
-- use `getting_started/06_getting_started_qite_h2.ipynb` for VarQITE
-- use `getting_started/13_getting_started_qrte_h2.ipynb` for prepared-state VarQRTE usage
+- start with `getting_started/02_getting_started_vqe_h2.ipynb` for the basic VQE API
+- use `getting_started/07_getting_started_qite_h2.ipynb` for VarQITE
+- use `getting_started/11_getting_started_qrte_h2.ipynb` for prepared-state VarQRTE usage
 - use `benchmarks/qite/H2/Exact_QRTE_Benchmark.ipynb` when you want to validate VarQRTE against exact evolution
 
 ---
@@ -140,7 +140,7 @@ VarQITE and VarQRTE are demonstrated on H2 as package-client workflows.
 | Notebook                           | Purpose                    | Style          |
 | ---------------------------------- | -------------------------- | -------------- |
 | `Real_Time.ipynb`                  | Noiseless VarQRTE on H2    | Package client |
-| `getting_started/13_getting_started_qrte_h2.ipynb` | Prepared-state VarQRTE intro on H2 | Package client |
+| `getting_started/11_getting_started_qrte_h2.ipynb` | Prepared-state VarQRTE intro on H2 | Package client |
 
 Note:
 
@@ -223,11 +223,11 @@ Notes:
 
 1. **Conceptual starting point**
 
-   * `getting_started/vqe_vs_qpe_from_scratch_h2.ipynb`
+   * `getting_started/01_vqe_vs_qpe_from_scratch_h2.ipynb`
 
 2. **Core VQE workflow**
 
-   * `getting_started/01_getting_started_vqe_h2.ipynb`
+   * `getting_started/02_getting_started_vqe_h2.ipynb`
    * `getting_started/09_bond_scan_h2.ipynb`
 
 3. **Noise studies**
@@ -253,16 +253,16 @@ Notes:
 
 6. **Larger systems and geometry**
 
-   * `getting_started/11_adapt_vqe_h3plus.ipynb`
+   * `getting_started/10_adapt_vqe_h3plus.ipynb`
    * `benchmarks/comparisons/multi_molecule/Scaling_Benchmark.ipynb`
    * `benchmarks/vqe/H3plus/Ansatz_Comparison_Noiseless.ipynb`
    * `benchmarks/vqe/H3plus/Ansatz_Comparison_Noisy.ipynb`
    * `vqe/H2O/Bond_Angle.ipynb`
 
 7. **Projected dynamics**
 
-   * `getting_started/06_getting_started_qite_h2.ipynb`
-   * `getting_started/13_getting_started_qrte_h2.ipynb`
+   * `getting_started/07_getting_started_qite_h2.ipynb`
+   * `getting_started/11_getting_started_qrte_h2.ipynb`
    * `benchmarks/qite/H2/Exact_QRTE_Benchmark.ipynb`
    * `qite/H2/Real_Time.ipynb`