FLComponent

nvflare.apis.fl_component.FLComponent is the base class of all the FL components. Executors, controllers, filters, aggregators, and their subtypes for example trainer are all FLComponents now.

class FLComponent(StatePersistable):
    def __init__(self):
        """Init FLComponent.

        The FLComponent is the base class of all FL Components.
        (executors, controllers, responders, filters, aggregators, and widgets are all FLComponents)

        FLComponents have the capability to handle and fire events and contain various methods for logging.
        """
        self._name = self.__class__.__name__
        self.logger = logging.getLogger(self._name)

    @property
    def name(self):
        return self._name

    def _fire(self, event_type: str, fl_ctx: FLContext):
        fl_ctx.set_prop(FLContextKey.EVENT_ORIGIN, self._name, private=True, sticky=False)
        engine = fl_ctx.get_engine()
        if engine is None:
            self.log_error(fl_ctx=fl_ctx, msg="Logic Error: no engine in fl_ctx: {}".format(fl_ctx), fire_event=False)
        else:
            engine.fire_event(event_type, fl_ctx)

    def fire_event(self, event_type: str, fl_ctx: FLContext):
        """Fires an event.

        Args:
            event_type (str): The type of event.
            fl_ctx (FLContext): FLContext information.
        """
        if not isinstance(event_type, str):
            raise TypeError("expect event_type to be str, but got {}".format(type(event_type)))

        if not event_type:
            raise ValueError("event_type must be specified")

        if not isinstance(fl_ctx, FLContext):
            raise TypeError("expect fl_ctx to be FLContext, but got {}".format(type(fl_ctx)))

        fl_ctx.set_prop(FLContextKey.EVENT_SCOPE, value=EventScope.LOCAL, private=True, sticky=False)
        self._fire(event_type, fl_ctx)

    def fire_fed_event(self, event_type: str, event_data: Shareable, fl_ctx: FLContext, targets=None):
        """Fires a federation event.

        A federation event means that the event will be sent to different sites.
        For example, if fire a federation event on the server side, one can decide what clients to send via the
        parameter `targets`.
        If fire a federation event on the client side, the event will be sent to the server.

        Args:
            event_type (str): The type of event.
            event_data (Shareable): The data of this fed event.
            fl_ctx (FLContext): FLContext information.
            targets: The targets to send to. It is only used when fire federation event from server side.
        """
        if not isinstance(fl_ctx, FLContext):
            raise TypeError("expect fl_ctx to be FLContext, but got {}".format(type(fl_ctx)))

        if not isinstance(event_data, Shareable):
            raise TypeError("expect event_data to be Shareable, but got {}".format(type(event_data)))

Each FLComponent is automatically added as an event handler in the system when a new instance is created. You can implement the handle_event to plugin additional customized actions to the FL workflows.

To fire events, fire_event can be used, and fire_fed_event can be used to fire an event across participants.

The logging methods log_debug, log_info, log_warning, log_error, and log_exception should be used to prefix log messages with contextual information and integrate with other system features.

In extreme cases where the system encounters errors that prevent further operation, task_panic can be called to end the task, or system_panic can be called to end the run.

Default data in the built-in FLComponents

For the built-in FLComponents provided by NVIDIA FLARE, we assure the following data is set in the Shareable and FLContext.

You can also define the structure of Sharable objects that fits your needs and add your training associated data into FLContext.