nvflare.client.cell.api module

Trainer-side Cell Client API for external_process and attach execution.

Rank 0 exchanges materialized tasks and results with ExternalProcessBackend. send() keeps the trainer available until all downstream result transfers settle; other ranks are passive and rely on their training framework’s collectives.

class CellClientAPI(bootstrap_file: str | None = None)[source]

Bases: APISpec

Client API implementation that speaks a Cell protocol to the CJ.

The control-rank task-state API is single-threaded: receive(), send(), and clear() must not be called concurrently.

Create the API from an explicit bootstrap path or the launch environment.

clear()[source]

Clears the cache.

Example

nvflare.client.clear()

get_config() → Dict[source]

Gets the ClientConfig dictionary.

Returns:: A dict of the configuration used in Client API.

Example

config = nvflare.client.get_config()

get_job_id() → str[source]

Gets job id.

Returns:: The current job id.

Example

job_id = nvflare.client.get_job_id()

get_site_name() → str[source]

Gets site name.

Returns:: The site name of this client.

Example

site_name = nvflare.client.get_site_name()

get_task_name() → str[source]

Gets task name.

Returns:: The task name.

Example

task_name = nvflare.client.get_task_name()

init(rank: str | None = None)[source]

Initializes NVFlare Client API environment.

Parameters:: rank (str) – rank of the process for Client API control-path behavior. In distributed training, use the global process rank (for example torchrun’s RANK), not the device-local rank used for GPU placement.
Returns:: None

Example

nvflare.client.init()

is_evaluate() → bool[source]

Returns whether the current task is an evaluate task.

Returns:: True, if the current task is an evaluate task. False, otherwise.

Example

if nvflare.client.is_evaluate():
# perform evaluate task on received model
    ...

is_running() → bool[source]

Returns whether the NVFlare system is up and running.

Returns:: True, if the system is up and running. False, otherwise.

Example

while nvflare.client.is_running():
    # receive model, perform task, send model, etc.
    ...

is_submit_model() → bool[source]

Returns whether the current task is a submit_model task.

Returns:: True, if the current task is a submit_model. False, otherwise.

Example

if nvflare.client.is_submit_model():
# perform submit_model task to obtain the best local model
    ...

is_train() → bool[source]

Returns whether the current task is a training task.

Returns:: True, if the current task is a training task. False, otherwise.

Example

if nvflare.client.is_train():
# perform train task on received model
    ...

log(key: str, value: Any, data_type: AnalyticsDataType, **kwargs)[source]

Logs a key value pair.

We suggest users use the high-level APIs in nvflare/client/tracking.py

Parameters:

key (str) – key string.
value (Any) – value to log.
data_type (AnalyticsDataType) – the data type of the “value”.
kwargs – additional arguments to be included.

Returns:

whether the key value pair is logged successfully

Example

log(
    key=tag,
    value=scalar,
    data_type=AnalyticsDataType.SCALAR,
    global_step=global_step,
    writer=LogWriterName.TORCH_TB,
    **kwargs,
)

receive(timeout: float | None = None) → FLModel | None[source]

Receives model from NVFlare side.

Returns:: An FLModel received.

Example

nvflare.client.receive()

send(model: FLModel, clear_cache: bool = True) → None[source]

Sends the model to NVFlare side.

Parameters:

model (FLModel) – The FLModel object to be sent.
clear_cache (bool) – Whether to clear the cache after send.

Raises:

RuntimeError – If the model cannot be submitted to NVFLARE.

Example

nvflare.client.send(fl_model=FLModel(...))

shutdown()[source]

Stop this trainer session and any process-global F3 runtime it owns.

External-process mode owns its dedicated F3 runtime and shuts it down. Attach mode stops only the session Cell because the externally managed process may share the process-global runtime with other work.

system_info() → Dict[source]

Gets NVFlare system information.

System information will be available after a valid FLModel is received. It does not retrieve information actively.

Note

system information includes job id and site name.

Returns:: A dict of system information.

Example

sys_info = nvflare.client.system_info()