improved documentation of controllers 2

moptipyapps/dynamic_control/__init__.py

@@ -1,9 +1,19 @@
 """
 Examples of dynamic control problems.
 
-Here we have examples for dynamic control problems that are systems whose
-state is governed by differential system which can be influenced by the
-output of controllers.
+Here we have examples for dynamic control problems. An
+:mod:`~moptipyapps.dynamic_control.instance` of the dynamic control problem
+is composed of
+
+- a :mod:`~moptipyapps.dynamic_control.system` of differential equations that
+  govern the state of a system and that also incorporate the output of a
+  controller,
+- a :mod:`~moptipyapps.dynamic_control.controller` blueprint, i.e., a function
+  that can be parameterized and that computes a controller output from the
+  system state, and
+- an :mod:`~moptipyapps.dynamic_control.objective` that rates how well-behaved
+  the system driven by the controller is in a simulation.
+
 Such systems can serve as primitive testbeds of actual dynamic control
 scenarios such as flight control or other fluid dynamic systems. Different
 from such more complicated systems, they are much faster and easier to

moptipyapps/dynamic_control/controller.py

@@ -1,4 +1,17 @@
-"""A base class for implementing controllers."""
+"""
+A base class for implementing controllers.
+
+A controller basically is a parameterizable function that receives the current
+state and time of a :mod:`~moptipyapps.dynamic_control.system` as input and
+computes one or multiple controller values as output. These controller values
+are then used to influence how the state of the system changes in the next
+iteration. In the dynamic systems control optimization task, the goal is to
+find the right parameterization for the controller such that an
+:mod:`~moptipyapps.dynamic_control.objective` is minimized.
+
+Examples for different controllers for dynamic systems are given in package
+:mod:`~moptipyapps.dynamic_control.controllers`.
+"""
 
 
 from typing import Callable, Final
@@ -11,7 +24,7 @@
 
 
 class Controller(Component):
-    """A class for governing a system via differential system."""
+    """A class for governing a system via differential equations."""
 
     def __init__(self, name: str,
                  state_dims: int, control_dims: int, param_dims: int,

moptipyapps/dynamic_control/instance.py

@@ -1,4 +1,17 @@
-"""An instance of the dynamic control problem."""
+"""
+An instance of the dynamic control synthesis problem.
+
+An instance of the dynamic control synthesis problem is comprised of two
+components: a :mod:`~moptipyapps.dynamic_control.system` of differential
+equations governing how the state of a system changes over time and a
+:mod:`~moptipyapps.dynamic_control.controller` that uses the current system
+state as input and computes a controller value as output that influences the
+state change. Notice that the controller here is a parametric function. The
+goal of the dynamic system control is to find the right parameterization of
+the controller such that an :mod:`~moptipyapps.dynamic_control.objective` is
+minimized. The objective here usually has the goal to bring the dynamic system
+into a stable state while using as little controller "energy" as possible.
+"""
 
 from typing import Final
 

moptipyapps/dynamic_control/starting_points.py

@@ -1,4 +1,23 @@
-"""Synthesize some interesting starting points."""
+"""
+Synthesize some interesting starting points.
+
+Here we have some basic functionality to synthesize starting points, i.e.,
+training cases, for the dynamic systems control task.
+The points synthesized here by function
+:func:`make_interesting_starting_points` try to fulfill two goals:
+
+1. the points should be as far away from each other as possible in the state
+   space,
+2. there should be points of many different distances from the state space
+   origin.
+
+These two goals are slightly contradicting and are achieved by forcing the
+points to be located on rings of increasing distance from the origin via
+:func:`interesting_point_transform` while maximizing their mean distance
+to each other via :func:`interesting_point_objective`.
+Since :func:`make_interesting_starting_points` is a bit slow, it makes sense
+to pre-compute the points and then store them as array constants.
+"""
 
 from typing import Callable, Final, Iterable, cast
 

moptipyapps/dynamic_control/system.py

@@ -1,4 +1,19 @@
-"""Classes for representing a problem to be solved."""
+"""
+A class to model a dynamic system governed by differential equations.
+
+A system has a current state vector at any point in time. The state changes
+over time based on differential equations. These equations can be influenced
+by the output of a :mod:`~moptipyapps.dynamic_control.controller`. Our
+:class:`System` presents the state dimension and differential equations. It
+also presents several starting states for simulating the system. The starting
+states are divided into training and testing states. The training states can
+be used for, well, training controllers to learn how to handle the system.
+The testing states are then used to verify whether a synthesized controller
+actually works.
+
+Examples for different dynamic systems are given in package
+:mod:`~moptipyapps.dynamic_control.systems`.
+"""
 
 from typing import Any, Callable, Final, Iterable, TypeVar