Skip to content

Helpers

This module contains the leftover functions that don't fit anywhere else in the utils module!

list2dictionary

Converts some input list to a dictionary. The input list entries can either be objects, in which case the keys are taken as the class name, else a (key, object) tuple can be used to specify a key.

If any duplicate keys are found, the key is appended with an index value. ie if two of the list entries have the same key 'layer', they will be assigned 'layer_0' and layer_1' respectively, depending on their input order in the list.

Parameters:

Name Type Description Default
list_in list

The list of objects to be converted into a dictionary.

 required
ordered bool

Whether to return an ordered or regular dictionary.

 required
allowed_types tuple

The allowed types of layers to be included in the dictionary.

 ()

Returns:

Name Type Description
dictionary dict

The equivalent dictionary or ordered dictionary.
Source code in src/dLux/utils/helpers.py 
 35
 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
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
def list2dictionary(
    list_in: list, ordered: bool, allowed_types: tuple = ()
) -> dict:
    """
    Converts some input list to a dictionary. The input list entries can either be
    objects, in which case the keys are taken as the class name, else a (key, object)
    tuple can be used to specify a key.

    If any duplicate keys are found, the key is appended with an index value. ie if two
    of the list entries have the same key 'layer', they will be assigned 'layer_0' and
    layer_1' respectively, depending on their input order in the list.

    Parameters
    ----------
    list_in : list
        The list of objects to be converted into a dictionary.
    ordered : bool
        Whether to return an ordered or regular dictionary.
    allowed_types : tuple
        The allowed types of layers to be included in the dictionary.

    Returns
    -------
    dictionary : dict
        The equivalent dictionary or ordered dictionary.
    """
    # Construct names list and identify repeats
    names, repeats = [], []
    for item in list_in:
        # Check for specified names
        if isinstance(item, tuple):
            # item, name = item
            name, item = item
        else:
            name = item.__class__.__name__

        # Check input types
        if allowed_types != () and not isinstance(item, allowed_types):
            raise TypeError(
                f"Item {name} is not an allowed type, got " f"{type(item)}"
            )

        # Check for Repeats
        if name in names:
            repeats.append(name)
        names.append(name)

    # Get list of unique repeats
    repeats = list(set(repeats))

    # Iterate over repeat names
    for i in range(len(repeats)):
        # Iterate over names list and append index value to name
        idx = 0
        for j in range(len(names)):
            if repeats[i] == names[j]:
                names[j] = names[j] + "_{}".format(idx)
                idx += 1

    # Turn list into Dictionary
    dict_out = OrderedDict() if ordered else {}
    for i in range(len(names)):
        # Check for spaces in names
        if " " in names[i]:
            raise ValueError(f"Names can not contain spaces, got {names[i]}")

        # Add to dict
        if isinstance(list_in[i], tuple):
            # item = list_in[i][0]
            item = list_in[i][1]
        else:
            item = list_in[i]
        dict_out[names[i]] = item
    return dict_out
map2array

Maps a function across a pytree, flattening it and turning it into an array.

Parameters:

Name Type Description Default
fn Callable

The function to be mapped across the pytree.

 required
tree Any

The pytree to be mapped across.

 required
leaf_fn Callable = None

The function to be used to determine whether a leaf is reached.

 None

Returns:

Name Type Description
array Array

The flattened array of the pytree.
Source code in src/dLux/utils/helpers.py 
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
def map2array(fn: Callable, tree: Any, leaf_fn: Callable = None) -> Array:
    """
    Maps a function across a pytree, flattening it and turning it into an
    array.

    Parameters
    ----------
    fn : Callable
        The function to be mapped across the pytree.
    tree : Any
        The pytree to be mapped across.
    leaf_fn : Callable = None
        The function to be used to determine whether a leaf is reached.

    Returns
    -------
    array : Array
        The flattened array of the pytree.
    """
    if leaf_fn is not None:
        return np.array(tree_flatten(tree_map(fn, tree, is_leaf=leaf_fn))[0])
    else:
        return np.array(tree_flatten(tree_map(fn, tree))[0])
insert_layer

Inserts a layer into a dictionary of layers at a specified index. This function calls the list2dictionary function to ensure all keys remain unique. Note that this can result in some keys being modified if they are duplicates. The input 'layer' can be a tuple of (key, layer) to specify a key, else the key is taken as the class name of the layer.

Parameters:

Name Type Description Default
layers dict

The dictionary of layers to insert the layer into.

 required
layer Any

The layer to be inserted.

 required
index int

The index at which to insert the layer.

 required
type Any

The type of layer to be inserted. Used for type-checking.

 required

Returns:

Name Type Description
layers dict

The updated dictionary of layers.
Source code in src/dLux/utils/helpers.py 
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
def insert_layer(layers: dict, layer: Any, index: int, type: Any) -> dict:
    """
    Inserts a layer into a dictionary of layers at a specified index. This function
    calls the list2dictionary function to ensure all keys remain unique. Note that this
    can result in some keys being modified if they are duplicates. The input 'layer'
    can be a tuple of (key, layer) to specify a key, else the key is taken as the
    class name of the layer.

    Parameters
    ----------
    layers : dict
        The dictionary of layers to insert the layer into.
    layer : Any
        The layer to be inserted.
    index : int
        The index at which to insert the layer.
    type : Any
        The type of layer to be inserted. Used for type-checking.

    Returns
    -------
    layers : dict
        The updated dictionary of layers.
    """
    layers_list = list(zip(layers.keys(), layers.values()))
    layers_list.insert(index, layer)
    return list2dictionary(layers_list, True, type)
remove_layer

Removes a layer from a dictionary of layers, specified by its key.

Parameters:

Name Type Description Default
layers dict

The dictionary of layers to remove the layer from.

 required
key str

The key of the layer to be removed.

 required

Returns:

Name Type Description
layers dict

The updated dictionary of layers.
Source code in src/dLux/utils/helpers.py 
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
def remove_layer(layers: dict, key: str) -> dict:
    """
    Removes a layer from a dictionary of layers, specified by its key.

    Parameters
    ----------
    layers : dict
        The dictionary of layers to remove the layer from.
    key : str
        The key of the layer to be removed.

    Returns
    -------
    layers : dict
        The updated dictionary of layers.
    """
    layers.pop(key)
    return layers