Documentation/Modules/Interfaces

Basics

The basic element of each OpenOpal optimization or learning environment is still the Module. Each optimization problem, each optimization algorithm and each learning algorithm is a module. A class that is used as a module must implement the interface org.openopal.core.modules.IModule (see [Documentation/IModule IModule]).

The whole structure of modules in OpenOpal is based on interfaces. The reason for this is that classes that are used as modules may be part of a class hierarchy and thus they cannot inherit from a basic module class.

There are modules that can be run, e.g. optimization algorithms. All these modules implement the interface org.openopal.core.modules.IRunnable.

Each optimization setup consists of at least two linked modules: a problem and an optimizer. The interfaces for these modules are org.openopal.core.modules.optimization.IEvaluable and IEvaluator, respecively. The corresponding pair for a learning task is org.openopal.core.modules.learning.IDataSource and IDataSink.

Modules can be linked between other modules. E.g. the protocoller is a module that you can link between an optimizer and a problem. In such a case, all modules except the optimizer must implement the interface IEvaluable and all modules except the problem must implement the interface IEvaluator. This means that the modules form a chain that looks like this (here, two intermediate modules are shown):

IEvaluator
    |
IEvaluable and IEvaluator
                   |
               IEvaluable and IEvaluator
                                  |
                              IEvaluable

where the topmost evaluator is the optimizer and the bottommost evaluable is the optimization problem. The meaning of this picure is that the optimizer produces points and sends them through the chain to the problem. The problem evaluates the points, assinging each point its objective value(s). These are read by the optimizer which then tries to create better points, etc. The same kind of interaction chain is possible for learners and data sources. But there, the information flow is mainly in unidirectional: from the data source to the data sink.

The class that represents solutions to optimization problems is Solution. Every instance of this class is a solution to the optimization problem. Each Solution object contains the design variables that define the solution and one or more objective values that assess the quality of the solution. The goal of each optimization algorithm is to find a Solution with minimal objective values. An object of the class Data represents the data involved in a particular learning setup. It is passed from data source to data sink.

Often, modules look similar, and someone writing a new module doens't want to implement all interface methods by hand. For these cases, we wrote the abstract classes org.openopal.core.modules.optimization.Optimizer and Problem and learning.Learner. These classes already implement almost all necessary methods. A writer of an optimizer just has to implement the algorithm itself and no other details (e.g. linking, checking etc.). Similarly, a writer of a problem just has to implement the evaluate method of the Problem class. In a learner, the method to override is run(). It executes the learning algorithm.

Documentation and Contracts

(Almost) each interface, class and method has a JavaDoc comment that defines its documentation. The documentation of methods consists of descriptions of the purpose, the parameters and the return value. We provided many methods with contracts. These are also described on the page https://www.openopal.org/wiki/index.php/Documentation:Contracts. It is important to know these contracts when using (or modifying) methods. Invariants can only be guaranteed if they are established by each constructor and not violated by any method. It should be impossible to access members of an object from outside the object without using a method of the object. That's why members that are part of invariants have to be cloned when they enter or leave the object.

The Interfaces

IModule

This is the basic interface implemented by all modules. It contains methods for the initialisation and checking of the module and for the management of the options of the module.

IRunnable

This interfaces is implemented by all modules that can be run. When a module is run, it executes its optimization algorithm. In the future this could be any kind of algorithm. The interface contains methods to start and stop the execution of the module.

IEvaluable

Every module that represents an optimization problem implements the interface IEvaluable. This means that the module can evaluate a given solution. To that end, it looks at the design variables of a solution object it gets from an optimizer and sets the objective value(s) of that object accordingly.

If a module is linked before a problem module, it must implement IEvaluable and delegate the evaluation of the solutions to the problem module. Thus, the optmimizer doesn't know if the module right after it is the problem itself or an intermediate module, it just calls the evaluate method of its successor module.

IEvaluable contains methods to evaluate one solution or an array of solutions and a method to get the properties of the problem.

IEvaluator

A module that can call an evaluable to evaluate solutions implements the interface IEvaluator. Normally, an evaluator is an optimizer module, but any intermediate module between the optimizer and the problem must implement this interface as well. Otherwise, it wouldn't be able to call the problem to evaluate the solutions.

IEvaluator contains methods to get and set the references to the evaluables and to check if these links are OK.

IDataSource

A module that provides data. This can be a file reader, the protocoller, or other modules that can produce or store data. The getData() method is the most important one.

IDataSink

A module implementing this interface represents a learner. It is linked with a data source and processes the given data. Very different kinds of processing are possible. A data viewer can just display the data, a neural network can learn a function from the data or a statistics module can compute some statistics on the data etc.