Component: Training Job (TrainingLocalModel)¶
Responsibility¶
Implementation of the local training algorithm executed by FederatedClientService inside the client's Docker container. It is the only piece of code the researcher needs to implement to integrate a new experiment into the framework.
Implementation¶
| Interface | br.ufma.lsdi.experiment.sdk.TrainingLocalModel |
|---|---|
| HAR experiment | br.ufma.lsdi.research.har.HarTrainingLocalModel |
| ECG experiment | br.ufma.lsdi.research.ecg.Ecg5000TrainingLocalModel |
TrainingLocalModel interface¶
public interface TrainingLocalModel {
/** Declares the algorithm and its supported targets. Validated before data access. */
default MlAlgorithmSpec algorithmSpec() {
return MlAlgorithmCatalog.CUSTOM_JAVA_TRAINING_JOB;
}
/**
* Executes local training.
*
* @param context round metadata, authorized data view, hyperparameters
* @return result with the update, metrics, profile, and convergence history
*/
TrainingResult execute(TrainingContext context) throws TrainingException;
}
Mandatory contract for execute()¶
- Read data exclusively from
context.authorizedDataView()— never opendataset.csvdirectly. - Write output files exclusively to
context.outputPath(). - Return a
TrainingResultwith the correct hash and norm. - Never connect to the network or external services.
- Never return an empty vector or one containing
NaN/Inf.
Implemented algorithms¶
1. ExampleTrainingLocalModel — DT (Industrial Digital Twins)¶
Numerical summary of industrial equipment sensors (temperature, vibration, pressure). Synthetic algorithm for validating the framework.
Algorithm: weighted average of features → vector of 3 doubles
Dataset: temperature, vibration, and pressure observations per equipment unit
Target: failure_next_24h (binary classification)
Update: vector of 3 doubles (normalized averages)
Metric: simulated_f1_score (synthetic — not evaluated externally)
2. HarTrainingLocalModel — HAR (Human Activity Recognition)¶
MLP trained with backpropagation for human activity classification using the 561 features of the UCI HAR Dataset.
Architecture: MLP 561 → 256 → 128 → 6
Optimizer: Adam (β₁=0.9, β₂=0.999, ε=1e-8)
Regularization: FedProx (μ=0.01), L2 weight decay, Dropout, Gradient Clipping
Early stopping: patience=3 rounds without improvement (Δ < 0.001)
Dataset: UCI HAR training split by subject (350–700 windows/subject)
Targets: WALKING, WALKING_UPSTAIRS, WALKING_DOWNSTAIRS, SITTING, STANDING, LAYING
Update: full MLP weight vector (≈ 185,474 doubles)
Metric: train_accuracy per epoch + perClassAccuracy
Hyperparameters via RoundConfig.hyperparameters():
| Parameter | Default value | Description |
|---|---|---|
epochs |
10 |
Training epochs per round |
learning_rate |
0.001 |
Adam learning rate |
mu |
0.01 |
FedProx strength (0 = pure FedAvg) |
dropout_rate |
0.3 |
Dropout on the hidden layer |
l2_lambda |
1e-4 |
L2 weight decay |
gradient_clip_norm |
1.0 |
Maximum gradient norm |
early_stopping_patience |
3 |
Epochs without improvement before stopping |
3. Ecg5000TrainingLocalModel — ECG5000 (Anomaly Detection)¶
MLP Autoencoder for anomaly detection in cardiac signals. Applies mandatory Differential Privacy (sensitive health data, LGPD Art. 5, II).
Architecture: Autoencoder 140→64→32→16→32→64→140 (23,388 parameters)
Optimizer: Adam + FedProx (μ=0.01) + L2 weight decay (λ=1e-4)
Training: normal samples only (ecgClass == 1)
Anomaly: reconstruction MSE > adaptive threshold (mean + 2.5·std)
Dataset: ECG5000 TRAIN split partitioned across 5 clients (~100 samples/client)
Metric: reconstruction_loss (average MSE over normal samples)
Differential Privacy (DP-SGD — Abadi et al., CCS 2016):
DP parameter (research.xml <orchestration><privacy>) |
Federated value | Note |
|---|---|---|
clippingNorm (C) |
1.0 |
L2 clipping bound |
noiseMultiplier (σ) |
0.5 |
Calibrated in research.xml (BL-301); note legacy apps (DockerEcgClientApp / Ecg5000MultiRoundExperimentApp) still use 1.1 |
Since BL-081, Differential Privacy is not applied inside Ecg5000TrainingLocalModel: FederatedClientService applies DataComponent.applyDifferentialPrivacyIfConfigured(...) (DifferentialPrivacyMath.clipAndNoise) centrally after validating the raw update hash and before uploading local_update.bin.
TrainingContext — training inputs¶
public record TrainingContext(
String experimentId,
String contractVersion,
long roundId,
Path authorizedDataView, // CSV generated by AuthorizedTrainingViewWriter
Path outputPath, // where to write outputs
Path globalModelPath, // previous model weights (FedProx)
Map<String,String> hyperparameters, // epochs, lr, mu, dropout, ...
PrivacyPolicy privacyPolicy, // dp_enabled, clip_norm, noise_multiplier
StudyDesign studyDesign,
AggregationPolicy aggregationPolicy,
TimeWindow dataWindow
)
TrainingResult — training outputs¶
public record TrainingResult(
Path localUpdatePath, // "local_update.bin"
Path metricsPath, // "metrics.json"
Path dataProfilePath, // "data_profile.json"
String updateHash, // sha256 of local_update.bin
double updateNorm, // L2 norm of the vector
TrainingStatus status, // SUCCESS | FAILED | PREFLIGHT_FAILED | COMPLETED_NOT_SUBMITTED | UPDATE_SUBMITTED
int sampleCount,
int positiveCount,
double localMetric, // e.g., train_accuracy = 0.8312
String localMetricName, // "train_accuracy", "reconstruction_loss"
List<EpochPoint> trainingHistory, // per-epoch convergence
Map<String,Double> perClassAccuracy // HAR: {"WALKING": 0.92, "SITTING": 0.87}
)
EpochPoint:
Output files (written to outputPath)¶
| File | Content |
|---|---|
local_update.bin |
CSV weight vector, e.g.: 0.012,−0.034,0.891,... |
metrics.json |
{"round_id":1,"loss":0.42,"train_accuracy":0.83,"sample_count":350,"update_norm":312.45} |
data_profile.json |
{"sample_count":350,"positive_count":0} |
Validation by FederatedClientService¶
After execute(), the framework validates:
| Check | Condition |
|---|---|
| Non-empty vector | updateVector.length > 0 |
| All finite | !Double.isNaN(v) && !Double.isInfinite(v) |
| Consistent norm | |declared - calculated| ≤ 1e-6 |
| Consistent hash | sha256(file) == result.updateHash() |
| Consistent counts | sampleCount within the authorized profile |
Any mismatch → ErrorCode.UPDATE_REJECTED.
Mandatory rules¶
- Never open
data/{clientId}/{experimentId}/dataset.csvdirectly — usecontext.authorizedDataView(). - Never write files outside
context.outputPath(). - Never connect to the network or external services during training.
- Declare
MlAlgorithmSpecwith supported targets (JVM_SERVER,ANDROID_JAVA, etc.). - Produce a non-empty, finite update vector with a correct hash and norm.
- When convergence history is available, propagate
trainingHistoryfor diagnostics in the monitor. - Sensitive health experiments (such as ECG5000) must configure
<orchestration><privacy>inresearch.xmlsoFederatedClientServiceappliesDataComponent.applyDifferentialPrivacyIfConfigured(...)before upload.