API reference

Everything below is importable from the top-level felcu package.

Solver

felcu.solve_fe_coefficients

solve_fe_coefficients(problem: str, *, method: str = 'sobolev', matrix: ndarray | Sequence[Sequence[complex]] | None = None, sigma_min: float | None = None, sigma_max: float | None = None, gap: tuple[float, float] | None = None, spectral_kind: str = 'auto', eta: float | None = None, target_error: float = 1e-12, error_metric: str = 'linf', m: int | None = None, m_values: Sequence[int] | int | None = None, lambdas: Sequence[float] | None = None, sobolev_w: float | None = None, sobolev_r: float | None = None, order_fit: int | None = None, fit_oversample: int | None = None, val_n: int = 4001, selection: str = 'smallest_alpha', hermitian_tol: float = 1e-12) -> FourierExtensionResult

Compute Fourier-extension LCU block-encoding coefficients.

The fit is centred on the spectrum: with mu and delta the centre and half-width of the fitted set, tau = pi / (eta delta) and f(H) = g(tau (H - mu I)) (result.mu, result.tau). Singular values are fitted through the Hermitian dilation of the matrix, whose spectrum is symmetric, so mu = 0 and the series is odd.

Parameters:

Name	Type	Description	Default
problem	str	One of 'identity' (or 'action'), 'inversion', 'exponentiation', 'square_root', or 'logarithm' (several aliases accepted; see :func:~felcu.utils.canonical_problem_name). Square root and logarithm need a positive-definite eigenvalue interval.	required
method	str	Coefficient-selection strategy (see :func:~felcu.canonical_method_name for aliases): 'sobolev' (default): Sobolev-regularised least squares. Near-exponential convergence down to target_error, with subnormalisation O(||f(H)||). 'reflected': the Fourier series of g reflected about x = +-pi/2. Optimal subnormalisation alpha_m = ||f(H)|| - epsilon_m for convex endpoint-maximising f (identity, exponentiation, definite inversion) at the default eta = 2, but only O(1/m) convergence, so the default target_error is out of reach. 'arcsine_taylor': the Taylor series of g(arcsin z) with z = sin x. Exponential convergence with factor sin(pi/eta) (requires eta > 2) and subnormalisation bounded independently of the error. The explicit methods do not support the two-interval fit of inversion on an indefinite interval or on singular values, and for definite inversion, square root and logarithm need eta < 2 |mu| / delta. They have no regularisation, so the Sobolev-only options (lambdas, sobolev_w, sobolev_r, order_fit, fit_oversample) must be left unset.	'sobolev'
matrix	ndarray | Sequence[Sequence[complex]] | None	Square matrix whose spectral information drives the fitting. Mutually exclusive with sigma_min / sigma_max / gap; one of the two is required.	None
sigma_min	float | None	Spectral interval: eigenvalue or singular-value bounds, per spectral_kind.	None
sigma_max	float | None	Spectral interval: eigenvalue or singular-value bounds, per spectral_kind.	None
gap	tuple[float, float] | None	For inversion on an indefinite eigenvalue interval (sigma_min < 0 < sigma_max), the eigenvalues (a, b) closest to 0 on either side: the spectrum lies in [sigma_min, a] U [b, sigma_max], and the series is fitted on both parts, leaving the gap around the pole free. Required in that case and not allowed otherwise; with matrix, it is read from the eigenvalues.	None
spectral_kind	str	Which spectral data the bounds (or matrix) describe. 'eigenvalues' needs a Hermitian matrix. 'singular_values' acts on a general matrix through its Hermitian dilation, with an odd series, so it is available for identity and inversion only. 'auto' (default) uses singular values for identity and inversion of a non-Hermitian matrix, and eigenvalues otherwise.	'auto'
eta	float | None	Fourier-extension parameter (must exceed 1). Computed automatically when omitted; see :func:~felcu.default_eta.	None
target_error	float	Desired approximation error.	1e-12
error_metric	str	'l2' or 'linf'.	'linf'
m	int | None	Fixed Fourier truncation order; overrides m_values.	None
m_values	Sequence[int] | int | None	Candidate truncation orders to search over.	None
lambdas	Sequence[float] | None	Grid of regularisation strengths lambda = sqrt(2 pi gamma), where gamma is the weight of the H_r^w penalty in the paper's regularised problem. The largest lambda meeting target_error is used.	None
sobolev_w	float | None	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), i.e. penalises every derivative up to order w; for fractional w, P_w(z) = (1 - z^(2(w+1))) / (1 - z^2). Must exceed 0.5; the paper's bounds cover 0.5 < w <= 1. Defaults to 1.	None
sobolev_r	float | None	Scale r of the H_r^w regulariser, with 0 < r <= 1. Chosen by :func:~felcu.default_sobolev_r when omitted.	None
order_fit	int | None	Number of derivative orders included in the fit system: 1 (default) fits in the H^1 norm, 0 in plain L^2.	None
fit_oversample	int | None	Oversampling factor for the Gauss quadrature grid. Defaults to 8.	None
val_n	int	Number of validation points.	4001
selection	str	'smallest_alpha' (default) picks the feasible order with the smallest subnormalisation alpha, which requires solving every order in the sweep. 'smallest_m' picks the shortest feasible series and stops the sweep there, so result.all_results only holds the orders up to it.	'smallest_alpha'
hermitian_tol	float	Tolerance for the Hermitian test.	1e-12

