Code Documentation

AppState class

class FeatureCloud.app.engine.app.AppState

Defining custom states

AppState is the class used when programming a FeatureCloud App to create states and to communicate with other clients. Generally, a FeatureCloud app consists of different states that all share the same AppState class. The states themselves are created as classes with the @app_state(“statename”) decorator. See the example below or the template apps for more details.

Attributes:

app: App

name: str

Methods

aggregate_data([operation, use_smpc, ...])	Waits for all participants (including the coordinator instance) to send data and returns the aggregated value.
await_data([n, unwrap, is_json, use_dp, ...])	Waits for n data pieces and returns them.
broadcast_data(data[, send_to_self, use_dp, ...])	Broadcasts data to all participants (only valid for the coordinator instance).
configure_dp([epsilon, delta, sensitivity, ...])	Configures the usage of differential privacy inside the FeatureCloud controller
configure_smpc([exponent, shards, ...])	Configures successive usage of SMPC aggregation performed in the FeatureCloud controller.
gather_data([is_json, use_smpc, use_dp, memo])	Waits for all participants (including the coordinator instance) to send data and returns a list containing the received data pieces.
load(key)	Load allows to access data shared across different AppState instances.
log(msg[, level])	Prints a log message or raises an exception according to the log level.
register()	This is an abstract method that should be implemented by developers it calls AppState.register_transition to register transitions for state.
register_transition(target[, role, name, label])	Registers a transition in the state machine.
run()	It is an abstract method that should be implemented by developers, to execute all local or global operation and calculations of the state.
send_data_to_coordinator(data[, ...])	Sends data to the coordinator instance.
send_data_to_participant(data, destination)	Sends data to a particular participant identified by its ID.
store(key, value)	Store allows to share data across different AppState instances.
update([message, progress, state])	Updates information about the execution.

aggregate_data(operation: SMPCOperation = SMPCOperation.ADD, use_smpc=False, use_dp=False, memo=None)

Waits for all participants (including the coordinator instance) to send data and returns the aggregated value. Will try to convert each data piece to a np.array and aggregate those arrays. Therefore, this method only works for numerical data and all datapieces should be addable.

Parameters:

operationSMPCOperation

specifies the aggregation type

use_smpcbool, default=False

if True, the data to be aggregated is expected to stem from an SMPC aggregation

use_dp: bool, default=False

if True, will assume that data was sent and modified with the controllers differential privacy capacities (with use_dp=true in the corresponding send function). This must be set in the receiving function due to serialization differences with DP

memostr or None, default=None

the string identifying a specific communication round. Any app should ensure that this string is the same over all clients over the same communication round and that a different string is used for each communication round. This ensures that no race condition problems occur

Returns

——-

aggregated value

await_data(n: int = 1, unwrap=True, is_json=False, use_dp=False, use_smpc=False, memo=None)

Waits for n data pieces and returns them. It is highly recommended to use the memo variable when using this method

Parameters:

nint, default=1

number of data pieces to wait for. Is ignored when use_smpc is used as smpc data is aggregated by the controller, therefore only one data piece is given when using smpc

unwrapbool, default=True

if True, will return the first element of the collected data (only useful if n = 1)

is_jsonbool, default=False

[deprecated] when data was sent via DP or SMPC, the data is sent in JSON serialization. This was used to indicate this to deserailize the data correctly, but is now DEPRICATED, use use_smpc/use_dp accordingly instead, they will take care of serialization automatically.

use_dpbool, default=False

if True, will assume that data was sent and modified with the controllers differential privacy capacities (with use_dp=true in the corresponding send function). This must be set in the receiving function due to serialization differences with DP

use_smpc: bool, default=False

if True, will ensure that n is set to 1 and the correct serialization is used (SMPC uses JSON serialization)

memostr or None, default=None

RECOMMENDED TO BE SET FOR THIS METHOD! the string identifying a specific communication round. The same string that is used in this call must be used before in the corresponding sending functions. Any app should ensure that this string is the same over all clients over the same communication round and that a different string is used for each communication round. This ensures that no race condition problems occur.

Returns

——-

list of data pieces (if n > 1 or unwrap = False) or a single data piece (if n = 1 and unwrap = True)

