API - CertifScripts

CertificationCircle(center, radius; samples = 256)

Discretisation of a circle with centre center, radius radius, and samples equally spaced points used for certification runs.

_bf_ogita_cache_stats()

Return statistics about the BigFloat Ogita cache usage.

_clear_bf_ogita_cache!()

Clear the worker-local BigFloat SVD cache used for Ogita optimization.

_clear_ogita_cache!()

Clear the worker-local SVD cache used for Ogita optimization.

_clear_parametric_cache!()

Clear the worker-local parametric certifier cache.

_compute_schur_and_error_bigfloat(A; polynomial = nothing)

BigFloat version of computeschurand_error. Uses GenericSchur.jl's native BigFloat Schur decomposition for full-precision results.

_compute_schur_bigfloat_direct(A; polynomial = nothing)

Compute BigFloat Schur decomposition directly via GenericSchur.jl (no Float64 seed). Works for matrices whose eigenvalues span many orders of magnitude.

_compute_schur_bigfloat_refined(A; polynomial = nothing)

Compute BigFloat Schur decomposition by refining a Float64 seed. Seeds from Float64 Schur, then refines iteratively in BigFloat. May fail for matrices with eigenvalues below ~10⁻¹⁶.

_evaluate_sample_ogita_bigfloat(T_matrix::BallMatrix, z::Number, idx::Int;
                                 max_iterations::Int=4,
                                 target_precision::Int=256,
                                 distance_threshold::Real=1e-4,
                                 use_cache::Bool=true)

Evaluate the smallest singular value at z using Ogita refinement with caching.

This function uses a worker-local cache to store the last refined BigFloat SVD. For nearby points (distance < distance_threshold), it uses the cached SVD as a starting point for Ogita refinement, which requires fewer iterations than starting from Float64.

Cache Strategy

• If cache hit: use cached BigFloat SVD → 1-2 Ogita iterations
• If cache miss: use Float64 SVD → 3-4 Ogita iterations

Arguments

• T_matrix: The Schur matrix T (BallMatrix)
• z: Sample point on the circle
• idx: Sample index for logging
• max_iterations: Number of Ogita iterations for cache miss (3-4 for 256-bit)
• target_precision: Target precision in bits
• distance_threshold: Maximum distance for cache reuse
• use_cache: Whether to use caching (default: true)

_evaluate_sample_parametric(T, z, idx; use_warm_start=true, distance_threshold=1e-4)

Evaluate sample using the parametric Sylvester-based certifier.

Returns a result compatible with the standard certification format.

_evaluate_sample_with_ogita_cache(T, z, idx; ogita_distance_threshold, ogita_quality_threshold)

Evaluate sample with Ogita optimization: try to refine from cached SVD if available.

If the cached SVD is from a nearby point (distance < ogitadistancethreshold), attempt Ogita refinement. If the refined SVD has acceptable quality (residual < ogitaqualitythreshold), use it; otherwise fall back to full SVD.

_ogita_cache_stats()

Return statistics about the Ogita cache usage.

_parametric_cache_stats()

Return statistics about the parametric cache usage.

_set_center_svd_cache!(U, S, V, z)

Set the center SVD cache. This should be called once at the start of certification with the SVD computed at the circle center.

adaptive_arcs!(arcs, cache, pending, η; kwargs...)

Drive the adaptive refinement routine. When job channels are provided the refinement uses asynchronous workers; otherwise the evaluation is carried out serially using the supplied evaluator.

bound_res_original(l2pseudo, η, norm_Z, norm_Z_inv, errF, errT, N; Cbound=1.0)

Return an upper bound on the ℓ₁ resolvent norm of the original matrix given the bounds obtained from the Schur form.

Thin wrapper that calls bound_resolvent_schur and schur_to_original_resolvent.

bound_resolvent_schur(l2pseudo, η)

