Barren Plateaus Submodule

Module meant to study barren plateaus

class AnalysisResult[source]

Bases: TypedDict

N_layers_extended: list[int]
N_qubits_extended: list[int]
metadata: list[Result]
padding_type: Literal['identity', 'I', 'linear_half', 'log'] | None
tracked: ndarray
class CostFunctionBuilder(*args, **kwargs)[source]

Bases: Protocol

class CostFunctionContext[source]

Bases: TypedDict

Ansatz: str
circuits: QuantumCircuit
depth: int
n_qubits: int
observables: Pauli | None
class ExecutionConfig(n_jobs: int = -1, verbose: bool = True)[source]

Bases: object

Parameters:

  • n_jobs (int)

  • verbose (bool)

n_jobs: int = -1

Number of parallel jobs used for sampling. A value of -1 usually means that all available cores are used.

verbose: bool = True

Whether to print progress information during the analysis.

class ExperimentConfig(analysis_type: str, N_qubits: Sequence[int], N_layers: Sequence[int], ansatz_name: str, observables_list: Sequence[qiskit.quantum_info.operators.symplectic.pauli.Pauli | str] | None = None, initial_Pauli_string: qiskit.quantum_info.operators.symplectic.pauli.Pauli | str | None = None, padding_types: Sequence[Literal['identity', 'I', 'linear_half', 'log']] | None = None)[source]

Bases: object

Parameters:

  • analysis_type (str)

  • N_qubits (Sequence[int])

  • N_layers (Sequence[int])

  • ansatz_name (str)

  • observables_list (Sequence[Pauli | str] | None)

  • initial_Pauli_string (Pauli | str | None)

  • padding_types (Sequence[Literal['identity', 'I', 'linear_half', 'log']] | None)

N_layers: Sequence[int]

List of circuit depths to test.

N_qubits: Sequence[int]

List of system sizes to test.

analysis_type: str

Type of scaling analysis to run. This selects how qubit counts, layer counts, observables, and padding strategies are combined.

ansatz_name: str

Name of the ansatz used to generate circuits.

initial_Pauli_string: Pauli | str | None = None

Initial Pauli string used when observables are generated by padding.

observables_list: Sequence[Pauli | str] | None = None

Observables used in the cost function. Entries may be Qiskit Pauli objects or Pauli strings.

padding_types: Sequence[Literal['identity', 'I', 'linear_half', 'log']] | None = None

Padding strategies used to grow the initial Pauli string with the number of qubits.

class LayerResult[source]

Bases: Result

lay: int
nq: int
obs: Pauli | None
var: float | ndarray
class Result[source]

Bases: TypedDict

nq: int
obs: Pauli | None
var: float | ndarray
class SamplingConfig(bootstrap_B: int = 500, rel_err_target: float = 0.05, N_min: int = 900, N_batch: int = 400, N_max: int = 20000, safety_factor: float = 1.2, max_batch: int = 10000)[source]

Bases: object

Parameters:

  • bootstrap_B (int)

  • rel_err_target (float)

  • N_min (int)

  • N_batch (int)

  • N_max (int)

  • safety_factor (float)

  • max_batch (int)

N_batch: int = 400

Number of new samples added at each adaptive sampling step.

N_max: int = 20000

Maximum number of samples allowed.

N_min: int = 900

Minimum number of samples collected before checking convergence.

bootstrap_B: int = 500

Number of bootstrap resamples used to estimate the uncertainty of the variance estimate.

max_batch: int = 10000

Maximum batch size used during adaptive sampling.

rel_err_target: float = 0.05

Target relative error for the variance estimate.

safety_factor: float = 1.2

Multiplicative safety factor applied to the estimated required sample count.

class VarianceNormalisation(*args, **kwargs)[source]

Bases: Protocol

adaptive_sampling_var(sample_function, N_min=50, N_batch=50, N_max=2000, B=500, rel_err_target=0.05, observable_index=0, rng=None, verbose=True, safety_factor=1.2, max_batch=None, abs_err_target=None, n_jobs=-1)[source]

