workbench_algorithms.experimental.utils.alias_sampling_utils

Utilities for alias sampling state prep.

AliasSamplingStatePrepDataProtocol

Bases: Protocol

Protocol for alias sampling state preparation data containers.

is_positive_real property

is_positive_real: bool

Determines whether coefficients are all positive, real values.

probabilities property

probabilities: list[float] | SymbolicArray

Converts coefficients to corresponding probabilities.

validate_inputs

validate_inputs() -> None

Check that all input coefficients and types are valid for alias sampling.

trim_register_if_needed

trim_register_if_needed(
    qbits: Qubits | SymbolicQubits,
) -> Qubits | SymbolicQubits

Trim register to appropriate size if too many qubits were provided.

combined_data_list

combined_data_list(
    max_shift: int | Parameter | None = None,
) -> list[int] | SymbolicArray

Helper to combine data output by QROM in alias sampling.

compute_num_states

compute_num_states() -> (
    tuple[int | Parameter, int | Parameter]
)

Helper to compute number of states to prepare in alias sampling.

NumericAliasSamplingStatePrepData dataclass

NumericAliasSamplingStatePrepData(
    coeffs: Iterable[float | complex],
    bits_of_precision: int | None = None,
    lambda_val: int | None = None,
    error_param: int | None = None,
)

Numeric implementation of alias sampling state preparation data.

is_positive_real property

is_positive_real: bool

Determines whether self.coeffs are all positive, real values.

probabilities cached property

probabilities: list[float]

Converts self.coeffs to the corresponding probabilities.

validate_inputs

validate_inputs() -> None

Check that all input coefficients and types are valid for alias sampling.

trim_register_if_needed

trim_register_if_needed(qbits: Qubits) -> Qubits

Trim register to appropriate size if too many qubits were provided.

combined_data_list

combined_data_list(
    max_shift: int | None = None,
) -> list[int]

Helper to combine data output by QROM in alias sampling.

compute_num_states

compute_num_states() -> tuple[int, int]

Helper to compute number of states to prepare in alias sampling.

SymbolicAliasSamplingStatePrepData dataclass

SymbolicAliasSamplingStatePrepData(
    coeffs: SymbolicArray,
    bits_of_precision: Parameter | None = None,
    lambda_val: Parameter | None = None,
    error_param: Parameter | None = None,
)

Symbolic implementation of alias sampling state preparation data.

is_positive_real property

is_positive_real: bool

Determines whether self.coeffs are all positive, real values.

probabilities cached property

probabilities: SymbolicArray

Converts self.coeffs to the corresponding probabilities.

validate_inputs

validate_inputs() -> None

Check that all input coefficients and types are valid for alias sampling.

trim_register_if_needed

trim_register_if_needed(
    qbits: SymbolicQubits,
) -> SymbolicQubits

Trim register to appropriate size if too many qubits were provided.

combined_data_list

combined_data_list(
    max_shift: Parameter | None = None,
) -> SymbolicArray

Helper to combine data output by QROM in alias sampling.

compute_num_states

compute_num_states() -> tuple[Parameter, Parameter]

Helper to compute number of states to prepare in alias sampling.

alias_sampling_state_prep_data

alias_sampling_state_prep_data(
    coeffs: SymbolicArray,
    bits_of_precision: Parameter | None = None,
    lambda_val: Parameter | None = None,
    error_param: Parameter | None = None,
) -> SymbolicAliasSamplingStatePrepData

alias_sampling_state_prep_data(
    coeffs: Iterable[float | complex],
    bits_of_precision: int | None = None,
    lambda_val: int | None = None,
    error_param: int | None = None,
) -> NumericAliasSamplingStatePrepData

alias_sampling_state_prep_data(
    coeffs: Iterable[float | complex] | SymbolicArray,
    bits_of_precision: int | Parameter | None = None,
    lambda_val: int | Parameter | None = None,
    error_param: int | Parameter | None = None,
) -> AliasSamplingStatePrepDataProtocol

Create appropriate alias sampling state prep data based on input type.

discretized_prob_distribution_improved

discretized_prob_distribution_improved(
    probabilities_list: Iterable[float], bit_precision: int
) -> np.array

Discretizes a probability distribution while preserving the total sum using a rounding correction.

Warning: this function now takes the input parameter in the form of the probabilities (amplitude square) rather than the state vector. This is compatible with the implementation in the experimental branch, and will cause conflict with the original Alias Sampling implementation

Parameters:

Name	Type	Description	Default
probabilities_list	Iterable[float]	List of non-negative values representing probabilities of coefficients (don't have to be normalized)	required
bit_precision	int	Number of bits to determine the number of discrete levels.	required

Returns:

Type	Description
array	Discretized values that sum to the expected total.

Raises:

Type	Description
ValueError	If input contains negative values.

alias_sampling_get_b_from_epsilon

alias_sampling_get_b_from_epsilon(
    inputs: Iterable[float],
    epsilon: float,
    b_upper_bound: int = 1000,
    return_theory_bound_and_actual_diff: bool = False,
) -> int | tuple[int, float, float]

Get the number of bits of precision needed for alias sampling to achieve an accuracy epsilon.

Finds the minimum bit precision required such that the 2-norm difference between the normalized input and its discretized version is below an epsilon threshold.

Parameters:

Name	Type	Description	Default
inputs	Iterable[float]	Input list of values to be normalized and discretized.	required
epsilon	float	Threshold for acceptable 2-norm difference.	required
b_upper_bound	int	Maximum bit precision to search. Default is 1000.	1000
return_theory_bound_and_actual_diff	bool	a boolean the user to set if they want to return the theory bound and actual l2-norm difference	False

Returns:

Type	Description
tuple	(bit_precision, norm_diff) if a suitable precision is found.

Raises:

Type	Description
ValueError	If no suitable bit precision is found within the range.