Home

This project provides a serial of APIs used for the interaction of three main components (Simulation and Optimization Orchestrator, Optimization Tool and Simulation Manager) based on parameter optimization in the distributed architecture of the Simulation and Optimization Environment in the CPSWarm project.

All of these APIs are used to transfer messages between the components by integrating an XMPP client to connect with each other through the XMPP server to control the optimization progress, automatically publish their own presence status and backup the optimization status for optimization recovery. They can be divided into three main groups based on their functionalities.

1. eu.cpswarm.optimization.messages

API	Description	Components involved	Type of communication	Data included
SimulatorConfigured	Replies to the simulation configuration files(e.g. fitness script, together with SCID in the description) sent from the SOO through the file transfer function of XMPP standard, indicating if the ST has been successfully configured or not.	Sent by an SM to the SOO after publishing its available presence with SCID.	Text message.	Fields: OID: The IDentifier (ID) of the optimization process. Type: The type of the message (fixed value: SimulatorConfigured). Success: Boolean value.
StartOptimization	Used to start an optimization task with the optimization configuration.	Sent by the SOO to the OT.	Text message.	Fields: OID: a unique ID assigned by the SOO that allows the optimization process to be tracked. Typically, it contains a reference to the corresponding simulation environment as well as the package to be optimized, for example cpswarm_sar. Type: The type of the message (fixed value: StartOptimization). Configuration: a JSON string containing the configuration of the OT. SCID: a simulation configuration ID, which informs the OT, which SMs can participate in the optimization process. The OT monitors SM presence information and will run simulations on any SM configured for this SCID. This allows the SOO to configure and start SMs during an optimization at runtime according to available resources and the desired system performance.
GetOptimizationStatus	Used to get the status of a running optimization, specified by OID.	Sent by the SOO to the OT when receiving the OT optimization status changes.	Text message.	Fields: OID: the ID of the optimization process to enquire about. Type: The type of the message (fixed value: GetOptimizationStatus)
CancelOptimization	Used to cancel a running optimization during a running optimization, specified by OID	Sent by the SOO to the OT.	Text message.	Fields: OID: the ID of the optimization process to cancel. Type: The type of the message (fixed value: CancelOptimization).
OptimizationStatus	Used to reply to the GetOptimizationStatus and CancelOptimization messages.	Sent by the OT to the SOO.	Text message.	Fields: OID: the ID of the optimization process. Type: The type of the message (fixed value: OptimizationStatus). StatusType: The status of the optimization process. Its value should be one of the values emulated in the below OptimizationStatusType API Generation: which generation the optimization is running in. MaxGeneration: The maximum generation to be finished by the optimization BestFitness: The best fitness value in current generation. BestParameters: The best list of optimizaed parameters in current generation. Configuration: The updated parameter optimization configuration, to be backup by SOO to recover the optimization
RunSimulation	Instructs the SM to run a simulation using the specified parameter values. It can be sent by the OT during optimization or by the SOO to request a simple simulation.	Sent by the SOO or by the OT to the SM.	Text message.	Fields: OID: the ID of the optimization process starting the simulation, it’s null when it’s sent by SOO. Type: The type of the message (fixed value: RunSimulation). SID: ID of the simulation, assigned by the OT, and default is 1 when it’s sent by SOO.
RunSimulation	Returns the result of a simulation performed for optimization.	Sent by an SM to the OT during optimization.	Text message.	Fields: OID: The ID of the optimization process. Type: The type of the message (fixed value: SimulationResult). SID: ID of the single simulation. FitnessValue: The fitness of the controller, calculated by the fitness function. Success: Boolean value.

2. eu.cpswarm.optimization.statuses

