troma package

Subpackages

• troma.decoding package
  • Submodules
  • troma.decoding.decoding_proced module
    • matchingpursuit_abstract()
    • matchingpursuit_explicit()
  • troma.decoding.matching_pursuit module
    • FunctionMatchingPursuit
      • FunctionMatchingPursuit.run()
      • FunctionMatchingPursuit.with_defaults()
    • MatchingPursuit
      • MatchingPursuit.run()
    • bind_matching_pursuit()
    • get_matching_pursuit()
    • list_matching_pursuits()
    • matching_pursuit()
    • run_matching_pursuit()
  • Module contents
    • bind_matching_pursuit()
    • get_matching_pursuit()
    • list_matching_pursuits()
    • matching_pursuit()
    • matchingpursuit_abstract()
    • matchingpursuit_explicit()
• troma.optimization package
  • Submodules
  • troma.optimization.classical module
    • brute_force_max()
    • dual_annealing()
    • simulated_annealing()
    • spin_chain_nn_max()
  • troma.optimization.optimizer module
    • FunctionOptimizer
      • FunctionOptimizer.optimize()
      • FunctionOptimizer.with_defaults()
    • Optimizer
      • Optimizer.optimize()
    • bind_optimizer()
    • get_optimizer()
    • list_optimizers()
    • optimize()
  • troma.optimization.quantum module
    • QAOA()
    • digital_annealing()
  • Module contents
    • QAOA()
    • bind_optimizer()
    • brute_force_max()
    • digital_annealing()
    • dual_annealing()
    • get_optimizer()
    • list_optimizers()
    • optimize()
    • simulated_annealing()
    • spin_chain_nn_max()
• troma.sketchs package
  • Submodules
  • troma.sketchs.abstract module
    • compute_marginal()
    • constraints_for_all_interactions()
    • constraints_for_nearest_neighbors_interactions()
    • reconstruct_structured_matrix_column()
  • troma.sketchs.explicit module
    • all_interactions_sketch()
    • compute_marginal()
    • nearest_neighbors_interactions_sketch()
    • random_sketch()
  • troma.sketchs.sketch module
    • sketch_base.py
    • ConstraintSketch
      • ConstraintSketch.build_all_interactions_sketch()
      • ConstraintSketch.build_nearest_neighbors_sketch()
      • ConstraintSketch.compute_marginal()
      • ConstraintSketch.compute_marginals()
      • ConstraintSketch.reconstruct_structured_matrix_column()
    • ExplicitSketch
      • ExplicitSketch.build_all_interactions_sketch()
      • ExplicitSketch.build_nearest_neighbors_sketch()
      • ExplicitSketch.compute_marginal()
      • ExplicitSketch.compute_marginals()
      • ExplicitSketch.random_sketch()
    • Sketch
      • Sketch.build_all_interactions_sketch()
      • Sketch.build_nearest_neighbors_sketch()
      • Sketch.compute_marginal()
  • Module contents
    • ConstraintSketch
      • ConstraintSketch.build_all_interactions_sketch()
      • ConstraintSketch.build_nearest_neighbors_sketch()
      • ConstraintSketch.compute_marginal()
      • ConstraintSketch.compute_marginals()
      • ConstraintSketch.reconstruct_structured_matrix_column()
    • ExplicitSketch
      • ExplicitSketch.build_all_interactions_sketch()
      • ExplicitSketch.build_nearest_neighbors_sketch()
      • ExplicitSketch.compute_marginal()
      • ExplicitSketch.compute_marginals()
      • ExplicitSketch.random_sketch()
    • Sketch
      • Sketch.build_all_interactions_sketch()
      • Sketch.build_nearest_neighbors_sketch()
      • Sketch.compute_marginal()
    • all_interactions_sketch()
    • constraint_compute_marginal()
    • constraints_for_all_interactions()
    • constraints_for_nearest_neighbors_interactions()
    • explicit_compute_marginal()
    • nearest_neighbors_interactions_sketch()
    • random_sketch()
    • reconstruct_structured_matrix_column()

Submodules

troma.data_structure module

troma.data_structure.belongs_to_cylinder_set(element, cylinder_set, dit_dimension=2)

