Coverage for moptipy / api / __init__.py: 100%

1""" 

2The API for implementing optimization algorithms and -problems. 

3 

4This package provides two things: 

5 

6* the basic, abstract API for implementing optimization algorithms and 

7 problems 

8* the abstraction and implementation of black-box processes in form of 

9 the :mod:`~moptipy.api.process` API and its implementations 

10 

11The former helps us to implement and plug together different components of 

12optimization problems and optimization algorithms. The latter allows us to 

13apply algorithms to problems and to collect the results in a transparent way. 

14It also permits logging of the algorithm progress or even the change of 

15dynamic parameters. 

16 

17The `moptipy` API has the following major elements for implementing 

18optimization algorithms and their components. You are encouraged to read more 

19about the logic behind this structure in our free online book at 

20https://thomasweise.github.io/oa. 

21 

22- :mod:`~moptipy.api.component` provides the base class 

23 :class:`~moptipy.api.component.Component` from which all components of 

24 algorithm and optimization problems inherit. It offers the basic methods 

25 :meth:`~moptipy.api.component.Component.log_parameters_to` for writing all 

26 parameters and configuration elements of a component to a 

27 :class:`~moptipy.utils.logger.KeyValueLogSection` of a log file (embodied by 

28 an instance of :class:`~moptipy.utils.logger.Logger`) and the method 

29 :meth:`~moptipy.api.component.Component.initialize`, which must be 

30 overwritten to do any initialization necessary before a run of the 

31 optimization process. 

32- :mod:`~moptipy.api.algorithm` provides the base class 

33 :class:`~moptipy.api.algorithm.Algorithm` from which any optimization 

34 algorithm will inherit and which defines the optimization algorithm 

35 API, most importantly the method 

36 :meth:`~moptipy.api.algorithm.Algorithm.solve` which must be overwritten to 

37 implement the algorithm behavior. Here you can also find subclasses such as 

38 :class:`~moptipy.api.algorithm.Algorithm0`, 

39 :class:`~moptipy.api.algorithm.Algorithm1`, and 

40 :class:`~moptipy.api.algorithm.Algorithm2` for algorithms that use nullary, 

41 nullary and unary, as well as nully, unary, and binary search operators. 

42- :mod:`~moptipy.api.encoding` provides the base class 

43 :class:`~moptipy.api.encoding.Encoding` which can be used to implement the 

44 decoding procedure :meth:`~moptipy.api.encoding.Encoding.decode` which 

45 translates elements of a search space to elements of the solution space. 

46 Such an encoding may be needed if the two spaces differ, as they do, for 

47 instance, in our Job Shop Scheduling Problem example (see 

48 :mod:`~moptipy.examples.jssp.ob_encoding`). 

49- :mod:`~moptipy.api.mo_algorithm` provides the base class 

50 :class:`~moptipy.api.mo_algorithm.MOAlgorithm` for multi-objective 

51 optimization algorithms, which is a subclass of 

52 :class:`~moptipy.api.algorithm.Algorithm`. 

53- :mod:`~moptipy.api.mo_archive` provides the base class 

54 :class:`~moptipy.api.mo_archive.MOArchivePruner` for pruning archives of 

55 non-dominated solutions during a multi-objective optimization process. Since 

56 multi-objective optimization problems may have many possible solutions, but 

57 we can only return/retain a finite number of them, it may be necessary to 

58 decide which solution to keep and which to dispose of. This is the task 

59 of the archive pruner. 

60- :mod:`~moptipy.api.objective` provides the base class 

61 :class:`~moptipy.api.objective.Objective` for objective functions, i.e., for 

62 implementing the criteria rating how good a solution is. Objective functions 

63 are subject to minimization and provide a method 

64 :meth:`~moptipy.api.objective.Objective.evaluate` which computes an integer 

65 or floating point value rating one solution. They may additionally have 

66 a :meth:`~moptipy.api.objective.Objective.lower_bound` and/or an 

67 :meth:`~moptipy.api.objective.Objective.upper_bound`. 

68- :mod:`~moptipy.api.mo_problem` provides the base class 

69 :class:`~moptipy.api.mo_problem.MOProblem`, which represents a 

70 multi-objective optimization problem. This is a subclass of 

71 :class:`~moptipy.api.objective.Objective` *and* at the same time, a 

72 collection of multiple instances of 

73 :class:`~moptipy.api.objective.Objective`. Each multi-objective problem can 

74 compute a vector of objective values via 

75 :meth:`~moptipy.api.mo_problem.MOProblem.f_evaluate`, but also implements 

76 the single-objective :meth:`~moptipy.api.mo_problem.MOProblem.evaluate` 

77 method returning a default scalarization of the objective vector. This makes 

78 multi-objective optimization compatible with single-objective optimization. 

79 While actual multi-objective algorithms can work in a truly multi-objective 

80 fashion, logging can be unified and even single-objective methods can be 

81 applied. To allow for the representation of preferences, the default 

82 Pareto domination relationship can be overwritten by providing a custom 

83 implementation of :meth:`~moptipy.api.mo_problem.MOProblem.f_dominates`. 

84- :mod:`~moptipy.api.operators` provides the base classes 

85 :class:`~moptipy.api.operators.Op0`, :class:`~moptipy.api.operators.Op1`, and 

86 :class:`~moptipy.api.operators.Op2` fur nullary, unary, and binary search 

87 operators, respectively. These can be used to implement the methods 

88 :meth:`~moptipy.api.operators.Op0.op0`, 

89 :meth:`~moptipy.api.operators.Op1.op1`, and 

90 :meth:`~moptipy.api.operators.Op2.op2` that are used by metaheuristic 

91 optimization algorithms to sample solutions and to derive solutions from 

92 existing ones. 

93- :mod:`~moptipy.api.space` provides the base class 

94 :class:`~moptipy.api.space.Space` for implementing the functionality of 

95 search and solution spaces. An instance of :class:`~moptipy.api.space.Space` 

96 offers methods such as :meth:`~moptipy.api.space.Space.create` for creating 

97 a data structure for holding point in the search space (with undefined 

98 contents), :meth:`~moptipy.api.space.Space.copy` for copying one data 

99 structure to another one, :meth:`~moptipy.api.space.Space.to_str` and 

100 :meth:`~moptipy.api.space.Space.from_str` to convert a data structure to 

101 and from a string, :meth:`~moptipy.api.space.Space.is_equal` to check 

102 whether one data structure equals another one, and 

103 :meth:`~moptipy.api.space.Space.validate` to verify whether the contents 

104 of a data structure are valid. With these methods, optimization algorithms 

105 can create and copy the data structure containers to hold solutions as they 

106 need without requiring any information about the actual contents and 

107 layout of these structures. The search operators (see above) then can handle 

108 the actual processing of the data structures. At the same time, the string 

109 conversion routines allow for storing the results of algorithms in log 

110 files. 

111 

112The algorithm and experiment execution API has the following major elements: 

113 

114- :mod:`~moptipy.api.execution` provides the builder class 

115 :class:`~moptipy.api.execution.Execution` that is used to construct one 

116 application of an optimization algorithm to an optimization problem. It 

117 configures the termination criteria, what information should be logged, and 

118 which algorithm to apply to which problem. Its method 

119 :meth:`~moptipy.api.execution.Execution.execute` returns an instance of 

120 :class:`~moptipy.api.process.Process` that contains the state of the 

121 optimization *after* it is completed, i.e., after the algorithm was 

122 executed. Log files follow the specification at 

123 https://thomasweise.github.io/moptipy/#log-file-sections. 

124- The module :mod:`~moptipy.api.logging` holds mainly string constants that 

125 identify sections and keys for the data to be written to log files. 

126- :mod:`~moptipy.api.mo_execution` provides the builder class 

127 :class:`~moptipy.api.mo_execution.MOExecution`, which is the multi-objective 

128 equivalent of :class:`~moptipy.api.execution.Execution`. 

129- :mod:`~moptipy.api.experiment` offers the function 

130 :func:`~moptipy.api.experiment.run_experiment` which allows you to execute 

131 a structured experiment applying a set of optimization algorithms to a set 

132 of optimization problems in a reproducible fashion, in parallel or in a 

133 distributed way. It will create a folder structure as prescribed in 

134 https://thomasweise.github.io/moptipy/#file-names-and-folder-structure. 

135 The data from such a folder structure can then be read in by the experiment 

136 evaluation tools in package :mod:`~moptipy.evaluation` and discussed in 

137 https://thomasweise.github.io/moptipy/#evaluating-experiments. 

138- :mod:`~moptipy.api.process` provides the class 

139 :class:`~moptipy.api.process.Process`, which is the basis for all 

140 optimization processes. It offers the functionality of an objective 

141 function, the search space, the termination criterion, and the random 

142 number generator to the optimization algorithm. At the same time, it 

143 collects the best-so-far solution and writes log files (if needed) for the 

144 user. 

145- :mod:`~moptipy.api.mo_process` provides the class 

146 :class:`~moptipy.api.mo_process.MOProcess`, which is the multi-objective 

147 equivalent of :class:`~moptipy.api.process.Process`. It also collects an 

148 archive of solutions. 

149- :mod:`~moptipy.api.subprocesses` offers several functions to slice off 

150 computational budget of a process to allow an algorithm to use a 

151 sub-algorithm, to wrap processes for running external algorithms that do 

152 not respect the `moptipy` API, or to run sub-algorithms starting with a 

153 specified initial solution. 

154"""