openfl.interface.interactive_api.experiment.FLExperiment

class openfl.interface.interactive_api.experiment.FLExperiment(federation, experiment_name: str | None = None, serializer_plugin: str = 'openfl.plugins.interface_serializer.cloudpickle_serializer.CloudpickleSerializer')

Bases: object

Central class for FL experiment orchestration.

This class is responsible for orchestrating the federated learning experiment. It manages the experiment’s lifecycle and interacts with the federation.

Class Attributes:

federation – The federation that this experiment is part of.
experiment_name (str) – The name of the experiment.
summary_writer (SummaryWriter) – The summary writer.
serializer_plugin (str) – The serializer plugin to use.
experiment_submitted (bool) – Whether the experiment has been submitted.
is_validate_task_exist (bool) – Whether a validate task exists.
logger (Logger) – The logger to use.
plan (Plan) – The plan for the experiment.

Methods

`define_task_assigner`	Define task assigner by registered tasks.
`get_best_model`	Retrieve the model with the best score.
`get_experiment_status`	Returns the current state of the experiment.
`get_last_model`	Retrieve the aggregated model after the last round.
`prepare_workspace_distribution`	Prepare an archive from a user workspace.
`remove_experiment_data`	Remove experiment data.
`remove_workspace_archive`	Remove the workspace archive.
`restore_experiment_state`	Restores the state of an accepted experiment object.
`start`	Prepare workspace distribution and send to Director.
`stream_metrics`	Stream metrics.
`write_tensorboard_metric`	Write metric callback.

define_task_assigner(task_keeper, rounds_to_train)

Define task assigner by registered tasks.

This method defines a task assigner based on the registered tasks. It checks if there are ‘train’ and ‘validate’ tasks among the registered tasks and defines the task assigner accordingly. If there are both ‘train’ and ‘validate’ tasks, the task assigner assigns these tasks to each collaborator. If there are only ‘validate’ tasks, the task assigner assigns only these tasks to each collaborator. If there are no ‘train’ or ‘validate’ tasks, an exception is raised.

Parameters:

task_keeper – The task keeper object that holds the registered tasks.
rounds_to_train (int) – The number of rounds to train.

Returns:

assigner – A function that assigns tasks to each collaborator.

Raises:

Exception – If there are no ‘train’ tasks and rounds_to_train is not 1.
Exception – If there are no ‘validate’ tasks.
Exception – If there are no ‘train’ or ‘validate’ tasks.

get_best_model(): Retrieve the model with the best score.

get_experiment_status(): Returns the current state of the experiment.

get_last_model(): Retrieve the aggregated model after the last round.

prepare_workspace_distribution(model_provider, task_keeper, data_loader, task_assigner, pip_install_options: Tuple[str] = ())

Prepare an archive from a user workspace.

This method serializes interface objects and saves them to disk, dumps the prepared plan, prepares a requirements file to restore the Python environment, and compresses the workspace to restore it on a collaborator.

Parameters:

model_provider – The model provider object.
task_keeper – The task keeper object.
data_loader – The data loader object.
task_assigner – The task assigner object.
pip_install_options (tuple, optional) – A tuple of options for pip install. Defaults to an empty tuple.

Returns:

None

remove_experiment_data(): Remove experiment data.

remove_workspace_archive(): Remove the workspace archive.

restore_experiment_state(model_provider)

Restores the state of an accepted experiment object.

This method restores the state of an accepted experiment object by getting the core task runner from the plan and setting the current model status to RESTORED. It also sets the experiment_submitted attribute to True.

Parameters:: model_provider – The provider of the model used in the experiment.

start(*, model_provider, task_keeper, data_loader, rounds_to_train: int, task_assigner=None, override_config: dict | None = None, delta_updates: bool = False, opt_treatment: str = 'RESET', device_assignment_policy: str = 'CPU_ONLY', pip_install_options: Tuple[str] = ()) → None

Prepare workspace distribution and send to Director.

A successful call of this function will result in sending the experiment workspace to the Director service and experiment start.

Parameters:

model_provider – Model Interface instance.
task_keeper – Task Interface instance.
data_loader – Data Interface instance.
rounds_to_train (int) – Required number of training rounds for the experiment.
task_assigner (optional) – Task assigner instance. Defaults to None.
override_config (dict, optional) – Configuration to override the default settings. Defaults to None.
delta_updates (bool, optional) – Flag to indicate if delta updates should be sent. Defaults to False.
opt_treatment (str, optional) – Optimizer state treatment policy. Defaults to ‘RESET’. Valid options: ‘RESET’ - reinitialize optimizer for every round, ‘CONTINUE_LOCAL’ - keep local optimizer state, ‘CONTINUE_GLOBAL’ - aggregate optimizer state.
device_assignment_policy (str, optional) – Device assignment policy. Defaults to ‘CPU_ONLY’. Valid options: ‘CPU_ONLY’ - device parameter passed to tasks will always be ‘cpu’, ‘CUDA_PREFERRED’ - enable passing CUDA device identifiers to tasks by collaborators, works with cuda-device-monitor plugin equipped Envoys.
pip_install_options (Tuple[str], optional) – Options for the remote pip install calls. Defaults to (). example: (‘-f some.website’, ‘–no-index’)

stream_metrics(tensorboard_logs: bool = True) → None: Stream metrics.

write_tensorboard_metric(metric: dict) → None: Write metric callback.