Automatic Control Knowledge Repository (ACKRep) Data

Note: The full documentation is available online at https://ackrep-doc.readthedocs.io/en/latest/index.html.

This repository holds the data for the ACKRep project. Due to the subject and the concept of that project, data consists mainly in source code and metadata. The associated backend is maintained in the ackrep_core-repository.

Basic Concept of ACKRep

The project aims to represent knowledge (in the field of automatic control) in a special way: as a combination of problem-specifications and problem-solutions. Both, problems and solutions can be represented by software modules. To ensure integrity and reproducability, solution-modules are checked automatically against the respective problems. To facilitate the operation of this process, some metadata and some other components are also managed in this repo. Alltogether there are the following entities:

• problem class
  • e.g. Trajectory Planning for Mechanical Systems
• problem specification
  • e.g. Swingup control for the Acrobot with specific parameters
• problem solution
  • e.g. Invocation of an allgorithm which calculates a swingup trajectory for the acrobot
• method package
  • e.g. A collection of functions which together implement an algorithm to calculate state space transitions for dynamical systems
• documentation
  • e.g. A mathematical description of an problem or algorithm e.g. as .tex-file or an different kind of documentation
• environment specification
  • A set of rules to setup a software environment such that the above software components can be executed
• comment
  • A structured way to add remarks or questions to any entity

Summary: In some sense ACKrep translates the concept of continous integration from software engineering to research in automatic control.

Data Structure

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")
• 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_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)

---

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

---

Contributing:

See guide: Contributing.md.

---

License

This repo might contain source code under different free software licenses. Contributors are encouraged to choose GPLv3-or-later. Alternatively other official recognized Free Software licenses like MIT license, BSD license or Apache license would also be OK. For any file in this repo, the license is applicable (in this order) which a) noted inside the file itself, b) in a LICENSE-file inside the same directory or c) in the nearest parent directory containing aLICENSE-file. As the root directory contains a LICENSE-file with GPLv3-or-later, this is the default for all subdirectories.