troma.decoding package

Submodules

troma.decoding.decoding_proced module

troma.decoding.decoding_proced.matchingpursuit_abstract(marginals, dit_constraints, dit_string_length, iteration_number, step=None, interaction_size=2, dit_dimension=2, optimizer=None)

Perform matching pursuit to find a sparse solution to the linear system defined by the sketch matrix and the marginals, using an abstract representation of the sketch matrix based on nearest neighbors interactions.

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_constraints (list of tuples) – The constraints on the dit strings, where each tuple represents a constraint on a subset of dits.

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

• iteration_number (int) – The number of iterations to perform in the matching pursuit algorithm.

• step (float, optional) – The step size for the matching pursuit algorithm. If None, an adaptive step size is used based on the projection of the residual onto the selected column of the sketch matrix. The default is None.

• interaction_size (int, optional) – The size of the interactions between the dits. The default is 2, which corresponds to nearest neighbors interactions.

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

• optimizer (Optimizer, optional) – Instantiated optimizer implementing an optimize method. If None, a default spin-chain nearest-neighbor optimizer is instantiated. The matching pursuit context (constraints, dimensions) is provided automatically.

Returns:

A 2D numpy array where each row contains the index of a selected column from the sketch matrix and its corresponding coefficient in the sparse solution.

Return type:

numpy array

troma.decoding.decoding_proced.matchingpursuit_explicit(marginals, sketch, iteration_number, step=None, optimizer=None)

Perform matching pursuit to find a sparse solution to the linear system defined by the sketch matrix and the marginals.

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.

• iteration_number (int) – The number of iterations to perform in the matching pursuit algorithm.

• step (float, optional) – The step size for the matching pursuit algorithm. If None, an adaptive step size is used based on the projection of the residual onto the selected column of the sketch matrix. The default is None

• optimizer (Optimizer, optional) – Instantiated optimizer implementing an optimize method. If None, a default brute-force optimizer is instantiated. The matching pursuit context (e.g. sketch) is provided automatically.

Returns:

A 2D numpy array where each row contains the index of a selected column from the sketch matrix and its corresponding coefficient in the sparse solution.

Return type:

numpy array

troma.decoding.matching_pursuit module

class troma.decoding.matching_pursuit.FunctionMatchingPursuit(name: str, function: Callable[[...], Any], default_args: tuple[Any, ...] = (), default_kwargs: dict[str, Any] | None = None)

Bases: MatchingPursuit

Adapter exposing a plain matching-pursuit function through a common interface.

run(*args: Any, **kwargs: Any) → Any

Run matching pursuit and return the sparse reconstruction.

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

Return a new matching-pursuit adapter with additional default arguments pre-bound.

class troma.decoding.matching_pursuit.MatchingPursuit

Bases: ABC

Common interface for all matching-pursuit backends.

abstractmethod run(*args: Any, **kwargs: Any) → Any

Run matching pursuit and return the sparse reconstruction.

troma.decoding.matching_pursuit.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.decoding.matching_pursuit.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.decoding.matching_pursuit.list_matching_pursuits() → list[str]

Return all registered matching-pursuit backend names.

Parameters:

None

Returns:

A list of all registered matching-pursuit backend names.

Return type:

list[str]

troma.decoding.matching_pursuit.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.decoding.matching_pursuit.run_matching_pursuit(name: str, *args: Any, **kwargs: Any) → Any

Convenience helper to run matching pursuit in one call.

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 pass to the matching-pursuit function.

• **kwargs (Any) – Keyword arguments to pass to the matching-pursuit function.

Returns:

The result of the matching-pursuit function.

Return type:

Any

Module contents

troma.decoding.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.decoding.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.decoding.list_matching_pursuits() → list[str]

Return all registered matching-pursuit backend names.

Parameters:

None

Returns:

A list of all registered matching-pursuit backend names.

Return type:

list[str]

troma.decoding.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.decoding.matchingpursuit_abstract(marginals, dit_constraints, dit_string_length, iteration_number, step=None, interaction_size=2, dit_dimension=2, optimizer=None)

Perform matching pursuit to find a sparse solution to the linear system defined by the sketch matrix and the marginals, using an abstract representation of the sketch matrix based on nearest neighbors interactions.

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_constraints (list of tuples) – The constraints on the dit strings, where each tuple represents a constraint on a subset of dits.

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

• iteration_number (int) – The number of iterations to perform in the matching pursuit algorithm.

• step (float, optional) – The step size for the matching pursuit algorithm. If None, an adaptive step size is used based on the projection of the residual onto the selected column of the sketch matrix. The default is None.

• interaction_size (int, optional) – The size of the interactions between the dits. The default is 2, which corresponds to nearest neighbors interactions.

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

• optimizer (Optimizer, optional) – Instantiated optimizer implementing an optimize method. If None, a default spin-chain nearest-neighbor optimizer is instantiated. The matching pursuit context (constraints, dimensions) is provided automatically.

Returns:

A 2D numpy array where each row contains the index of a selected column from the sketch matrix and its corresponding coefficient in the sparse solution.

Return type:

numpy array

troma.decoding.matchingpursuit_explicit(marginals, sketch, iteration_number, step=None, optimizer=None)

Perform matching pursuit to find a sparse solution to the linear system defined by the sketch matrix and the marginals.

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.

• iteration_number (int) – The number of iterations to perform in the matching pursuit algorithm.

• step (float, optional) – The step size for the matching pursuit algorithm. If None, an adaptive step size is used based on the projection of the residual onto the selected column of the sketch matrix. The default is None

• optimizer (Optimizer, optional) – Instantiated optimizer implementing an optimize method. If None, a default brute-force optimizer is instantiated. The matching pursuit context (e.g. sketch) is provided automatically.

Returns:

A 2D numpy array where each row contains the index of a selected column from the sketch matrix and its corresponding coefficient in the sparse solution.

Return type:

numpy array