troma.optimization package

Submodules

troma.optimization.classical module

troma.optimization.classical.brute_force_max(marginals, sketch)

Brute force method to find the value of the dit string that maximizes the sum of the marginals. This method is not efficient for large dit string lengths, but it can be used as a baseline for testing other optimization methods.

Parameters:

  • marginals (list of float) – The marginals of the function defined on the full spectrum of dit strings. The order of the values should correspond to the order of the dit strings in the full spectrum.

  • sketch (2D numpy array) – The sketch matrix, where each column corresponds to a dit string and each row corresponds to a marginal.

Returns:

The index of the dit string that maximizes the sum of the marginals.

Return type:

int

troma.optimization.classical.dual_annealing(marginals, dit_constraints, dit_string_length, dit_dimension=2, opt_func_kwargs=None)

Use dual-annealing to find the value of the dit string that maximizes the sum of the marginals. This method is more efficient than brute force for large dit string lengths, but it may not always find the optimal solution.

Parameters:

  • marginals (list of float) – The marginals of the function defined on the full spectrum of dit strings. The order of the values should correspond to the order of the dit strings in the full spectrum.

  • dit_string_length (int) – The length of the dit strings.

  • dit_dimension (int) – The dimension of the dits, i.e., the number of possible values each dit can take.

  • opt_func_kwargs (dict, optional) – Keyword arguments passed to dual_annealing. The default is None.

Returns:

The index of the dit string that maximizes the sum of the marginals.

Return type:

int

troma.optimization.classical.simulated_annealing(marginals, dit_constraints, dit_string_length, dit_dimension=2, max_iter=1000, T0=1.0, alpha=0.99)

Use simulated annealing to find the value of the dit string that maximizes the sum of the marginals.

Parameters:

  • marginals (list of float) – The marginals of the function defined on the full spectrum of dit strings.

  • dit_constraints (list of tuples) – The list of dit constraints, where each constraint is represented as a tuple of the form ( indices, values), with ‘indices’ being a list of dit positions and ‘values’ being the corresponding dit values for the constraint.

  • dit_string_length (int) – The length of the dit strings.

  • dit_dimension (int) – The dimension of the dits, i.e., the number of possible values each dit can take.

  • max_iter (int, optional) – The maximum number of iterations for the simulated annealing algorithm. The default is 1000.

  • T0 (float, optional) – The initial temperature for the simulated annealing algorithm. The default is 1.0.

  • alpha (float, optional) – The cooling rate for the simulated annealing algorithm. The default is 0.99.

Returns:

The index of the dit string that maximizes the sum of the marginals.

Return type:

int

troma.optimization.classical.spin_chain_nn_max(marginals, dit_string_length, interaction_size=2, dit_dimension=2)

Find the value of the spin chain of length dit_string_length that maximizes the sum of the nearest-neighbor uplets marginals. Marginals can contained negative values. Spins are of dimension dit_dimension with value from 0 to dit_dimension-1.

Parameters:

  • marginals (list of float) – The marginals of the function defined on the full spectrum of dit strings. The order of the values should correspond to the order of the dit strings in the full spectrum.

  • dit_string_length (int) – The length of the dit string (i.e., the number of spins in the chain).

  • interaction_size (int, optional) – The size of the nearest neighbor pattern. The default is 2.

  • dit_dimension (int, optional) – The dimension of the dits (i.e., the number of possible values each dit can take ). The values of the dits should be from 0 to dit_dimension-1.

Returns:

The integer index of the optimal dit string configuration.

Return type:

int

troma.optimization.optimizer module

class troma.optimization.optimizer.FunctionOptimizer(name: str, function: Callable[[...], int], default_args: tuple[Any, ...] = (), default_kwargs: dict[str, Any] | None = None)

Bases: Optimizer

Adapter exposing a plain optimization function through the Optimizer interface.

optimize(*args: Any, **kwargs: Any) → int

Run the optimization and return the best configuration index.

with_defaults(*args: Any, **kwargs: Any) → FunctionOptimizer

Return a new optimizer with additional default arguments pre-bound.

class troma.optimization.optimizer.Optimizer

Bases: ABC

Common interface for all optimization backends.

abstractmethod optimize(*args: Any, **kwargs: Any) → int

Run the optimization and return the best configuration index.

troma.optimization.optimizer.bind_optimizer(name: str, *args: Any, **kwargs: Any) → Optimizer

Instantiate an optimizer with default arguments pre-bound.

