Skip to content

Units: Structured Representation

The JSON structured representations for the different types of units supported on our platform are contained in the expandable sections presented throughout the present page, accompanied each time by a corresponding example.

For a description of unit input templating, the reader is referred to this section of the documentation.

General Case

 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
{
    "$id": "workflow/unit",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "workflow unit schema",
    "type": "object",
    "oneOf": [
        {
            "$ref": "./unit/io.json"
        },
        {
            "$ref": "./unit/reduce.json"
        },
        {
            "$ref": "./unit/condition.json"
        },
        {
            "$ref": "./unit/assertion.json"
        },
        {
            "$ref": "./unit/execution.json"
        },
        {
            "$ref": "./unit/assignment.json"
        },
        {
            "$ref": "./unit/processing.json"
        },
        {
            "$ref": "./unit/map.json"
        },
        {
            "$ref": "./unit/subworkflow.json"
        }
    ],
    "discriminator": {
        "propertyName": "type"
    },
    "required": [
        "type"
    ]
}

1

Execution

 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
{
    "$id": "workflow/unit/execution",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "execution unit schema (base)",
    "type": "object",
    "allOf": [
        {
            "$ref": "./base.json"
        },
        {
            "$ref": "runtime/runtime_items.json"
        }
    ],
    "properties": {
        "type": {
            "enum": [
                "execution"
            ]
        },
        "application": {
            "description": "Contains information about the simulation engine/application.",
            "$ref": "../../software/application.json"
        },
        "executable": {
            "description": "Contains information about the simulation engine/application executable.",
            "$ref": "../../software/executable.json"
        },
        "flavor": {
            "description": "Contains information about the simulation engine/application flavor.",
            "$ref": "../../software/flavor.json"
        },
        "input": {
            "description": "unit input (type to be specified by the application's execution unit)"
        }
    },
    "required": [
        "input",
        "application"
    ]
}

 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
{
    "application": {
        "...": "include(../../software/application.json)"
    },
    "compute": null,
    "executable": {
        "...": "include(../../software/executable.json)"
    },
    "flavor": {
        "...": "include(../../software/flavor.json)"
    },
    "flowchartId": "execution",
    "head": true,
    "input": [
        {
            "content": "K_POINTS automatic\n2 2 2 0 0 0",
            "name": "pw_scf.in"
        }
    ],
    "monitors": [
        {
            "name": "scf_accuracy"
        },
        {
            "name": "standard_output"
        }
    ],
    "name": "execution",
    "next": "pw-bands",
    "postProcessors": [],
    "preProcessors": [],
    "results": [
        {
            "name": "harris_foulkes_estimate"
        }
    ],
    "status": "idle",
    "type": "execution"
}