Returns:

Type	Description
FourierExtensionResult	The selected result; result.all_results contains every candidate.

felcu.compute_fe_coefficients

compute_fe_coefficients(*args, **kwargs) -> tuple[float, np.ndarray, np.ndarray]

Convenience wrapper; returns (a0, ak, bk) directly.

Takes the same arguments as :func:solve_fe_coefficients and discards everything but the coefficients. Use :func:solve_fe_coefficients when you also need tau, the achieved error, or whether the fit converged.

Returns:

Name	Type	Description
a0	float	Constant term.
	ak, bk : numpy.ndarray	Sine and cosine coefficients (copies), each of length m.

Result

felcu.FourierExtensionResult dataclass

Result of a Fourier-extension coefficient computation.

Returned by :func:~felcu.solve_fe_coefficients. The fitted series is g(x) = a0 + sum_k ak[k-1] sin(kx) + bk[k-1] cos(kx), and the matrix function is f(H) = g(tau (H - mu I)). For singular values, H is the Hermitian dilation of the matrix and mu = 0.

Attributes:

Name	Type	Description
problem	str	'identity', 'inversion', 'exponentiation', 'square_root', or 'logarithm'.
method	str	Coefficient-selection strategy: 'sobolev', 'reflected', or 'arcsine_taylor'.
basis_used	str	'odd_sine' (sine terms only), 'const_plus_sine' (constant plus sine terms), or 'full'.
m	int	Truncation order: the number of harmonics.
eta	float	Extension parameter; the series was fitted on [-pi/eta, pi/eta].
tau	float	Scale between the matrix spectrum and the fitted variable, pi / (eta delta) with delta the half-width of the fitted spectrum; infinite for a zero-width interval.
mu	float	Centre of the fitted spectrum, which the fit is shifted by: the midpoint of [sigma_min, sigma_max] for eigenvalues, and 0 for singular values.
alpha	float	Subnormalisation alpha_m = sum_k |c_k| = |a0| + sum_k sqrt(ak**2 + bk**2).
target_error	float	The requested error.
error_metric	str	'l2' or 'linf': the metric compared with target_error.
achieved_error	float	Achieved error in error_metric.
achieved_l2_error	float	Achieved L2 error on the fitted domain. A side of a two-interval domain that is a single point counts as much as the whole domain.
achieved_linf_error	float	Achieved maximum pointwise error on the fitted domain.
converged	bool	Whether achieved_error meets target_error.
lambda_used	float or None	Sobolev regularisation strength chosen for this m; None for the explicit ('reflected', 'arcsine_taylor') methods.
sobolev_r	float or None	Scale r of the H_r^w regulariser that was used; None for the explicit methods.
sobolev_w	float or None	Order w of the H_r^w regulariser that was used; None for the explicit methods.
a0	float	Constant term.
ak	ndarray	Sine coefficients, length m.
bk	ndarray	Cosine coefficients, length m (all zero for the sine-only bases).
complex_coefficients	ndarray	The same series as [c_{-m}, ..., c_m]; see :func:~felcu.to_complex_coefficients. For the order a circuit consumes them in, see :attr:circuit_coefficients.
k	ndarray	Harmonic indices 1, ..., m matching ak and bk.
x_max	float	Outer edge of the fitted domain, pi / eta.
x_gap	tuple of float or None	For inversion on an indefinite interval or on singular values, the gap around the pole that the fit leaves free, in the fitted variable: the fitted set is [-x_max, x_gap[0]] U [x_gap[1], x_max]. None when it is [-x_max, x_max].
sigma_min, sigma_max	float	Spectral interval used (eigenvalues or singular values, per spectral_kind_used).
gap	tuple of float or None	Eigenvalue gap (a, b) around 0 for inversion on an indefinite interval; None otherwise.
spectral_kind_used	str	'eigenvalues' or 'singular_values'.
matrix_shape	tuple of int or None	Shape of the input matrix, if one was given.
matrix_is_hermitian	bool or None	Whether the input matrix passed the Hermitian test, if one was given.
all_results	tuple of FourierExtensionResult	Every candidate tried, sorted by m. Empty on the candidates themselves.

