Structure of the Data Repository

Every entity consists of a subdirectory with a special structure.

Metadata

All entities have a file metadata.yml which contains both generic data (applicable to all entity types) and type specific data. Data format is YAML (human-readable data-serialization language).

Naming convention: Attributes, files or directories starting with underscore have a special meaning. In most cases they are autogenerated by software.

<generic metadata>

• key

  • (identification key; uppercase alphanumeric string of length-5)

• name

  • (string of length <= 40)

• short_description

  • (string of length <= 500)

• version

  • (string like 1.2.3)

• tag_list

  • (list of strings)

• creator

  • (string)

• editor_list

  • (list of strings (email addresses or aliases) )

• creation_date

  • (string of format YYYY-MM-DD hh:mm:ss)

• external_references

  • (list of strings, plain text format (ISO 690), preferably with doi)

• notes

  • (string)

---

Problem Class

• metadata.yml

  • <generic metadata>

• README.md

---

Problem Specification

• metadata.yml

  • <generic metadata>

  • problemclasses

    • (list of keys)

  • compatible_environments

    • (list of keys)

  • problemfile

    • (string like problem.py)

  • related_system_model_list:

    • (list of keys)

• problem.py

• README.md

• dependencies.yml

problem.py example

import numpy as np
from scipy.integrate import odeint

from ackrep_core import ResultContainer

class ProblemSpecification(object):
    """
    DoubleIntegratorTransition
    """
    xx_start = (0, 0)
    xx_end = (1, 0)
    T_transition = 1
    constraints = {"x2": [-3, 3], "u1": [-5, 5]}

    @staticmethod
    def rhs(xx, uu):
        return (xx[1], uu[0])


def evaluate_solution(solution_data):

    # assume solution_data.u_func is callable and returns the desired input trajectory

    P = ProblemSpecification

    def rhs(xx, t):
        u_act = solution_data.u_func(t)
        return P.rhs(xx, u_act)

    umin, umax = P.constraints["u1"]
    x2min, x2max = P.constraints["x2"]

    tt = np.linspace(0, P.T_transition, 1000)

    xx_res = odeint(rhs, P.xx_start, tt)

    # boolean result
    success = abs(xx_res[-1, 1] - P.xx_end) < 1e-2

    success &= all(x2min <= xx_res[:, 1]) and all(xx_res[:, 1] <= x2max)

    uu = solution_data.u_func(tt)
    success &= all(umin <= uu) and all(uu <= umax)

    # a simple score heuristic:
    score = np.clip(1 / solution_data.consumed_time, 0, 10)

    return ResultContainer(success=success, score=score)

---

Problem Solution

• metadata.yml

  • <generic metadata>

  • solved_problem_list

    • (list of keys)

  • method_package_list

    • (list of keys; only these method packagess will be available to the software)

  • compatible_environment_list

    • (list of keys)

  • estimated_runtime:

    • (string of format hh:mm:ss; refers to a single core process on a “usual” PC)

  • solution_file:

    • e.g. solution.py

  • postprocessing_file: e.g. postprocessing.py (optional)

• README.md

• dependencies.yml

• solution.py

• _solution_data/

  • might be created by the solution code

  • may be used for the postprocessing (e.g. to visualize results)

solution.py example

def solve(problem_spec)

    # ...
    # solve the problem
    # ...
    return solution_data

---

Method Package

• metadata.yml

  • <generic metadata>

  • compatible_environments

• src/

  • (contains all source files)

• makescript.py

• README.md

• check_integrity.py (optional)

• dependencies.yml

• _build/

  • (must be generated by makescript.py, should contain a python module or package or something equivalent for other languages)

---

System Model

• metadata.yml

  • <generic metadata>

  • estimated_runtime:

    • (string of format hh:mm:ss; refers to a single core process on a “usual” PC)

  • system_model_file:

    • e.g. system_model.py

  • simulation_file:

    • e.g. simulation.py

• README.md

• dependencies.yml

• system_model.py

• parameters.py

• simulation.py

• _solution_data/

  • might be created by the simulation code

  • contains documentation of the system model

---

Comment

• metadata.yml

  • <generic metadata>

• parent_keys

• comment.md

• extra_data

  • (optional; may contain images etc.)

---

Environment Specification

• metadata.yml

  • <generic metadata>

• README.md

• dependencies.yml