Processing

 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
{
    "$id": "workflow/unit/processing",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "processing unit schema",
    "type": "object",
    "allOf": [
        {
            "$ref": "./base.json"
        }
    ],
    "properties": {
        "type": {
            "enum": [
                "processing"
            ]
        },
        "operation": {
            "description": "Contains information about the operation used.",
            "type": "string"
        },
        "operationType": {
            "description": "Contains information about the specific type of the operation used.",
            "type": "string"
        },
        "inputData": {
            "description": "unit input (type to be specified by the child units)"
        }
    },
    "required": [
        "operation",
        "operationType",
        "inputData"
    ]
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
{
    "flowchartId": "data_transformation_manipulation",
    "inputData": {
        "cleanMissingData": true,
        "removeDuplicateRows": true,
        "replaceNoneValuesWith": 0
    },
    "name": "data_transformation_manipulation",
    "operation": "data_transformation",
    "operationType": "manipulation",
    "status": "idle",
    "type": "processing"
}

I/O

DataFrame

 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
50
51
52
53
{
    "$id": "workflow/unit/io",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "data IO unit schema",
    "type": "object",
    "allOf": [
        {
            "$ref": "./base.json"
        }
    ],
    "properties": {
        "type": {
            "enum": [
                "io"
            ]
        },
        "subtype": {
            "enum": [
                "input",
                "output",
                "dataFrame"
            ]
        },
        "source": {
            "enum": [
                "api",
                "db",
                "object_storage"
            ]
        },
        "input": {
            "type": "array",
            "items": {
                "anyOf": [
                    {
                        "$ref": "io/api.json"
                    },
                    {
                        "$ref": "io/db.json"
                    },
                    {
                        "$ref": "io/object_storage.json"
                    }
                ]
            }
        }
    },
    "required": [
        "subtype",
        "source",
        "input"
    ]
}

 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
{
    "flowchartId": "io",
    "head": true,
    "input": [
        {
            "endpoint": "data-frame",
            "endpoint_options": {
                "data": {
                    "features": [
                        "elemental_ratio:Si",
                        "elemental_ratio:Ge",
                        "ionization_potential:Ge",
                        "ionization_potential:Si"
                    ],
                    "ids": [
                        "KuAsBRwofzGfHPWiT"
                    ],
                    "targets": [
                        "band_gaps:indirect",
                        "band_gaps:direct"
                    ]
                },
                "headers": {
                    "X-Auth-Token": "",
                    "X-User-Id": ""
                },
                "method": "POST",
                "params": {
                    "query": {
                        "formula": "SiGe"
                    }
                }
            }
        }
    ],
    "name": "io",
    "source": "api",
    "status": "idle",
    "subtype": "input",
    "type": "io"
}

API

 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
{
    "$id": "workflow/unit/io/api",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "data IO rest API input schema",
    "type": "object",
    "properties": {
        "endpoint": {
            "description": "rest API endpoint",
            "type": "string"
        },
        "endpoint_options": {
            "description": "rest API endpoint options",
            "type": "object"
        },
        "name": {
            "description": "the name of the variable in local scope to save the data under",
            "type": "string"
        }
    },
    "required": [
        "endpoint",
        "endpoint_options"
    ],
    "additionalProperties": true
}

 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
{
    "endpoint": "data-frame",
    "endpoint_options": {
        "data": {
            "features": [
                "elemental_ratio:Si",
                "elemental_ratio:Ge",
                "ionization_potential:Ge",
                "ionization_potential:Si"
            ],
            "ids": [
                "KuAsBRwofzGfHPWiT"
            ],
            "targets": [
                "band_gaps:indirect",
                "band_gaps:direct"
            ]
        },
        "headers": {
            "X-Auth-Token": "",
            "X-User-Id": ""
        },
        "method": "POST",
        "params": {
            "query": {
                "formula": "SiGe"
            }
        }
    },
    "name": "DATA"
}

Database

 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
{
    "$id": "workflow/unit/io/db",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "data IO database input/output schema",
    "type": "object",
    "oneOf": [
        {
            "properties": {
                "ids": {
                    "description": "IDs of item to retrieve from db",
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                }
            },
            "required": [
                "ids"
            ],
            "additionalProperties": true
        },
        {
            "properties": {
                "collection": {
                    "description": "db collection name",
                    "type": "string"
                },
                "draft": {
                    "description": "whether the result should be saved as draft",
                    "type": "boolean",
                    "default": true
                }
            },
            "required": [
                "collection",
                "draft"
            ],
            "additionalProperties": true
        }
    ]
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
{
    "features": [
        "elemental_ratio:Si",
        "elemental_ratio:Ge",
        "ionization_potential:Ge",
        "ionization_potential:Si"
    ],
    "ids": [
        "KuAsBRwofzGfHPWiT"
    ],
    "targets": [
        "band_gaps:indirect",
        "band_gaps:direct"
    ]
}

Object Storage

 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
{
    "$id": "workflow/unit/io/object-storage",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "object_storage io schema",
    "type": "object",
    "allOf": [
        {
            "$ref": "../../../core/reusable/file_metadata.json"
        }
    ],
    "properties": {
        "objectData": {
            "$ref": "../../../core/reusable/object_storage_container_data.json"
        },
        "overwrite": {
            "description": "if a file with the same filename already exists, whether to overwrite the old file",
            "type": "boolean",
            "default": false
        }
    },
    "required": [
        "objectData"
    ],
    "additionalProperties": true
}

1
2
3
4
5
6
7
{
    "basename": "index.html",
    "overwrite": true,
    "objectData": {
        "...": "include(../../../core/reusable/object_storage_container_data.json)"
    }
}

Assignment

 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
50
51
{
    "$id": "workflow/unit/assignment",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "assignment unit schema",
    "type": "object",
    "allOf": [
        {
            "$ref": "./base.json"
        },
        {
            "$ref": "./../../system/scope.json"
        }
    ],
    "properties": {
        "type": {
            "enum": [
                "assignment"
            ]
        },
        "input": {
            "description": "Input information for assignment. if omitted, means that it is an initialization unit, otherwise it is an assignment.",
            "type": "array",
            "items": {
                "$ref": "input/_inputItemScope.json"
            }
        },
        "operand": {
            "description": "Name of the global variable. e.g. 'x'",
            "type": "string"
        },
        "value": {
            "description": "Value of the variable. The value content could be a simple integer, string or a python expression. e.g. '0' (initialization), 'sin(x)+1' (expression)",
            "oneOf": [
                {
                    "type": "string"
                },
                {
                    "type": "boolean"
                },
                {
                    "type": "number"
                }
            ]
        }
    },
    "required": [
        "name",
        "operand",
        "value"
    ]
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
{
    "flowchartId": "assignment",
    "head": true,
    "input": [
        {
            "name": "N_K_x",
            "scope": "global"
        },
        {
            "name": "N_K_y",
            "scope": "global"
        }
    ],
    "name": "assignment",
    "operand": "N_K_x",
    "status": "idle",
    "type": "assignment",
    "value": "N_K_x+N_K_y+1"
}

Conditional

 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
50
51
52
{
    "$id": "workflow/unit/condition",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "condition unit schema",
    "type": "object",
    "allOf": [
        {
            "$ref": "./base.json"
        }
    ],
    "properties": {
        "type": {
            "enum": [
                "condition"
            ]
        },
        "input": {
            "description": "Input information for condition.",
            "type": "array",
            "items": {
                "$ref": "input/_inputItemScope.json"
            }
        },
        "statement": {
            "description": "Condition statement. e.g. 'abs(x-total_energy) < 1e-5'",
            "type": "string"
        },
        "then": {
            "description": "Flowchart ID reference for `then` part of the condition.",
            "type": "string"
        },
        "else": {
            "description": "Flowchart ID reference for `else` part of the condition.",
            "type": "string"
        },
        "maxOccurrences": {
            "description": "Maximum occurrence of the condition, usable for loops.",
            "type": "integer"
        },
        "throwException": {
            "description": "Throw exception on reaching to maximum occurence.",
            "type": "boolean"
        }
    },
    "required": [
        "input",
        "statement",
        "then",
        "else",
        "maxOccurrences"
    ]
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
    "else": "sample_id_6",
    "flowchartId": "condition",
    "head": true,
    "input": [
        {
            "name": "x",
            "scope": "global"
        },
        {
            "name": "total_energy",
            "scope": "sample_id_2"
        }
    ],
    "maxOccurrences": 100,
    "name": "condition",
    "statement": "abs(x-total_energy) < 1e-5",
    "status": "idle",
    "then": "sample_id_4",
    "throwException": true,
    "type": "condition"
}

Map

 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
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
{
    "$id": "workflow/unit/map",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "map unit schema",
    "type": "object",
    "allOf": [
        {
            "$ref": "./base.json"
        }
    ],
    "properties": {
        "type": {
            "enum": [
                "map"
            ]
        },
        "workflowId": {
            "description": "Id of workflow to run inside map",
            "type": "string"
        },
        "input": {
            "description": "Input information for map.",
            "type": "object",
            "properties": {
                "target": {
                    "description": "Name of the target variable to substitute using the values below. e.g. K_POINTS",
                    "type": "string"
                },
                "scope": {
                    "description": "Scope to retrieve `values` from, global or flowchartId. Optional if `values` is given.",
                    "type": "string"
                },
                "name": {
                    "description": "Name of the variable inside the scope to retrieve `values` from. Optional if `values` is given.",
                    "type": "string"
                },
                "values": {
                    "description": "Sequence of values for the target Jinja variable. Optional if `scope` and `name` are given. This can be used for map-reduce type parallel execution",
                    "type": "array",
                    "items": {
                        "oneOf": [
                            {
                                "type": "string"
                            },
                            {
                                "type": "number"
                            },
                            {
                                "type": "object"
                            }
                        ]
                    }
                },
                "useValues": {
                    "type": "boolean"
                }
            },
            "required": [
                "target"
            ]
        }
    },
    "required": [
        "input",
        "workflowId"
    ]
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
{
    "flowchartId": "map",
    "head": true,
    "input": {
        "target": "MAP_K_POINTS_1",
        "values": [
            "2 2 2 0 0 0",
            "3 3 3 0 0 0",
            "4 4 4 0 0 0"
        ]
    },
    "name": "map",
    "status": "idle",
    "type": "map",
    "workflowId": "zxjhEiaQvwWwvB3oM"
}

Reduce

 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
50
{
    "$id": "workflow/unit/reduce",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "reduce unit schema",
    "type": "object",
    "allOf": [
        {
            "$ref": "./base.json"
        }
    ],
    "properties": {
        "type": {
            "enum": [
                "reduce"
            ]
        },
        "mapFlowchartId": {
            "description": "corresponding map unit flowchart ID",
            "type": "string"
        },
        "input": {
            "description": "input information for reduce unit",
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "operation": {
                        "description": "reduce operation, e.g. aggregate",
                        "type": "string"
                    },
                    "arguments": {
                        "description": "arguments which are passed to reduce operation function",
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    }
                },
                "required": [
                    "operation",
                    "arguments"
                ]
            }
        }
    },
    "required": [
        "mapFlowchartId",
        "input"
    ]
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
{
    "flowchartId": "reduce",
    "head": true,
    "input": [
        {
            "arguments": [
                "band_gaps"
            ],
            "operation": "aggregate"
        }
    ],
    "mapFlowchartId": "1",
    "name": "reduce",
    "status": "idle",
    "type": "reduce"
}