Skip to content

qoolqit.embedding

embedding

Collection of graph and matrix embedding algorithms.

Modules:

  • algorithms –
  • base_embedder –
  • graph_embedder –
  • matrix_embedder –

Classes:

BaseEmbedder 

BaseEmbedder(algorithm: Callable, config: ConfigType)

Abstract base class for all embedders.

An embedder is a function that maps a InDataType to an OutDataType through an embedding algorithm. Parameters of the embedding algorithm can be customized through the EmbedderConfig.

An algorithm should be a standalone function that takes a piece of data of an InDataType and maps it to an OutDataType. Any extra configuration parameters taken as input by the algorithm function should be defined in the config dataclass, inheriting from EmbedderConfig.

Parameters:

  • algorithm (Callable) –

    a callable to the algorithm function.

  • config (ConfigType) –

    a config dataclass holding parameter values for the algorithm.

Methods:

  • embed –

    Validates the input, runs the embedding algorithm, and validates the output.

  • validate_input –

    Checks if the given data is compatible with the embedder.

  • validate_output –

    Checks if the resulting output is expected by the embedder.

Attributes:

  • algorithm (Callable) –

    Returns the callable to the embedding algorithm.

  • config (ConfigType) –

    Returns the config for the embedding algorithm.

  • info (str) –

    Prints info about the embedding algorithm.

Source code in qoolqit/embedding/base_embedder.py 
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
def __init__(self, algorithm: Callable, config: ConfigType) -> None:
    """Default initializer for all embedders, taking an algorithm and a config.

    An algorithm should be a standalone function that takes a piece of data of an
    InDataType and maps it to an OutDataType. Any extra configuration parameters
    taken as input by the algorithm function should be defined in the config dataclass,
    inheriting from EmbedderConfig.

    Arguments:
        algorithm: a callable to the algorithm function.
        config: a config dataclass holding parameter values for the algorithm.
    """
    if not isinstance(config, EmbedderConfig):
        raise TypeError(
            "The config must be an instance of a dataclass inheriting from EmbedderConfig."
        )

    algo_signature = inspect.signature(algorithm)
    config_keys = set(config.dict().keys())
    algo_signature_keys = set(algo_signature.parameters.keys())
    if not config_keys <= algo_signature_keys:
        config_keys_str = "\n".join(f"\t- {key}" for key in config_keys)
        algo_keys_str = "\n".join(f"\t- {key}" for key in algo_signature_keys)
        raise TypeError(
            f"Config {config.__class__.__name__} is not compatible with the "
            + f"algorithm {algorithm.__name__}, as not all configuration fields "
            + "correspond to keyword arguments in the algorithm function.\n\n"
            + f"Config {config.__class__.__name__} keys:\n{config_keys_str}\n\n"
            + f"Algorithm signature parameters:\n{algo_keys_str}"
        )

    self._algorithm = algorithm
    self._config = config

algorithm property 

algorithm: Callable

Returns the callable to the embedding algorithm.

config property 

config: ConfigType

Returns the config for the embedding algorithm.

info property 

info: str

Prints info about the embedding algorithm.

embed 

embed(data: InDataType) -> OutDataType

Validates the input, runs the embedding algorithm, and validates the output.

Parameters:

  • data (InDataType) –

    the data to embed.

Source code in qoolqit/embedding/base_embedder.py 
124
125
126
127
128
129
130
131
132
133
def embed(self, data: InDataType) -> OutDataType:
    """Validates the input, runs the embedding algorithm, and validates the output.

    Arguments:
        data: the data to embed.
    """
    self.validate_input(data)
    result: OutDataType = self.algorithm(data, **self.config.dict())
    self.validate_output(result)
    return result

validate_input abstractmethod 

validate_input(data: InDataType) -> None

Checks if the given data is compatible with the embedder.

Each embedder should write its own data validator. If the data is not of the supported type or in the specific supported format for that embedder, an error should be raised.

Parameters:

  • data (InDataType) –

    the data to validate.

Raises:

  • TypeError –

    if the data is not of the supported type.

  • SomeError –

    some other error if other constraints are not met.

