Class Sofomore

Initialization:

• `list_of_solvers_instances` is a list of single-objective solvers' instances
• The reference_point is set by the user during the initialization.
• `opts` is a dictionary updating the values of 'indicator_front', 'archive', 'restart', 'update_order'; that respond respectfully to the changing fitness we will choose within an iteration of Sofomore, whether or not keeping an archive, how to do the restart in case of any restart, and the order of update of the kernels. It also has the keys 'verb_filename', 'verb_log' and 'verb_disp'; that respectfully indicate the name of the filename containing the Sofomore data, the logging of the Sofomore data every 'verb_log' iterations and the display of the data via `self.disp()` every 'verb_disp' iterations.

Overrides: object.__init__

return length of the `Sofomore` instance by calling ``len(.)``.

The length is the number of (active and inactive) kernels and hence consistent with subscription like ``[moes[i] for i in range(len(moes)) if i in moes._active_indices]``.

return a reversed sorted list of kernels.

By default kernels are reversed sorted by HV contribution or UHVI (which we aim to maximize) in the set of kernels. Exact copies have zero or negative UHVI value.

>>> import comocma, cma
>>> list_of_solvers_instances = comocma.get_cmas(13 * [5 * [1]], 0.7, {'verbose':-9})
>>> fitness = comocma.FitFun(cma.ff.sphere, lambda x: cma.ff.sphere(x-1))
>>> moes = comocma.Sofomore(list_of_solvers_instances, [11, 11])
>>> moes.optimize(fitness, iterations=31) # doctest:+ELLIPSIS
Iterat #Fevals   Hypervolume   axis ratios   sigmas   min&max stds***
>>> moes.sorted(key = lambda k: moes.archive.contributing_hypervolume(
...                          k.objective_values)) # doctest:+ELLIPSIS
[<comocma.como.CmaKernel object at***

sorts w.r.t. archive contribution (clones may get positive contribution).

get the kernels' incumbents to be evaluated and sample new candidate solutions from 
`number_to_ask` kernels.
The sampling is done by calling the `ask` method of the
`cma.CMAEvolutionStrategy` class.
The indices of the considered kernels' incumbents are given by the 
`_told_indices` attribute.

To get the `number_to_ask` kernels, we use the function `self.key_sort_indices` as
a key to sort `self._remaining_indices_to_ask` (which is the list of
kernels' indices wherein we choose the first `number_to_ask` elements.
And if `number_to_ask` is larger than `len(self._remaining_indices_to_ask)`,
we select the list `self._remaining_indices_to_ask` extended with the  
first `number_to_ask - len(self._remaining_indices_to_ask)` elements
of `range(len(self))`, sorted with `self.key_sort_indices` as key.

Arguments
---------
- `number_to_ask`: the number of kernels for which we sample solutions
 from, it is of TYPE int or str and is smaller or equal to `len(self)`.
 The unique case where it is a str instance is when it is equal to 
 "all", meaning that all the kernels are asked. That case is mainly used
 on parallel mode by distributing the evaluations of the kernels at the
 same time before calling the `tell` method. The opposite is when
 `number_to_ask` is equal to 1, which is the exact COMO-CMA-ES algorithm,
 where the evaluations are done sequentially by updating the kernels one
 by one.

Return
------
The list of the kernels' incumbents to be evaluated, extended with a
list of N-dimensional (N is the dimension of the search space) 
candidate solutions generated from `number_to_ask` kernels 
to be evaluated.

:See: the `ask` method from the class `cma.CMAEvolutionStrategy`,
    in `evolution_strategy.py` from the `cma` module.
    

Overrides: cma.interfaces.OOOptimizer.ask

pass objective function values to update the state variables of some 
kernels, `self._told_indices` and eventually `self.archive`.
Arguments
---------
`solutions`
    list or array of points (of type `numpy.ndarray`), most presumably 
    before delivered by the `ask()` method.
`objective_values`
    list of multiobjective function values (of type `list`)
    corresponding to the respective points in `solutions`.
`constraints_values`
    list of list of constraint values: each element is a list containing
    the values of one constraint function, that are obtained by evaluation
    on `solutions`.
    

Details
-------
To update a kernel, `tell()` applies the kernel's `tell` method
to the kernel's corresponding candidate solutions (offspring) along
with the "changing" fitness `- self.indicator_front.hypervolume_improvement`.

:See: 
    - the `tell` method from the class `cma.CMAEvolutionStrategy`,
    in `evolution_strategy.py` from the `cma` module.
    - the `hypervolume_improvement` method from the class
    `BiobjectiveNondominatedSortedList`, in the module `moarchiving.py`
    - the `hypervolume_improvement` method from the class
    `NonDominatedList`, in the module `nondominatedarchive.py`

Overrides: cma.interfaces.OOOptimizer.tell

return a nonempty dictionary when all kernels stop, containing all the
termination status. Therefore it's solely ... on the kernels' `stop`
method, which also return dictionaries.
Return
------
For example with 5 kernels, stop should return either None, or a `dict`
of the form:
    {0: dict0,
     1: dict1,
     2: dict2,
     3: dict2,
     4: dict4},
where each index `i` is a key which value is the `dict` instance
`self.kernels[i].stop()`

Overrides: cma.interfaces.OOOptimizer.stop

add `kernels` of type `list` to `self.kernels`. Generally, `kernels` are created from a factory function. If `kernels` is of length 1, the brackets can be omitted.

remove elements of the `kernels` (type `list`) that belong to `self.kernels`, and update the `_active_indices` attribute. If `kernels` is of length 1, the brackets can be omitted.

inactivate `kernel`, assuming that it's an element of `self.kernels`, or an index in `range(len(self))`. When inactivated, `kernel` is no longer updated, it is ignored. However we do not remove it from `self.kernels`, meaning that `kernel` might still play a role, due to its eventual trace in `self.pareto_front_cut`.

activate `kernel` when it was inactivated beforehand. Otherwise it remains quiet.

We expect the kernel's `stop` method in interest to look like: kernel.stop() = {'callback': ['kernel turned off']}

copy-pasted from `cma.evolution_strategy`. print annotation line for `disp` ()

copy-pasted from `cma.evolution_strategy`. print current state variables in a single-line. copy-pasted from `cma.evolution_strategy` module

Prints only if ``iteration_counter % modulo == 0``.

:See also: `disp_annotation`.

Overrides: cma.interfaces.OOOptimizer.disp

pareto_front_cut

return the non-dominated solutions dominating the reference point, among the kernels' objective values. It's the image of `self.pareto_set_cut`.

Get Method:

unreachable.pareto_front_cut(self) - return the non-dominated solutions dominating the reference point, among the kernels' objective values.

pareto_set_cut

return the non-dominated solutions whose images dominate the reference point, among the kernels' incumbents. It's the pre-image of `self.pareto_front_cut`.

Get Method:

unreachable.pareto_set_cut(self) - return the non-dominated solutions whose images dominate the reference point, among the kernels' incumbents.

pareto_front_uncut

provisorial, return _all_ non-dominated objective values irrespectively

of the current reference point. Only points whose contributing HV does not depend on the current reference point still have the same cHV in the resulting `list`. HV improvements in general may change.

Get Method:

unreachable.pareto_front_uncut(self) - provisorial, return _all_ non-dominated objective values irrespectively

termination_status

return a dictionary of the current termination states of the kernels.

Get Method:

unreachable.termination_status(self) - return a dictionary of the current termination states of the kernels.

median_stds

Get Method:

unreachable.median_stds(self)

max_max_stds

Get Method:

unreachable.max_max_stds(self)