Perform adaptive sampling to estimate the loss variance with bootstrap-based error control.

This method dynamically adjusts the number of samples using the expected \(1 / \sqrt(N)\) scaling of the bootstrap relative error.

Parameters:

  • sample_function (Callable[[], Any]) – Callable that returns a single sample

  • N_min (int) – Initial number of samples. Default is 50.

  • N_batch (int) – Minimum number of additional samples added per iteration. In this adaptive scheme, the effective batch size may vary.

  • N_max (int) – Maximum allowed number of samples. Default is 2000.

  • B (int) – Number of bootstrap resamples. Default is 500.

  • rel_err_target (float) – Target relative bootstrap error. Default is 0.05.

  • observable_index (int) – Index of the observable used for the stopping criterion.

  • rng (Generator | None) – Random number generator for reproducibility. If None, a default generator is used.

  • verbose (bool) – Whether to print progress information. Default is True.

  • safety_factor (float) – Multiplicative safety factor applied to the estimated required sample size. Typical values range from 1.1 to 1.5.

  • max_batch (int | None) – Maximum number of samples added in a single iteration. If None, no explicit cap is applied apart from N_max.

  • abs_err_target (float | None) – Optional absolute bootstrap error target. If provided, the algorithm stops when either: - relative_error <= rel_err_target, or - absolute_error <= abs_err_target. This is particularly useful when the standard deviation is very small and relative error becomes overly strict.

  • n_jobs (int) – Number of parallel jobs used when drawing new samples. Passed to joblib.Parallel. A value of -1 usually uses all available cores.

Returns:

an array containing all collected samples; the variance computed over all samples; and a dictionary containing bootstrap diagnostic information for the selected observable.

Return type:

A the three following elements

barren_plateaus_analysis(experiment, cost_function_builder, generate_params, generate_circuits, sampling=None, execution=None, variance_normalization=None, **cost_kwargs)[source]

Run a barren plateau scaling analysis for a given experiment configuration.

The function builds the requested circuits and cost functions, samples loss values, estimates their variance, and stores the results for the selected analysis type. Optional sampling and execution configurations control the adaptive sampling procedure and parallel execution. Extra keyword arguments are passed to the cost function builder.

Parameters:

  • experiment (ExperimentConfig) – Main experiment configuration.

  • cost_function_builder (CostFunctionBuilder) – Function used to build the cost function for each experiment setting.

  • generate_params (Callable[[int, int], list[float]]) – Function used to generate random circuit parameters.

  • generate_circuits (Callable[[int, int, str], QuantumCircuit]) – Function used to generate circuits for the selected ansatz and settings.

  • sampling (SamplingConfig | None) – Sampling configuration. If None, default sampling settings are used.

  • execution (ExecutionConfig | None) – Execution configuration. If None, default execution settings are used.

  • variance_normalization (VarianceNormalisation | None) – Optional function used to normalize the estimated variance before storing or plotting it.

  • **cost_kwargs (Any) – Additional keyword arguments passed to the cost function builder.

Returns:

Results produced by the selected analysis type. The returned objects contain variance estimates and metadata such as qubit count, layer count and observable.

Return type:

AnalysisResult | dict[int, list[Result]]

bootstrap_var_diagnostic_1d(var, L_samples, B=500, rng=None, rel_err_warn=0.05, rel_err_fail=0.1)[source]

Perform a bootstrap diagnostic for a single variance estimate.

Parameters:

  • var (float) – Reference estimate of the variance of the loss.

  • L_samples (ndarray) – Array of loss values evaluated for different parameter samples. Can have shape (N_samples,) or (N_samples, 1).

  • B (int) – Number of bootstrap resamples. Default is 500.

  • rng (Generator | None) – Random number generator for reproducibility. If None, a default generator is used.

  • rel_err_warn (float) – Relative error threshold for issuing a warning.

  • rel_err_fail (float) – Relative error threshold for declaring failure.

