troma.sketchs package

Submodules

troma.sketchs.abstract module

troma.sketchs.abstract.compute_marginal(function_input_dits, function_values, dit_constraints)

Compute marginals of a sparse spectrum on one or several dit constraints.

Supported constraint formats

• single dict: {dit_index: dit_value, ...} -> returns float

• single full dit assignment: [0, 1, 2, ...] -> returns float

• list of constraints (dicts or full dit assignments) -> returns list[float]

param function_input_dits:

List of function inputs, each input is given in dits representation.

type function_input_dits:

list or ndarray

param function_values:

Image of the function associated with each input.

type function_values:

list or ndarray

param dit_constraints:

One constraint or several constraints.

type dit_constraints:

dict | sequence | list[dict | sequence]

returns:

Sum(s) of values for states matching each provided constraint.

rtype:

float or list of float

troma.sketchs.abstract.constraints_for_all_interactions(dit_string_length, interaction_size, dit_dimension=2)

Compute constraints for all interactions and bit values, for a given interaction size.

Parameters:

• dit_string_length (int) – The length of the dit string (number of dits in the string).

• interaction_size (int) – The size of the interaction (number of neighbors to consider).

• dit_dimension (int, optional) – The dimension of the dits (number of possible values for each dit), by default 2.

Returns:

List of all dit constraints corresponding to each interaction and bit value combination.

Return type:

list

troma.sketchs.abstract.constraints_for_nearest_neighbors_interactions(dit_string_length, interaction_size, dit_dimension=2)

Compute constraints for nearest neighbor interactions and bit values, for a given interaction size.

Parameters:

• dit_string_length (int) – The length of the dit string (number of dits in the string).

• interaction_size (int) – The size of the interaction (number of nearest neighbors to consider).

• dit_dimension (int, optional) – The dimension of the dits (number of possible values for each dit), by default 2.

Returns:

List of all dit constraints corresponding to each nearest neighbor interaction and bit value combination.

Return type:

list

troma.sketchs.abstract.reconstruct_structured_matrix_column(index, dit_constraints, dit_string_length, dit_dimension=2)

Reconstruct a column of a structured matrix made of cylinder set indicators defined by the dit constraints, and given the element index.

Parameters:

• index (int) – The index of the element to check.

• dit_constraints (list of dict) – List of dit constraints given as dictionaries to check.

Returns:

The column of the structured matrix corresponding to this index, i.e. a list indicating whether the element satisfies each dit constraint or not.

Return type:

numpy array of bool

troma.sketchs.explicit module

troma.sketchs.explicit.all_interactions_sketch(dit_string_length, interaction_size, dit_dimension=2)

Generate the sketch matrix corresponding to all interactions for a given dit string length, interaction size, and dit dimension.

Parameters:

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

• interaction_size (int) – The size of the interactions (i.e., the number of neighboring dits involved in each interaction).

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

Returns:

The sketch matrix corresponding to all interactions.

Return type:

np.ndarray

troma.sketchs.explicit.compute_marginal(full_sprectrum_values, sketch_function)

Compute the marginal of a function defined on the full spectrum of dit strings, given a sketch function that maps each dit string to a value.

Parameters:

• full_sprectrum_values (list of float) – The values 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_function (function) – A function that takes a dit string (as a list of integers) as input and returns a float value. This function is used to compute the marginal.

Returns:

The computed marginal value.

Return type:

float

troma.sketchs.explicit.nearest_neighbors_interactions_sketch(dit_string_length, interaction_size, dit_dimension=2)

Generate the sketch matrix corresponding to nearest neighbors interactions for a given dit string length, interaction size, and dit dimension.

Parameters:

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

• interaction_size (int) – The size of the interactions (i.e., the number of neighboring dits involved in each interaction).

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

Returns:

The sketch matrix corresponding to nearest neighbors interactions.

Return type:

np.ndarray

troma.sketchs.explicit.random_sketch(dit_string_length, m, dit_dimension=2, random_state=None)

Generate a random Gaussian sketch matrix typical of compressive sensing.

Parameters:

• dit_string_length (int) – Length of dit strings.

• m (int) – Number of sketch rows (measurements).

• dit_dimension (int, optional) – Dimension of each dit, by default 2.

• random_state (int | np.random.Generator | None, optional) – Seed or numpy Generator for reproducibility. If None, use NumPy default RNG.

Returns:

Random matrix of shape (m, dit_dimension ** dit_string_length) with i.i.d. entries sampled from N(0, 1/m).