problem instance-attribute

problem: str

method instance-attribute

method: str

basis_used instance-attribute

basis_used: str

m instance-attribute

m: int

eta instance-attribute

eta: float

tau instance-attribute

tau: float

mu instance-attribute

mu: float

alpha instance-attribute

alpha: float

target_error instance-attribute

target_error: float

error_metric instance-attribute

error_metric: str

achieved_error instance-attribute

achieved_error: float

achieved_l2_error instance-attribute

achieved_l2_error: float

achieved_linf_error instance-attribute

achieved_linf_error: float

converged instance-attribute

converged: bool

lambda_used instance-attribute

lambda_used: float | None

sobolev_r instance-attribute

sobolev_r: float | None

sobolev_w instance-attribute

sobolev_w: float | None

a0 instance-attribute

a0: float

ak instance-attribute

ak: ndarray

bk instance-attribute

bk: ndarray

complex_coefficients instance-attribute

complex_coefficients: ndarray

k instance-attribute

k: ndarray

x_max instance-attribute

x_max: float

x_gap instance-attribute

x_gap: tuple[float, float] | None

sigma_min instance-attribute

sigma_min: float

sigma_max instance-attribute

sigma_max: float

gap instance-attribute

gap: tuple[float, float] | None

spectral_kind_used instance-attribute

spectral_kind_used: str

matrix_shape instance-attribute

matrix_shape: tuple[int, int] | None

matrix_is_hermitian instance-attribute

matrix_is_hermitian: bool | None

all_results class-attribute instance-attribute

all_results: tuple[FourierExtensionResult, ...] = ()

coefficients property

coefficients: ndarray

Coefficients packed as a single vector in the order of basis_used.

[ak] for 'odd_sine', [a0, ak] for 'const_plus_sine', and [a0, ak, bk] for 'full'.

circuit_coefficients property

circuit_coefficients: ndarray

Complex coefficients in circuit order, [c_0, 0, c_1, c_{-1}, ..., c_m, c_{-m}].

Length 2m + 2: the zero after c_0 is required by the compressed circuit. See :func:~felcu.to_circuit_coefficients.

achieved_inf_error property

achieved_inf_error: float

Alias for :attr:achieved_linf_error.

evaluate

evaluate(x: ArrayLike) -> np.ndarray

Evaluate the approximation to f at points x of the original variable.

Applies the scaling for you: this is g(tau (x - mu)), which approximates f(x) for x in the fitted spectrum. For singular values mu = 0 and x is a singular value (or its negative, an eigenvalue of the dilation). To evaluate g itself in the scaled variable, use :func:~felcu.evaluate_fourier_series.

Parameters:

Name	Type	Description	Default
x	ArrayLike	Points, of any shape, at which to approximate f.	required