Check if a element belongs to a given cylinder set.

Parameters:

• element (list or ndarray) – The element to check, given within its computational basis representation.

• cylinder_set (list) – The cylinder set represented by its factorized indicator.

Returns:

If the element belongs to the cylinder set or not.

Return type:

bool

troma.data_structure.create_cylinder_set_indicator(fixed_dit_positions, set_size, dit_dimension=2)

Create all facotirzed indicators of the cylinder sets defined by fixing the dit positions for each possible values.

Parameters:

• fixed_dit_positions (iterable of int) – Dits which define the cylinder sets.

• set_size (int) – The size of the set (number of dits).

• dit_dimension (int, optional) – Dimension of each dit. Default is 2 (binary).

Returns:

A list whose entries are the factorized indicators of the possible cylinder sets defined by fixing the dit positions to each possible values.

Return type:

list

Examples

>>> create_cylinder_set_indicator([0, 1], 3, 2)
[[[1, 0], [1, 0], [1, 1]],
 [[1, 0], [0, 1], [1, 1]],
 [[0, 1], [1, 0], [1, 1]],
 [[0, 1], [0, 1], [1, 1]]]

troma.data_structure.dit_string_to_computational_basis(dit_string, dit_dimension=2)

Decompose a dit_string into its computational basis representation.

Parameters:

• dit_string (iterable of int or str) – The dit_string to decompose.

• dit_dimension (int, optional) – Dit dimension. Default is 2 (binary).

Returns:

The computational basis representation of the input dit_string.

Return type:

list

troma.data_structure.dit_string_to_integer(dit_string, dit_dimension=2, convention='R')

Decode a dit_string back into an integer.

Parameters:

• dit_string (list or ndarray) – The dit_string to decode.

• dit_dimension (int, optional) – The dimension of the dits (e.g., 2 for binary, 3 for ternary). Default is 2.

• convention (str, optional) – The direction of the encoding. ‘R’ for right-aligned (default), ‘L’ for left-aligned.

Returns:

The decoded integer.

Return type:

int

troma.data_structure.integer_to_dit_string(integer, dit_string_length, dit_dimension=2, convention='R')

Encode an integer into a dit_string.

Parameters:

• integer (int) – The integer to encode.

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

• dit_dimension (int, optional) – The dimension of the dits (e.g., 2 for binary, 3 for ternary). Default is 2.

• convention (str, optional) – The direction of the encoding. ‘R’ for right-aligned (default), ‘L’ for left-aligned.

Returns:

The dit_string representation of the integer.

Return type:

ndarray

troma.data_structure.kronecker_develop(cylinder_set, dit_dimension=2, convention='R')

Developp a computational basis representation or a factorized cylinder set indicator using Kronecker product.

Parameters:

• cylinder_set (list) – A cylinder set factorized indicator, represented as a list of computational basis and identity vectors (lists or ndarrays).

• dit_dimension (int, optional) – The dimension of the dits (e.g., 2 for binary, 3 for ternary). Default is 2.

• convention (str, optional) – The direction of the encoding. ‘R’ for right-aligned (default), ‘L’ for left-aligned.

Returns:

The developed indicator of the cylinder set.

Return type:

ndarray

troma.mcco_workflow module

troma.mcco_workflow.solve_via_mcco(objective_function, number_samples, dit_string_length, interaction_size, iteration_number=5, step=None, thereshold_parameter='Auto', dit_dimension=2, optimizer=None, optimizer_name='spin_chain_nn_max')

Run the full MCCO pipeline : modeling + sketching + matching pursuit.

This helper orchestrates: 1) mcco_modeling to build a sparse problem representation, 2) constraint sketch construction and marginal computation, 3) abstract matching pursuit reconstruction.

Parameters:

• objective_function (Callable) – Function evaluated on dit strings.

• number_samples (int) – Number of sampled configurations used by MCCO.

• dit_string_length (int) – Number of dits/spins.

• interaction_size (int) – Local interaction size for nearest-neighbor constraints.

• iteration_number (int, optional) – Number of matching-pursuit iterations.

