Utilities

Utilities for PyKEEN.

class Bias(dim)[source]

A module wrapper for adding a bias.

Initialize the module.

Parameters:

dim (int) – >0 The dimension of the input.

forward(x)[source]

Add the learned bias to the input.

Parameters:

x (FloatTensor) – shape: (n, d) The input.

Return type:

FloatTensor

Returns:

x + b[None, :]

reset_parameters()[source]

Reset the layer’s parameters.

class ExtraReprMixin[source]

A mixin for modules with hierarchical extra_repr.

It takes up the torch.nn.Module.extra_repr() idea, and additionally provides a simple composable way to generate the components of extra_repr() via iter_extra_repr().

If combined with torch.nn.Module, make sure to put ExtraReprMixin behind torch.nn.Module to prefer the latter’s __repr__() implementation.

extra_repr()[source]

Generate the extra repr, cf. :meth`torch.nn.Module.extra_repr`.

Return type:

str

Returns:

the extra part of the repr()

iter_extra_repr()[source]

Iterate over the components of the extra_repr().

This method is typically overridden. A common pattern would be

def iter_extra_repr(self) -> Iterable[str]:
    yield from super().iter_extra_repr()
    yield "<key1>=<value1>"
    yield "<key2>=<value2>"
Return type:

Iterable[str]

Returns:

an iterable over individual components of the extra_repr()

class NoRandomSeedNecessary[source]

Used in pipeline when random seed is set automatically.

class Result[source]

A superclass of results that can be saved to a directory.

abstract save_to_directory(directory, **kwargs)[source]

Save the results to the directory.

Return type:

None

Parameters:

directory (str) –

abstract save_to_ftp(directory, ftp)[source]

Save the results to the directory in an FTP server.

Return type:

None

Parameters:

  • directory (str) –

  • ftp (FTP) –

abstract save_to_s3(directory, bucket, s3=None)[source]

Save all artifacts to the given directory in an S3 Bucket.

Parameters:

  • directory (str) – The directory in the S3 bucket

  • bucket (str) – The name of the S3 bucket

  • s3 – A client from boto3.client(), if already instantiated

Return type:

None

all_in_bounds(x, low=None, high=None, a_tol=0.0)[source]

Check if tensor values respect lower and upper bound.

Parameters:
Return type:

bool

Returns:

If all values are within the given bounds

at_least_eps(x)[source]

Make sure a tensor is greater than zero.

Return type:

FloatTensor

Parameters:

x (FloatTensor) –

broadcast_upgrade_to_sequences(*xs)[source]

Apply upgrade_to_sequence to each input, and afterwards repeat singletons to match the maximum length.

Parameters:

xs (Union[~X, Sequence[~X]]) – length: m the inputs.

Return type:

Sequence[Sequence[~X]]

Returns:

a sequence of length m, where each element is a sequence and all elements have the same length.

Raises:

ValueError – if there is a non-singleton sequence input with length different from the maximum sequence length.

>>> broadcast_upgrade_to_sequences(1)
((1,),)
>>> broadcast_upgrade_to_sequences(1, 2)
((1,), (2,))
>>> broadcast_upgrade_to_sequences(1, (2, 3))
((1, 1), (2, 3))
calculate_broadcasted_elementwise_result_shape(first, second)[source]

Determine the return shape of a broadcasted elementwise operation.

Return type:

Tuple[int, …]

Parameters:
check_shapes(*x, raise_on_errors=True)[source]

Verify that a sequence of tensors are of matching shapes.

Parameters:

  • x (Tuple[Union[Tensor, Tuple[int, …]], str]) – A tuple (t, s), where t is a tensor, or an actual shape of a tensor (a tuple of integers), and s is a string, where each character corresponds to a (named) dimension. If the shapes of different tensors share a character, the corresponding dimensions are expected to be of equal size.

  • raise_on_errors (bool) – Whether to raise an exception in case of a mismatch.

Return type:

bool

Returns:

Whether the shapes matched.

Raises:

ValueError – If the shapes mismatch and raise_on_error is True.

Examples: >>> check_shapes(((10, 20), “bd”), ((10, 20, 20), “bdd”)) True >>> check_shapes(((10, 20), “bd”), ((10, 30, 20), “bdd”), raise_on_errors=False) False

clamp_norm(x, maxnorm, p='fro', dim=None)[source]

