ParametersRecord

class ParametersRecord(array_dict: OrderedDict[str, Array] | None = None, keep_input: bool = False)

Bases: TypedDict[str, Array]

Parameters record.

A dataclass storing named Arrays in order. This means that it holds entries as an OrderedDict[str, Array]. ParametersRecord objects can be viewed as an equivalent to PyTorch’s state_dict, but holding serialised tensors instead. A ParametersRecord is one of the types of records that a flwr.common.RecordSet supports and can therefore be used to construct common.Message objects.

Parameters:

• array_dict (Optional[OrderedDict[str, Array]]) – A dictionary that stores serialized array-like or tensor-like objects.

• keep_input (bool (default: False)) – A boolean indicating whether parameters should be deleted from the input dictionary immediately after adding them to the record. If False, the dictionary passed to set_parameters() will be empty once exiting from that function. This is the desired behaviour when working with very large models/tensors/arrays. However, if you plan to continue working with your parameters after adding it to the record, set this flag to True. When set to True, the data is duplicated in memory.

Examples

The usage of ParametersRecord is envisioned for storing data arrays (e.g. parameters of a machine learning model). These first need to be serialized into a flwr.common.Array data structure.

Let’s see some examples:

>>> import numpy as np
>>> from flwr.common import ParametersRecord
>>> from flwr.common import array_from_numpy
>>>
>>> # Let's create a simple NumPy array
>>> arr_np = np.random.randn(3, 3)
>>>
>>> # If we print it
>>> array([[-1.84242409, -1.01539537, -0.46528405],
>>>      [ 0.32991896,  0.55540414,  0.44085534],
>>>      [-0.10758364,  1.97619858, -0.37120501]])
>>>
>>> # Let's create an Array out of it
>>> arr = array_from_numpy(arr_np)
>>>
>>> # If we print it you'll see (note the binary data)
>>> Array(dtype='float64', shape=[3,3], stype='numpy.ndarray', data=b'@\x99\x18...')
>>>
>>> # Adding it to a ParametersRecord:
>>> p_record = ParametersRecord({"my_array": arr})

Now that the NumPy array is embedded into a ParametersRecord it could be sent if added as part of a common.Message or it could be saved as a persistent state of a ClientApp via its context. Regardless of the usecase, we will sooner or later want to recover the array in its original NumPy representation. For the example above, where the array was serialized using the built-in utility function, deserialization can be done as follows:

>>> # Use the Array's built-in method
>>> arr_np_d = arr.numpy()
>>>
>>> # If printed, it will show the exact same data as above:
>>> array([[-1.84242409, -1.01539537, -0.46528405],
>>>      [ 0.32991896,  0.55540414,  0.44085534],
>>>      [-0.10758364,  1.97619858, -0.37120501]])

If you need finer control on how your arrays are serialized and deserialized, you can construct Array objects directly like this:

>>> from flwr.common import Array
>>> # Serialize your array and construct Array object
>>> arr = Array(
>>>         data=ndarray.tobytes(),
>>>         dtype=str(ndarray.dtype),
>>>         stype="",  # Could be used in a deserialization function
>>>         shape=list(ndarray.shape),
>>>       )
>>>
>>> # Then you can deserialize it like this
>>> arr_np_d = np.frombuffer(
>>>             buffer=array.data,
>>>             dtype=array.dtype,
>>>            ).reshape(array.shape)

Note that different arrays (e.g. from PyTorch, Tensorflow) might require different serialization mechanism. Howerver, they often support a conversion to NumPy, therefore allowing to use the same or similar steps as in the example above.

Methods

clear()
count_bytes()	Return number of Bytes stored in this object.
get(k[,d])
items()
keys()
pop(k[,d])	If key is not found, d is returned if given, otherwise KeyError is raised.
popitem()	as a 2-tuple; but raise KeyError if D is empty.
setdefault(k[,d])
update([E, ]**F)	If E present and has a .keys() method, does: for k in E: D[k] = E[k] If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k, v in F.items(): D[k] = v
values()

clear() → None.  Remove all items from D.

count_bytes() → int

Return number of Bytes stored in this object.

Note that a small amount of Bytes might also be included in this counting that correspond to metadata of the serialized object (e.g. of NumPy array) needed for deseralization.

get(k[, d]) → D[k] if k in D, else d.  d defaults to None.

items() → a set-like object providing a view on D's items.

keys() → a set-like object providing a view on D's keys.

pop(k[, d]) → v, remove specified key and return the corresponding value.

If key is not found, d is returned if given, otherwise KeyError is raised.

popitem() → (k, v), remove and return some (key, value) pair

as a 2-tuple; but raise KeyError if D is empty.

setdefault(k[, d]) → D.get(k,d), also set D[k]=d if k not in D

update([E, ]**F) → None.  Update D from mapping/iterable E and F.

If E present and has a .keys() method, does: for k in E: D[k] = E[k] If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k, v in F.items(): D[k] = v

values() → an object providing a view on D's values.