broadcast_data(data, send_to_self=True, use_dp=False, memo=None)

Broadcasts data to all participants (only valid for the coordinator instance).

Parameters:

dataobject

data to be sent

send_to_selfbool

if True, the data will also be sent internally to this coordinator instance

use_dpbool, default=False

Whether to use differential privacy(dp) before sending out the data. To configure the hypterparameters of dp, use the configure_dp method before this method. The receiving method must also use the same setting of the use_dp flag or there will be serialization problems

memostr or None, default=None

the string identifying a specific communication round. This ensures that there are no race condition problems so that the participants and the coordinator can differentiate between this data piece broadcast and other data pieces they receive from the coordinator.

property clients

Contains a list of client IDs of all clients involved in the current learning run.

configure_dp(epsilon: float = 1.0, delta: float = 0.0, sensitivity: Optional[float] = None, clippingVal: float = 10.0, noisetype: DPNoisetype = DPNoisetype.LAPLACE)

Configures the usage of differential privacy inside the FeatureCloud controller

Parameters:

epsilon:float, default = 1.0

the epsilon value determining how much privacy is wanted

deltafloat, default = 0.0

the delta value determining how much privacy is wanted. Should be 0 when using laplace noise (noisetype=DPNoisetype.LAPLACE)

sensitivity: float, default = None

describes the amount of privacy introduced by the function used on the data that was used to create the model that is send with DP. Depends on the function or on the function and the data. If using a clippingVal, the sensitivity must not be defined.

clippingValfloat, default = 10.0

Determines the scaling down of values sent via the controller. if e.g. an array of 5 numeric values ( 5 weights) is sent via the controller and clippingVal = 10.0 is choosen, then the p-norm of all 5 values will not exceed 10. For laplace the 1-norm is choosen, for gauss noise the 2-norm.

noisetype: DPNoisetype.LAPLACE or DPNoisetype.GAUSS, default = DPNoisetype.LAPLACE

The distribution of noise added when adding differential privacy to the model

configure_smpc(exponent: int = 8, shards: int = 0, operation: SMPCOperation = SMPCOperation.ADD, serialization: SMPCSerialization = SMPCSerialization.JSON)

Configures successive usage of SMPC aggregation performed in the FeatureCloud controller.

Parameters:

exponentint, default=8

exponent to be used for converting floating point numbers to fixed-point numbers

shardsint, default=0

number of secrets to be created, if 0, the total number of participants will be used

operationSMPCOperation, default=SMPCOperation.ADD

operation to perform for aggregation. Options are SMPCOperation.ADD and SMPCOperation.MULTIPLY SMPCOperation.MULTIPLY is still experimental and may lead to values being 0 or integer overflows for many clients involved.

serializationSMPCSerialization, default=SMPCSerialization.JSON

serialization to be used for the data, currently only the default Option (SMPCSerialization.JSON) is supported

property coordintor_id

Contains the id of the coordinator

gather_data(is_json=False, use_smpc=False, use_dp=False, memo=None)

Waits for all participants (including the coordinator instance) to send data and returns a list containing the received data pieces. Only valid for the coordinator instance.

Parameters:

is_jsonbool, default=False

[deprecated] when data was sent via DP or SMPC, the data is sent in JSON serialization. This was used to indicate this but is now DEPRICATED, use use_smpc/use_dp accordingly instead, they will take care of serialization automatically.

use_smpc: bool, default=False

Indicated whether the data that is gather was sent using SMPC. If this is not set to True when data was sent using SMPC, this function ends up in an endless loop

use_dp: bool, default=False

if True, will assume that data was sent and modified with the controllers differential privacy capacities (with use_dp=true in the corresponding send function). This must be set in the receiving function due to serialization differences with DP

memostr or None, default=None

the string identifying a specific communication round. Any app should ensure that this string is the same over all clients over the same communication round and that a different string is used for each communication round. This ensures that no race condition problems occur

Returns

——-

list of n data pieces, where n is the number of participants

property id

Contains the id of this client

property is_coordinator

Boolean variable, if True the this AppState instance represents the coordinator. False otherwise.

load(key: str)

Load allows to access data shared across different AppState instances.

Parameters:

key: str