Ensure that a tensor’s norm does not exceeds some threshold.

Parameters:
Return type:

Tensor

Returns:

A vector with \(|x| <= maxnorm\).

combine_complex(x_re, x_im)[source]

Combine a complex tensor from real and imaginary part.

Return type:

FloatTensor

Parameters:

  • x_re (FloatTensor) –

  • x_im (FloatTensor) –

compact_mapping(mapping)[source]

Update a mapping (key -> id) such that the IDs range from 0 to len(mappings) - 1.

Parameters:

mapping (Mapping[~X, int]) – The mapping to compact.

Return type:

Tuple[Mapping[~X, int], Mapping[int, int]]

Returns:

A pair (translated, translation) where translated is the updated mapping, and translation a dictionary from old to new ids.

complex_normalize(x)[source]

Normalize a vector of complex numbers such that each element is of unit-length.

Let \(x \in \mathbb{C}^d\) denote a complex vector. Then, the operation computes

\[x_i' = \frac{x_i}{|x_i|}\]

where \(|x_i| = \sqrt{Re(x_i)^2 + Im(x_i)^2}\) is the modulus of complex number

Parameters:

x (Tensor) – A tensor formulating complex numbers

Return type:

Tensor

Returns:

An elementwise noramlized vector.

class compose(*operations, name)[source]

A class representing the composition of several functions.

Initialize the composition with a sequence of operations.

Parameters:

  • operations (Callable[[~X], ~X]) – unary operations that will be applied in succession

  • name (str) – The name of the composed function.

compute_box(base, delta, size)[source]

Compute the lower and upper corners of a resulting box.

Parameters:

  • base (FloatTensor) – shape: (*, d) the base position (box center) of the input relation embeddings

  • delta (FloatTensor) – shape: (*, d) the base shape of the input relation embeddings

  • size (FloatTensor) – shape: (*, d) the size scalar vectors of the input relation embeddings

Return type:

Tuple[FloatTensor, FloatTensor]

Returns:

shape: (*, d) each lower and upper bounds of the box whose embeddings are provided as input.

convert_to_canonical_shape(x, dim, num=None, batch_size=1, suffix_shape=-1)[source]

Convert a tensor to canonical shape.

Parameters:

  • x (FloatTensor) – The tensor in compatible shape.

  • dim (Union[int, str]) – The “num” dimension.

  • batch_size (int) – The batch size.

  • num (Optional[int]) – The number.

  • suffix_shape (Union[int, Sequence[int]]) – The suffix shape.

Return type:

FloatTensor

Returns:

shape: (batch_size, num_heads, num_relations, num_tails, *) A tensor in canonical shape.

create_relation_to_entity_set_mapping(triples)[source]

Create mappings from relation IDs to the set of their head / tail entities.

Parameters:

triples (Iterable[Tuple[int, int, int]]) – The triples.

Return type:

Tuple[Mapping[int, Set[int]], Mapping[int, Set[int]]]

Returns:

A pair of dictionaries, each mapping relation IDs to entity ID sets.

einsum(*args)[source]

Sums the product of the elements of the input operands along dimensions specified using a notation based on the Einstein summation convention.

Einsum allows computing many common multi-dimensional linear algebraic array operations by representing them in a short-hand format based on the Einstein summation convention, given by equation. The details of this format are described below, but the general idea is to label every dimension of the input operands with some subscript and define which subscripts are part of the output. The output is then computed by summing the product of the elements of the operands along the dimensions whose subscripts are not part of the output. For example, matrix multiplication can be computed using einsum as torch.einsum(“ij,jk->ik”, A, B). Here, j is the summation subscript and i and k the output subscripts (see section below for more details on why).

Equation:

The equation string specifies the subscripts (letters in [a-zA-Z]) for each dimension of the input operands in the same order as the dimensions, separating subcripts for each operand by a comma (‘,’), e.g. ‘ij,jk’ specify subscripts for two 2D operands. The dimensions labeled with the same subscript must be broadcastable, that is, their size must either match or be 1. The exception is if a subscript is repeated for the same input operand, in which case the dimensions labeled with this subscript for this operand must match in size and the operand will be replaced by its diagonal along these dimensions. The subscripts that appear exactly once in the equation will be part of the output, sorted in increasing alphabetical order. The output is computed by multiplying the input operands element-wise, with their dimensions aligned based on the subscripts, and then summing out the dimensions whose subscripts are not part of the output.

Optionally, the output subscripts can be explicitly defined by adding an arrow (‘->’) at the end of the equation followed by the subscripts for the output. For instance, the following equation computes the transpose of a matrix multiplication: ‘ij,jk->ki’. The output subscripts must appear at least once for some input operand and at most once for the output.

Ellipsis (’…’) can be used in place of subscripts to broadcast the dimensions covered by the ellipsis. Each input operand may contain at most one ellipsis which will cover the dimensions not covered by subscripts, e.g. for an input operand with 5 dimensions, the ellipsis in the equation ‘ab…c’ cover the third and fourth dimensions. The ellipsis does not need to cover the same number of dimensions across the operands but the ‘shape’ of the ellipsis (the size of the dimensions covered by them) must broadcast together. If the output is not explicitly defined with the arrow (‘->’) notation, the ellipsis will come first in the output (left-most dimensions), before the subscript labels that appear exactly once for the input operands. e.g. the following equation implements batch matrix multiplication ‘…ij,…jk’.

A few final notes: the equation may contain whitespaces between the different elements (subscripts, ellipsis, arrow and comma) but something like ‘…’ is not valid. An empty string ‘’ is valid for scalar operands.

Note

torch.einsum handles ellipsis (’…’) differently from NumPy in that it allows dimensions covered by the ellipsis to be summed over, that is, ellipsis are not required to be part of the output.

Note

This function uses opt_einsum (https://optimized-einsum.readthedocs.io/en/stable/) to speed up computation or to consume less memory by optimizing contraction order. This optimization occurs when there are at least three inputs, since the order does not matter otherwise. Note that finding _the_ optimal path is an NP-hard problem, thus, opt_einsum relies on different heuristics to achieve near-optimal results. If opt_einsum is not available, the default order is to contract from left to right.

To bypass this default behavior, add the following line to disable the usage of opt_einsum and skip path calculation: torch.backends.opt_einsum.enabled = False

To specify which strategy you’d like for opt_einsum to compute the contraction path, add the following line: torch.backends.opt_einsum.strategy = ‘auto’. The default strategy is ‘auto’, and we also support ‘greedy’ and ‘optimal’. Disclaimer that the runtime of ‘optimal’ is factorial in the number of inputs! See more details in the opt_einsum documentation (https://optimized-einsum.readthedocs.io/en/stable/path_finding.html).

Note

As of PyTorch 1.10 torch.einsum() also supports the sublist format (see examples below). In this format, subscripts for each operand are specified by sublists, list of integers in the range [0, 52). These sublists follow their operands, and an extra sublist can appear at the end of the input to specify the output’s subscripts., e.g. torch.einsum(op1, sublist1, op2, sublist2, …, [subslist_out]). Python’s Ellipsis object may be provided in a sublist to enable broadcasting as described in the Equation section above.

Args:

equation (str): The subscripts for the Einstein summation. operands (List[Tensor]): The tensors to compute the Einstein summation of.

Examples:

>>> # trace
>>> # xdoctest: +IGNORE_WANT("non-deterministic")
>>> torch.einsum('ii', torch.randn(4, 4))
tensor(-1.2104)

>>> # diagonal
>>> # xdoctest: +IGNORE_WANT("non-deterministic")
>>> torch.einsum('ii->i', torch.randn(4, 4))
tensor([-0.1034,  0.7952, -0.2433,  0.4545])

>>> # outer product
>>> # xdoctest: +IGNORE_WANT("non-deterministic")
>>> x = torch.randn(5)
>>> y = torch.randn(4)
>>> torch.einsum('i,j->ij', x, y)
tensor([[ 0.1156, -0.2897, -0.3918,  0.4963],
        [-0.3744,  0.9381,  1.2685, -1.6070],
        [ 0.7208, -1.8058, -2.4419,  3.0936],
        [ 0.1713, -0.4291, -0.5802,  0.7350],
        [ 0.5704, -1.4290, -1.9323,  2.4480]])

>>> # batch matrix multiplication
>>> # xdoctest: +IGNORE_WANT("non-deterministic")
>>> As = torch.randn(3,2,5)
>>> Bs = torch.randn(3,5,4)
>>> torch.einsum('bij,bjk->bik', As, Bs)
tensor([[[-1.0564, -1.5904,  3.2023,  3.1271],
        [-1.6706, -0.8097, -0.8025, -2.1183]],

        [[ 4.2239,  0.3107, -0.5756, -0.2354],
        [-1.4558, -0.3460,  1.5087, -0.8530]],

        [[ 2.8153,  1.8787, -4.3839, -1.2112],
        [ 0.3728, -2.1131,  0.0921,  0.8305]]])

>>> # with sublist format and ellipsis
>>> # xdoctest: +IGNORE_WANT("non-deterministic")
>>> torch.einsum(As, [..., 0, 1], Bs, [..., 1, 2], [..., 0, 2])
tensor([[[-1.0564, -1.5904,  3.2023,  3.1271],
        [-1.6706, -0.8097, -0.8025, -2.1183]],

        [[ 4.2239,  0.3107, -0.5756, -0.2354],
        [-1.4558, -0.3460,  1.5087, -0.8530]],

        [[ 2.8153,  1.8787, -4.3839, -1.2112],
        [ 0.3728, -2.1131,  0.0921,  0.8305]]])

>>> # batch permute
>>> A = torch.randn(2, 3, 4, 5)
>>> torch.einsum('...ij->...ji', A).shape
torch.Size([2, 3, 5, 4])

>>> # equivalent to torch.nn.functional.bilinear
>>> A = torch.randn(3,5,4)
>>> l = torch.randn(2,5)
>>> r = torch.randn(2,4)
>>> torch.einsum('bn,anm,bm->ba', l, A, r)
tensor([[-0.3430, -5.2405,  0.4494],
        [ 0.3311,  5.5201, -3.0356]])
Return type:

Tensor

Parameters:

args (Any) –

ensure_complex(*xs)[source]

Ensure that all tensors are of complex dtype.

Reshape and convert if necessary.

Parameters:

xs (Tensor) – the tensors

Yields:

complex tensors.

Return type:

Iterable[Tensor]

ensure_ftp_directory(*, ftp, directory)[source]

Ensure the directory exists on the FTP server.

Return type:

None

Parameters:

  • ftp (FTP) –

  • directory (str) –

ensure_torch_random_state(random_state)[source]

Prepare a random state for PyTorch.

Return type:

Generator

Parameters:

random_state (None | int | Generator) –

ensure_tuple(*x)[source]

Ensure that all elements in the sequence are upgraded to sequences.

Parameters:

x (Union[~X, Sequence[~X]]) – A sequence of sequences or literals

Return type:

Sequence[Sequence[~X]]

Returns:

An upgraded sequence of sequences

>>> ensure_tuple(1, (1,), (1, 2))
((1,), (1,), (1, 2))
estimate_cost_of_sequence(shape, *other_shapes)[source]

Cost of a sequence of broadcasted element-wise operations of tensors, given their shapes.

Return type:

int

Parameters:
extend_batch(batch, max_id, dim, ids=None)[source]

Extend batch for 1-to-all scoring by explicit enumeration.

Parameters:

  • batch (LongTensor) – shape: (batch_size, 2) The batch.

  • max_id (int) – The maximum IDs to enumerate.

  • ids (Optional[LongTensor]) – shape: (num_ids,) | (batch_size, num_ids) explicit IDs

  • dim (int) – in {0,1,2} The column along which to insert the enumerated IDs.

Return type:

LongTensor

Returns:

shape: (batch_size * num_choices, 3) A large batch, where every pair from the original batch is combined with every ID.

fix_dataclass_init_docs(cls)[source]

Fix the __init__ documentation for a dataclasses.dataclass.

Parameters:

cls (Type) – The class whose docstring needs fixing

Return type:

Type

Returns:

The class that was passed so this function can be used as a decorator

See also

https://github.com/agronholm/sphinx-autodoc-typehints/issues/123

flatten_dictionary(dictionary, prefix=None, sep='.')[source]

Flatten a nested dictionary.

Return type:

Dict[str, Any]

Parameters:
format_relative_comparison(part, total)[source]

Format a relative comparison.

Return type:

str

Parameters:

  • part (int) –

  • total (int) –

get_batchnorm_modules(module)[source]

Return all submodules which are batch normalization layers.

Return type:

List[Module]

Parameters:

module (Module) –

get_benchmark(name)[source]

Get the benchmark directory for this version.

Return type:

Path

Parameters:

name (str) –

get_connected_components(pairs)[source]

Calculate the connected components for a graph given as edge list.

The implementation uses a union-find data structure with path compression.

Parameters:

pairs (Iterable[Tuple[~X, ~X]]) – the edge list, i.e., pairs of node ids.

Return type:

Collection[Collection[~X]]

Returns:

a collection of connected components, i.e., a collection of disjoint collections of node ids.

get_devices(module)[source]

Return the device(s) from each components of the model.

Return type:

Collection[device]

Parameters:

module (Module) –

get_df_io(df)[source]

Get the dataframe as bytes.

Return type:

BytesIO

Parameters:

df (DataFrame) –

get_dropout_modules(module)[source]

Return all submodules which are dropout layers.

Return type:

List[Module]

Parameters:

module (Module) –

get_edge_index(*, triples_factory=None, mapped_triples=None, edge_index=None)[source]

Get the edge index from a number of different sources.

Parameters:

  • triples_factory (Optional[Any]) – the triples factory

  • mapped_triples (Optional[LongTensor]) – shape: (m, 3) ID-based triples

  • edge_index (Optional[LongTensor]) – shape: (2, m) the edge index

Raises:

ValueError – if none of the source was different from None

Return type:

LongTensor

Returns:

shape: (2, m) the edge index

get_expected_norm(p, d)[source]

Compute the expected value of the L_p norm.

\[E[\|x\|_p] = d^{1/p} E[|x_1|^p]^{1/p}\]

under the assumption that \(x_i \sim N(0, 1)\), i.e.

\[E[|x_1|^p] = 2^{p/2} \cdot \Gamma(\frac{p+1}{2} \cdot \pi^{-1/2}\]
Parameters:

  • p (Union[int, float, str]) – The parameter p of the norm.

  • d (int) – The dimension of the vector.

Return type:

float

Returns:

The expected value.

Raises:

See also

https://math.stackexchange.com/questions/229033/lp-norm-of-multivariate-standard-normal-random-variable https://www.wolframalpha.com/input/?i=expected+value+of+%7Cx%7C%5Ep

get_json_bytes_io(obj)[source]

Get the JSON as bytes.

Return type:

BytesIO

get_model_io(model)[source]

Get the model as bytes.

Return type:

BytesIO

get_optimal_sequence(*shapes)[source]

Find the optimal sequence in which to combine tensors elementwise based on the shapes.

Parameters:

shapes (Tuple[int, …]) – The shapes of the tensors to combine.

Return type:

Tuple[int, Tuple[int, …]]

Returns:

The optimal execution order (as indices), and the cost.

get_preferred_device(module, allow_ambiguity=True)[source]

Return the preferred device.

Return type:

device

Parameters:
get_until_first_blank(s)[source]

Recapitulate all lines in the string until the first blank line.

Return type:

str

Parameters:

s (str) –

invert_mapping(mapping)[source]

Invert a mapping.

Parameters:

mapping (Mapping[~K, ~V]) – The mapping, key -> value.

Return type:

Mapping[~V, ~K]

Returns:

The inverse mapping, value -> key.

Raises:

ValueError – if the mapping is not bijective

is_cuda_oom_error(runtime_error)[source]

Check whether the caught RuntimeError was due to CUDA being out of memory.

Return type:

bool

Parameters:

runtime_error (RuntimeError) –

is_cudnn_error(runtime_error)[source]

Check whether the caught RuntimeError was due to a CUDNN error.

Return type:

bool

Parameters:

runtime_error (RuntimeError) –

is_triple_tensor_subset(a, b)[source]

Check whether one tensor of triples is a subset of another one.

Return type:

bool

Parameters:

  • a (LongTensor) –

  • b (LongTensor) –

isin_many_dim(elements, test_elements, dim=0)[source]

Return whether elements are contained in test elements.

Return type:

BoolTensor

Parameters:
logcumsumexp(a)[source]

Compute log(cumsum(exp(a))).

Parameters:

a (ndarray) – shape: s the array

Return type:

ndarray

Returns:

shape s the log-cumsum-exp of the array

See also

scipy.special.logsumexp() and torch.logcumsumexp()

lp_norm(x, p, dim, normalize)[source]

Return the \(L_p\) norm.

Return type:

FloatTensor

Parameters:

  • x (FloatTensor) –

  • p (float) –

  • dim (int | None) –

  • normalize (bool) –

negative_norm(x, p=2, power_norm=False)[source]

Evaluate negative norm of a vector.

Parameters:
Return type:

FloatTensor

Returns:

shape: (batch_size, num_heads, num_relations, num_tails) The scores.

negative_norm_of_sum(*x, p=2, power_norm=False)[source]

Evaluate negative norm of a sum of vectors on already broadcasted representations.

Parameters:
Return type:

FloatTensor

Returns:

shape: (batch_size, num_heads, num_relations, num_tails) The scores.

nested_get(d, *key, default=None)[source]

Get from a nested dictionary.

Parameters:

  • d (Mapping[str, Any]) – the (nested) dictionary

  • key (str) – a sequence of keys

  • default – the default value

Return type:

Any

Returns:

the value or default

normalize_path(path, *other, mkdir=False, is_file=False, default=None)[source]

Normalize a path.

Parameters:

  • path (Union[str, Path, TextIO, None]) – the path in either of the valid forms.

  • other (Union[str, Path]) – additional parts to join to the path

  • mkdir (bool) – whether to ensure that the path refers to an existing directory by creating it if necessary

  • is_file (bool) – whether the path is intended to be a file - only relevant for creating directories

  • default (Union[None, str, Path, TextIO]) – the default to use if path is None

Raises:
Return type:

Path

Returns:

the absolute and resolved path

normalize_string(s, *, suffix=None)[source]

Normalize a string for lookup.

Return type:

str

Parameters:

  • s (str) –

  • suffix (str | None) –

point_to_box_distance(points, box_lows, box_highs)[source]

Compute the point to box distance function proposed by [abboud2020] in an element-wise fashion.

Parameters:

  • points (FloatTensor) – shape: (*, d) the positions of the points being scored against boxes

  • box_lows (FloatTensor) – shape: (*, d) the lower corners of the boxes

  • box_highs (FloatTensor) – shape: (*, d) the upper corners of the boxes

Return type:

FloatTensor

Returns:

Element-wise distance function scores as per the definition above

Given points \(p\), box_lows \(l\), and box_highs \(h\), the following quantities are defined:

  • Width \(w\) is the difference between the upper and lower box bound: \(w = h - l\)

  • Box centers \(c\) are the mean of the box bounds: \(c = (h + l) / 2\)

Finally, the point to box distance \(dist(p,l,h)\) is defined as the following piecewise function:

\[\begin{split}dist(p,l,h) = \begin{cases} |p-c|/(w+1) & l <= p <+ h \\ |p-c|*(w+1) - 0.5*w*((w+1)-1/(w+1)) & otherwise \\ \end{cases}\end{split}\]

powersum_norm(x, p, dim, normalize)[source]

Return the power sum norm.

Return type:

FloatTensor

Parameters:

  • x (FloatTensor) –

  • p (float) –

  • dim (int | None) –

  • normalize (bool) –

prepare_filter_triples(mapped_triples, additional_filter_triples=None, warn=True)[source]

Prepare the filter triples from the evaluation triples, and additional filter triples.

Return type:

LongTensor

Parameters:

  • mapped_triples (LongTensor) –

  • additional_filter_triples (None | LongTensor | List[LongTensor]) –

  • warn (bool) –

product_normalize(x, dim=-1)[source]

Normalize a tensor along a given dimension so that the geometric mean is 1.0.

Parameters:

  • x (FloatTensor) – shape: s An input tensor

  • dim (int) – the dimension along which to normalize the tensor

Return type:

FloatTensor

Returns:

shape: s An output tensor where the given dimension is normalized to have a geometric mean of 1.0.

project_entity(e, e_p, r_p)[source]

Project entity relation-specific.

\[e_{\bot} = M_{re} e = (r_p e_p^T + I^{d_r \times d_e}) e = r_p e_p^T e + I^{d_r \times d_e} e = r_p (e_p^T e) + e'\]

and additionally enforces

\[\|e_{\bot}\|_2 \leq 1\]
Parameters:

  • e (FloatTensor) – shape: (…, d_e) The entity embedding.

  • e_p (FloatTensor) – shape: (…, d_e) The entity projection.

  • r_p (FloatTensor) – shape: (…, d_r) The relation projection.

Return type:

FloatTensor

Returns:

shape: (…, d_r)

random_non_negative_int()[source]

Generate a random positive integer.

Return type:

int

rate_limited(xs, min_avg_time=1.0)[source]

Iterate over iterable with rate limit.

Parameters:

  • xs (Iterable[~X]) – the iterable

  • min_avg_time (float) – the minimum average time per element

Yields:

elements of the iterable

Return type:

Iterable[~X]

resolve_device(device=None)[source]

Resolve a torch.device given a desired device (string).

Return type:

device

Parameters:

device (str | device | None) –

set_random_seed(seed)[source]

Set the random seed on numpy, torch, and python.

Parameters:

seed (int) – The seed that will be used in np.random.seed(), torch.manual_seed(), and random.seed().

Return type:

Tuple[None, Generator, None]

Returns:

A three tuple with None, the torch generator, and None.

split_complex(x)[source]

Split a complex tensor into real and imaginary part.

Return type:

Tuple[FloatTensor, FloatTensor]

Parameters:

x (FloatTensor) –

split_list_in_batches_iter(input_list, batch_size)[source]

Split a list of instances in batches of size batch_size.

Return type:

Iterable[List[~X]]

Parameters:

  • input_list (List[X]) –

  • batch_size (int) –

tensor_product(*tensors)[source]

Compute element-wise product of tensors in broadcastable shape.

Return type:

FloatTensor

Parameters:

tensors (FloatTensor) –

tensor_sum(*tensors)[source]

Compute element-wise sum of tensors in broadcastable shape.

Return type:

FloatTensor

Parameters:

tensors (FloatTensor) –

triple_tensor_to_set(tensor)[source]

Convert a tensor of triples to a set of int-tuples.

Return type:

Set[Tuple[int, …]]

Parameters:

tensor (LongTensor) –

unpack_singletons(*xs)[source]

Unpack sequences of length one.

Parameters:

xs (Tuple[~X]) – A sequence of tuples of length 1 or more

Return type:

Sequence[Union[~X, Tuple[~X]]]

Returns:

An unpacked sequence of sequences

>>> unpack_singletons((1,), (1, 2), (1, 2, 3))
(1, (1, 2), (1, 2, 3))
upgrade_to_sequence(x)[source]

Ensure that the input is a sequence.

Note

While strings are technically also a sequence, i.e.,

isinstance("test", typing.Sequence) is True

this may lead to unexpected behaviour when calling upgrade_to_sequence(“test”). We thus handle strings as non-sequences. To recover the other behavior, the following may be used:

upgrade_to_sequence(tuple("test"))
Parameters:

x (Union[~X, Sequence[~X]]) – A literal or sequence of literals

Return type:

Sequence[~X]

Returns:

If a literal was given, a one element tuple with it in it. Otherwise, return the given value.

>>> upgrade_to_sequence(1)
(1,)
>>> upgrade_to_sequence((1, 2, 3))
(1, 2, 3)
>>> upgrade_to_sequence("test")
('test',)
>>> upgrade_to_sequence(tuple("test"))
('t', 'e', 's', 't')
view_complex(x)[source]

Convert a PyKEEN complex tensor representation into a torch one.

Return type:

Tensor

Parameters:

x (FloatTensor) –

env(file=None)[source]

Print the env or output as HTML if in Jupyter.

Parameters:

file – The file to print to if not in a Jupyter setting. Defaults to sys.stdout

Returns:

A IPython.display.HTML if in a Jupyter notebook setting, otherwise none.

Version information for PyKEEN.

get_git_branch()[source]

Get the PyKEEN branch, if installed from git in editable mode.

Return type:

Optional[str]

Returns:

Returns the name of the current branch, or None if not installed in development mode.

get_git_hash(terse=True)[source]

Get the PyKEEN git hash.

Parameters:

terse (bool) – Should the hash be clipped to 8 characters?

Return type:

str

Returns:

The git hash, equals ‘UNHASHED’ if encountered CalledProcessError, signifying that the code is not installed in development mode.

get_version(with_git_hash=False)[source]

Get the PyKEEN version string, including a git hash.

Parameters:

with_git_hash (bool) – If set to True, the git hash will be appended to the version.

Return type:

str

Returns:

The PyKEEN version as well as the git hash, if the parameter with_git_hash was set to true.