firelight.utils package

firelight.utils.dim_utils module

class firelight.utils.dim_utils.SpecFunction(in_specs=None, out_spec=None, collapse_into=None, suppress_spec_adjustment=True)

Bases: object

Class that wraps a function, specified in the method internal(), to be applicable to tensors with of almost arbitrary dimensionality. This is achieved by applying the following steps when the function is called:

• The inputs are reshaped and their dimensions are permuted to match their respective order of dimensions specified in in_specs. Dimensions present in inputs but not requested by in_specs are collapsed in the batch dimension, labeled ‘B’ (per default, see collapse_into). Dimensions not present in the inputs but requested by in_specs are added (with length 1).

• If the batch dimension ‘B’ is present in the in_specs, ‘internal’ is applied on the inputs, returning a tensor with dimensions as specified in out_spec. If ‘B’ is not present in the in_specs, this dimension is iterated over and each slice is individually passed through ‘internal’. The individual outputs are then stacked, recovering the ‘B’ dimension.

• Finally, the output is reshaped. The dimensions previously collapsed into ‘B’ are uncollapsed, and dimensions added in the first step are removed.

Parameters

• in_specs (dict, optional) –

  Dictionary specifying how the dimensionality and order of dimensions of input arguments of internal() should be adjusted.

  • Keys: Names of input arguments (as in signature of internal())

  • Values: List of dimension names. The tensor supplied to internal under the name of the corresponding key will have this order of dimensions.

• out_spec (list, optional) – List of dimension names of the output of internal()

• collapse_into (list, optional) – If given, the default behaviour of collapsing any extra given dimensions of states into the batch dimension ‘B’ is overridden. Each entry of collapse_into must be a two element tuple, with the first element being the dimension to collapse, the second one being the dimension to collapse it into (prior to passing the tensor to internal() ).

• suppress_spec_adjustment (bool, optional) – Argument to completely suppress the adjustment of dimensionalities in call(), for example if it is taken care of in call() of derived class (see firelight.visualizers.base.ConatainerVisualizer)

__call__(*args, out_spec=None, return_spec=False, **kwargs)

Apply the wrapped function to a set of input arguments. Tensors will be reshaped as specified at initialization.

Parameters

• args (list) – List of positional input arguments to the wrapped function. They will be passed to internal() without any processing.

• out_spec (list, optional) – List of dimension names of the output.

• return_spec (bool, optional) – Weather the output should consist of a tuple containing the output tensor and the resulting spec, or only the former.

• **kwargs – Keyword arguments that will be passed to internal(). The ones with names present in SpecFunction.in_specs will be reshaped as required.

Returns

torch.Tensor or tuple

internal(*args, **kwargs)

Function that is being wrapped.

firelight.utils.dim_utils.add_dim(tensor, length=1, new_dim=None, spec=None, return_spec=False)

Adds a single dimension of specified length (achieved by repeating the tensor) to the input tensor.

Parameters

• tensor (torch.Tensor) –

• length (int) – Length of the new dimension.

• new_dim (str, optional) – Name of the new dimension

• spec (list, optional) – Names of dimensions of the input tensor

• return_spec (bool, optional) – If true, a dictionary containing arguments to reverse the conversion (with this function) are added to the output tuple.

Returns

torch.Tensor or tuple

firelight.utils.dim_utils.collapse_dim(tensor, to_collapse, collapse_into=None, spec=None, return_spec=False)

Reshapes the input tensor, collapsing one dimension into another. This is achieved by

• first permuting the tensors dimensions such that the dimension to collapse is next to the one to collapse it into,

• reshaping the tensor, making one dimension out of the to affected.

Parameters

• tensor (torch.Tensor) –

• to_collapse (int or str) – Dimension to be collapsed.

• collapse_into (int or str, optional) – Dimension into which the other will be collapsed.

• spec (list, optional) – Name of dimensions of input tensor. If not specified, will be taken to be range(len(tensor.shape())).

• return_spec (bool, optional) – Weather the output should consist of a tuple containing the output tensor and the resulting spec, or only the former.

Returns

torch.Tensor or tuple

Examples

>>> tensor = torch.Tensor([[1, 2, 3], [10, 20, 30]]).long()
>>> collapse_dim(tensor, to_collapse=1, collapse_into=0)
tensor([ 1,  2,  3, 10, 20, 30])
>>> collapse_dim(tensor, to_collapse=0, collapse_into=1)
tensor([ 1, 10,  2, 20,  3, 30])

firelight.utils.dim_utils.convert_dim(tensor, in_spec, out_spec=None, collapsing_rules=None, uncollapsing_rules=None, return_spec=False, return_inverse_kwargs=False)

Convert the dimensionality of tensor from in_spec to out_spec.

Parameters

• tensor (torch.Tensor) –

• in_spec (list) – Name of dimensions of the input tensor.

• out_spec (list, optional) – Name of dimensions that the output tensor will have.

• collapsing_rules (list of tuple, optional) – List of two element tuples. The first dimension in a tuple will be collapsed into the second (dimensions given by name).

• uncollapsing_rules (list of tuple, optional) – List of three element tuples. The first element of each specifies the dimension to ‘uncollapse’ (=split into two). The second element specifies the size of the added dimension, and the third its name.