Return type:

np.ndarray

troma.sketchs.sketch module

sketch_base.py

Common interface grouping the two sketch representations:

• ConstraintSketch — matrix described implicitly via dit constraints (memory-efficient, no need to materialise the full matrix).

• ExplicitSketch — matrix stored explicitly in memory (fast repeated computation once the matrix has been built).

Both classes expose the same three static methods so they can be used interchangeably:

from sketch_base import ConstraintSketch, ExplicitSketch

# Build the sketch once
sketch = ConstraintSketch.build_nearest_neighbors_sketch(n, k)
# Or
sketch = ExplicitSketch.build_nearest_neighbors_sketch(n, k)

# Then compute marginals with the matching class
result = ConstraintSketch.compute_marginal((input_dits, values), sketch)
result = ExplicitSketch.compute_marginal(full_spectrum_values, sketch)

class troma.sketchs.sketch.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.sketchs.sketch.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

class troma.sketchs.sketch.Sketch

Bases: ABC

Abstract interface for sketch-based marginal computation.

A sketch is a compact representation of the structured matrix used to compute marginals of a function defined on the full dit-string spectrum. Concrete subclasses differ in how that matrix is stored / described:

• ConstraintSketch — implicit description via dit constraints.

• ExplicitSketch — explicit np.ndarray stored in memory.

All three methods are static so that the class itself acts as a strategy/namespace: no instance state is needed.

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

Build the sketch structure for all (non-consecutive) interactions.

Parameters:

• dit_string_length – Number of dits in each string.

• interaction_size – Number of dits per interaction (all combinations considered).

• dit_dimension – Number of possible values per dit (default: 2 for bits).

Return type:

Sketch object (see build_nearest_neighbors_sketch()).

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

Build the sketch structure for nearest-neighbor interactions.

Parameters:

• dit_string_length – Number of dits in each string.

• interaction_size – Number of consecutive dits per interaction window.

• dit_dimension – Number of possible values per dit (default: 2 for bits).

Returns:

• Sketch object whose type depends on the concrete implementation

• (list of dict for ConstraintSketch,

• np.ndarray for ExplicitSketch).

abstractmethod static compute_marginal(function_data, sketch)

Compute marginals given function data and a sketch structure.

Parameters:

• function_data –

  • For ConstraintSketch: a (function_input_dits, function_values) tuple where function_input_dits is a list of dit strings and function_values is the corresponding list of values.

  • For ExplicitSketch: a flat list/array of floats holding the function value for every dit string in lexicographic order (full spectrum).

• sketch – The sketch object returned by one of the build_* methods.

Returns:

• float, list[float], or np.ndarray depending on the

• concrete implementation and the number of constraints / rows.

Module contents

class troma.sketchs.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.sketchs.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

class troma.sketchs.Sketch

Bases: ABC

Abstract interface for sketch-based marginal computation.

A sketch is a compact representation of the structured matrix used to compute marginals of a function defined on the full dit-string spectrum. Concrete subclasses differ in how that matrix is stored / described:

• ConstraintSketch — implicit description via dit constraints.

• ExplicitSketch — explicit np.ndarray stored in memory.

All three methods are static so that the class itself acts as a strategy/namespace: no instance state is needed.

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

Build the sketch structure for all (non-consecutive) interactions.

Parameters:

• dit_string_length – Number of dits in each string.

• interaction_size – Number of dits per interaction (all combinations considered).

• dit_dimension – Number of possible values per dit (default: 2 for bits).

Return type:

Sketch object (see build_nearest_neighbors_sketch()).

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

Build the sketch structure for nearest-neighbor interactions.

Parameters:

• dit_string_length – Number of dits in each string.

• interaction_size – Number of consecutive dits per interaction window.

• dit_dimension – Number of possible values per dit (default: 2 for bits).

Returns:

• Sketch object whose type depends on the concrete implementation

• (list of dict for ConstraintSketch,

• np.ndarray for ExplicitSketch).

abstractmethod static compute_marginal(function_data, sketch)

Compute marginals given function data and a sketch structure.

Parameters:

• function_data –

  • For ConstraintSketch: a (function_input_dits, function_values) tuple where function_input_dits is a list of dit strings and function_values is the corresponding list of values.

  • For ExplicitSketch: a flat list/array of floats holding the function value for every dit string in lexicographic order (full spectrum).

• sketch – The sketch object returned by one of the build_* methods.

Returns:

• float, list[float], or np.ndarray depending on the

• concrete implementation and the number of constraints / rows.

troma.sketchs.all_interactions_sketch(dit_string_length, interaction_size, dit_dimension=2)

Generate the sketch matrix corresponding to all interactions for a given dit string length, interaction size, and dit dimension.

Parameters:

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

• interaction_size (int) – The size of the interactions (i.e., the number of neighboring dits involved in each interaction).

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

Returns:

The sketch matrix corresponding to all interactions.

Return type:

np.ndarray

troma.sketchs.constraint_compute_marginal(function_input_dits, function_values, dit_constraints)

Compute marginals of a sparse spectrum on one or several dit constraints.

Supported constraint formats

• single dict: {dit_index: dit_value, ...} -> returns float

• single full dit assignment: [0, 1, 2, ...] -> returns float

• list of constraints (dicts or full dit assignments) -> returns list[float]

param function_input_dits:

List of function inputs, each input is given in dits representation.

type function_input_dits:

list or ndarray

param function_values:

Image of the function associated with each input.

type function_values:

list or ndarray

param dit_constraints:

One constraint or several constraints.

type dit_constraints:

dict | sequence | list[dict | sequence]

returns:

Sum(s) of values for states matching each provided constraint.

rtype:

float or list of float

troma.sketchs.constraints_for_all_interactions(dit_string_length, interaction_size, dit_dimension=2)

Compute constraints for all interactions and bit values, for a given interaction size.

Parameters:

• dit_string_length (int) – The length of the dit string (number of dits in the string).

• interaction_size (int) – The size of the interaction (number of neighbors to consider).

• dit_dimension (int, optional) – The dimension of the dits (number of possible values for each dit), by default 2.

Returns:

List of all dit constraints corresponding to each interaction and bit value combination.

Return type:

list

troma.sketchs.constraints_for_nearest_neighbors_interactions(dit_string_length, interaction_size, dit_dimension=2)

Compute constraints for nearest neighbor interactions and bit values, for a given interaction size.

Parameters:

• dit_string_length (int) – The length of the dit string (number of dits in the string).

• interaction_size (int) – The size of the interaction (number of nearest neighbors to consider).

• dit_dimension (int, optional) – The dimension of the dits (number of possible values for each dit), by default 2.

Returns:

List of all dit constraints corresponding to each nearest neighbor interaction and bit value combination.

Return type:

list

troma.sketchs.explicit_compute_marginal(full_sprectrum_values, sketch_function)

Compute the marginal of a function defined on the full spectrum of dit strings, given a sketch function that maps each dit string to a value.

Parameters:

• full_sprectrum_values (list of float) – The values 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_function (function) – A function that takes a dit string (as a list of integers) as input and returns a float value. This function is used to compute the marginal.

Returns:

The computed marginal value.

Return type:

float

troma.sketchs.nearest_neighbors_interactions_sketch(dit_string_length, interaction_size, dit_dimension=2)

Generate the sketch matrix corresponding to nearest neighbors interactions for a given dit string length, interaction size, and dit dimension.

Parameters:

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

• interaction_size (int) – The size of the interactions (i.e., the number of neighboring dits involved in each interaction).

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

Returns:

The sketch matrix corresponding to nearest neighbors interactions.

Return type:

np.ndarray

troma.sketchs.random_sketch(dit_string_length, m, dit_dimension=2, random_state=None)

Generate a random Gaussian sketch matrix typical of compressive sensing.

Parameters:

• dit_string_length (int) – Length of dit strings.

• m (int) – Number of sketch rows (measurements).

• dit_dimension (int, optional) – Dimension of each dit, by default 2.

• random_state (int | np.random.Generator | None, optional) – Seed or numpy Generator for reproducibility. If None, use NumPy default RNG.

Returns:

Random matrix of shape (m, dit_dimension ** dit_string_length) with i.i.d. entries sampled from N(0, 1/m).

Return type:

np.ndarray

troma.sketchs.reconstruct_structured_matrix_column(index, dit_constraints, dit_string_length, dit_dimension=2)

Reconstruct a column of a structured matrix made of cylinder set indicators defined by the dit constraints, and given the element index.

Parameters:

• index (int) – The index of the element to check.

• dit_constraints (list of dict) – List of dit constraints given as dictionaries to check.

Returns:

The column of the structured matrix corresponding to this index, i.e. a list indicating whether the element satisfies each dit constraint or not.

Return type:

numpy array of bool