Parameters:

  • name (str) – The name of the optimizer to retrieve. Available optimizers can be listed with list_optimizers().

  • *args (Any) – Positional arguments to pre-bind. Typical examples are (marginals,) for "brute_force_max" or "spin_chain_nn_max".

  • **kwargs (Any) –

    Keyword arguments matching the chosen backend. For example:

    • bind_optimizer("brute_force_max", marginals, sketch=sketch)

    • bind_optimizer("spin_chain_nn_max", marginals, dit_string_length=6, interaction_size=2, dit_dimension=2)

    • bind_optimizer("dual_annealing", marginals, dit_constraints=constraints, dit_string_length=6, dit_dimension=2)

    • bind_optimizer("qaoa", marginals, bit_constraints=constraints, bit_string_length=6, number_layers=3, number_shots=2048)

Returns:

An instance of the requested optimizer with the specified default arguments.

Return type:

Optimizer

troma.optimization.optimizer.get_optimizer(name: str) → Optimizer

Instantiate an optimizer adapter from a registered name.

Parameters:

name (str) – The name of the optimizer to retrieve. Available optimizers can be listed with list_optimizers(). optimizers()`.

Returns:

An instance of the requested optimizer.

Examples

  • get_optimizer("brute_force_max") returns an optimizer that can be used as

    optimizer.optimize(marginals, sketch=sketch).

  • get_optimizer("spin_chain_nn_max") returns an optimizer that can be used as

    optimizer.optimize(marginals, dit_string_length=6, interaction_size=2, dit_dimension=2).

  • get_optimizer("qaoa") returns an optimizer that can be used as

    optimizer.optimize(marginals, bit_constraints=constraints, bit_string_length=6, number_layers=3).

Return type:

Optimizer

troma.optimization.optimizer.list_optimizers() → list[str]

Return all registered optimizer names.

Parameters:

None

Returns:

A list of all registered optimizer names.

Return type:

list[str]

troma.optimization.optimizer.optimize(name: str, *args: Any, **kwargs: Any) → int

Convenience helper to optimize in one call.

Parameters:

  • name (str) – The name of the optimizer to retrieve. Available optimizers can be listed with list_optimizers().

  • *args (Any) – Positional arguments for the selected backend. In practice this is often (marginals,).

  • **kwargs (Any) –

    Keyword arguments for the selected backend. Common usable combinations are:

    • optimize("brute_force_max", marginals, sketch=sketch)

    • optimize("spin_chain_nn_max", marginals, dit_string_length=6, interaction_size=2, dit_dimension=2)

    • optimize("simulated_annealing", marginals, dit_constraints=constraints, dit_string_length=6, max_iter=500)

    • optimize("digital_annealing", marginals, number_iter=2000)

    • optimize("qaoa", marginals, bit_constraints=constraints, bit_string_length=6, number_layers=3, method="COBYLA")

Returns:

The result of the optimization.

Return type:

int

troma.optimization.quantum module

troma.optimization.quantum.QAOA(marginals, bit_constraints, bit_string_length, number_layers=4, method='COBYLA', backend=AerSimulator('aer_simulator'), number_shots=4096, random_seed=123)

Perform Quantum Approximate Optimization Algorithm (QAOA) to find a solution to the optimization problem defined by the marginals and constraints. The function assumes that the optimization problem can be mapped to a Hamiltonian defined on qubits, where the terms in the Hamiltonian correspond to the patterns in the constraints_sketch. Applicable on bit strings of any length, and can handle arbitrary patterns of constraints, including those that do not correspond to nearest neighbor interactions.

Parameters:

  • marginals (list of float) – The marginals corresponding to each pattern in constraints_sketch. The order of the values should correspond to the order of the patterns in constraints_sketch.

  • bit_constraints (list of patterns) – Each pattern can be either a list of local states (for full patterns) or a dict mapping qubit indices to fixed bit values (for constraints). The order of the patterns should correspond to the order of the marginals in the input.

  • bit_string_length (int) – The length of the bit strings (i.e., the number of qubits).

  • number_layers (int, optional) – The number of layers in the QAOA circuit. The default is 4.

  • method (str, optional) – The optimization method to use for finding the optimal parameters of the QAOA circuit. The default is “COBYLA”.

  • backend (qiskit provider, optional) – The quantum backend to use for running the QAOA circuit. The default is AerSimulator().

  • number_shots (int, optional) – The number of shots to use when running the QAOA circuit. The default is 4096.

  • random_seed (int, optional) – The random seed to use for reproducibility when running the QAOA circuit. The default is 123.

Returns:

The index of the bit string that maximizes the sum of the marginals, as found by the QAOA algorithm.

Return type:

int

troma.optimization.quantum.digital_annealing(marginals, number_iter=1000)

Perform digital annealing to find a solution to the optimization problem defined by the marginals. Only work for QUBO problems, i.e., when marginals are defined on nearest neighbor pairs of bits.

Parameters:

  • marginals (list of float) – The marginals of the function defined on the full spectrum of dit strings. The order of the values should correspond to the order of the dit strings in the full spectrum.

  • number_iter (int, optional) – The number of iterations for the digital annealing algorithm. The default is 1000.

Returns:

The index of the dit string that maximizes the sum of the marginals.

Return type:

int

Module contents

troma.optimization.QAOA(marginals, bit_constraints, bit_string_length, number_layers=4, method='COBYLA', backend=AerSimulator('aer_simulator'), number_shots=4096, random_seed=123)

Perform Quantum Approximate Optimization Algorithm (QAOA) to find a solution to the optimization problem defined by the marginals and constraints. The function assumes that the optimization problem can be mapped to a Hamiltonian defined on qubits, where the terms in the Hamiltonian correspond to the patterns in the constraints_sketch. Applicable on bit strings of any length, and can handle arbitrary patterns of constraints, including those that do not correspond to nearest neighbor interactions.

Parameters:

  • marginals (list of float) – The marginals corresponding to each pattern in constraints_sketch. The order of the values should correspond to the order of the patterns in constraints_sketch.

  • bit_constraints (list of patterns) – Each pattern can be either a list of local states (for full patterns) or a dict mapping qubit indices to fixed bit values (for constraints). The order of the patterns should correspond to the order of the marginals in the input.

  • bit_string_length (int) – The length of the bit strings (i.e., the number of qubits).

  • number_layers (int, optional) – The number of layers in the QAOA circuit. The default is 4.

  • method (str, optional) – The optimization method to use for finding the optimal parameters of the QAOA circuit. The default is “COBYLA”.

  • backend (qiskit provider, optional) – The quantum backend to use for running the QAOA circuit. The default is AerSimulator().

  • number_shots (int, optional) – The number of shots to use when running the QAOA circuit. The default is 4096.

  • random_seed (int, optional) – The random seed to use for reproducibility when running the QAOA circuit. The default is 123.

Returns:

The index of the bit string that maximizes the sum of the marginals, as found by the QAOA algorithm.

Return type:

int

troma.optimization.bind_optimizer(name: str, *args: Any, **kwargs: Any) → Optimizer

Instantiate an optimizer with default arguments pre-bound.

Parameters:

  • name (str) – The name of the optimizer to retrieve. Available optimizers can be listed with list_optimizers().

  • *args (Any) – Positional arguments to pre-bind. Typical examples are (marginals,) for "brute_force_max" or "spin_chain_nn_max".

  • **kwargs (Any) –

    Keyword arguments matching the chosen backend. For example:

    • bind_optimizer("brute_force_max", marginals, sketch=sketch)

    • bind_optimizer("spin_chain_nn_max", marginals, dit_string_length=6, interaction_size=2, dit_dimension=2)

    • bind_optimizer("dual_annealing", marginals, dit_constraints=constraints, dit_string_length=6, dit_dimension=2)

    • bind_optimizer("qaoa", marginals, bit_constraints=constraints, bit_string_length=6, number_layers=3, number_shots=2048)

Returns:

An instance of the requested optimizer with the specified default arguments.

Return type:

Optimizer

troma.optimization.brute_force_max(marginals, sketch)

Brute force method to find the value of the dit string that maximizes the sum of the marginals. This method is not efficient for large dit string lengths, but it can be used as a baseline for testing other optimization methods.

Parameters:

  • marginals (list of float) – The marginals of the function defined on the full spectrum of dit strings. The order of the values should correspond to the order of the dit strings in the full spectrum.

  • sketch (2D numpy array) – The sketch matrix, where each column corresponds to a dit string and each row corresponds to a marginal.

Returns:

The index of the dit string that maximizes the sum of the marginals.

Return type:

int

troma.optimization.digital_annealing(marginals, number_iter=1000)

Perform digital annealing to find a solution to the optimization problem defined by the marginals. Only work for QUBO problems, i.e., when marginals are defined on nearest neighbor pairs of bits.

Parameters:

  • marginals (list of float) – The marginals of the function defined on the full spectrum of dit strings. The order of the values should correspond to the order of the dit strings in the full spectrum.

  • number_iter (int, optional) – The number of iterations for the digital annealing algorithm. The default is 1000.

Returns:

The index of the dit string that maximizes the sum of the marginals.

Return type:

int

troma.optimization.dual_annealing(marginals, dit_constraints, dit_string_length, dit_dimension=2, opt_func_kwargs=None)

Use dual-annealing to find the value of the dit string that maximizes the sum of the marginals. This method is more efficient than brute force for large dit string lengths, but it may not always find the optimal solution.

Parameters:

  • marginals (list of float) – The marginals of the function defined on the full spectrum of dit strings. The order of the values should correspond to the order of the dit strings in the full spectrum.

  • dit_string_length (int) – The length of the dit strings.

  • dit_dimension (int) – The dimension of the dits, i.e., the number of possible values each dit can take.

  • opt_func_kwargs (dict, optional) – Keyword arguments passed to dual_annealing. The default is None.

Returns:

The index of the dit string that maximizes the sum of the marginals.

Return type:

int

troma.optimization.get_optimizer(name: str) → Optimizer

Instantiate an optimizer adapter from a registered name.

Parameters:

name (str) – The name of the optimizer to retrieve. Available optimizers can be listed with list_optimizers(). optimizers()`.