Adjust the raw Schur pseudospectral resolvent for the trapezoid rule discretization error η. Returns a rigorous upper bound on the Schur resolvent.

choose_snapshot_to_load(basepath)

Return the most recent valid snapshot stored at basepath.

compute_schur_and_error(A; polynomial = nothing)

Compute the Schur decomposition of A and certified bounds for the orthogonality defect, the reconstruction error, and the norms of Z and Z⁻¹. When polynomial is provided (as coefficients in ascending order), additional bounds are computed for p(A) and p(T).

Supports both Float64 and BigFloat precision based on the element type of A. For BigFloat, the Schur decomposition is computed in Float64 and then refined to higher precision using iterative refinement.

configure_certification!(; job_channel, result_channel, certification_log, snapshot, io)

Cache common resources used by the certification helpers. The stored values are used as defaults by adaptive_arcs! and save_snapshot!. Any keyword may be omitted to keep its previous value.

dowork(jobs, results)

Process tasks received on jobs, computing the SVD certification routine for T - zI. The Schur factor must have been registered in advance with set_schur_matrix!.

dowork_ogita(jobs, results; ogita_distance_threshold=1e-4, ogita_quality_threshold=1e-10)

Process tasks with Ogita optimization enabled. Similar to dowork but tries to use cached SVD from previous evaluations to speed up nearby points.

The worker maintains a cache of the last computed SVD. When a new point z arrives, if it's within ogita_distance_threshold of the cached point, Ogita refinement is attempted. If the refined SVD has acceptable quality (relative residual < ogita_quality_threshold), it's used; otherwise a full SVD is computed.

This is beneficial when the adaptive bisection sends consecutive jobs for nearby points, which happens naturally as arcs get smaller during refinement.

dowork_ogita_bigfloat(jobs, results; target_precision=256, max_ogita_iterations=3,
                      distance_threshold=1e-4)

Process tasks with BigFloat precision using Ogita SVD refinement with caching.

For each job (id, z), this worker:

1. Checks if a cached BigFloat SVD exists from a nearby point
2. If cache hit: refines from cached SVD (1-2 iterations)
3. If cache miss: computes Float64 SVD and refines to BigFloat (3-4 iterations)
4. Certifies with Miyajima bounds
5. Caches the result for future reuse

This is the distributed equivalent of run_certification_ogita for parallel execution. The Schur matrix must be a BigFloat BallMatrix registered with set_schur_matrix!.

Performance

• Cache miss: Ogita from Float64 requires ~4 iterations (10^-16 → 10^-64)
• Cache hit: Ogita from BigFloat requires ~1-2 iterations (already at high precision)
• For adaptive bisection with nearby points, expect 50-90% cache hit rate

dowork_parametric(jobs, results; distance_threshold=1e-4)

Process tasks using the parametric Sylvester-based certifier.

The Schur factor and parametric config must have been registered in advance with set_schur_matrix! and set_parametric_config!.

points_on(circle)

Return the discretisation of circle used for certification.

poly_from_roots(roots::AbstractVector)

Given a list of roots r₁, r₂, …, rₙ, returns the coefficients [a₀, a₁, …, aₙ] of the monic polynomial p(x) = (x - r₁)(x - r₂)…(x - rₙ) so that p(x) = a₀ + a₁x + a₂x² + … + aₙ*xⁿ.

run_certification(A, circle; schur_data = nothing, polynomial = nothing, kwargs...)

Run the adaptive certification routine on circle using a serial evaluator.

Arguments

• A: matrix to certify. Converted to BallMatrix when required.
• circle: CertificationCircle describing the contour used for the adaptive refinement.

Keyword Arguments

