qoolqit.embedding

embedding

Collection of graph and matrix embedding algorithms.

Modules:

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

Classes:

• BaseEmbedder –

  Abstract base class for all embedders.

• Blade –

  A matrix to graph embedder using the BLaDE algorithm.

• BladeConfig –

  Configuration parameters to embed with BLaDE.

• EmbedderConfig –

  Base abstract dataclass for all embedding algorithm configurations.

• GraphToGraphEmbedder –

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

• InteractionEmbedder –

  A matrix to graph embedder using the interaction embedding algorithm.

• InteractionEmbedderConfig –

  Configuration parameters for the interaction embedding.

• MatrixToGraphEmbedder –

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

• SpringLayoutConfig –

  Configuration parameters for the spring-layout embedding.

• SpringLayoutEmbedder –

  A graph to graph embedder using the spring layout algorithm.

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

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

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

@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

@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



      dataclass
   (qoolqit.embedding.algorithms.BladeConfig)" href="#qoolqit.embedding.BladeConfig">BladeConfig =             BladeConfig



      dataclass
   (qoolqit.embedding.algorithms.BladeConfig)" href="#qoolqit.embedding.BladeConfig">BladeConfig())

A matrix to graph embedder using the BLaDE algorithm.

Parameters:

• config (BladeConfig, default: BladeConfig() ) –

  configuration object for the BLaDE algorithm.

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

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 (qoolqit.graphs.DataGraph)" href="../graphs/#qoolqit.graphs.DataGraph">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

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 (qoolqit.devices.device.Device)" href="../devices/#qoolqit.devices.Device">Device | None] = None,
)

Configuration parameters to embed with BLaDE.

Used by:

• API reference qoolqit.embedding  embedding  Blade

Methods:

• __post_init__ –

  Post initialization of the BladeConfig dataclass.

• dict –

  Returns the dataclass as a dictionary.

__post_init__

__post_init__(device:             Device (qoolqit.devices.device.Device)" href="../devices/#qoolqit.devices.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

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 (qoolqit.embedding.base_embedder.EmbedderConfig.dict)" href="#qoolqit.embedding.BladeConfig.dict">dict

Returns the dataclass as a dictionary.

Returned by:

• API reference qoolqit.embedding  embedding
  •  BladeConfig  dict
  •  EmbedderConfig  dict
  •  InteractionEmbedderConfig  dict
  •  SpringLayoutConfig  dict

Source code in qoolqit/embedding/base_embedder.py

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 (qoolqit.embedding.base_embedder.EmbedderConfig.dict)" href="#qoolqit.embedding.BladeConfig.dict">dict

Returns the dataclass as a dictionary.

Returned by:

• API reference qoolqit.embedding  embedding
  •  BladeConfig  dict
  •  EmbedderConfig  dict
  •  InteractionEmbedderConfig  dict
  •  SpringLayoutConfig  dict

Source code in qoolqit/embedding/base_embedder.py

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

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

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

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

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 (qoolqit.embedding.base_embedder.EmbedderConfig.dict)" href="#qoolqit.embedding.BladeConfig.dict">dict

Returns the dataclass as a dictionary.

Returned by:

• API reference qoolqit.embedding  embedding
  •  BladeConfig  dict
  •  EmbedderConfig  dict
  •  InteractionEmbedderConfig  dict
  •  SpringLayoutConfig  dict

Source code in qoolqit/embedding/base_embedder.py

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

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

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:

• API reference qoolqit.embedding  embedding  SpringLayoutEmbedder

Methods:

• dict –

  Returns the dataclass as a dictionary.

dict

dict() ->             dict (qoolqit.embedding.base_embedder.EmbedderConfig.dict)" href="#qoolqit.embedding.BladeConfig.dict">dict

Returns the dataclass as a dictionary.

Returned by:

• API reference qoolqit.embedding  embedding
  •  BladeConfig  dict
  •  EmbedderConfig  dict
  •  InteractionEmbedderConfig  dict
  •  SpringLayoutConfig  dict

Source code in qoolqit/embedding/base_embedder.py

def dict(self) -> dict:
    """Returns the dataclass as a dictionary."""
    return asdict(self)

SpringLayoutEmbedder

SpringLayoutEmbedder(
    config:             SpringLayoutConfig



      dataclass
   (qoolqit.embedding.algorithms.SpringLayoutConfig)" href="#qoolqit.embedding.SpringLayoutConfig">SpringLayoutConfig =             SpringLayoutConfig



      dataclass
   (qoolqit.embedding.algorithms.SpringLayoutConfig)" href="#qoolqit.embedding.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

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

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