Returns:

Type	Description
ndarray	The approximation, with the same shape as x.

apply

apply(matrix: ndarray | Sequence[Sequence[complex]], hermitian_tol: float = 1e-12, interval_tol: float = 1e-08) -> np.ndarray

Apply the approximation to a Hermitian matrix: g(tau (H - mu I)) ~ f(H).

Computed classically by eigendecomposition, to check a fit against an exact f(H). The eigenvalues of matrix must lie in the fitted spectrum: outside it the series is a periodic extension that bears no relation to f. They must also lie in the domain of f, which is checked separately, so the interval slack can never admit an eigenvalue where f is undefined: they must be positive for the square root and the logarithm, and nonzero for inversion, with the sign of the fitted spectrum when that is definite. For a singular-value fit, pass the Hermitian dilation of the matrix.

Both checks use the eigenvalues as computed in floating point, so a matrix is accepted exactly when its computed eigenvalues lie in the fitted spectrum and the domain of f. A matrix that is singular in exact arithmetic, but whose computed eigenvalues pass both checks, is nonsingular to working precision, and the result is g(tau (H - mu I)) for those computed eigenvalues.

Parameters:

Name	Type	Description	Default
matrix	ndarray | Sequence[Sequence[complex]]	Square Hermitian matrix H.	required
hermitian_tol	float	Relative tolerance for the Hermitian test.	1e-12
interval_tol	float	How far, relative to the half-width of the fitted spectrum, an eigenvalue may stray outside it before it is rejected. At the edges of an inversion gap it is relative to the edge's distance from 0 instead, and for a zero-width spectrum [mu, mu] to |mu| (absolute when mu = 0).	1e-08

Returns:

Type	Description
ndarray	The matrix g(tau (H - mu I)), the same shape as matrix.

Raises:

Type	Description
ValueError	If matrix is not square, not Hermitian, or has an eigenvalue outside the domain of f or outside the fitted spectrum.

format_circuit_coefficients

format_circuit_coefficients() -> str

:attr:circuit_coefficients as a bare Python list literal, for pasting by hand.

See :func:~felcu.format_circuit_coefficients.

to_dict

to_dict(include_candidates: bool = False) -> dict

Return the result as a JSON-compatible dictionary.

Arrays become lists, complex_coefficients becomes {"k": [-m..m], "real": [...], "imag": [...]}, and non-finite floats (tau is infinite for a zero-width interval) become the strings "inf", "-inf" or "nan". The dictionary also records format, format_version and felcu_version.

Parameters:

Name	Type	Description	Default
include_candidates	bool	Also store :attr:all_results, every order tried in the sweep.	False

from_dict classmethod

from_dict(data: dict) -> FourierExtensionResult

Rebuild a result from :meth:to_dict output.

Raises:

Type	Description
ValueError	If data is not a saved felcu result, has an unsupported format_version, or is missing a field.

to_json

to_json(path: str | Path | None = None, *, indent: int | None = 2, include_candidates: bool = False) -> str

Serialise the result to JSON, and write it to path if given.

The file is standard JSON (no NaN or Infinity literals) and can be read from any language; floats are written with enough digits to round-trip exactly. See :meth:to_dict for the layout.

Parameters:

Name	Type	Description	Default
path	str | Path | None	File to write. If omitted, only the string is returned.	None
indent	int | None	Indentation passed to :func:json.dumps; None for one line.	2
include_candidates	bool	Also store :attr:all_results.	False

Returns:

Type	Description
str	The JSON text.

Examples:

>>> result.to_json("exp_coefficients.json")
>>> loaded = FourierExtensionResult.from_json("exp_coefficients.json")

from_json classmethod

from_json(source: str | Path) -> FourierExtensionResult

Load a result saved with :meth:to_json.

Parameters:

Name	Type	Description	Default
source	str | Path	A path to a JSON file, or the JSON text itself.	required

Raises:

Type	Description
ValueError	As for :meth:from_dict.

__init__