• schur_data = nothing: pre-computed Schur data as the 5-tuple (S, errF, errT, norm_Z, norm_Z_inv) returned by compute_schur_and_error. When provided, the expensive Schur computation is skipped entirely. This is useful for reusing the same Schur decomposition across multiple circles or when the default Float64-seeded refinement fails (e.g., matrices with eigenvalues below ~10⁻¹⁶).
• polynomial = nothing: optional coefficients (ascending order) describing a polynomial p. When provided the certification is carried out on p(T) and the returned error corresponds to the reconstruction error of p(A).
• η = 0.5: admissible threshold for the adaptive refinement. Must lie in the open unit interval.
• check_interval = 100: number of processed arcs between progress reports and consistency checks.
• log_io = stdout: destination IO for log messages.
• Cbound = 1.0: constant used by bound_res_original when lifting resolvent bounds back to the original matrix.

The return value is a named tuple containing the computed Schur form, the accumulated certification log, and the resolvent bounds for both the Schur factor and the original matrix.

run_certification_ogita(A, circle; target_precision=256, kwargs...)

Optimized BigFloat certification using Ogita SVD refinement.

This function is specifically designed for BigFloat precision certification where computing fresh BigFloat SVDs at each sample point is expensive. Instead, it:

1. Computes Schur decomposition with BigFloat refinement
2. At each sample point z, computes Float64 SVD of (T - zI)
3. Refines the Float64 SVD to BigFloat using Ogita's algorithm (3-4 iterations)

Due to quadratic convergence, 4 Ogita iterations from Float64 (~10^-16 error) achieve ~10^-64 error, saturating 256-bit precision.

Performance

Typically 10-100x faster than computing fresh BigFloat SVDs at each point.

Arguments

• A: matrix to certify (will be converted to BigFloat BallMatrix)
• circle: CertificationCircle describing the contour
• target_precision::Int=256: precision in bits for BigFloat
• max_ogita_iterations::Int=3: Ogita iterations (3 is optimal for 256-bit precision)
• Other kwargs passed to standard certification

run_certification_parametric(A, circle; k=nothing, config=config_v2(), kwargs...)

Run the adaptive certification routine using the parametric Sylvester-based certifier.

This method uses block-diagonalization via Sylvester equation to certify the resolvent norm, which can be more efficient than full SVD for large matrices.

Arguments

• A: matrix to certify. Converted to BallMatrix when required.
• circle: CertificationCircle describing the contour.

Keyword Arguments

• k::Union{Nothing, Int}=nothing: Split index for the Schur block decomposition. If nothing, automatically selects k ≈ n/4.
• config::ResolventBoundConfig=config_v2(): Configuration specifying estimators. Options: config_v1(), config_v2(), config_v2p5(), config_v3().
• polynomial = nothing: optional coefficients for polynomial certification.
• η = 0.5: admissible threshold for adaptive refinement.
• check_interval = 100: number of arcs between progress reports.
• log_io = stdout: destination for log messages.
• Cbound = 1.0: constant for resolvent bound lifting.

Example

using BallArithmetic
A = randn(ComplexF64, 50, 50)
circle = CertificationCircle(0.0, 1.5; samples=64)

# Use V2 configuration (default)
result = run_certification_parametric(A, circle)

# Use V3 configuration with Neumann bounds
result = run_certification_parametric(A, circle; config=config_v3())

# Specify custom split
result = run_certification_parametric(A, circle; k=10)

save_snapshot!(arcs, cache, log, pending, basepath, toggle)

Persist the current certification state to disk using alternating files.

schur_to_original_resolvent(resolvent_schur, ϵ; Cbound=1.0)

Transform a Schur resolvent bound to the original matrix using the Schur perturbation theorem. Returns Inf when the bound is not computable (ε·resolvent too large for the perturbation estimate).

set_parametric_config!(precomp, R, config; k=0)

Set the parametric certifier configuration.

Arguments

• precomp: Precomputed Sylvester quantities from sylvester_resolvent_precompute
• R: Sylvester residual matrix
• config: ResolventBoundConfig specifying estimators
• k: Split index (for reference)

set_schur_matrix!(T)

Store the Schur factor T used by dowork.