qoolqit.embedding.algorithms.blade.blade

module

qoolqit.embedding.algorithms.blade.blade

Classes

• BladeConfig — Configuration parameters to embed with BLaDE.

Functions

• update_positions — Compute vector moves to adjust node positions toward target interactions.

• evolve_with_forces_through_dim_change

• generate_random_positions

• augment_dimensions_with_random_values

• evolve_with_dimension_transition

• blade — Embed an interaction matrix or QUBO with the BLaDE algorithm.

update_positions (*, positions: np.ndarray, target_interactions: np.ndarray, weight_relative_threshold: float = 0.0, min_dist: float | None = None, max_dist: float | None = None, max_distance_to_walk: float | tuple[float, float, float] = np.inf, draw_step: bool = False) → np.ndarray

Compute vector moves to adjust node positions toward target interactions.

positions: Starting positions of the nodes. target_interactions: Desired interactions. weight_relative_threshold: It is used to compute a weight difference threshold defining which weights differences are significant and should be considered. For this purpose, it is multiplied by the higher weight difference. It is also used to reduce the precision when targeting the objective weights. min_dist: If set, defined the minimum distance that should be met, and creates forces to enforce the constraint. max_dist: If set, defined the maximum distance that should be met, and creates forces to enforce the constraint. max_distance_to_walk: It set, limits the distance that nodes can walk when the forces are applied. It impacts the priorities of the forces because they only consider the slope of the differences in weights that can be targeting with this ceiling. draw_steps: Whether to draw the nodes and the forces.

evolve_with_forces_through_dim_change (*, target_interactions: np.ndarray, draw_steps: bool = False, starting_dimensions: int, final_dimensions: int, nb_steps: int, positions: np.ndarray, starting_min: float | None = None, start_ratio: float | None = None, final_ratio: float | None = None, compute_weight_relative_threshold_by_step: Callable[[int], float], compute_max_distance_to_walk_by_step: Callable[[int, float | None], float | tuple[float, float, float]]) → tuple[np.ndarray, float | None]

generate_random_positions (target_interactions: np.ndarray, dimension: int) → np.ndarray

augment_dimensions_with_random_values (positions: np.ndarray, *, new_dimensions: int) → np.ndarray

evolve_with_dimension_transition (*, dimensions: tuple[int, ...], starting_min: float | None, pca: bool, steps_per_round: int, compute_weight_relative_threshold: Callable[[float], float], compute_max_distance_to_walk: Callable[[float, float | None], float | tuple[float, float, float]], target_interactions: np.ndarray, positions: np.ndarray, final_ratio: float | None, total_steps: int, dim_idx: int, start_ratio: float | None, draw_steps: bool | list[int]) → tuple[np.ndarray, float | None]

Raises

• ModuleNotFoundError

blade (matrix: np.ndarray, *, max_min_dist_ratio: float | None = None, dimensions: tuple[int, ...] = (5, 4, 3, 2, 2, 2), starting_positions: np.ndarray | None = None, pca: bool = False, steps_per_round: int = 200, compute_weight_relative_threshold: Callable[[float], float] = lambda _: 0.1, compute_max_distance_to_walk: Callable[[float, float | None], float | tuple[float, float, float]] = lambda x, max_radial_dist: np.inf, starting_ratio_factor: int = 2, draw_steps: bool | list[int] = False) → np.ndarray

Embed an interaction matrix or QUBO with the BLaDE algorithm.

BLaDE stands for Balanced Latently Dimensional Embedder. It compute positions for nodes so that their interactions approach the desired values. The interactions assume that the interaction coefficient of the device is set to 1. Its typical target is on interaction matrices or QUBOs, but it can also be used for MIS with limitations if the adjacency matrix is converted into a QUBO. The general principle is based on the Fruchterman-Reingold algorithm.

matrix: An objective interaction matrix or QUBO between the nodes. It must be either symmetrical or triangular. max_min_dist_ratio: If present, set the maximum ratio between the maximum radial distance and the minimum pairwise distances. dimensions: List of numbers of dimensions to explore one after the other. A list with one value is equivalent to a list containing twice the same value. For a 2D embedding, the last value should be 2. Increasing the number of intermediate dimensions can help to escape from local minima. starting_positions: If provided, initial positions to start from. Otherwise, random positions will be generated. The number of dimensions of the starting positions must be lower than or equal to the first dimension to explore. If it is lower, it is added dimensions filled with random values. pca: Whether to apply Principal Component Analysis to prioritize dimensions to keep when transitioning from a space to a space with fewer dimensions. It is disabled by default because it can raise an error when there are too many dimensions compared to the number of nodes. steps_per_round: Number of elementary steps to perform for each dimension transition, where at each step move vectors are computed and applied on the nodes. compute_weight_relative_threshold: Function that is called at each step. It takes a float number between 0 and 1 that represents the progress on the steps. It must return a float number between 0 and 1 that gives a threshold determining which weights are significant (see update_positions to learn more). compute_max_distance_to_walk: Function that is called at each step. It takes a float number between 0 and 1 that represents the progress on the steps, and takes another argument that is set to None when max_min_dist_ratio is not enabled, otherwise, it is set to the maximum radial distance for the current step. It must return a float number that limits the distances nodes can move at one step (see update_positions to learn more). starting_ratio_factor: When max_min_dist_ratio is enabled, defines a multiplying factor on the target ratio to start the evolution on a larger ratio, to let more flexibility in the beginning. draw_steps: Whether to draw the nodes and the forces. Requires installing the seaborn library.

Raises

• ValueError

dataclass

BladeConfig (max_min_dist_ratio: float | None = None, dimensions: tuple[int, ...] = (5, 4, 3, 2, 2, 2), starting_positions: np.ndarray | None = None, pca: bool = False, steps_per_round: int = 200, compute_weight_relative_threshold: Callable[[float], float] = lambda _: 0.1, compute_max_distance_to_walk: Callable[[float, float | None], float | tuple[float, float, float]] = lambda x, max_radial_dist: np.inf, starting_ratio_factor: int = 2, draw_steps: bool | list[int] = False, device: InitVar[Device | None] = None)

Bases : EmbeddingConfig

Configuration parameters to embed with BLaDE.