@epfml/discojs 2.1.2-p20240722093114.0 → 2.1.2-p20240723143623.0

package/dist/aggregator/base.d.ts

@@ -100,8 +100,8 @@ export declare abstract class Base<T> {
      */
     log(step: AggregationStep, from?: client.NodeID): void;
     /**
-     * Sets the aggregator's TF.js model.
-     * @param model The new TF.js model
+     * Sets the aggregator's model.
+     * @param model The new model
      */
     setModel(model: Model): void;
     /**
@@ -109,6 +109,7 @@ export declare abstract class Base<T> {
      * peer/client within the network, whom we are communicating with during this aggregation
      * round.
      * @param nodeId The node to be added
+     * @returns True is the node wasn't already in the list of nodes, False if already included
      */
     registerNode(nodeId: client.NodeID): boolean;
     /**

package/dist/aggregator/base.js

@@ -97,7 +97,7 @@ export class Base {
     log(step, from) {
         switch (step) {
             case AggregationStep.ADD:
-                console.log(`> Adding contribution from node ${from ?? '"unknown"'} for round (${this.communicationRound}, ${this.round})`);
+                console.log(`Adding contribution from node ${from ?? '"unknown"'} for round (${this.communicationRound}, ${this.round})`);
                 break;
             case AggregationStep.UPDATE:
                 if (from === undefined) {
@@ -116,8 +116,8 @@ export class Base {
         }
     }
     /**
-     * Sets the aggregator's TF.js model.
-     * @param model The new TF.js model
+     * Sets the aggregator's model.
+     * @param model The new model
      */
     setModel(model) {
         this._model = model;
@@ -127,6 +127,7 @@ export class Base {
      * peer/client within the network, whom we are communicating with during this aggregation
      * round.
      * @param nodeId The node to be added
+     * @returns True is the node wasn't already in the list of nodes, False if already included
      */
     registerNode(nodeId) {
         if (!this.nodes.has(nodeId)) {

package/dist/aggregator/get.d.ts

@@ -1,16 +1,30 @@
 import type { Task } from '../index.js';
 import { aggregator } from '../index.js';
+import type { Model } from "../index.js";
+type AggregatorOptions = Partial<{
+    model: Model;
+    scheme: Task['trainingInformation']['scheme'];
+    roundCutOff: number;
+    threshold: number;
+    thresholdType: 'relative' | 'absolute';
+}>;
 /**
- * Enumeration of the available types of aggregator.
- */
-export declare enum AggregatorChoice {
-    MEAN = 0,
-    SECURE = 1,
-    BANDIT = 2
-}
-/**
- * Provides the aggregator object adequate to the given task.
- * @param task The task
+ * Initializes an aggregator according to the task definition, the training scheme and the aggregator parameters.
+ * Here is the ordered list of parameters used to define the aggregator and its default behavior:
+ * task.trainingInformation.aggregator > options.scheme > task.trainingInformation.scheme
+ *
+ * If `task.trainingInformation.aggregator` is defined, we initialize the chosen aggregator with `options` parameter values.
+ * Otherwise, we default to a MeanAggregator for both training schemes.
+ *
+ * For the MeanAggregator we rely on `options.scheme` and fallback on `task.trainingInformation.scheme` to infer default values.
+ * Unless specified otherwise, for federated learning or local training the aggregator default to waiting
+ * for a single contribution to trigger a model update.
+ * (the server's model update for federated learning or our own contribution if training locally)
+ * For decentralized learning the aggregator defaults to waiting for every nodes' contribution to trigger a model update.
+ *
+ * @param task The task object associated with the current training session
+ * @param options Options passed down to the aggregator's constructor
  * @returns The aggregator
  */
-export declare function getAggregator(task: Task): aggregator.Aggregator;
+export declare function getAggregator(task: Task, options?: AggregatorOptions): aggregator.Aggregator;
+export {};

package/dist/aggregator/get.js

@@ -1,31 +1,48 @@
 import { aggregator } from '../index.js';
 /**
- * Enumeration of the available types of aggregator.
- */
-export var AggregatorChoice;
-(function (AggregatorChoice) {
-    AggregatorChoice[AggregatorChoice["MEAN"] = 0] = "MEAN";
-    AggregatorChoice[AggregatorChoice["SECURE"] = 1] = "SECURE";
-    AggregatorChoice[AggregatorChoice["BANDIT"] = 2] = "BANDIT";
-})(AggregatorChoice || (AggregatorChoice = {}));
-/**
- * Provides the aggregator object adequate to the given task.
- * @param task The task
+ * Initializes an aggregator according to the task definition, the training scheme and the aggregator parameters.
+ * Here is the ordered list of parameters used to define the aggregator and its default behavior:
+ * task.trainingInformation.aggregator > options.scheme > task.trainingInformation.scheme
+ *
+ * If `task.trainingInformation.aggregator` is defined, we initialize the chosen aggregator with `options` parameter values.
+ * Otherwise, we default to a MeanAggregator for both training schemes.
+ *
+ * For the MeanAggregator we rely on `options.scheme` and fallback on `task.trainingInformation.scheme` to infer default values.
+ * Unless specified otherwise, for federated learning or local training the aggregator default to waiting
+ * for a single contribution to trigger a model update.
+ * (the server's model update for federated learning or our own contribution if training locally)
+ * For decentralized learning the aggregator defaults to waiting for every nodes' contribution to trigger a model update.
+ *
+ * @param task The task object associated with the current training session
+ * @param options Options passed down to the aggregator's constructor
  * @returns The aggregator
  */
-export function getAggregator(task) {
-    const error = new Error('not implemented');
-    switch (task.trainingInformation.aggregator) {
-        case AggregatorChoice.MEAN:
-            return new aggregator.MeanAggregator();
-        case AggregatorChoice.BANDIT:
-            throw error;
-        case AggregatorChoice.SECURE:
-            if (task.trainingInformation.scheme !== 'decentralized') {
+export function getAggregator(task, options = {}) {
+    const aggregatorType = task.trainingInformation.aggregator ?? 'mean';
+    const scheme = options.scheme ?? task.trainingInformation.scheme;
+    switch (aggregatorType) {
+        case 'mean':
+            if (scheme === 'decentralized') {
+                // If options are not specified, we default to expecting a contribution from all peers, so we set the threshold to 100%
+                options = {
+                    model: undefined, roundCutOff: undefined, threshold: 1, thresholdType: 'relative',
+                    ...options
+                };
+            }
+            else {
+                // If scheme == 'federated' then we only expect the server's contribution at each round 
+                // so we set the aggregation threshold to 1 contribution
+                // If scheme == 'local' then we only expect our own contribution
+                options = {
+                    model: undefined, roundCutOff: undefined, threshold: 1, thresholdType: 'absolute',
+                    ...options
+                };
+            }
+            return new aggregator.MeanAggregator(options.model, options.roundCutOff, options.threshold, options.thresholdType);
+        case 'secure':
+            if (scheme !== 'decentralized') {
                 throw new Error('secure aggregation is currently supported for decentralized only');
             }
-            return new aggregator.SecureAggregator();
-        default:
-            return new aggregator.MeanAggregator();
+            return new aggregator.SecureAggregator(options.model, task.trainingInformation.maxShareValue);
     }
 }

package/dist/aggregator/index.d.ts

@@ -3,5 +3,5 @@ import type { Base } from './base.js';
 export { Base as AggregatorBase, AggregationStep } from './base.js';
 export { MeanAggregator } from './mean.js';
 export { SecureAggregator } from './secure.js';
-export { getAggregator, AggregatorChoice } from './get.js';
+export { getAggregator } from './get.js';
 export type Aggregator = Base<WeightsContainer>;

package/dist/aggregator/index.js

@@ -1,4 +1,4 @@
 export { Base as AggregatorBase, AggregationStep } from './base.js';
 export { MeanAggregator } from './mean.js';
 export { SecureAggregator } from './secure.js';
-export { getAggregator, AggregatorChoice } from './get.js';
+export { getAggregator } from './get.js';

package/dist/aggregator/mean.d.ts

@@ -1,18 +1,37 @@
 import type { Map } from "immutable";
 import { Base as Aggregator } from "./base.js";
 import type { Model, WeightsContainer, client } from "../index.js";
-/** Mean aggregator whose aggregation step consists in computing the mean of the received weights. */
+type ThresholdType = 'relative' | 'absolute';
+/**
+ * Mean aggregator whose aggregation step consists in computing the mean of the received weights.
+ *
+ */
 export declare class MeanAggregator extends Aggregator<WeightsContainer> {
     #private;
     /**
-     * @param threshold - how many contributions for trigger an aggregation step.
-     *   - relative: 0 < t <= 1, thus requiring t * |nodes| contributions
-     *   - absolute: t > 1, thus requiring t contributions
+     * Create a mean aggregator that averages all weight updates received when a specified threshold is met.
+     * By default, initializes an aggregator that waits for 100% of the nodes' contributions and that
+     * only accepts contributions from the current round (drops contributions from previous rounds).
+     *
+     * @param threshold - how many contributions trigger an aggregation step.
+     * It can be relative (a proportion): 0 < t <= 1, requiring t * |nodes| contributions.
+     * Important: to specify 100% of the nodes, set `threshold = 1` and `thresholdType = 'relative'`.
+     * It can be an absolute number, if t >=1 (then t has to be an integer), the aggregator waits fot t contributions
+     * Note, to specify waiting for a single contribution (such as a federated client only waiting for the server weight update),
+     * set `threshold = 1` and `thresholdType = 'absolute'`
+     * @param thresholdType 'relative' or 'absolute', defaults to 'relative'. Is only used to clarify the case when threshold = 1,
+     * If `threshold != 1` then the specified thresholdType is ignored and overwritten
+     * If `thresholdType = 'absolute'` then `threshold = 1` means waiting for 1 contribution
+     * if `thresholdType = 'relative'` then `threshold = 1`` means 100% of this.nodes' contributions,
+     * @param roundCutoff - from how many past rounds do we still accept contributions.
+     * If 0 then only accept contributions from the current round,
+     * if 1 then the current round and the previous one, etc.
      */
-    constructor(model?: Model, roundCutoff?: number, threshold?: number);
+    constructor(model?: Model, roundCutoff?: number, threshold?: number, thresholdType?: ThresholdType);
     /** Checks whether the contributions buffer is full. */
     isFull(): boolean;
     add(nodeId: client.NodeID, contribution: WeightsContainer, round: number, currentContributions?: number): boolean;
     aggregate(): void;
     makePayloads(weights: WeightsContainer): Map<client.NodeID, WeightsContainer>;
 }
+export {};

package/dist/aggregator/mean.js

@@ -1,34 +1,82 @@
 import { AggregationStep, Base as Aggregator } from "./base.js";
 import { aggregation } from "../index.js";
-/** Mean aggregator whose aggregation step consists in computing the mean of the received weights. */
+/**
+ * Mean aggregator whose aggregation step consists in computing the mean of the received weights.
+ *
+ */
 export class MeanAggregator extends Aggregator {
     #threshold;
+    #thresholdType;
     /**
-     * @param threshold - how many contributions for trigger an aggregation step.
-     *   - relative: 0 < t <= 1, thus requiring t * |nodes| contributions
-     *   - absolute: t > 1, thus requiring t contributions
+     * Create a mean aggregator that averages all weight updates received when a specified threshold is met.
+     * By default, initializes an aggregator that waits for 100% of the nodes' contributions and that
+     * only accepts contributions from the current round (drops contributions from previous rounds).
+     *
+     * @param threshold - how many contributions trigger an aggregation step.
+     * It can be relative (a proportion): 0 < t <= 1, requiring t * |nodes| contributions.
+     * Important: to specify 100% of the nodes, set `threshold = 1` and `thresholdType = 'relative'`.
+     * It can be an absolute number, if t >=1 (then t has to be an integer), the aggregator waits fot t contributions
+     * Note, to specify waiting for a single contribution (such as a federated client only waiting for the server weight update),
+     * set `threshold = 1` and `thresholdType = 'absolute'`
+     * @param thresholdType 'relative' or 'absolute', defaults to 'relative'. Is only used to clarify the case when threshold = 1,
+     * If `threshold != 1` then the specified thresholdType is ignored and overwritten
+     * If `thresholdType = 'absolute'` then `threshold = 1` means waiting for 1 contribution
+     * if `thresholdType = 'relative'` then `threshold = 1`` means 100% of this.nodes' contributions,
+     * @param roundCutoff - from how many past rounds do we still accept contributions.
+     * If 0 then only accept contributions from the current round,
+     * if 1 then the current round and the previous one, etc.
      */
-    // TODO no way to require a single contribution
-    constructor(model, roundCutoff = 0, threshold = 1) {
+    constructor(model, roundCutoff = 0, threshold = 1, thresholdType) {
         if (threshold <= 0)
-            throw new Error("threshold must be striclty positive");
-        if (threshold > 1 && !Number.isInteger(threshold))
-            throw new Error("absolute thresholds must be integeral");
+            throw new Error("threshold must be strictly positive");
+        if (threshold > 1 && (!Number.isInteger(threshold)))
+            throw new Error("absolute thresholds must be integral");
         super(model, roundCutoff, 1);
         this.#threshold = threshold;
+        if (threshold < 1) {
+            // Throw exception if threshold and thresholdType are conflicting
+            if (thresholdType === 'absolute') {
+                throw new Error(`thresholdType has been set to 'absolute' but choosing threshold=${threshold} implies that thresholdType should be 'relative'.`);
+            }
+            this.#thresholdType = 'relative';
+        }
+        else if (threshold > 1) {
+            // Throw exception if threshold and thresholdType are conflicting
+            if (thresholdType === 'relative') {
+                throw new Error(`thresholdType has been set to 'relative' but choosing threshold=${threshold} implies that thresholdType should be 'absolute'.`);
+            }
+            this.#thresholdType = 'absolute';
+        }
+        // remaining case: threshold == 1
+        else {
+            // Print a warning regarding the default behavior when thresholdType is not specified
+            if (thresholdType === undefined) {
+                console.warn("[WARN] Setting the aggregator's threshold to 100% of the nodes' contributions by default. " +
+                    "To instead wait for a single contribution, set thresholdType = 'absolute'");
+                this.#thresholdType = 'relative';
+            }
+            else {
+                this.#thresholdType = thresholdType;
+            }
+        }
     }
     /** Checks whether the contributions buffer is full. */
     isFull() {
-        const actualThreshold = this.#threshold <= 1
+        const thresholdValue = this.#thresholdType == 'relative'
             ? this.#threshold * this.nodes.size
             : this.#threshold;
-        return (this.contributions.get(0)?.size ?? 0) >= actualThreshold;
+        return (this.contributions.get(0)?.size ?? 0) >= thresholdValue;
     }
     add(nodeId, contribution, round, currentContributions = 0) {
         if (currentContributions !== 0)
             throw new Error("only a single communication round");
-        if (!this.nodes.has(nodeId) || !this.isWithinRoundCutoff(round))
+        if (!this.nodes.has(nodeId) || !this.isWithinRoundCutoff(round)) {
+            if (!this.nodes.has(nodeId))
+                console.warn("Contribution rejected because node id is not registered");
+            if (!this.isWithinRoundCutoff(round))
+                console.warn(`Contribution rejected because round ${round} is not within round cutoff`);
             return false;
+        }
         this.log(this.contributions.hasIn([0, nodeId])
             ? AggregationStep.UPDATE
             : AggregationStep.ADD, nodeId);

package/dist/client/base.d.ts

@@ -1,4 +1,3 @@
-import type { Set } from 'immutable';
 import type { Model, Task, WeightsContainer } from '../index.js';
 import type { NodeID } from './types.js';
 import type { EventConnection } from './event_connection.js';
@@ -70,7 +69,7 @@ export declare abstract class Base {
      * @param _round The current training round
      */
     onRoundEndCommunication(_weights: WeightsContainer, _round: number): Promise<void>;
-    get nodes(): Set<NodeID>;
+    get nbOfParticipants(): number;
     get ownId(): NodeID;
     get server(): EventConnection;
 }

package/dist/client/base.js

@@ -70,8 +70,12 @@ export class Base {
      * @param _round The current training round
      */
     async onRoundEndCommunication(_weights, _round) { }
-    get nodes() {
-        return this.aggregator.nodes;
+    // Number of contributors to a collaborative session
+    // If decentralized, it should be the number of peers
+    // If federated, it should the number of participants excluding the server
+    // If local it should be 1
+    get nbOfParticipants() {
+        return this.aggregator.nodes.size; // overriden by the federated client
     }
     get ownId() {
         if (this._ownId === undefined) {

package/dist/client/decentralized/base.d.ts

@@ -1,7 +1,5 @@
 import { type WeightsContainer } from '../../index.js';
 import { Client } from '../index.js';
-import { type PeerConnection } from '../event_connection.js';
-import * as messages from './messages.js';
 /**
  * Represents a decentralized client in a network of peers. Peers coordinate each other with the
  * help of the network's server, yet only exchange payloads between each other. Communication
@@ -14,19 +12,38 @@ export declare class Base extends Client {
      */
     private pool?;
     private connections?;
+    private get isDisconnected();
     /**
-     * Send message to server that this client is ready for the next training round.
+     * Public method called by disco.ts when starting training. This method sends
+     * a message to the server asking to join the task and be assigned a client ID.
+     *
+     * The peer also establishes a WebSocket connection with the server to then
+     * create peer-to-peer WebRTC connections with peers. The server is used to exchange
+     * peers network information.
      */
-    private waitForPeers;
-    protected sendMessagetoPeer(peer: PeerConnection, msg: messages.PeerMessage): void;
+    connect(): Promise<void>;
     /**
-     * Creation of the WebSocket for the server, connection of client to that WebSocket,
-     * deals with message reception from the decentralized client's perspective (messages received by client).
+     * Create a WebSocket connection with the server
+     * The client then waits for the server to forward it other client's network information.
+     * Upon receiving other peer's information, the clients establish a peer-to-peer WebRTC connection.
      */
     private connectServer;
-    connect(): Promise<void>;
     disconnect(): Promise<void>;
+    /**
+     * At the beginning of a round, each peer tells the server it is ready to proceed
+     * The server answers with the list of all peers connected for the round
+     * Given the list, the peers then create peer-to-peer connections with each other.
+     * When connected, one peer creates a promise for every other peer's weight update
+     * and waits for it to resolve.
+     *
+     */
     onRoundBeginCommunication(_: WeightsContainer, round: number): Promise<void>;
-    onRoundEndCommunication(weights: WeightsContainer, round: number): Promise<void>;
+    /**
+     * At each communication rounds, awaits peers contributions and add them to the client's aggregator.
+     * This method is used as callback by getPeers when connecting to the rounds' peers
+     * @param connections
+     * @param round
+     */
     private receivePayloads;
+    onRoundEndCommunication(weights: WeightsContainer, round: number): Promise<void>;
 }