Source code in qoolqit/embedding/base_embedder.py 
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
@abstractmethod
def validate_input(self, data: InDataType) -> None:
    """Checks if the given data is compatible with the embedder.

    Each embedder should write its own data validator. If the data
    is not of the supported type or in the specific supported format
    for that embedder, an error should be raised.

    Arguments:
        data: the data to validate.

    Raises:
        TypeError: if the data is not of the supported type.
        SomeError: some other error if other constraints are not met.
    """
    ...

validate_output abstractmethod 

validate_output(result: OutDataType) -> None

Checks if the resulting output is expected by the embedder.

Each embedder should write its own output validator. If the result is not of the supported type or in the specific supported format for that embedder, an error should be raised.

Parameters:

  • result (OutDataType) –

    the output to validate.

Raises:

  • TypeError –

    if the output is not of the supported type.

  • SomeError –

    some other error if other constraints are not met.

Source code in qoolqit/embedding/base_embedder.py 
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
@abstractmethod
def validate_output(self, result: OutDataType) -> None:
    """Checks if the resulting output is expected by the embedder.

    Each embedder should write its own output validator. If the result
    is not of the supported type or in the specific supported format
    for that embedder, an error should be raised.

    Arguments:
        result: the output to validate.

    Raises:
        TypeError: if the output is not of the supported type.
        SomeError: some other error if other constraints are not met.
    """
    ...

Blade 

Blade(config: BladeConfig = BladeConfig())

A matrix to graph embedder using the BLaDE algorithm.

Parameters:

Methods:

  • embed –

    Return a DataGraph with coordinates that embeds the input matrix.

Attributes:

  • algorithm (Callable) –

    Returns the callable to the embedding algorithm.

  • config (ConfigType) –

    Returns the config for the embedding algorithm.

  • info (str) –

    Prints info about the embedding algorithm.

Source code in qoolqit/embedding/matrix_embedder.py 
51
52
53
54
55
56
57
def __init__(self, config: BladeConfig = BladeConfig()) -> None:
    """Inits Blade.

    Args:
        config (BladeConfig): configuration object for the BLaDE algorithm.
    """
    super().__init__(_blade, config=config)

algorithm property 

algorithm: Callable

Returns the callable to the embedding algorithm.

config property 

config: ConfigType

Returns the config for the embedding algorithm.

info property 

info: str

Prints info about the embedding algorithm.

embed 

embed(data: ndarray) -> DataGraph

Return a DataGraph with coordinates that embeds the input matrix.

Validates the input, runs the embedding algorithm, and validates the output.

Parameters:

  • data (ndarray) –

    the matrix to embed into a DataGraph with coordinates.

Source code in qoolqit/embedding/matrix_embedder.py 
59
60
61
62
63
64
65
66
67
68
69
70
def embed(self, data: np.ndarray) -> DataGraph:
    """Return a DataGraph with coordinates that embeds the input matrix.

    Validates the input, runs the embedding algorithm, and validates the output.

    Args:
        data (np.ndarray): the matrix to embed into a DataGraph with coordinates.
    """
    self.validate_input(data)
    positions = self.algorithm(data, **self.config.dict())
    graph = DataGraph.from_coordinates(positions.tolist())
    return graph

BladeConfig dataclass 

BladeConfig(
    max_min_dist_ratio: float | None = None,
    dimensions: tuple[int, ...] = default_dimensions,
    starting_positions: ndarray | None = None,
    pca: bool = default_pca,
    steps_per_round: int = default_steps_per_round,
    compute_weight_relative_threshold: Callable[
        [float], float
    ] = default_compute_weight_relative_threshold,
    compute_max_distance_to_walk: Callable[
        [float, float], float | tuple[float, float, float]
    ] = default_compute_max_distance_to_walk,
    compute_regulation_cursor: Callable[
        [float], float
    ] = default_compute_regulation_cursor,
    compute_ratio_step_factors: Callable[
        [float], float
    ] = default_compute_ratio_step_factors,
    ratio_rerun: int = default_ratio_rerun,
    device: InitVar[Device | None] = None,
)

Configuration parameters to embed with BLaDE.

Used by:

Methods:

  • __post_init__ –

    Post initialization of the BladeConfig dataclass.

  • dict –

    Returns the dataclass as a dictionary.

__post_init__ 

__post_init__(device: Device | None) -> None

Post initialization of the BladeConfig dataclass.