• step (float or None, optional) – Matching-pursuit step size. If None, adaptive step is used.

• thereshold_parameter (float, str or None, optional) – Threshold applied in mcco_modeling ("Auto" uses 90th percentile).

• dit_dimension (int, optional) – Dit alphabet size.

• optimizer (Optimizer or None, optional) – Instantiated optimizer object. If None, optimizer_name is used.

• optimizer_name (str or None, optional) – Name passed to get_optimizer when optimizer is not provided.

Returns:

Pipeline outputs with keys: spectrum_pos, spectrum_val, spectrum_bin, constraints, y, solution.

Return type:

dict

troma.modeling module

troma.modeling.mcco_modeling(objective_function, number_samples, dit_string_length, thereshold_parameter=None, dit_dimension=2)

Create a MCCO model of the objective function seen as a blackbox. The model is created by sampling the objective function on a random subset of the search space, and then applying a threshold to the sampled values. The model defined an unconstrained optimization problem, which can be solved by a matching pursuit decoder.

Parameters:

• objective_function (Callable) – Function evaluated on dit strings.

• number_samples (int) – Number of configurations sampled.

• dit_string_length (int) – Length of the dit strings.

• thereshold_parameter (float or str, optional) – Threshold applied to the sampled values. If “Auto”, the threshold is set to the 90th percentile of the sampled values.

• dit_dimension (int, optional) – Dimension of the dits. Default is 2.

Returns:

sample_indexeslist of int

List of the indexes of the sampled configurations.

sample_valueslist of float

List of the values of the objective function on the sampled configurations.

sample_dit_stringslist of list of int

List of the sampled configurations as dit strings.

Return type:

tuple

Module contents

class troma.ConstraintSketch

Bases: Sketch

Sketch backed by dit constraints (implicit / abstract representation).

The sketch is a list of dict {dit_index: dit_value}. The function is provided as a sparse (input_dits, values) pair — no need to enumerate every possible dit string.

See abstract for the underlying implementation.

static build_all_interactions_sketch(dit_string_length: int, interaction_size: int, dit_dimension: int = 2) → list[dict]

Return a list of all-interaction constraint dicts.

static build_nearest_neighbors_sketch(dit_string_length: int, interaction_size: int, dit_dimension: int = 2) → list[dict]

Return a list of nearest-neighbor constraint dicts.

static compute_marginal(function_data: tuple, sketch: list[dict]) → float | list[float]

Compute marginals from sparse function data and constraint sketch.

Parameters:

• function_data – (function_input_dits, function_values) — sparse representation of the function.

• sketch – List of constraint dicts as returned by build_nearest_neighbors_sketch() or build_all_interactions_sketch().

static compute_marginals(*args) → float | list[float]

static reconstruct_structured_matrix_column(index: int, dit_constraints: list[dict], dit_string_length: int, dit_dimension: int = 2) → ndarray

class troma.ExplicitSketch

Bases: Sketch

Sketch backed by an explicit matrix stored in memory.

The sketch is a np.ndarray whose rows correspond to indicator vectors for each cylinder set. The function must be given as a dense array of values over the full dit-string spectrum.

See explicit for the underlying implementation.

static build_all_interactions_sketch(dit_string_length: int, interaction_size: int, dit_dimension: int = 2) → ndarray

Return the all-interactions sketch matrix.

static build_nearest_neighbors_sketch(dit_string_length: int, interaction_size: int, dit_dimension: int = 2) → ndarray

Return the nearest-neighbor sketch matrix.

static compute_marginal(function_data: list | ndarray, sketch: matrix) → ndarray

Compute marginals from a full-spectrum array and an explicit sketch.

Parameters:

• function_data – 1-D array/list of floats, one value per dit string in lexicographic order (full spectrum, length = dit_dimension ** dit_string_length).

• sketch – Explicit sketch matrix as returned by build_nearest_neighbors_sketch() or build_all_interactions_sketch().

static compute_marginals(function_data: list | ndarray, sketch: ndarray) → ndarray

static random_sketch(dit_string_length: int, m: int, dit_dimension: int = 2, random_state=None) → ndarray

troma.belongs_to_cylinder_set(element, cylinder_set, dit_dimension=2)