__init__(problem: str, method: str, basis_used: str, m: int, eta: float, tau: float, mu: float, alpha: float, target_error: float, error_metric: str, achieved_error: float, achieved_l2_error: float, achieved_linf_error: float, converged: bool, lambda_used: float | None, sobolev_r: float | None, sobolev_w: float | None, a0: float, ak: ndarray, bk: ndarray, complex_coefficients: ndarray, k: ndarray, x_max: float, x_gap: tuple[float, float] | None, sigma_min: float, sigma_max: float, gap: tuple[float, float] | None, spectral_kind_used: str, matrix_shape: tuple[int, int] | None, matrix_is_hermitian: bool | None, all_results: tuple[FourierExtensionResult, ...] = ()) -> None

felcu.ConvergenceWarning

Bases: UserWarning

No candidate order met the requested target_error.

Issued by :func:~felcu.solve_fe_coefficients, which still returns the best candidate, with converged=False. Silence it with warnings.simplefilter("ignore", felcu.ConvergenceWarning).

Evaluating results

felcu.evaluate_fourier_series

evaluate_fourier_series(x: ArrayLike, a0: float | complex, ak: Sequence, bk: Sequence) -> np.ndarray

Evaluate the real Fourier series g(x) = a0 + sum_k ak sin(kx) + bk cos(kx).

The sum runs over k = 1, ..., len(ak).

Parameters:

Name	Type	Description	Default
x	ArrayLike	Evaluation points, of any shape.	required
a0	float | complex	Constant term.	required
ak	Sequence	Sine and cosine coefficients, of equal length. Complex values are allowed.	required
bk	Sequence	Sine and cosine coefficients, of equal length. Complex values are allowed.	required

Returns:

Type	Description
ndarray	g(x), with the same shape as x. The result is complex if any coefficient is complex.

Raises:

Type	Description
ValueError	If ak and bk have different lengths.

felcu.evaluate_target_function

evaluate_target_function(x: ArrayLike, result: FourierExtensionResult) -> np.ndarray

Evaluate the exact target function for result at points x.

This is the function the series was fitted to, in the scaled variable, so it can be compared directly with :func:evaluate_fourier_series. It is g(x) = f(mu + x / tau), not f itself: mu + x / tau, 1 / (mu + x / tau), exp(mu + x / tau), sqrt(mu + x / tau) or log(mu + x / tau). If tau is infinite (a zero-width interval), the target is constant.

Parameters:

Name	Type	Description	Default
x	ArrayLike	Evaluation points in the scaled variable.	required
result	FourierExtensionResult	A result from :func:~felcu.solve_fe_coefficients.	required

Returns:

Type	Description
ndarray	Target values, with the same shape as x.

Raises:

Type	Description
ValueError	If the problem is unknown.

felcu.fitted_domain_segments

fitted_domain_segments(result: FourierExtensionResult, num: int = 2001) -> list[np.ndarray]

Return x-arrays covering the fitted domain of result.

Use these to plot or check a fit, e.g. by comparing :func:evaluate_fourier_series with :func:evaluate_target_function on each segment.

Parameters:

Name	Type	Description	Default
result	FourierExtensionResult	A result from :func:~felcu.solve_fe_coefficients.	required
num	int	Number of points. For a double-interval domain, each interval gets num // 2 points.	2001

Returns:

Type	Description
list of numpy.ndarray	One array spanning [-x_max, x_max] for a single-interval domain, or two arrays spanning [-x_max, x_gap[0]] and [x_gap[1], x_max] for a double-interval one.

Raises:

Type	Description
ValueError	If num < 2.

felcu.to_complex_coefficients

to_complex_coefficients(a0_or_result: FourierExtensionResult | float | complex, ak: Sequence | None = None, bk: Sequence | None = None) -> np.ndarray

Convert a0, ak, bk to [c_{-m}, ..., c_0, ..., c_m].

The complex coefficients give the same series in exponential form, g(x) = sum_{k=-m}^{m} c_k exp(i k x), with

• c_0 = a0,
• c_k = (bk[k-1] - i ak[k-1]) / 2 for k > 0,
• c_{-k} = (bk[k-1] + i ak[k-1]) / 2.

Parameters:

Name	Type	Description	Default
a0_or_result	FourierExtensionResult | float | complex	Either a :class:~felcu.FourierExtensionResult, in which case its coefficients are used and ak / bk are ignored, or the constant term a0.	required
ak	Sequence | None	Sine and cosine coefficients, of equal length. Required unless a result is passed.	None
bk	Sequence | None	Sine and cosine coefficients, of equal length. Required unless a result is passed.	None

Returns:

Type	Description
ndarray	Complex array of length 2m + 1, ordered from c_{-m} to c_m.

Raises:

Type	Description
ValueError	If ak or bk is missing, or their lengths differ.

felcu.to_circuit_coefficients

to_circuit_coefficients(a0_or_result: FourierExtensionResult | float | complex, ak: Sequence | None = None, bk: Sequence | None = None) -> np.ndarray

Convert a0, ak, bk to the circuit order [c_0, 0, c_1, c_{-1}, ..., c_m, c_{-m}].

This is the order the compressed LCU circuit consumes the coefficients in: c_0, then a zero, then the pairs c_k, c_{-k} for k = 1, ..., m. The zero pads the 2m + 1 coefficients of :func:to_complex_coefficients to the 2m + 2 the compressed circuit requires; it must be kept.

Parameters:

Name	Type	Description	Default
a0_or_result	FourierExtensionResult | float | complex	As for :func:to_complex_coefficients.	required
ak	FourierExtensionResult | float | complex	As for :func:to_complex_coefficients.	required
bk	FourierExtensionResult | float | complex	As for :func:to_complex_coefficients.	required

Returns:

Type	Description
ndarray	Complex array of length 2m + 2.

Raises:

Type	Description
ValueError	As for :func:to_complex_coefficients.

felcu.format_circuit_coefficients

format_circuit_coefficients(a0_or_result: FourierExtensionResult | float | complex, ak: Sequence | None = None, bk: Sequence | None = None) -> str

Format the circuit-order coefficients as a bare Python list literal.

For pasting the coefficients somewhere by hand. Code that imports felcu should use :func:to_circuit_coefficients (or :attr:FourierExtensionResult.circuit_coefficients) directly instead. Each entry is written with :func:repr, so the list reproduces :func:to_circuit_coefficients exactly, including the zero after c_0 that the compressed circuit requires.

Parameters:

Name	Type	Description	Default
a0_or_result	FourierExtensionResult | float | complex	As for :func:to_complex_coefficients.	required
ak	FourierExtensionResult | float | complex	As for :func:to_complex_coefficients.	required
bk	FourierExtensionResult | float | complex	As for :func:to_complex_coefficients.	required

Returns:

Type	Description
str	A Python list literal, [c_0, 0j, c_1, c_-1, ..., c_m, c_-m].

Examples:

>>> print(format_circuit_coefficients(result))
[(2.718...+0j), 0j, (0.5-0.1j), (0.5+0.1j), ...]

Defaults

felcu.default_eta

default_eta(problem: str, *, method: str = 'sobolev', matrix: ndarray | Sequence[Sequence[complex]] | None = None, sigma_min: float | None = None, sigma_max: float | None = None, gap: tuple[float, float] | None = None, spectral_kind: str = 'auto', hermitian_tol: float = 1e-12) -> float

Return the default extension parameter eta for the given problem and method.

The series is fitted on [-pi/eta, pi/eta], so eta > 1 sets how much of the period is left free. With mu and delta the centre and half-width of the fitted spectrum, the defaults for the Sobolev-regularised method are

• identity and exponentiation: 2;
• inversion on a definite interval, square root and logarithm: |mu| / delta = (kappa + 1) / (kappa - 1), which puts the pole or branch point at 0 on the periodic boundary (2 if kappa == 1);
• inversion on an indefinite interval or on singular values: 1 + (b - a) / (2 delta), with (a, b) the gap around the pole, which leaves the gap and the free part of the period equally wide. For singular values (or a symmetric gap) this is 1 + 1/kappa.

