Utilities¶
Utilities for PyKEEN.
-
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
-
abstract
-
all_in_bounds(x, low=None, high=None, a_tol=0.0)[source]¶ Check if tensor values respect lower and upper bound.
-
broadcast_cat(x, y, dim)[source]¶ Concatenate with broadcasting.
- Parameters
x (
FloatTensor) – The first tensor.y (
FloatTensor) – The second tensor.dim (
int) – The concat dimension.
- Return type
FloatTensor- Returns
A concatenated, broadcasted
- Raises
ValueError – if the x and y dimensions are not the same
ValueError – if broadcasting is not possible
-
calculate_broadcasted_elementwise_result_shape(first, second)[source]¶ Determine the return shape of a broadcasted elementwise operation.
-
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
- 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, eps=1e-08)[source]¶ Ensure that a tensor’s norm does not exceeds some threshold.
-
combine_complex(x_re, x_im)[source]¶ Combine a complex tensor from real and imaginary part.
- Return type
FloatTensor
-
compact_mapping(mapping)[source]¶ Update a mapping (key -> id) such that the IDs range from 0 to len(mappings) - 1.
-
class
compose(*operations)[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
-
convert_to_canonical_shape(x, dim, num=None, batch_size=1, suffix_shape=- 1)[source]¶ Convert a tensor to canonical shape.
- Parameters
- Return type
FloatTensor- Returns
shape: (batch_size, num_heads, num_relations, num_tails,
*) A tensor in canonical shape.
-
ensure_ftp_directory(*, ftp, directory)[source]¶ Ensure the directory exists on the FTP server.
- Return type
-
ensure_torch_random_state(random_state)[source]¶ Prepare a random state for PyTorch.
- Return type
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
- 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
-
extend_batch(batch, all_ids, dim)[source]¶ Extend batch for 1-to-all scoring by explicit enumeration.
- Parameters
- 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.
-
extended_einsum(eq, *tensors)[source]¶ Drop dimensions of size 1 to allow broadcasting.
- Return type
FloatTensor
-
get_batchnorm_modules(module)[source]¶ Return all submodules which are batch normalization layers.
- Return type
List[Module]
-
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}\]
-
get_optimal_sequence(*shapes)[source]¶ Find the optimal sequence in which to combine tensors elementwise based on the shapes.
-
get_until_first_blank(s)[source]¶ Recapitulate all lines in the string until the first blank line.
- Return type
-
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
-
is_cudnn_error(runtime_error)[source]¶ Check whether the caught RuntimeError was due to a CUDNN error.
- Return type
-
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.
-
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)
-
resolve_device(device=None)[source]¶ Resolve a torch.device given a desired device (string).
- Return type
device
-
set_random_seed(seed)[source]¶ Set the random seed on numpy, torch, and python.
- Parameters
seed (
int) – The seed that will be used innp.random.seed(),torch.manual_seed(), andrandom.seed().- Return type
- 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]
-
split_list_in_batches_iter(input_list, batch_size)[source]¶ Split a list of instances in batches of size batch_size.
-
tensor_product(*tensors)[source]¶ Compute element-wise product of tensors in broadcastable shape.
- Return type
FloatTensor
-
tensor_sum(*tensors)[source]¶ Compute element-wise sum of tensors in broadcastable shape.
- Return type
FloatTensor
-
torch_is_in_1d(query_tensor, test_tensor, max_id=None, invert=False)[source]¶ Return a boolean mask with
Q[i]in T.The method guarantees memory complexity of
max(size(Q), size(T))and is thus, memory-wise, superior to naive broadcasting.- Parameters
- Return type
BoolTensor- Returns
shape: S A boolean mask.
-
unpack_singletons(*xs)[source]¶ Unpack sequences of length one.
- Parameters
xs (
Tuple[~X]) – A sequence of tuples of length 1 or more- Return type
- 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.
- 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)