Tuning the solver

All options are keyword arguments to solve_fe_coefficients. The defaults suit most problems; this page explains when to change them.

Method

method (default "sobolev")

The coefficient-selection strategy: "sobolev" (regularised least squares), "reflected" (optimal \(\alpha\), \(O(m^{-1})\) error) or "arcsine_taylor" (exponential convergence at a larger \(\alpha\)). See Method for the trade-offs. Aliases: "regularised", "regularized", "reg"; "refl", "reflected_extension", "reflected-extension"; "asin", "arcsine", "arcsine-taylor".

Accuracy

target_error (default 1e-12)

The target tolerance \(\epsilon_{\rm t}\) the fit must meet. Tightening it increases \(m\) roughly logarithmically for smooth targets such as \(e^{x}\), and much faster for inversion with a large condition number. With method="reflected" the error falls only as \(O(m^{-1})\), so pass a loose target such as 1e-2.

error_metric (default "linf")

"linf" bounds \(\epsilon_m = \|g - g_m\|_{L^\infty(\Omega)}\), which bounds the block-encoding error \(\|f(\mathcal H) - g_m(\mathcal G)\|\). "l2" bounds the integrated error and is looser. Aliases: "inf", "max", "infinity", "l_inf", "l-infinity", "2".

val_n (default 4001)

Validation points used to measure the error. Increase it if you see the error rise when checked on a finer grid.

Truncation order

m

Fix a single order and skip the sweep.

m_values

Candidate orders to try, as a sequence or a single integer. Defaults to default_m_grid(): 31 values from 4 to 256.

selection (default "smallest_alpha")

"smallest_alpha" or "smallest_m"; see Choosing m. "smallest_m" stops the sweep at the first feasible order, so it is usually faster.

The sweep sets both the cost and the answer

With smallest_alpha, every order in m_values is solved; the default sweep takes a few seconds. smallest_m stops at the first feasible order and usually takes well under a second. Because \(\alpha\) tends to keep falling as \(m\) grows, the upper end of m_values often decides which order smallest_alpha returns, so cap it if circuit depth matters.

Regularisation

The options in this section, and fit_oversample, only apply to method="sobolev"; passing them with an explicit method raises an error.

lambdas

Initial grid of regularisation strengths \(\lambda = \sqrt{2\pi\gamma}\), where \(\gamma\) is the weight of the \(H^w_r\) penalty (see The regularised problem). Defaults to default_lambda_grid(): 12 log-spaced values from \(10^{-16}\) to \(1\). The solver expands beyond it and bisects, so the grid only needs to bracket the answer roughly.

sobolev_w (default 1)

Order \(w\) of the \(H_r^w\) regulariser, which weights the \(k\)-th Fourier mode by \(P_w(r|k|) = \sum_{j=0}^{w} (r|k|)^{2j}\) (see The Sobolev penalty). Must exceed \(1/2\); need not be an integer. The paper's bounds cover \(1/2 < w \le 1\).

sobolev_r (default: problem-dependent)

Scale \(r\) of the \(H_r^w\) regulariser, with \(0 < r \le 1\). When omitted it comes from default_sobolev_r, the paper's scale-adapted choices: \(r_{\rm id} = 1\) for identity, \(r_{\exp} = (1 + 1/\tau)^{-1}\) for exponentiation, and the distance from the fitted set to the pole, capped at \(1\), for inversion (at the default \(\eta\), \(r_{\rm def} = \min\{1, 2\pi/(\kappa+1)\}\) for a definite interval and \(r_{\rm indef} = \min\{1, \pi/(\kappa+1)\}\) for singular values), \(r_{\rm sqrt} = \kappa^{-(2w-1)/(2w)}\) for the square root, and \(r_{\log,w} = \kappa^{-(2w-1)/(2w)}(1 + \ln\kappa)^{-1/w}\) for the logarithm (see The Sobolev penalty). The value used is reported as result.sobolev_r.

order_fit (default 1)

Number of derivatives matched in the fit. 1 fits in \(H^1(\Omega)\), as in the paper; 0 falls back to \(L^2(\Omega)\). See The fitting norm.

Note

Passing lambdas=[0.0] does not disable regularisation: if \(\lambda = 0\) meets the target, the solver still expands upwards to find a larger feasible \(\lambda\).

Fitting grid

fit_oversample (default 8)

Gauss–Legendre nodes per unknown.

eta

The domain extension factor \(\eta > 1\) (\(\eta \ge 2\) for "reflected", \(\eta > 2\) for "arcsine_taylor"); see The extension parameter.

Spectral input

spectral_kind (default "auto")

"eigenvalues", "singular_values", or "auto": which data the bounds or matrix give. Singular values are fitted through the Hermitian dilation; see Spectral information.

gap (default None)

For inversion on an indefinite eigenvalue interval, the eigenvalues (a, b) closest to 0 on either side. Required in that case and read from the eigenvalues when matrix= is given; see Inversion.

hermitian_tol (default 1e-12)

Tolerance for deciding whether matrix is Hermitian.

Logging

felcu logs its progress through the standard logging module under the felcu logger:

import logging

logging.basicConfig(level=logging.INFO)  # one line per m
logging.getLogger("felcu").setLevel(logging.DEBUG)  # every lambda step