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