openapi: 3.0.3
info:
  version: 0.3.0
  title: Schemata for command instructions
servers:
  - url: "."
paths: {}
components:
  schemas:
    # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    # Commands
    # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    Commands:
      description: |-
        List of commands to test algorithms/datastructures.
      type: array
      items:
        $ref: "#/components/schemas/Command"
      default: []
    # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    # Command
    # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    Command:
      description: |-
        Instructions for command to call
      type: object
      required:
        - name
      properties:
        name:
          $ref: '#/components/schemas/EnumAlgorithmNames'
      additionalProperties: true
    # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    # Algorithm: Tarjan
    # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    CommandTarjan:
      description: |-
        Instructions for execution of Tarjan-Algorithm
      type: object
      required:
        - name
        - nodes
        - edges
      properties:
        name:
          $ref: '#/components/schemas/EnumAlgorithmNames'
        nodes:
          type: array
          items:
            anyOf:
              - type: integer
              - type: number
              - type: string
        edges:
          type: array
          items:
            type: array
            minItems: 2
            maxItems: 2
            items:
              anyOf:
                - type: integer
                - type: number
                - type: string
    # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    # Algorithm: TSP
    # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    CommandTsp:
      description: |-
        Instructions for execution of TSP-Algorithm
      type: object
      required:
        - name
        - optimise
        - dist
      properties:
        name:
          $ref: '#/components/schemas/EnumAlgorithmNames'
        dist:
          type: array
          items:
            type: array
            items:
              type: number
        optimise:
          $ref: '#/components/schemas/EnumOptimiseMode'
    # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    # Algorithm: Hirschberg
    # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    CommandHirschberg:
      description: |-
        Instructions for execution of Hirschberg-Algorithm
      type: object
      required:
        - name
        - word1
        - word2
      properties:
        name:
          $ref: '#/components/schemas/EnumAlgorithmNames'
        word1:
          description: Word that gets placed vertically in algorithm.
          type: string
        word2:
          description: Word that gets placed horizontally in algorithm
          type: string
        once:
          type: boolean
          default: false
    # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    # Algorithm: Rucksack Branch & Bound
    # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    CommandRucksack:
      description: |-
        Instructions for execution of Branch & Bound-Algorithm for the Rucksack-Problem
      type: object
      required:
        - name
        - algorithm
        - max-cost
        - costs
        - values
      properties:
        name:
          $ref: '#/components/schemas/EnumAlgorithmNames'
        algorithm:
          $ref: '#/components/schemas/EnumRucksackAlgorithm'
        allow-fractional:
          type: boolean
          default: false
        max-cost:
          description: Upper bound for total cost of rucksack.
          type: number
          minimum: 0
        costs:
          description: Array of cost for each item (e.g. volume, weight, price, time, etc.).
          type: array
          items:
            type: number
            exclusiveMinimum: 0
        values:
          description: Value extracted from each item (e.g. energy, profit, etc.).
          type: array
          items:
            type: number
        items:
          description: Optional names of the items (if empty, defaults to 1-based indexes).
          type: array
          items:
            type: string
          default: []
    # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    # Algorithm: Random Walk
    # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    CommandRandomWalk:
      description: |-
        Instructions for execution of random walks to determine local extrema in a fitness landscape
      type: object
      required:
        - name
        - algorithm
        - landscape
        - optimise
      properties:
        name:
          $ref: '#/components/schemas/EnumAlgorithmNames'
        algorithm:
          $ref: '#/components/schemas/EnumWalkMode'
        landscape:
          $ref: '#/components/schemas/DataTypeLandscapeGeometry'
        optimise:
          $ref: '#/components/schemas/EnumOptimiseMode'
        coords-init:
          description: Initial co-ordinates to start the algorithm.
          type: array
          items:
            type: integer
          minItems: 1
        temperature-init:
          type: float
          default: 1.
        annealing:
          type: boolean
          default: false
        one-based:
          type: boolean
          default: false
    # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    # Algorithm: Genetic Algorithm
    # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    CommandGenetic:
      description: |-
        Instructions for execution of the Genetic algorithm
      type: object
      required:
        - name
        - population
      properties:
        name:
          $ref: '#/components/schemas/EnumAlgorithmNames'
        population:
          type: array
          items:
            type: array
            items:
              type: string
          minItems: 2
          # maxItems: 2 # FIXME: does not work!
    # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    # Algorithm: Euklidean algorithm
    # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    CommandEuklid:
      description: |-
        Instructions for execution of the Euklidean gcd-algorithm
      type: object
      required:
        - name
        - numbers
      properties:
        name:
          $ref: '#/components/schemas/EnumAlgorithmNames'
        numbers:
          type: array
          items:
            type: integer
            exclusiveMinimum: 0
          minItems: 2
          maxItems: 2
    # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    # Algorithm: Pollard's rho
    # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    CommandPollard:
      description: |-
        Instructions for execution of the Pollard's rho algorithm
      type: object
      required:
        - name
        - growth
        - number
      properties:
        name:
          $ref: '#/components/schemas/EnumAlgorithmNames'
        number:
          type: integer
          exclusiveMinimum: 0
        growth:
          $ref: '#/components/schemas/EnumPollardGrowthRate'
        x-init:
          type: integer
          default: 2
          minimum: 2
    # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    # Data-type Landscape Geometry, Landscape Values
    # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    DataTypeLandscapeGeometry:
      description: |-
        Structure for the geometry of a fitness landscape
      type: object
      required:
        - neighbourhoods
        - labels
        - values
      properties:
        neighbourhoods:
          $ref: '#/components/schemas/DataTypeLandscapeNeighbourhoods'
        labels:
          type: array
          items:
            type: string
          minItems: 1
        values:
          $ref: '#/components/schemas/DataTypeLandscapeValues'
    DataTypeLandscapeNeighbourhoods:
      description: |-
        Options for the definition of discrete neighbourhoods of a fitness landscape
      type: object
      required:
        - metric
      properties:
        radius:
          type: number
          minimum: 1
          default: 1
        metric:
          $ref: '#/components/schemas/EnumLandscapeMetric'
    DataTypeLandscapeValues:
      description: |-
        A (potentially multi-dimensional) array of values for the fitness landscape.
      oneOf:
        - type: array
          items:
            type: number
        - type: array
          items:
            $ref: '#/components/schemas/DataTypeLandscapeValues'
    # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    # Enum Algorithm Names
    # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    EnumAlgorithmNames:
      description: |-
        Enumeration of possible algorithm options.
      type: string
      enum:
        - TARJAN
        - TSP
        - HIRSCHBERG
        - RUCKSACK
        - RANDOM-WALK
        - GENETIC
        - EUKLID
        - POLLARD-RHO
    # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    # Enum Optimise Mode
    # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    EnumOptimiseMode:
      description: |-
        Enumeration of optimisation modi.
      type: string
      enum:
        - MIN
        - MAX
    # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    # Enum Rucksack mode for algorithm
    # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    EnumRucksackAlgorithm:
      description: |-
        Enumeration of mode for Rucksack problem
      type: string
      enum:
        - GREEDY
        - BRANCH-AND-BOUND
    # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    # Enum Type for choice of growth rate in Pollard Algorithm
    # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    EnumPollardGrowthRate:
      description: |-
        Via the 'tail-chasing' period finding method in Pollard's rho algorithm,
        the difference between the indexes of the pseudo-random sequence
        can be chosen to growth according to different rates, e.g.

        - `LINEAR` - choose `x[k]` and `x[2k]`
        - `EXPONENTIAL` - choose `x[k]` and `x[2^{k}]`
      type: string
      enum:
        - LINEAR
        - EXPONENTIAL
    # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    # Enum Type of walk mode for fitness walk algorithm
    # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    EnumWalkMode:
      description: |-
        Enumeration of walk mode for fitness walk algorithm
        - `ADAPTIVE` - points uniformly randomly chosen from nbhd.
        - `GRADIENT` - points uniformly randomly chosen amongst points in nbhd with steepest gradient.
        - `METROPOLIS` - points uniformly randomly chosen from nbhd. or by entropy.
      type: string
      enum:
        - ADAPTIVE
        - GRADIENT
        - METROPOLIS
    # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    # Enum for metric for neighbourhoods in fitness landscape
    # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    EnumLandscapeMetric:
      description: |-
        Enumeration of mode for Rucksack problem
        - `MAXIMUM` - `Q` is a neighbour of `P` <==> `max_i d(P_i, Q_i) <= r`
        - `MANHATTAN` - `Q` is a neighbour of `P` <==> `sum_i d(P_i, Q_i) <= r`
      type: string
      enum:
        - MAXIMUM
        - MANHATTAN