The reflected extension always defaults to 2, which maps the spectral endpoints onto the reflection points and gives the optimal subnormalisation. Arcsine-Taylor needs eta > 2: it defaults to 3 for identity and exponentiation, and to min(3, 1 + |mu|/delta) for definite inversion, square root and logarithm, the midpoint of the admissible range 2 < eta < 2 |mu|/delta.

Parameters:

Name	Type	Description	Default
problem	str	One of 'identity', 'inversion', 'exponentiation', 'square_root', or 'logarithm' (or an alias; see :func:~felcu.canonical_problem_name).	required
method	str	'sobolev', 'reflected', or 'arcsine_taylor' (or an alias; see :func:~felcu.canonical_method_name).	'sobolev'
matrix	ndarray | Sequence[Sequence[complex]] | None	Square matrix to read the spectral interval from. Mutually exclusive with sigma_min / sigma_max / gap.	None
sigma_min	float | None	Spectral interval bounds.	None
sigma_max	float | None	Spectral interval bounds.	None
gap	tuple[float, float] | None	Eigenvalue gap (a, b) around 0, for inversion on an indefinite interval; see :func:~felcu.solve_fe_coefficients.	None
spectral_kind	str	'auto', 'eigenvalues', or 'singular_values'.	'auto'
hermitian_tol	float	Tolerance for the Hermitian test.	1e-12

Returns:

Type	Description
float	The default eta.

Raises:

Type	Description
ValueError	For inversion, square root and logarithm, if no spectral information is given or the interval is invalid (see :func:~felcu.solve_fe_coefficients), or for a two-interval inversion with an explicit method.

Notes

Spectral information is only used for inversion, square root and logarithm; for identity and exponentiation it is ignored.

felcu.default_sobolev_r

default_sobolev_r(problem: str, *, matrix: ndarray | Sequence[Sequence[complex]] | None = None, sigma_min: float | None = None, sigma_max: float | None = None, gap: tuple[float, float] | None = None, spectral_kind: str = 'auto', hermitian_tol: float = 1e-12, eta: float | None = None, sobolev_w: float = 1.0) -> float

Return the default scale r of the H_r^w regulariser for the given problem.

The regulariser weights the k-th Fourier mode by P_w(r|k|) = sum_{j=0}^{w} (r|k|)^(2j), so r should match the shortest length scale the fitted function g has to resolve. The defaults follow the scale-adapted choices of Brearley, Howarth and Adcock (Sec. VI):

• identity: r_id = 1, since g is linear;
• exponentiation: r_exp = 1 / (1 + 1/tau), since g' = g / tau, which is 1 / (1 + eta delta / pi);
• inversion: min(1, d), with d the distance from the fitted set to the pole in the scaled variable. At the default eta this is the paper's r_def = min(1, 2 pi / (kappa + 1)) for a definite interval and r_indef = min(1, pi / (kappa + 1)) for singular values;
• square root: r_sqrt = kappa^(-(2w - 1) / (2w)), which balances the two contributions to the extension's H_r^w norm (kappa^(-1/2) for w = 1);
• logarithm: r_log = kappa^(-(2w - 1) / (2w)) (1 + ln kappa)^(-1/w), the square-root rule with a factor for the logarithm's slower growth (kappa^(-1/2) / (1 + ln kappa) for w = 1).

Parameters:

Name	Type	Description	Default
problem	str	One of 'identity', 'inversion', 'exponentiation', 'square_root', or 'logarithm' (or an alias; see :func:~felcu.canonical_problem_name).	required
matrix	ndarray | Sequence[Sequence[complex]] | None	Square matrix to read the spectral interval from. Mutually exclusive with sigma_min / sigma_max / gap.	None
sigma_min	float | None	Spectral interval bounds.	None
sigma_max	float | None	Spectral interval bounds.	None
gap	tuple[float, float] | None	Eigenvalue gap (a, b) around 0, for inversion on an indefinite interval; see :func:~felcu.solve_fe_coefficients.	None
spectral_kind	str	'auto', 'eigenvalues', or 'singular_values'.	'auto'
hermitian_tol	float	Tolerance for the Hermitian test.	1e-12
eta	float | None	Extension parameter of the fit. Defaults to :func:~felcu.default_eta for the same problem.	None
sobolev_w	float	Order w of the regulariser; only the square-root and logarithm rules use it.	1.0

