Update doctsrings and minor changes

.gitignore

@@ -11,3 +11,4 @@ x86_64
 /cov_reports
 .coverage
 coverage.xml
+.idea/

Dockerfile

@@ -1,4 +1,4 @@
-# Copyright (c) 2016-2020, EPFL/Blue Brain Project
+# Copyright (c) 2016-2022, EPFL/Blue Brain Project
 #
 # This file is part of BluePyOpt <https://github.com/BlueBrain/BluePyOpt>
 #

LICENSE.txt

@@ -6,7 +6,7 @@ Examples and test are BSD-licensed.
 External dependencies are either LGPL or BSD-licensed. 
 See file ACKNOWLEDGEMENTS.txt and AUTHORS.txt for further details.
 
-Copyright (c) Blue Brain Project/EPFL 2016-2021.
+Copyright (c) Blue Brain Project/EPFL 2016-2022.
 
 This program is free software: you can redistribute it and/or modify it under 
 the terms of the GNU Lesser General Public License as published by the 

README.rst

@@ -198,7 +198,7 @@ Funding
 This work has been partially funded by the European Union Seventh Framework Program (FP7/2007­2013) under grant agreement no. 604102 (HBP), the European Union’s Horizon 2020 Framework Programme for Research and Innovation under the Specific Grant Agreement No. 720270, 785907 (Human Brain Project SGA1/SGA2) and by the EBRAINS research infrastructure, funded from the European Union’s Horizon 2020 Framework Programme for Research and Innovation under the Specific Grant Agreement No. 945539 (Human Brain Project SGA3).
 This project/research was supported by funding to the Blue Brain Project, a research center of the École polytechnique fédérale de Lausanne (EPFL), from the Swiss government’s ETH Board of the Swiss Federal Institutes of Technology.
 
-Copyright (c) 2016-2021 Blue Brain Project/EPFL 
+Copyright (c) 2016-2022 Blue Brain Project/EPFL
 
 ..
     The following image is also defined in the index.rst file, as the relative path is 

bluepyopt/__init__.py

@@ -1,7 +1,7 @@
 """Init script"""
 
 """
-Copyright (c) 2016-2020, EPFL/Blue Brain Project
+Copyright (c) 2016-2022, EPFL/Blue Brain Project
 
  This file is part of BluePyOpt <https://github.com/BlueBrain/BluePyOpt>
 

bluepyopt/deapext/CMA_MO.py

@@ -1,7 +1,7 @@
 """Multi Objective CMA-es class"""
 
 """
-Copyright (c) 2016-2020, EPFL/Blue Brain Project
+Copyright (c) 2016-2022, EPFL/Blue Brain Project
 
  This file is part of BluePyOpt <https://github.com/BlueBrain/BluePyOpt>
 
@@ -37,23 +37,36 @@
 logger = logging.getLogger("__main__")
 
 
-def get_hyped(pop):
+def get_hyped(pop, ubound_score=250., threshold_improvement=240.):
+    """Compute the hypervolume contribution of each individual.
+    The fitness space is first bounded and all dimension who do not show
+    improvement are ignored.
+    """
+
     # Cap the obj at 250
     points = numpy.array([ind.fitness.values for ind in pop])
-    points[points > 250.0] = 250.0
+    points[points > ubound_score] = ubound_score
     lbounds = numpy.min(points, axis=0)
     ubounds = numpy.max(points, axis=0)
 
     # Remove the dimensions that do not show any improvement
     to_remove = []
-    for i, (lb, ub) in enumerate(zip(lbounds, ubounds)):
-        if lb >= 240:
+    for i, lb in enumerate(lbounds):
+        if lb >= threshold_improvement:
             to_remove.append(i)
     points = numpy.delete(points, to_remove, axis=1)
     lbounds = numpy.delete(lbounds, to_remove)
     ubounds = numpy.delete(ubounds, to_remove)
 
+    if not len(lbounds):
+        logger.warning("No dimension along which to compute the hypervolume.")
+        return [0.] * len(pop)
+
     # Rescale the objective space
+    # Note: 2 here is a magic number used to make the hypercube larger than it
+    # really is. It makes sure that the individual always have a non-zero
+    # hyper-volume contribution and improves the results while avoiding an
+    # edge case.
     points = (points - lbounds) / numpy.max(ubounds.flatten())
     ubounds = numpy.max(points, axis=0) + 2.0
 