Returns:

value:

Value stored previously using store

log(msg, level: LogLevel = LogLevel.DEBUG)

Prints a log message or raises an exception according to the log level.

Parameters:

msgstr

message to be displayed

levelLogLevel, default=LogLevel.DEBUG

determines the channel (stdout, stderr) or whether to trigger an exception

abstract register()

This is an abstract method that should be implemented by developers it calls AppState.register_transition to register transitions for state. it will be called in App.register method so that, once all states are defined, in a verifiable way, all app transitions can be registered.

register_transition(target: str, role: Role = Role.BOTH, name: Optional[str] = None, label: Optional[str] = None)

Registers a transition in the state machine.

Parameters:

targetstr

name of the target state

roleRole, default=Role.BOTH

role for which this transition is valid

namestr or None, default=None

name of the transition

abstract run() → str

It is an abstract method that should be implemented by developers, to execute all local or global operation and calculations of the state. It will be called in App.run() method so that the state perform its operations.

send_data_to_coordinator(data, send_to_self=True, use_smpc=False, use_dp=False, memo=None)

Sends data to the coordinator instance. Must be used by all clients or all clients except for the coordinator itself when no memo is given, as the automated memo used when using memo=None breaks otherwise. If any subset of clients should communicate with the coordinator, either define the memo or use send_data_to_participant(destination=self.coordintor_id) with a memo.

Parameters:

dataobject

data to be sent

send_to_selfbool, default=True

if True, the data will also be sent internally to this instance (only applies to the coordinator instance)

use_smpcbool, default=False

if True, the data will be sent as part of an SMPC aggregation step

use_dpbool, default=False

Whether to use differential privacy(dp) before sending out the data. To configure the hypterparameters of dp, use the configure_dp method before this method. The receiving method must also use the same setting of the use_dp flag or there will be serialization problems

memostr or None, default=None

the string identifying a specific communication round. This ensures that there are no race condition problems so that the coordinator uses the correct data piece from each client for each communication round. This also ensures that workflows where participants send data to the coordinator without waiting for a response work

send_data_to_participant(data, destination, use_dp=False, memo=None)

Sends data to a particular participant identified by its ID. Should be used for any specific communication to individual clients. For the communication schema of all clients/all clients except the coordinator sending data to the coordinator, use send_data_to_coordinator

Parameters:

dataobject

data to be sent

destinationstr

destination client ID, get this from e.g. self.clients

use_dpbool, default=False

Whether to use differential privacy(dp) before sending out the data. To configure the hypterparameters of dp, use the configure_dp method before this method. The receiving method must also use the same setting of the use_dp flag or there will be serialization problems

memostr or None, default=None

RECOMMENDED TO BE SET FOR THIS METHOD! the string identifying a specific communication round. This ensures that there are no race condition problems and the correct data piece can be identified by the recipient of the data piece sent with this function call. The recipient of this data must use the same memo to identify the data.

store(key: str, value)

Store allows to share data across different AppState instances.

Parameters:

key: str

value:

update(message: Optional[str] = None, progress: Optional[float] = None, state: Optional[State] = None)

Updates information about the execution.

Parameters:

messagestr

message briefly summarizing what is happening currently

progressfloat

number between 0 and 1, indicating the overall progress

stateState or None

overall state (running, error or action_required)

Parameters

class FeatureCloud.app.engine.app.Role(value)

Describes the Role of a client

Can be one of the following values:

Role.PARTICIPANT

Role.COORDINATOR

Role.BOTH

class FeatureCloud.app.engine.app.SMPCOperation(value)

It’s parameters are used to describe SMPC Operations for other functions

One of the following:

SMPCOperation.ADD

SMPCOperation.MULTIPLY

class FeatureCloud.app.engine.app.SMPCSerialization(value)

Describes the serialization used with data when using SMPC, so the format data is send between different components of Featurecloud, e.g. between the app instance and the controller

Currently ony the following is supported

SMPCSerialization.JSON

class FeatureCloud.app.engine.app.LogLevel(value)

The level of a log, given to the log function.

LogLevel.DEBUG: Just for debugging

LogLevel.ERROR: Throws an error but does not halt the program

LogLevel.FATAL: Stops the program