Returns:

Type	Description
float	The default r, which lies in (0, 1].

Raises:

Type	Description
ValueError	Except for identity, if no spectral information is given or the interval is invalid.

felcu.default_m_grid

default_m_grid(m_min: int = 4, m_max: int = 256, count: int = 32, power: float = 2.0) -> np.ndarray

Return a grid of candidate Fourier truncation orders.

The grid is m_min + (m_max - m_min) * t**power for count equally spaced t in [0, 1], truncated to integers. With power > 1 the grid is denser at small m. This is the default m_values for :func:~felcu.solve_fe_coefficients.

Parameters:

Name	Type	Description	Default
m_min	int	Smallest and largest order.	4
m_max	int	Smallest and largest order.	4
count	int	Number of grid points before duplicates are removed.	32
power	float	Spacing exponent; 1 gives a uniform grid.	2.0

Returns:

Type	Description
ndarray	Sorted unique integer orders. Truncation can merge neighbouring points, so there may be fewer than count. If count == 1 the grid is [m_max].

Raises:

Type	Description
ValueError	Unless 0 <= m_min <= m_max and count > 0.

felcu.default_lambda_grid

default_lambda_grid(lambda_max: float = 1.0, lambda_min: float = 1e-16, count: int = 12) -> np.ndarray

Return a log-spaced grid of regularisation parameters.

This is the default lambdas for :func:~felcu.solve_fe_coefficients. The solver sorts the grid itself and searches beyond it, so the grid only needs to bracket the answer roughly.

Parameters:

Name	Type	Description	Default
lambda_max	float	Largest and smallest value.	1.0
lambda_min	float	Largest and smallest value.	1.0
count	int	Number of values.	12

Returns:

Type	Description
ndarray	count geometrically spaced values from lambda_max down to lambda_min.

Raises:

Type	Description
ValueError	Unless 0 < lambda_min <= lambda_max and count >= 2.

Name normalisation

felcu.canonical_problem_name

canonical_problem_name(name: str) -> str

Normalise a problem name to 'identity', 'inversion', 'exponentiation', 'square_root' or 'logarithm'.

Matching ignores case and surrounding whitespace.

Parameters:

Name	Type	Description	Default
name	str	Problem name. Accepted aliases are 'action' (an equivalent name) and 'matrix-action' for 'identity'; 'inverse' for 'inversion'; 'exp' and 'exponential' for 'exponentiation'; 'sqrt' and 'square-root' for 'square_root'; and 'log' and 'ln' for 'logarithm'.	required

Returns:

Type	Description
str	'identity', 'inversion', 'exponentiation', 'square_root', or 'logarithm'.

Raises:

Type	Description
ValueError	If name is not a recognised problem or alias.

felcu.canonical_method_name

canonical_method_name(name: str) -> str

Normalise a coefficient-selection method to 'sobolev', 'reflected' or 'arcsine_taylor'.

Matching ignores case and surrounding whitespace.

Parameters:

Name	Type	Description	Default
name	str	Method name. Accepted aliases are 'regularised', 'regularized' and 'reg' for 'sobolev'; 'refl', 'reflected_extension' and 'reflected-extension' for 'reflected'; and 'asin', 'arcsine' and 'arcsine-taylor' for 'arcsine_taylor'.	required

Returns:

Type	Description
str	'sobolev', 'reflected', or 'arcsine_taylor'.

Raises:

Type	Description
ValueError	If name is not a recognised method or alias.

felcu.canonical_error_metric

canonical_error_metric(name: str) -> str

Normalise an error-metric name to 'l2' or 'linf'.

Matching ignores case and surrounding whitespace.

Parameters:

Name	Type	Description	Default
name	str	Metric name. '2' is accepted for 'l2'; 'inf', 'max', 'infinity', 'l_inf' and 'l-infinity' for 'linf'.	required

Returns:

Type	Description
str	'l2' or 'linf'.

Raises:

Type	Description
ValueError	If name is not a recognised metric or alias.