The specification

  • Kliko is based on standard docker containers
  • A Kliko container should have a /kliko.yml fiel which defines the accepted parameters.
  • A Kliko container should have a runable binary or script named /kliko. This will be the entrypoint for the Kliko runner.
  • Logging should be written to STDOUT and STDERR.
  • We define two types of compute containers, split IO and joined IO containers. For split IO Input files will be mounted read only into /input. Output file should be written to /output, which will be mounted by the host. For joined IO containers input & output is the /work folder which will be mounted RW.
  • Parameters for the computation will be given when the container is run in the form of a file in json format called /parameters.json
  • Fields with type file will enable supply of custom input files. these will be put in the /input folder.

The /kliko.yml file

The kliko file should be in YAML format and has these required fields:

schema_version

The version of the kliko specification. note that this is independent of the versioning of the Kliko library.

name

Name of the kliko image. For example radioastro/simulator. Optional.

description

A more detailed description of the image.

author

Who made the container. Optional.

email

email adres of the author. Optional.

url

Where to find the specific kliko project on the web.

io

Which IO mode to use, could be join or split. For split IO Input files will be mounted read only into /input. Output file should be written to /output, which will be mounted by the host. For joined IO containers input & output is the /work folder which will be mounted RW.

Sections

The parameters are grouped in sections. Sections are just lists of fields.

fields

A section consists of a list of fields.

field

each field has 2 obligatory keys, a name and a type. Name is a short reference to the field which needs to be unique. This will be the name for internal reference. The type defines the type of the field and can be one of choice, string, float, file, bool or int.

Optional keys are:
  • initial: supply a initial (default) value for a field
  • max_length: define a maximum length in case of string type
  • choices: define a list of choices in case of a choice field. The choices should be a mapping
  • label: The label used for representing the field to the end user. If no label is given the name of the field is used.
  • required: Indicates if the field is required or optional
  • help_text: An optional help text that is presented to the end user next to the field.

An example kliko.yml file

Below is an example kliko file.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
schema_version: 3
name: kliko test image
description: for testing purposes only
url: https://github.com/gijzelaerr/kliko/tree/master/examples/fitsdoubler
io: split

sections:
  -
    name: section1
    description: The first section
    fields:
      -
        name: choice
        label: choice field
        type: choice
        initial: second
        required: True
        choices:
          first: option 1
          second: option 2
      -
        name: string
        label: char field
        help_text: maximum of 10 chars
        type: str
        max_length: 10
        initial: empty
        required: True
      -
        name: float
        label: float field
        type: float
        initial: 0.0
        required: False
  -
     name: section2
     description: The final section
     fields:
       -
         name: file
         label: file field
         help_text: this file will be put in /input in case of split io, /work in case of join io
         type: file
         required: True
       -
         name: int
         label: int field
         type: int
         required: True

Loading a Kliko container with the previous kliko file is loaded up in RODRIGUES will result in the form below:

_images/rodrigues.png

Processing this form will result in the following parameters.json file which is presented to the Kliko container on runtime:

1
{"int": 10, "file": "some-file", "string": "gijs", "float": 0.0, "choice": "first"}