Returns:

An instance of the requested optimizer.

Examples

  • get_optimizer("brute_force_max") returns an optimizer that can be used as

    optimizer.optimize(marginals, sketch=sketch).

  • get_optimizer("spin_chain_nn_max") returns an optimizer that can be used as

    optimizer.optimize(marginals, dit_string_length=6, interaction_size=2, dit_dimension=2).

  • get_optimizer("qaoa") returns an optimizer that can be used as

    optimizer.optimize(marginals, bit_constraints=constraints, bit_string_length=6, number_layers=3).

Return type:

Optimizer

troma.optimization.list_optimizers() → list[str]

Return all registered optimizer names.

Parameters:

None

Returns:

A list of all registered optimizer names.

Return type:

list[str]

troma.optimization.optimize(name: str, *args: Any, **kwargs: Any) → int

Convenience helper to optimize in one call.

Parameters:

  • name (str) – The name of the optimizer to retrieve. Available optimizers can be listed with list_optimizers().

  • *args (Any) – Positional arguments for the selected backend. In practice this is often (marginals,).

  • **kwargs (Any) –

    Keyword arguments for the selected backend. Common usable combinations are:

    • optimize("brute_force_max", marginals, sketch=sketch)

    • optimize("spin_chain_nn_max", marginals, dit_string_length=6, interaction_size=2, dit_dimension=2)

    • optimize("simulated_annealing", marginals, dit_constraints=constraints, dit_string_length=6, max_iter=500)

    • optimize("digital_annealing", marginals, number_iter=2000)

    • optimize("qaoa", marginals, bit_constraints=constraints, bit_string_length=6, number_layers=3, method="COBYLA")