• return_spec (bool, optional) – Weather the output should consist of a tuple containing the output tensor and the resulting spec, or only the former.

• return_inverse_kwargs (bool, optional) – If true, a dictionary containing arguments to reverse the conversion (with this function) are added to the output tuple.

Returns

torch.Tensor or tuple

Examples

>>> tensor = torch.Tensor([[1, 2, 3], [10, 20, 30]]).long()
>>> convert_dim(tensor, ['A', 'B'], ['B', 'A'])  
tensor([[ 1, 10],
        [ 2, 20],
        [ 3, 30]])
>>> convert_dim(tensor, ['A', 'B'], collapsing_rules=[('A', 'B')])  
tensor([ 1, 10,  2, 20,  3, 30])
>>> convert_dim(tensor, ['A', 'B'], collapsing_rules=[('B', 'A')])  
tensor([ 1,  2,  3, 10, 20, 30])
>>> convert_dim(tensor.flatten(), ['A'], ['A', 'B'], uncollapsing_rules=[('A', 3, 'B')])  
tensor([[ 1,  2,  3],
        [10, 20, 30]])

firelight.utils.dim_utils.equalize_shapes(tensor_spec_pairs)

Manipulates a list of tensors such that their shapes end up equal.

Axes that are not present in all tensors will be added as a trivial dimension to all tensors that do not have them.

If shapes do not match along a certain axis, the tensors with the smaller shape will be repeated along that axis. Hence, the maximum length along each axis present in the list of tensors must be divisible by the lengths of all other input tensors along that axis.

Parameters

tensor_spec_pairs (list of tuple) – List of two element tuples, each consisting of a tensor and a spec (=list of names of dimensions).

Returns

torch.Tensor

firelight.utils.dim_utils.equalize_specs(tensor_spec_pairs)

Manipulates a list of tensors such that their dimension names (including order of dimensions) match up.

Parameters

tensor_spec_pairs (list of tuple) – List of two element tuples, each consisting of a tensor and a spec (=list of names of dimensions).

Returns

torch.Tensor

firelight.utils.dim_utils.extend_dim(tensor, in_spec, out_spec, return_spec=False)

Adds extra (length 1) dimensions to the input tensor such that it has all the dimensions present in out_spec.

Parameters

• tensor (torch.Tensor) –

• in_spec (list) – spec of the input tensor

• out_spec (list) – spec of the output tensor

• return_spec (bool, optional) – Weather the output should consist of a tuple containing the output tensor and the resulting spec, or only the former.

Returns

torch.Tensor or tuple

Examples

>>> tensor, out_spec = extend_dim(
...     torch.empty(2, 3),
...     ['A', 'B'], ['A', 'B', 'C', 'D'],
...     return_spec=True
... )
>>> print(tensor.shape)
torch.Size([2, 3, 1, 1])
>>> print(out_spec)
['A', 'B', 'C', 'D']

firelight.utils.dim_utils.join_specs(*specs)

Returns a list of dimension names which includes each dimension in any of the supplied specs exactly once, ordered by their occurrence in specs.

Parameters

specs (list) – List of lists of dimension names to be joined

Returns

list

Examples

>>> join_specs(['B', 'C'], ['B', 'H', 'W'])
['B', 'C', 'H', 'W']
>>> join_specs(['B', 'C'], ['H', 'B', 'W'])
['B', 'C', 'H', 'W']

firelight.utils.dim_utils.moving_permutation(length, origin, goal)

Returns a permutation moving the element at position origin to the position goal (in the format requested by torch.Tensor.permute)

Parameters

• length (int) – length of the sequence to be permuted

• origin (int) – position of the element to be moved

• goal (int) – position the element should end up after the permutation

Returns

list of int

Examples

>>> moving_permutation(length=5, origin=1, goal=3)
[0, 2, 3, 1, 4]
>>> moving_permutation(length=5, origin=3, goal=1)
[0, 3, 1, 2, 4]

firelight.utils.dim_utils.uncollapse_dim(tensor, to_uncollapse, uncollapsed_length, uncollapse_into=None, spec=None, return_spec=False)

Splits a dimension in the input tensor into two, adding a dimension of specified length.

Parameters

• tensor (torch.Tensor) –

• to_uncollapse (str or int) – Dimension to be split.

• uncollapsed_length (int) – Length of the new dimension.

• uncollapse_into (str or int, optional) – Name of the new dimension.

• spec (list, optional) – Names or the dimensions of the input tensor

• return_spec (bool, optional) – Weather the output should consist of a tuple containing the output tensor and the resulting spec, or only the former.

Returns

torch.Tensor or tuple

Examples

>>> tensor = torch.Tensor([1, 2, 3, 10, 20, 30]).long()
>>> uncollapse_dim(tensor, 0, 3, 1)  
tensor([[ 1,  2,  3],
        [10, 20, 30]])

firelight.utils.io_utils module

firelight.utils.io_utils.yaml2dict(path)

Read a yaml file.

Parameters

path (str or dict) – Path to the file. If dict, will be returned as is.

Returns

dict