Set the max_min_dist_ratio argument of the blade_embedding algorithm based on the specification of the selected device.

Parameters:

  • device (Device) –

    the QoolQit device to use to set the maximum ratio between the maximum radial distance and the minimum pairwise distance between atoms.

Source code in qoolqit/embedding/algorithms/blade/blade.py 
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
def __post_init__(self, device: Device | None) -> None:
    """Post initialization of the `BladeConfig` dataclass.

    Set the `max_min_dist_ratio` argument of the `blade_embedding` algorithm
    based on the specification of the selected device.

    Args:
        device (Device): the QoolQit device to use to set the maximum ratio between the maximum
            radial distance and the minimum pairwise distance between atoms.
    """
    if device:
        if self.max_min_dist_ratio:
            logger.warning(
                "`max_min_dist_ratio` and `device` attributes should not be set simultaneously."
            )
        min_distance = device._min_distance
        max_radial_distance = device._max_radial_distance
        if max_radial_distance and min_distance:
            self.max_min_dist_ratio = max_radial_distance / min_distance

dict 

dict() -> dict

Returns the dataclass as a dictionary.

Returned by:
Source code in qoolqit/embedding/base_embedder.py 
18
19
20
def dict(self) -> dict:
    """Returns the dataclass as a dictionary."""
    return asdict(self)

EmbedderConfig dataclass 

EmbedderConfig()

Base abstract dataclass for all embedding algorithm configurations.

Subclasses define parameters specific to their algorithms. Each config should define fields that directly translate to arguments in the respective embedding function it configures.

Methods:

  • dict –

    Returns the dataclass as a dictionary.

dict 

dict() -> dict

Returns the dataclass as a dictionary.

Returned by:
Source code in qoolqit/embedding/base_embedder.py 
18
19
20
def dict(self) -> dict:
    """Returns the dataclass as a dictionary."""
    return asdict(self)

GraphToGraphEmbedder 

GraphToGraphEmbedder(
    algorithm: Callable, config: ConfigType
)

A family of embedders that map a graph to a graph.

Focused on unit-disk graph embedding, where the goal is to find a set of coordinates for a graph that has no coordinates, such that the final unit-disk edges matches the set of edges in the original graph.

A custom algorithm and configuration can be set at initialization.

An algorithm should be a standalone function that takes a piece of data of an InDataType and maps it to an OutDataType. Any extra configuration parameters taken as input by the algorithm function should be defined in the config dataclass, inheriting from EmbedderConfig.

Parameters:

  • algorithm (Callable) –

    a callable to the algorithm function.

  • config (ConfigType) –

    a config dataclass holding parameter values for the algorithm.

Methods:

  • embed –

    Validates the input, runs the embedding algorithm, and validates the output.

Attributes:

  • algorithm (Callable) –

    Returns the callable to the embedding algorithm.

  • config (ConfigType) –

    Returns the config for the embedding algorithm.

  • info (str) –

    Prints info about the embedding algorithm.

Source code in qoolqit/embedding/base_embedder.py 
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
def __init__(self, algorithm: Callable, config: ConfigType) -> None:
    """Default initializer for all embedders, taking an algorithm and a config.

    An algorithm should be a standalone function that takes a piece of data of an
    InDataType and maps it to an OutDataType. Any extra configuration parameters
    taken as input by the algorithm function should be defined in the config dataclass,
    inheriting from EmbedderConfig.

    Arguments:
        algorithm: a callable to the algorithm function.
        config: a config dataclass holding parameter values for the algorithm.
    """
    if not isinstance(config, EmbedderConfig):
        raise TypeError(
            "The config must be an instance of a dataclass inheriting from EmbedderConfig."
        )

    algo_signature = inspect.signature(algorithm)
    config_keys = set(config.dict().keys())
    algo_signature_keys = set(algo_signature.parameters.keys())
    if not config_keys <= algo_signature_keys:
        config_keys_str = "\n".join(f"\t- {key}" for key in config_keys)
        algo_keys_str = "\n".join(f"\t- {key}" for key in algo_signature_keys)
        raise TypeError(
            f"Config {config.__class__.__name__} is not compatible with the "
            + f"algorithm {algorithm.__name__}, as not all configuration fields "
            + "correspond to keyword arguments in the algorithm function.\n\n"
            + f"Config {config.__class__.__name__} keys:\n{config_keys_str}\n\n"
            + f"Algorithm signature parameters:\n{algo_keys_str}"
        )

    self._algorithm = algorithm
    self._config = config