@@ -83,13 +96,19 @@ def __init__(
         Args:
             centroid (list): initial guess used as the starting point of
             the CMA-ES
+            offspring_size (int): number of offspring individuals in each
+                 generation
             sigma (float): initial standard deviation of the distribution
             max_ngen (int): total number of generation to run
             IndCreator (fcn): function returning an individual of the pop
+            RandIndCreator (fcn): function creating a random individual.
             weight_hv (float): between 0 and 1. Weight given to the
                 hypervolume contribution when computing the score of an
                 individual in MO-CMA. The weight of the fitness contribution
                 is computed as 1 - weight_hv.
+            map_function (map): function used to map (parallelize) the
+                 evaluation function calls
+            use_scoop (bool): use scoop map for parallel computation
         """
 
         if offspring_size is None:
@@ -104,7 +123,9 @@ def __init__(
                 from itertools import cycle
 
                 generator = cycle(centroids)
-                starters = [copy.deepcopy(next(generator)) for i in range(lambda_)]
+                starters = [
+                    copy.deepcopy(next(generator)) for i in range(lambda_)
+                ]
             else:
                 starters = centroids
 
@@ -128,7 +149,7 @@ def __init__(
         if self.use_scoop:
             if self.map_function:
                 raise Exception(
-                    "Impossible to use scoop is providing self defined map "
+                    "Impossible to use scoop and provide self defined map "
                     "function: %s" % self.map_function
                 )
             from scoop import futures
@@ -147,19 +168,19 @@ def __init__(
     def _select(self, candidates):
         """Select the best candidates of the population
 
-        The quality of an individual is based on a mixture of
-        absolute fitness and hyper-volume contribution.
-        """
+         Fill the next population (chosen) with the Pareto fronts until there
+         is not enough space. When an entire front does not fit in the space
+         left we rely on a mixture of hypervolume and fitness. The respective
+         weights of hypervolume and fitness are "hv" and "1-hv". The remaining
+         fronts are explicitly not chosen"""
 
         if self.weight_hv == 0.0:
             fit = [numpy.sum(ind.fitness.values) for ind in candidates]
-            idx_fit = list(numpy.argsort(fit))
-            idx_scores = idx_fit[:]
+            idx_scores = list(numpy.argsort(fit))
 
         elif self.weight_hv == 1.0:
             hv = get_hyped(candidates)
-            idx_hv = list(numpy.argsort(hv))[::-1]
-            idx_scores = idx_hv[:]
+            idx_scores = list(numpy.argsort(hv))[::-1]
 
         else:
             hv = get_hyped(candidates)
@@ -221,6 +242,6 @@ def check_termination(self, gen):
             if c.criteria_met:
                 logger.info(
                     "CMA stopped because of termination criteria: " +
-                    "" + " ".join(c.name)
+                    " ".join(c.name)
                 )
                 self.active = False

bluepyopt/deapext/CMA_SO.py

@@ -1,7 +1,7 @@
 """Single Objective CMA-es class"""
 
 """
-Copyright (c) 2016-2020, EPFL/Blue Brain Project
+Copyright (c) 2016-2022, EPFL/Blue Brain Project
 
  This file is part of BluePyOpt <https://github.com/BlueBrain/BluePyOpt>
 
@@ -63,11 +63,17 @@ def __init__(
         """Constructor
 
         Args:
-            centroid (list): initial guess used as the starting point of
-            the CMA-ES
-            sigma (float): initial standard deviation of the distribution
-            max_ngen (int): total number of generation to run
-            IndCreator (fcn): function returning an individual of the pop
+             centroid (list): initial guess used as the starting point of
+             the CMA-ES
+             offspring_size (int): number of offspring individuals in each
+                 generation
+             sigma (float): initial standard deviation of the distribution
+             max_ngen (int): total number of generation to run
+             IndCreator (fcn): function returning an individual of the pop
+             RandIndCreator (fcn): function creating a random individual.
+             map_function (map): function used to map (parallelize) the
+                 evaluation function calls
+             use_scoop (bool): use scoop map for parallel computation
         """
 
         if offspring_size is None:
@@ -214,6 +220,6 @@ def check_termination(self, gen):
             if c.criteria_met:
                 logger.info(
                     "CMA stopped because of termination criteria: " +
-                    "" + " ".join(c.name)
+                    " ".join(c.name)
                 )
                 self.active = False

bluepyopt/deapext/algorithms.py

@@ -1,7 +1,7 @@
 """Optimisation class"""
 
 """
-Copyright (c) 2016-2020, EPFL/Blue Brain Project
+Copyright (c) 2016-2022, EPFL/Blue Brain Project
 
  This file is part of BluePyOpt <https://github.com/BlueBrain/BluePyOpt>
 
@@ -155,7 +155,7 @@ def eaAlphaMuPlusLambdaCheckpoint(
         )
 
     stopping_criteria = [MaxNGen(ngen)]
-        
+
     # Begin the generational process
     gen = start_gen + 1
     stopping_params = {"gen": gen}
@@ -169,7 +169,7 @@ def eaAlphaMuPlusLambdaCheckpoint(
         invalid_count = _evaluate_invalid_fitness(toolbox, offspring)
         utils.update_history_and_hof(halloffame, history, population)
         utils.record_stats(stats, logbook, gen, population, invalid_count)
-        
+
         # Select the next generation parents
         parents = toolbox.select(population, mu)
 

bluepyopt/deapext/hype.py

@@ -1,5 +1,5 @@
 """
-Copyright (c) 2016-2020, EPFL/Blue Brain Project
+Copyright (c) 2016-2022, EPFL/Blue Brain Project
 
  This file is part of BluePyOpt <https://github.com/BlueBrain/BluePyOpt>
 
@@ -16,12 +16,13 @@
  along with this library; if not, write to the Free Software Foundation, Inc.,
  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 """
-
 import numpy
 
 
-def hypesub_(L, A, actDim, bounds, pvec, alpha, k):
-    h = numpy.zeros(L)
+def hypesub(la, A, actDim, bounds, pvec, alpha, k):
+    """HypE algorithm sub function"""
+
+    h = numpy.zeros(la)
     i = numpy.argsort(A[:, actDim - 1])
     S = A[i]
     pvec = pvec[i]
@@ -39,8 +40,8 @@ def hypesub_(L, A, actDim, bounds, pvec, alpha, k):
             if alpha[i - 1] >= 0:
                 h[pvec[0:i]] += extrusion * alpha[i - 1]
         elif extrusion > 0.0:
-            h += extrusion * hypesub_(
-                L, S[0:i, :], actDim - 1, bounds, pvec[0:i], alpha, k
+            h += extrusion * hypesub(
+                la, S[0:i, :], actDim - 1, bounds, pvec[0:i], alpha, k
             )
 
     return h
@@ -70,7 +71,7 @@ def hypeIndicatorExact(points, bounds, k):
         alpha.append(numpy.prod((k - j) / (Ps - j) / i))
     alpha = numpy.asarray(alpha)
 
-    return hypesub_(points.shape[0], points, actDim, bounds, pvec, alpha, k)
+    return hypesub(points.shape[0], points, actDim, bounds, pvec, alpha, k)
 
 
 def hypeIndicatorSampled(points, bounds, k, nrOfSamples):

bluepyopt/deapext/optimisations.py

@@ -1,7 +1,7 @@
 """Optimisation class"""
 
 """
-Copyright (c) 2016-2020, EPFL/Blue Brain Project
+Copyright (c) 2016-2022, EPFL/Blue Brain Project
 
  This file is part of BluePyOpt <https://github.com/BlueBrain/BluePyOpt>
 
@@ -107,6 +107,7 @@ def __init__(self, evaluator=None,
 
         Args:
             evaluator (Evaluator): Evaluator object
+            use_scoop (bool): use scoop map for parallel computation
             seed (float): Random number generator seed
             offspring_size (int): Number of offspring individuals in each
                 generation

bluepyopt/deapext/optimisationsCMA.py

@@ -1,7 +1,7 @@
 """CMA Optimisation class"""
 
 """
-Copyright (c) 2016-2020, EPFL/Blue Brain Project
+Copyright (c) 2016-2022, EPFL/Blue Brain Project
 
  This file is part of BluePyOpt <https://github.com/BlueBrain/BluePyOpt>
 
@@ -39,6 +39,9 @@
 
 
 def _ind_convert_space(ind, convert_fcn):
+    """util function to pass the individual from normalized to real space and
+    inversely"""
+
     return [f(x) for f, x in zip(convert_fcn, ind)]
 
 
@@ -64,6 +67,7 @@ def __init__(
 
         Args:
             evaluator (Evaluator): Evaluator object
+            use_scoop (bool): use scoop map for parallel computation
             seed (float): Random number generator seed
             offspring_size (int): Number of offspring individuals in each
                 generation
@@ -192,16 +196,12 @@ def setup_deap(self):
             ),
         )
 
-        # A Random Indiviual is create by ListIndividual and parameters are
+        # A Random Individual is created by ListIndividual and parameters are
         # initially picked by 'uniform'
         self.toolbox.register(
             "RandomInd",
             deap.tools.initIterate,
-            functools.partial(
-                utils.WSListIndividual,
-                obj_size=self.ind_size,
-                reduce_fcn=self.fitness_reduce,
-            ),
+            self.toolbox.Individual,
             self.toolbox.uniformparams,
         )
 
@@ -293,6 +293,7 @@ def run(
                 fitness = self.toolbox.map(self.toolbox.evaluate, to_evaluate)
                 fitness = list(map(list, fitness))
                 CMA_es.set_fitness_parents(fitness)
+
             gen = 1
 
         pop = CMA_es.get_population(self.to_space)