Design: Control API for OpenCLGA UI and Server

We introduced server and client to support GA computation across different devices/computers. But we don't have an UI to control it. Before implementing the UI, we need to define the protocol for them, that is Control API. Control API is comprised of two parts: controls, and events.

Base

Control API is based on the Web Socket API of browsers. All messages are exchanging through the data field of MessageEvent. The basic data payload example can be found as:

    {
      "command": "run",
      "payload": {
        "prob_mutation": 0.15,
        "prob_crossover": 0.8
      }
    }

This JSON object the received MessageEvent object. In the data field, we put a command message which is from UI to request the execution of OpenCLGA. In this message, it has an optional payload which is the crossover and mutation ratio.

A message without payload look like this one:

{
  "command": "run"
}

Besides command message, we have status message and event message. These two messages are from server to UI.

Command Message

Command messages are sent from UI to server. The command message has 6 types: prepare, pause, restore, run, save, stop.

• prepare: this message creates an OpenCLGA instance and calls prepare API. The payload of this type contains generation count, population count, crossover ratio, mutation ratio, extinction options, elitism options. An example can be found:

  {
    "command": "prepare",
    "payload": {
      "termination": {
        "type": "count",
        "count": 100000
      },
      "population": 1000,
      "prob_mutation": 0.1,
      "prob_crossover": 0.8,
      "extinction": {
        "type": "best_avg",
        "diff": 1,
        "ratio": 0.9
      },
      "elitism_mode":{
        "top": 10,
        "every": 100
      }
    }
  }

• pause: this message calls pause API of OpenCLGA. There is no payload needed for this type.
• restore: this message calls restore API of OpenCLGA. The payload of this type is a saved token for restoring. The saved token can be obtained from save event, which is dispatched when OpenCLGA finishes a save operation. An example can be found:

  {
    "command": "prepare",
    "payload": {
      "token": ".........."
    }
  }

• run: this message calls run API of OpenCLGA. The payload of this type is optional. We can override mutation ratio or crossover ratio through this message.
• save: this message calls save API. After OpenCLGA saved, it sends an save event to notify user the saved token. There is no payload of this type.
• stop: this message calls stop API. There is no payload of this type.

Event Message

Event message is used by server to notify something changed.

• stateChanged: this event is sent when a worker's OpenCLGA state changed. An example message can be:

  {
    "type": "stateChanged",
    "data": {
      "worker": 123,
      "state": "running"
    }
  }

• workerConnected: this event is sent when a new worker connected. An example message can be:

  {
    "type": "workerConnected",
    "data": {
      "worker": 123,
      "platform": "Intel",
      "name": "Intel i7 CPU",
      "type": "cpu",
      "ip": "127.0.0.1"
    }
  }

• workerLost: this event is sent when a worker disconnected. An example message can be:

  {
    "type": "workerLost",
    "data": {
      "worker": 123
    }
  }

• generationResult: this event is sent when a worker reports its generation result. The value in best result field is an array of object that object is a candidate value for each genes in the best chromosome. An example message can be:

  {
    "type": "generationResult",
    "data": {
      "worker": 123,
      "result": {
        "best_fitness": 1023,
        "avg_fitness": 2230,
        "worst_fitness": 2340,
        "best_result": [{}, {}, {}]
      }
    }
  }