algorithm property 

algorithm: Callable

Returns the callable to the embedding algorithm.

config property 

config: ConfigType

Returns the config for the embedding algorithm.

info property 

info: str

Prints info about the embedding algorithm.

embed 

embed(data: InDataType) -> OutDataType

Validates the input, runs the embedding algorithm, and validates the output.

Parameters:

  • data (InDataType) –

    the data to embed.

Source code in qoolqit/embedding/base_embedder.py 
124
125
126
127
128
129
130
131
132
133
def embed(self, data: InDataType) -> OutDataType:
    """Validates the input, runs the embedding algorithm, and validates the output.

    Arguments:
        data: the data to embed.
    """
    self.validate_input(data)
    result: OutDataType = self.algorithm(data, **self.config.dict())
    self.validate_output(result)
    return result

InteractionEmbedder 

InteractionEmbedder()

A matrix to graph embedder using the interaction embedding algorithm.

Methods:

  • embed –

    Validates the input, runs the embedding algorithm, and validates the output.

Attributes:

  • algorithm (Callable) –

    Returns the callable to the embedding algorithm.

  • config (ConfigType) –

    Returns the config for the embedding algorithm.

  • info (str) –

    Prints info about the embedding algorithm.

Source code in qoolqit/embedding/matrix_embedder.py 
44
45
def __init__(self) -> None:
    super().__init__(interaction_embedding, InteractionEmbedderConfig())

algorithm property 

algorithm: Callable

Returns the callable to the embedding algorithm.

config property 

config: ConfigType

Returns the config for the embedding algorithm.

info property 

info: str

Prints info about the embedding algorithm.

embed 

embed(data: InDataType) -> OutDataType

Validates the input, runs the embedding algorithm, and validates the output.

Parameters:

  • data (InDataType) –

    the data to embed.

Source code in qoolqit/embedding/base_embedder.py 
124
125
126
127
128
129
130
131
132
133
def embed(self, data: InDataType) -> OutDataType:
    """Validates the input, runs the embedding algorithm, and validates the output.

    Arguments:
        data: the data to embed.
    """
    self.validate_input(data)
    result: OutDataType = self.algorithm(data, **self.config.dict())
    self.validate_output(result)
    return result

InteractionEmbedderConfig dataclass 

InteractionEmbedderConfig(
    method: str = "Nelder-Mead",
    maxiter: int = 200000,
    tol: float = 1e-08,
    x0: ndarray | None = None,
)

Configuration parameters for the interaction embedding.

Methods:

  • dict –

    Returns the dataclass as a dictionary.

dict 

dict() -> dict

Returns the dataclass as a dictionary.

Returned by:
Source code in qoolqit/embedding/base_embedder.py 
18
19
20
def dict(self) -> dict:
    """Returns the dataclass as a dictionary."""
    return asdict(self)

MatrixToGraphEmbedder 

MatrixToGraphEmbedder(
    algorithm: Callable, config: ConfigType
)

A family of embedders that map a matrix to a graph.

A custom algorithm and configuration can be set at initialization.

An algorithm should be a standalone function that takes a piece of data of an InDataType and maps it to an OutDataType. Any extra configuration parameters taken as input by the algorithm function should be defined in the config dataclass, inheriting from EmbedderConfig.

Parameters:

  • algorithm (Callable) –

    a callable to the algorithm function.

  • config (ConfigType) –

    a config dataclass holding parameter values for the algorithm.

Methods:

  • embed –

    Validates the input, runs the embedding algorithm, and validates the output.

Attributes:

  • algorithm (Callable) –

    Returns the callable to the embedding algorithm.

  • config (ConfigType) –

    Returns the config for the embedding algorithm.

  • info (str) –

    Prints info about the embedding algorithm.