Returns:

The result of the optimization.

Return type:

int

troma.optimization.simulated_annealing(marginals, dit_constraints, dit_string_length, dit_dimension=2, max_iter=1000, T0=1.0, alpha=0.99)

Use simulated annealing to find the value of the dit string that maximizes the sum of the marginals.

Parameters:

  • marginals (list of float) – The marginals of the function defined on the full spectrum of dit strings.

  • dit_constraints (list of tuples) – The list of dit constraints, where each constraint is represented as a tuple of the form ( indices, values), with ‘indices’ being a list of dit positions and ‘values’ being the corresponding dit values for the constraint.

  • dit_string_length (int) – The length of the dit strings.

  • dit_dimension (int) – The dimension of the dits, i.e., the number of possible values each dit can take.

  • max_iter (int, optional) – The maximum number of iterations for the simulated annealing algorithm. The default is 1000.

  • T0 (float, optional) – The initial temperature for the simulated annealing algorithm. The default is 1.0.

  • alpha (float, optional) – The cooling rate for the simulated annealing algorithm. The default is 0.99.

Returns:

The index of the dit string that maximizes the sum of the marginals.

Return type:

int

troma.optimization.spin_chain_nn_max(marginals, dit_string_length, interaction_size=2, dit_dimension=2)

Find the value of the spin chain of length dit_string_length that maximizes the sum of the nearest-neighbor uplets marginals. Marginals can contained negative values. Spins are of dimension dit_dimension with value from 0 to dit_dimension-1.

Parameters:

  • marginals (list of float) – The marginals of the function defined on the full spectrum of dit strings. The order of the values should correspond to the order of the dit strings in the full spectrum.

  • dit_string_length (int) – The length of the dit string (i.e., the number of spins in the chain).

  • interaction_size (int, optional) – The size of the nearest neighbor pattern. The default is 2.

  • dit_dimension (int, optional) – The dimension of the dits (i.e., the number of possible values each dit can take ). The values of the dits should be from 0 to dit_dimension-1.

Returns:

The integer index of the optimal dit string configuration.

Return type:

int