Check if a element belongs to a given cylinder set.

Parameters:

• element (list or ndarray) – The element to check, given within its computational basis representation.

• cylinder_set (list) – The cylinder set represented by its factorized indicator.

Returns:

If the element belongs to the cylinder set or not.

Return type:

bool

troma.bind_matching_pursuit(name: str, *args: Any, **kwargs: Any) → MatchingPursuit

Instantiate a matching-pursuit adapter with default arguments pre-bound.

Parameters:

• name (str) – The name of the matching-pursuit backend to retrieve. Available backends can be listed with list_matching_pursuits().

• *args (Any) – Positional arguments to pre-bind. Typical examples are (marginals,).

• **kwargs (Any) –

  Keyword arguments matching the chosen backend. For example:

  • bind_matching_pursuit("explicit", marginals, sketch=sketch, iteration_number=10)

  • bind_matching_pursuit("explicit", marginals, sketch=sketch, iteration_number=10, step=0.2, optimizer=get_optimizer("brute_force_max"))

  • bind_matching_pursuit("abstract", marginals, dit_constraints=constraints, dit_string_length=6, iteration_number=10)

  • bind_matching_pursuit("abstract", marginals, dit_constraints=constraints, dit_string_length=6, iteration_number=10, interaction_size=2, dit_dimension=2)

Returns:

An instance of the requested matching-pursuit adapter with the specified default arguments.

Return type:

MatchingPursuit

troma.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.create_cylinder_set_indicator(fixed_dit_positions, set_size, dit_dimension=2)

Create all facotirzed indicators of the cylinder sets defined by fixing the dit positions for each possible values.

Parameters:

• fixed_dit_positions (iterable of int) – Dits which define the cylinder sets.

• set_size (int) – The size of the set (number of dits).

• dit_dimension (int, optional) – Dimension of each dit. Default is 2 (binary).

Returns:

A list whose entries are the factorized indicators of the possible cylinder sets defined by fixing the dit positions to each possible values.

Return type:

list

Examples

>>> create_cylinder_set_indicator([0, 1], 3, 2)
[[[1, 0], [1, 0], [1, 1]],
 [[1, 0], [0, 1], [1, 1]],
 [[0, 1], [1, 0], [1, 1]],
 [[0, 1], [0, 1], [1, 1]]]

troma.dit_string_to_computational_basis(dit_string, dit_dimension=2)

Decompose a dit_string into its computational basis representation.

Parameters:

• dit_string (iterable of int or str) – The dit_string to decompose.

• dit_dimension (int, optional) – Dit dimension. Default is 2 (binary).

Returns:

The computational basis representation of the input dit_string.

Return type:

list

troma.dit_string_to_integer(dit_string, dit_dimension=2, convention='R')

Decode a dit_string back into an integer.

Parameters:

• dit_string (list or ndarray) – The dit_string to decode.

• dit_dimension (int, optional) – The dimension of the dits (e.g., 2 for binary, 3 for ternary). Default is 2.

• convention (str, optional) – The direction of the encoding. ‘R’ for right-aligned (default), ‘L’ for left-aligned.

Returns:

The decoded integer.

Return type:

int

troma.get_matching_pursuit(name: str) → MatchingPursuit

Instantiate a matching-pursuit adapter from a registered backend name.

Parameters:

name (str) – The name of the matching-pursuit backend to retrieve. Available backends can be listed with list_matching_pursuits().

Returns:

An instance of the requested matching-pursuit adapter.

Examples

• get_matching_pursuit("explicit") returns an adapter usable as

  mp.run(marginals, sketch=sketch, iteration_number=10, step=0.2).

• get_matching_pursuit("abstract") returns an adapter usable as

  mp.run(marginals, dit_constraints=constraints, dit_string_length=6, iteration_number=10, interaction_size=2).

Return type:

MatchingPursuit

troma.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.integer_to_dit_string(integer, dit_string_length, dit_dimension=2, convention='R')

Encode an integer into a dit_string.

Parameters:

• integer (int) – The integer to encode.

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

• dit_dimension (int, optional) – The dimension of the dits (e.g., 2 for binary, 3 for ternary). Default is 2.