Source code in qoolqit/embedding/base_embedder.py 
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
def __init__(self, algorithm: Callable, config: ConfigType) -> None:
    """Default initializer for all embedders, taking an algorithm and a config.

    An algorithm should be a standalone function that takes a piece of data of an
    InDataType and maps it to an OutDataType. Any extra configuration parameters
    taken as input by the algorithm function should be defined in the config dataclass,
    inheriting from EmbedderConfig.

    Arguments:
        algorithm: a callable to the algorithm function.
        config: a config dataclass holding parameter values for the algorithm.
    """
    if not isinstance(config, EmbedderConfig):
        raise TypeError(
            "The config must be an instance of a dataclass inheriting from EmbedderConfig."
        )

    algo_signature = inspect.signature(algorithm)
    config_keys = set(config.dict().keys())
    algo_signature_keys = set(algo_signature.parameters.keys())
    if not config_keys <= algo_signature_keys:
        config_keys_str = "\n".join(f"\t- {key}" for key in config_keys)
        algo_keys_str = "\n".join(f"\t- {key}" for key in algo_signature_keys)
        raise TypeError(
            f"Config {config.__class__.__name__} is not compatible with the "
            + f"algorithm {algorithm.__name__}, as not all configuration fields "
            + "correspond to keyword arguments in the algorithm function.\n\n"
            + f"Config {config.__class__.__name__} keys:\n{config_keys_str}\n\n"
            + f"Algorithm signature parameters:\n{algo_keys_str}"
        )

    self._algorithm = algorithm
    self._config = config

algorithm property 

algorithm: Callable

Returns the callable to the embedding algorithm.

config property 

config: ConfigType

Returns the config for the embedding algorithm.

info property 

info: str

Prints info about the embedding algorithm.

embed 

embed(data: InDataType) -> OutDataType

Validates the input, runs the embedding algorithm, and validates the output.

Parameters:

  • data (InDataType) –

    the data to embed.

Source code in qoolqit/embedding/base_embedder.py 
124
125
126
127
128
129
130
131
132
133
def embed(self, data: InDataType) -> OutDataType:
    """Validates the input, runs the embedding algorithm, and validates the output.

    Arguments:
        data: the data to embed.
    """
    self.validate_input(data)
    result: OutDataType = self.algorithm(data, **self.config.dict())
    self.validate_output(result)
    return result

SpringLayoutConfig dataclass 

SpringLayoutConfig(
    iterations: int = 100,
    threshold: float = 0.0001,
    seed: int | None = None,
)

Configuration parameters for the spring-layout embedding.

Used by:

Methods:

  • dict –

    Returns the dataclass as a dictionary.

dict 

dict() -> dict

Returns the dataclass as a dictionary.

Returned by:
Source code in qoolqit/embedding/base_embedder.py 
18
19
20
def dict(self) -> dict:
    """Returns the dataclass as a dictionary."""
    return asdict(self)

SpringLayoutEmbedder 

SpringLayoutEmbedder(
    config: SpringLayoutConfig = SpringLayoutConfig(),
)

A graph to graph embedder using the spring layout algorithm.

Methods:

  • embed –

    Validates the input, runs the embedding algorithm, and validates the output.

Attributes:

  • algorithm (Callable) –

    Returns the callable to the embedding algorithm.

  • config (ConfigType) –

    Returns the config for the embedding algorithm.

  • info (str) –

    Prints info about the embedding algorithm.

Source code in qoolqit/embedding/graph_embedder.py 
37
38
39
def __init__(self, config: SpringLayoutConfig = SpringLayoutConfig()) -> None:
    """Inits SpringLayoutEmbedder."""
    super().__init__(spring_layout_embedding, config=config)

algorithm property 

algorithm: Callable

Returns the callable to the embedding algorithm.

config property 

config: ConfigType

Returns the config for the embedding algorithm.

info property 

info: str

Prints info about the embedding algorithm.

embed 

embed(data: InDataType) -> OutDataType

Validates the input, runs the embedding algorithm, and validates the output.

Parameters:

  • data (InDataType) –

    the data to embed.

Source code in qoolqit/embedding/base_embedder.py 
124
125
126
127
128
129
130
131
132
133
def embed(self, data: InDataType) -> OutDataType:
    """Validates the input, runs the embedding algorithm, and validates the output.

    Arguments:
        data: the data to embed.
    """
    self.validate_input(data)
    result: OutDataType = self.algorithm(data, **self.config.dict())
    self.validate_output(result)
    return result