Returns:

  • bootstrap estimates of the standard deviation

  • relative error metrics

  • diagnostic flags based on thresholds

Return type:

Dictionary containing diagnostic quantities, including

extend_with_last(lst, target_len)[source]

Extend a sequence to a target length by repeating its last element.

Parameters:

  • lst (Sequence[T]) – Input sequence to extend. Must not be empty.

  • target_len (int) – Desired minimum length of the output list. If target_len is smaller than len(lst), the original list is returned unchanged.

Returns:

A list extended to target_len by repeating the last element.

Return type:

list[T]

pad_pauli_strings_growth(pauli, target_n, growth='linear_half', log_base=2)[source]

Pad a Pauli string on the left to reach a target number of qubits.

Parameters:

  • pauli (Pauli | str) – Input Pauli string. (for instance Pauli("IIYY"))

  • target_n (int) – Desired total number of qubits.

  • growth (Literal['identity', 'I', 'linear_half', 'log']) –

    Padding strategy. Available options are:

    • ”identity” or “I”: Pad with identity operators only.

    • ”linear_half”: Pad with X, Y or Z operators such that the total number of X/Y/Z operators is approximately target_n / 2.

    • ”log”: Pad with X, Y or Z operators such that the total number of X/Y/Z operators is approximately log(target_n).

  • log_base (float) – Base of the logarithm used when growth="log".

Returns:

Padded Pauli string of size target_n.

Return type:

Pauli

plot_joint_scaling_padding(tracked, A_ext, B_ext, N_qubits, N_layers, padding_type, padding_latex, Ansatz, rel_err_target)[source]

Plot the variance of loss values as a joint function of system size and circuit depth for a given padding strategy.

Parameters:

  • tracked (ArrayLike) – Sequence of tracked variance values.

  • A_ext (Sequence[int]) – Extended sequence associated with the primary scan axis.

  • B_ext (Sequence[int]) – Extended sequence associated with the secondary grouping axis.

  • N_qubits (Sequence[int]) – Sequence of qubit counts considered in the scan.

  • N_layers (Sequence[int]) – Sequence of circuit depths considered in the scan.

  • padding_type (str | None) – Identifier of the padding strategy used.

  • padding_latex (dict[str, str]) – Mapping from padding strategy identifiers to LaTeX labels.

  • Ansatz (str) – Name of the variational ansatz displayed in the figure.

  • rel_err_target (float) – Target relative error displayed in the figure annotations.

Return type:

None

plot_layerwise_qubits(results, N_layers, make_param_text)[source]

Plot the variance of loss values as a function of the number of qubits for different circuit depths.

Parameters:

  • results (dict[int, list[Result]]) – Mapping from circuit depth to computed statistics. Each entry must contain dictionaries with at least: - “nq”: number of qubits - “var”: variance value - “obs”: observable identifier

  • N_layers (Sequence[int]) – Sequence of circuit depths to display.

  • make_param_text (str) – Parameter summary text displayed on the figure.

Return type:

None

plot_layerwise_qubits_padding(results, N_layers, padding_types, padding_latex, make_param_text)[source]

Plot the variance of loss values as a function of the number of qubits for different circuit depths and padding strategies.

Parameters:

  • results (dict[tuple[int, Literal['identity', 'I', 'linear_half', 'log'] | None], list[~landscape_tools.barren_plateaus.Result]]) – Mapping indexed by (depth, padding_type) tuples. Each entry must contain dictionaries with at least: - “nq”: number of qubits - “var”: variance value - “obs”: observable identifier

  • N_layers (Sequence[int]) – Sequence of circuit depths to display.

  • padding_types (Sequence[Literal['identity', 'I', 'linear_half', 'log']] | None) – Sequence of padding strategies to include in the plot.

  • padding_latex (dict[str, str]) – Mapping from padding strategy identifiers to LaTeX labels used in the legend.

  • make_param_text (str) – Parameter summary text displayed on the figure.

Return type:

None