• convention (str, optional) – The direction of the encoding. ‘R’ for right-aligned (default), ‘L’ for left-aligned.

Returns:

The dit_string representation of the integer.

Return type:

ndarray

troma.kronecker_develop(cylinder_set, dit_dimension=2, convention='R')

Developp a computational basis representation or a factorized cylinder set indicator using Kronecker product.

Parameters:

• cylinder_set (list) – A cylinder set factorized indicator, represented as a list of computational basis and identity vectors (lists or ndarrays).

• dit_dimension (int, optional) – The dimension of the dits (e.g., 2 for binary, 3 for ternary). Default is 2.

• convention (str, optional) – The direction of the encoding. ‘R’ for right-aligned (default), ‘L’ for left-aligned.

Returns:

The developed indicator of the cylinder set.

Return type:

ndarray

troma.matching_pursuit(name: str, *args: Any, **kwargs: Any) → Any

Alias of run_matching_pursuit().

Parameters:

• name (str) – The name of the matching-pursuit backend to retrieve. Available backends can be listed with list_matching_pursuits().

• *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:

  • matching_pursuit("explicit", marginals, sketch=sketch, iteration_number=10)

  • matching_pursuit("explicit", marginals, sketch=sketch, iteration_number=10, step=0.2)

  • matching_pursuit("abstract", marginals, dit_constraints=constraints, dit_string_length=6, iteration_number=10)

  • matching_pursuit("abstract", marginals, dit_constraints=constraints, dit_string_length=6, iteration_number=10, interaction_size=2, dit_dimension=2)

Returns:

The result of the matching-pursuit function.

Return type:

Any

troma.mcco_modeling(objective_function, number_samples, dit_string_length, thereshold_parameter=None, dit_dimension=2)

Create a MCCO model of the objective function seen as a blackbox. The model is created by sampling the objective function on a random subset of the search space, and then applying a threshold to the sampled values. The model defined an unconstrained optimization problem, which can be solved by a matching pursuit decoder.

Parameters:

• objective_function (Callable) – Function evaluated on dit strings.

• number_samples (int) – Number of configurations sampled.

• dit_string_length (int) – Length of the dit strings.

• thereshold_parameter (float or str, optional) – Threshold applied to the sampled values. If “Auto”, the threshold is set to the 90th percentile of the sampled values.

• dit_dimension (int, optional) – Dimension of the dits. Default is 2.

Returns:

sample_indexeslist of int

List of the indexes of the sampled configurations.

sample_valueslist of float

List of the values of the objective function on the sampled configurations.

sample_dit_stringslist of list of int

List of the sampled configurations as dit strings.

Return type:

tuple

troma.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.solve_via_mcco(objective_function, number_samples, dit_string_length, interaction_size, iteration_number=5, step=None, thereshold_parameter='Auto', dit_dimension=2, optimizer=None, optimizer_name='spin_chain_nn_max')

Run the full MCCO pipeline : modeling + sketching + matching pursuit.

This helper orchestrates: 1) mcco_modeling to build a sparse problem representation, 2) constraint sketch construction and marginal computation, 3) abstract matching pursuit reconstruction.

Parameters:

• objective_function (Callable) – Function evaluated on dit strings.

• number_samples (int) – Number of sampled configurations used by MCCO.

• dit_string_length (int) – Number of dits/spins.

• interaction_size (int) – Local interaction size for nearest-neighbor constraints.

• iteration_number (int, optional) – Number of matching-pursuit iterations.

• step (float or None, optional) – Matching-pursuit step size. If None, adaptive step is used.

• thereshold_parameter (float, str or None, optional) – Threshold applied in mcco_modeling ("Auto" uses 90th percentile).

• dit_dimension (int, optional) – Dit alphabet size.

• optimizer (Optimizer or None, optional) – Instantiated optimizer object. If None, optimizer_name is used.

• optimizer_name (str or None, optional) – Name passed to get_optimizer when optimizer is not provided.

Returns:

Pipeline outputs with keys: spectrum_pos, spectrum_val, spectrum_bin, constraints, y, solution.

Return type:

dict