API	Description	Components involved	Type of communication	Data included
OptimizationStatusType	Enumaration of the possible status of the optimization process. It’s a field of the OptimizationStatus API, but also a field of OptimizationTaskStatus API	Sent by a OT to the SOO through the OptimizationStatus message, or published by OT through its available presence when optimization status is changed	Text message.	Enumeration: None: unknown optimization process. Started: Optimization is started, reply to the StartOptimization message Running: Optimization is running. ErrorOptimizationFaild: Optimization is failed in OT side due to unknown error Cancelled: Optimization is cancelled by request from SOO Complete: Optimization is completed successfully
OptimizationToolStatus	Used by OT to publish its Available presence together with its status(the serialized json string of this class instance) in case one running optimization status is changed	Published by the OT. It can be received by all components	Text message.	Fields: tasks: a list of OptimizationTaskStatus messages. It means one OT instance can manage multiple optimization processes at same time Type: The type of the message (fixed value: OptimizationTool). It indicates that the publisher of the presence.
OptimizationTaskStatus	Used by OT to record the info of each optimization process	Generated and integrated as a field in the OptimizationToolStatus by OT when publishing the OT presence status.	Text message.	Fields: OID: the ID of a specific optimization process StatusType: The status of current optimization process, its value is one of the emulation in the OptimizationStatusType API BestFitness: The best fitness value in current generation for the optimization. Generation: which generation the optimization is running in. MaxGeneration: The maximum generation to be finished by the optimization.
SOOStatus	Used by SOO to publish its Available presence together with its status (the serialized json string of this class instance) to indicate the current optimization info	Published by the SOO. It can be received by all components	Text message.	Fields: TaskId: the ID of current optimization process managed by SOO SCID: the simulation configuration ID hold by all available SMs used by current optimization Type: The type of the message (fixed value: SOO). It indicates that the publisher of the resence.
SimulationManagerCapability	Used by SM to specify its capabilities, this info will be used by SOO to select the available SMs for the optimization.	Generated and integrated as a field in the SimulationManagerStatus message by SM.	Text message.	Fields: Dimensions: the supported dimension of the simulator, possible values: any, 2D, 3D MaxAgents: The maximum number of agents that the SM can support
SimulationManagerStatus	Used by the SM to publish its Available presence together with its status (the serialized JSON string of this class instance) to indicate its capability used by SOO when it starts up and if it’s configured which is useful for OT to recognize available SM.	Published by the SM, received by all components.	Text message.	Fields: SCID: the simulation configuration ID of the SM received during the file transfer process from SOO. It’s used by OT to filter all SMs for optimization process. Type: The type of message (fixed value: SimulationManager). It indicates that the publisher of the presence SID: ID of the simulation, assigned by the OT, and default is 1 when it’s sent by SOO. Capability: the capabilities of the SM

3. eu.cpswarm.optimization.parameters

API	Description	Components involved	Type of communication	Data included
ParameterDefinition	The definition of the parameters which include the key information used in the simulation run to control the result. These parameters are to be optimized in optimization. OT will generate the parameter values based on the definition	Sent from an SOO to OT through the optimization configuration message integrated into the StartOptimization message	Text message.	Emulation: name: the name of the parameter. meta: the meta-information of the parameter minimum: the minimum value of the parameter maximum: the maximum value of the parameter scale: the number to increase by when scale for each time
Parameter	A specific parameter object generated by OT based on the definition. It will be sent to SM by inserted in the RunSimulation message	Sent from OT to SM through RunSimulation message	Text message.	Fields: name: the name of the parameter to be optimized meta: The meta information of the parameter value: parameter value used in simulation packages
Candidate	Used by OT to record the best set of parameter values in the current generation stored in the ParameterOptimizationConfiguration object through an OptimizationStatus message as a reply to GetOptimizationStatus. Or through a StartOptimization sent from SOO to OT	Sent from OT to SOO
Or sent from SOO to OT	Text message.	Fields: Values: an array of int type to store the best set of parameter values Fitness: The current best fitness for the optimization
ParameterOptimizationConfiguration	Used to store the current optimization configuration, it’s a field in the StartOptimization message and the OptimizationStatus message	Sent from OT to SOO through OptimizationStatus message. Or sent from SOO to OT through StartOptimization message	Text message.	Fields: ParameterOptimizationStatus: the ID of current optimization process managed by SOO Candidates: a list of Candidate type to store the current the best set of parameter values. Generation: The current generation that optimization process MaxGeneration: the maximum number of generations to be run by the optimization VariantCount: the number of seeds to be generated for each set of the parameter values, to be sent together with the parameter values in the RunSimulation message MaximumFitness: the highest fitness value of a simulations EliteWeight: the percentage of the sets of parameter values to be selected by OT as validate candidates in the current generation some other fields that are used by OT in the evolutionary algorithm.