oqp.library.baeka
Generalized Baek adaptive-penalty kernel for conical intersections.
The published three-state objective removes the redundant outer-state gap and
penalizes only the two consecutive gaps. This module extends that construction
to ``N >= 2`` states by using the ``N - 1`` adjacent gaps, together with an SVD
projector for their independent gradient subspace. It contains no OpenQP
backend calls and is therefore directly unit-testable.
The multiplier updates are additive, as in Baek's equations 3.12--3.13::
sigma <- sigma + delta_beta (ordinary macro iteration)
sigma <- sigma + beta (locally stationary, gap still open)
``alpha`` and all gaps are energies (Hartree); ``sigma``, ``delta_beta`` and
``beta`` are dimensionless.
Attributes
Exceptions
Classes
Functions
|
|
|
|
|
|
|
Module Contents
- ArrayLike
- parse_jump_schedule(value) Tuple[float, Ellipsis]
Return a validated additive ``beta`` schedule. The sectioned input reader may deliver the schedule as a comma-separated string, while the concise parser and Python API can provide a sequence. A scalar is accepted as a one-jump schedule; exhaustion is deliberately an error rather than silently inventing a continuation rule.
- penalty_subspace(gap_gradients: ArrayLike, *, rtol: float = 1e-10, atol: float = 1e-12) Tuple[numpy.ndarray, numpy.ndarray]
Return an orthonormal basis and singular values for the gap subspace. ``gap_gradients`` has shape ``(N - 1, 3 * natom)``. Raw adjacent gap-gradient vectors are used instead of multiplying by the penalty slope: the column space is identical away from exact degeneracy, while the raw vectors remain well-defined as the gap and the penalty slope approach zero.
- penalty_projector(gap_gradients: ArrayLike, *, rtol: float = 1e-10, atol: float = 1e-12) Tuple[numpy.ndarray, int, numpy.ndarray]
Return ``P = U U.T``, its numerical rank, and singular values.
- class BaekAObjective
One generalized Baek objective/gradient evaluation.
- energies: numpy.ndarray
- gradients: numpy.ndarray
- gaps: numpy.ndarray
- gap_gradients: numpy.ndarray
- average_energy: float
- average_gradient: numpy.ndarray
- penalty: float
- penalty_gradient: numpy.ndarray
- objective: float
- gradient: numpy.ndarray
- span: float
- sigma: float
- effective_sigma: float
- alpha: float
- projector_basis: numpy.ndarray
- projector_singular_values: numpy.ndarray
- projector_rank: int
- parallel_gradient: numpy.ndarray
- perpendicular_gradient: numpy.ndarray
- parallel_norm: float
- parallel_scaled_norm: float
- perpendicular_norm: float
- baeka_objective(energies: ArrayLike, gradients: ArrayLike, *, sigma: float, alpha: float, gap_weight: float = 1.0, projector_rtol: float = 1e-10, projector_atol: float = 1e-12) BaekAObjective
Evaluate the generalized adjacent-gap Baek objective. .. math:: F_N = N^{-1}\sum_i E_i + w\sigma\sum_i \frac{(E_{i+1}-E_i)^2}{E_{i+1}-E_i+\alpha}. States must be supplied in ascending adiabatic/root order. Only adjacent gaps are included; adding all pairs would reintroduce the redundancy that the three-state Baek objective was designed to remove.
- class BaekAEvaluation
Objective data plus one transition of the additive-sigma state machine.
- tested_data: BaekAObjective
- data: BaekAObjective
- tested_sigma: float
- next_sigma: float
- delta_f: float
- local_stationary: bool
- gap_converged: bool
- converged: bool
- action: str
- jump: float | None
- jump_index: int
- exception BaekAJumpScheduleExhausted
Bases:
RuntimeErrorRaised when another large additive jump is required but unavailable.
- class BaekAState(*, sigma: float, alpha: float, delta_beta: float, beta_schedule, gap_tol: float, tol_f: float, tol_g: float, gap_weight: float = 1.0, projector_rtol: float = 1e-10, projector_atol: float = 1e-12)
State machine for the generalized Baek adaptive multiplier.
- sigma
- alpha
- delta_beta
- beta_schedule
- gap_tol
- tol_f
- tol_g
- gap_weight
- projector_rtol
- projector_atol
- jump_index = 0
- evaluate(energies: ArrayLike, gradients: ArrayLike) BaekAEvaluation
Evaluate the objective and advance the sigma state machine once.