Merge branch 'review'

Author: geoffreyp

docs/_static/components.png

@@ -3,7 +3,9 @@ Contributing
 ===========================================
 
 When contributing to this project, please first discuss the change you wish to make via GitHub discussions,
-email, or any other method with the owners of this repository before making a change. 
+email, or any other method with the owners of this repository before making a change.
+The contribution can be the report of a bug, the request for a new feature or
+modifying the code of the framework to improve it.
 
 Please note we have a code of conduct, please follow it in all your interactions with the project.
 
@@ -31,6 +33,13 @@ help us to understand your request. Share with us the following information:
 - the error raised by your code
 - all steps to reproduce the bug
 
+
+Support
+________________________________
+
+If you have any questions about the project, don't hesitate to create a new discussion with GitHub Discussions (https://github.com/moead-framework/framework/discussions).
+It is the space for our community to have conversations, ask questions and post answers without opening issues.
+
 Code of Conduct
 ________________________________
 

docs/contributing.rst

@@ -22,6 +22,7 @@ If you have any questions about the framework or the project, feel free to creat
    :maxdepth: 2
 
    install
+   user_guide
    tuto
    api
    examples

docs/index.rst

@@ -0,0 +1,151 @@
+
+User guide
+===========================================
+
+Overview
+-------------------------------------- 
+
+moead-framework is a modular framework composed of 10 customizable components summarized in the following figure.
+In this user guide, we will present the role of each component in a general way.
+For more detailed information, you can visit the following documentation : https://moead-framework.github.io/framework/html/api.html
+
+.. image:: _static/components.png
+  :width: 600
+  :alt: overview
+
+Problem & Solution
+--------------------------------------
+
+The problem is one of the main components of the framework.
+The solutions are the link between the algorithm and the problem. The solutions are generated during the algorithm
+in order to solve the problem.
+
+The problem in the framework is a component that allows to randomly generate solutions and to evaluate them.
+The solutions have two important attributes:
+    - ``decision_vector`` : list of all decision variables of the solution
+    - ``F`` : all objectives values of the solution, for example, ``F[0]`` is the objective value for the function f0 and ``F[1]`` is the objective value for the function f1.
+
+Example of the Rmnk problem :
+    >>> from moead_framework.problem.combinatorial import Rmnk
+    >>>
+    >>> # The file is available here : https://github.com/moead-framework/data/blob/master/problem/RMNK/Instances/rmnk_0_2_100_1_0.dat
+    >>> # Others instances are available here : https://github.com/moead-framework/data/tree/master/problem/RMNK/Instances
+    >>> instance_file = "rmnk_0_2_100_1_0.dat"
+    >>> problem = Rmnk(instance_file=instance_file)
+    >>>
+    >>> # Generate a new solution
+    >>> solution = problem.generate_random_solution()
+    >>>
+    >>> # Print all decision variables of the solution
+    >>> print(solution.decision_vector)
+    >>>
+    >>> # Print all objectives values of the solution
+    >>> print(solution.F)
+
+
+Algorithm
+--------------------------------------
+
+In the framework, the algorithm is the main component, composed of several sub-components to easily parameterize it.
+The algorithms are defined with default components which allows to execute them very easily with few parameters.
+The mandatory parameters are the problem, the maximum number of evaluations,
+the number of sub-problems in the neighborhood, the file that defines the weight vectors and the aggregation function.
+The complete and detailed settings of each algorithm are available here : https://moead-framework.github.io/framework/html/main_components.html#algorithms.
+
+Example with the original MOEA/D algorithm :
+    >>> from moead_framework.aggregation import Tchebycheff
+    >>> from moead_framework.algorithm.combinatorial import Moead
+    >>> from moead_framework.problem.combinatorial import Rmnk
+    >>>
+    >>> # The file is available here : https://github.com/moead-framework/data/blob/master/problem/RMNK/Instances/rmnk_0_2_100_1_0.dat
+    >>> # Others instances are available here : https://github.com/moead-framework/data/tree/master/problem/RMNK/Instances
+    >>> instance_file = "moead_framework/test/data/instances/rmnk_0_2_100_1_0.dat"
+    >>> rmnk = Rmnk(instance_file=instance_file)
+    >>>
+    >>> number_of_weight = 10
+    >>> # The file is available here : https://github.com/moead-framework/data/blob/master/weights/SOBOL-2objs-10wei.ws
+    >>> # Others weights files are available here : https://github.com/moead-framework/data/tree/master/weights
+    >>> weight_file = "moead_framework/test/data/weights/SOBOL-" + str(rmnk.number_of_objective) + "objs-" + str(number_of_weight) + "wei.ws"
+    >>>
+    >>> moead = Moead(problem=rmnk,
+    >>>               max_evaluation=1000,
+    >>>               number_of_weight_neighborhood=2,
+    >>>               weight_file=weight_file,
+    >>>               aggregation_function=Tchebycheff,
+    >>>               )
+    >>>
+    >>> population = moead.run()
+
+
+Sub-problem selection strategy
+--------------------------------------
+
+This component, introduced in :cite:`moead_dra` and :cite:`gpruvost_evocop2020`, has the objective to select the sub-problems
+to be optimized during the next generation. By default in MOEA/D, all subproblems are selected.
+This component requires the attribute ``number_of_subproblem`` in the algorithm which defines the
+number of subproblems to select.
+
+More information : https://moead-framework.github.io/framework/html/other_components.html#sub-problem-selection-strategy
+
+
+Aggregation functions
+--------------------------------------
+
+This component defines the aggregation function used to decompose the multi-objective problem into several single-objective sub-problems.
+The function ``run(solution, number_of_objective, weights, sub_problem, z)`` allows to evaluate a solution for a
+given sub-problem and the function ``is_better(old_value, new_value)`` allows to compare two aggregation values.
+
+More information : https://moead-framework.github.io/framework/html/main_components.html#aggregation-functions
+
+
+Mating Selector
+--------------------------------------
+
+This component aims to select the solutions that can be chosen as parent solutions to generate an offspring.
+The method ``select(sub_problem)`` returns the indexes of the selected solutions.
+By default in MOEA/D, this component returns the index of the solutions in the neighborhood of the subproblem
+currently visited.
+
+More information : https://moead-framework.github.io/framework/html/other_components.html#mating-selector
+
+
+Offspring generator
+--------------------------------------
+
+This component is designed to generate offsprings from a set of solutions given in parameter.
+Its unique method ``run(population_indexes)`` returns a unique solution.
+By default, a generic component is used, it uses two subcomponents which allow to select
+parent solutions (Parent Selector) and then to execute a genetic operator to generate the new offspring.
+
+More information : https://moead-framework.github.io/framework/html/other_components.html#offspring-generator
+
+
+Parent Selector
+~~~~~~~~~~~~~~~~~~~~~~
+
+This component is used in the offspring generator component.
+It allows to choose the solutions which will be used to generate new solutions.
+The method ``select(indexes)`` takes as parameter the indexes of the solutions available to be
+selected (chosen by the Mating selector component) to return a list of solutions.
+
+More information : https://moead-framework.github.io/framework/html/other_components.html#parent-selector
+
+
+Genetic operators
+~~~~~~~~~~~~~~~~~~~~~~
+
+This component is used in the offspring generator component. This component is initialized by its constructor with
+the solutions chosen by the Parent Selector component. Other parameters can be added according to the operators
+like the number of crossover points or the mutation rate for example.
+The ``run()`` method returns after its execution a new offspring.
+
+More information : https://moead-framework.github.io/framework/html/other_components.html#genetic-operators
+
+
+Termination criteria
+--------------------------------------
+
+This component aims at defining the stopping criteria of the algorithm. The method ``test()`` of this component
+returns a boolean to define if the algorithm can continue to be executed.
+
+More information : https://moead-framework.github.io/framework/html/other_components.html#termination-criteria

docs/user_guide.rst

@@ -1,5 +1,8 @@
+import numpy as np
 from abc import ABC, abstractmethod
 
+from moead_framework.solution.base import Solution
+
 
 class AggregationFunction(ABC):
     """
@@ -18,6 +21,29 @@ def run(self, solution, number_of_objective, weights, sub_problem, z):
         :param z: {list<float>} coordinates of the reference point Z*
         :return: {float} the aggregation value of the solution for the weight vector: weights[sub-problem]
         """
+        if not isinstance(solution, Solution):
+            raise TypeError(
+                f"The parameter 'solution' of {self.__class__.__name__}.run() must be a child of the Solution class. Instead, we have {type(solution)}")
+
+        if not isinstance(number_of_objective, int):
+            raise TypeError(
+                f"The parameter 'number_of_objective' of {self.__class__.__name__}.run() must be an integer. Instead, we have {type(number_of_objective)}")
+
+        if not isinstance(weights, list):
+            raise TypeError(
+                f"The parameter 'weights' of {self.__class__.__name__}.run() must be a list. Instead, we have {type(weights)}")
+
+        if not isinstance(sub_problem, int):
+            raise TypeError(
+                f"The parameter 'sub_problem' of {self.__class__.__name__}.run() must be an integer. Instead, we have {type(sub_problem)}")
+
+        if (not isinstance(z, list)) & (not isinstance(z, np.ndarray)):
+            raise TypeError(
+                f"The parameter 'z' of {self.__class__.__name__}.run() must be a list. Instead, we have {type(z)}")
+        else:
+            if len(z) != number_of_objective:
+                raise TypeError(
+                    f"The number of items in the parameter 'z' of {self.__class__.__name__}.run() must be equals at {number_of_objective}. Instead, we have {len(z)}")
 
     @abstractmethod
     def is_better(self, old_value, new_value):
@@ -29,3 +55,6 @@ def is_better(self, old_value, new_value):
         :return: {boolean} True if new_value is better than old_value.
         The test depends of the aggregation function and of the context (minimization or maximization).
         """
+        # if not isinstance(old_value, (np.floating, float)) & (not isinstance(new_value, (np.floating, float))):
+        if ((not np.issubdtype(type(old_value), (np.floating))) & (not isinstance(old_value, int))) | (not np.issubdtype(type(new_value), (np.floating))) & (not isinstance(new_value, int)):
+            raise TypeError(f"Parameters of {self.__class__.__name__}.is_better() must be float or int. Instead, we have {type(old_value)} and {type(new_value)}")

moead_framework/aggregation/functions.py

@@ -16,6 +16,7 @@ def is_better(self, old_value, new_value):
         :param new_value: {float} new aggregation value
         :return: {boolean} True if new_value is better than old_value.
         """
+        super().is_better(old_value, new_value)
         return new_value < old_value
 
     def run(self, solution, number_of_objective, weights, sub_problem, z):
@@ -29,6 +30,7 @@ def run(self, solution, number_of_objective, weights, sub_problem, z):
         :param z: {list<float>} coordinates of the reference point Z*
         :return: {float} the aggregation value of the solution for the weight vector: weights[sub-problem]
         """
+        super().run(solution,number_of_objective,weights, sub_problem, z)
         max_distance = 0
 
         for i in range(number_of_objective):

moead_framework/aggregation/tchebycheff.py

@@ -13,6 +13,7 @@ def is_better(self, old_value, new_value):
         :param new_value: {float} new aggregation value
         :return: {boolean} True if new_value is better than old_value.
         """
+        super().is_better(old_value, new_value)
         return new_value < old_value
 
     def run(self, solution, number_of_objective, weights, sub_problem, z):
@@ -26,6 +27,8 @@ def run(self, solution, number_of_objective, weights, sub_problem, z):
         :param z: {list<float>} coordinates of the reference point Z*
         :return: {float} the aggregation value of the solution for the weight vector: weights[sub-problem]
         """
+        super().run(solution, number_of_objective, weights, sub_problem, z)
+
         res = 0
         for i in range(number_of_objective):
             res += solution.F[i] * weights[sub_problem][i]

moead_framework/aggregation/weighted_sum.py

@@ -2,10 +2,18 @@
 
 import numpy as np
 
+from moead_framework.aggregation.functions import AggregationFunction
+from moead_framework.core.genetic_operator import GeneticOperator
+from moead_framework.core.offspring_generator.abstract_mating import OffspringGenerator
 from moead_framework.core.offspring_generator.offspring_generator import OffspringGeneratorGeneric
+from moead_framework.core.parent_selector.abstract_parent_selector import ParentSelector
+from moead_framework.core.selector.abstract_selector import MatingPoolSelector
 from moead_framework.core.selector.closest_neighbors_selector import ClosestNeighborsSelector
+from moead_framework.core.sps_strategy.abstract_sps import SpsStrategy
 from moead_framework.core.sps_strategy.sps_all import SpsAllSubproblems
+from moead_framework.core.termination_criteria.abstract_termination_criteria import TerminationCriteria
 from moead_framework.core.termination_criteria.max_evaluation import MaxEvaluation
+from moead_framework.problem import Problem
 from moead_framework.tool.mop import is_duplicated, get_non_dominated, generate_weight_vectors
 
 
@@ -44,8 +52,18 @@ def __init__(self, problem, max_evaluation, number_of_weight_neighborhood,
         :param number_of_weight: Deprecated -- {integer} number of weight vector used to decompose the problem. Deprecated, remove in the next major release.
         :param number_of_objective: Deprecated -- {integer} number of objective in the problem. Deprecated, remove in the next major release.
         """
-        self.problem = problem
-        self.aggregation_function = aggregation_function()
+        if isinstance(problem, Problem):
+            self.problem = problem
+        else:
+            raise TypeError("The expected type of `problem` is `Problem`")
+
+        if not isinstance(weight_file, str):
+            raise TypeError("The expected type of `weight_file` is `Str`")
+
+        if issubclass(aggregation_function, AggregationFunction):
+            self.aggregation_function = aggregation_function()
+        else:
+            raise TypeError("The expected type of `aggregation_function` is `AggregationFunction`")
 
         if number_of_weight is not None:
             import warnings
@@ -58,11 +76,23 @@ def __init__(self, problem, max_evaluation, number_of_weight_neighborhood,
         if termination_criteria is None:
             self.termination_criteria = MaxEvaluation(algorithm_instance=self)
         else:
-            self.termination_criteria = termination_criteria(algorithm_instance=self)
+            if issubclass(termination_criteria, TerminationCriteria):
+                self.termination_criteria = termination_criteria(algorithm_instance=self)
+            else:
+                raise TypeError("The expected type of `termination_criteria` is `TerminationCriteria`")
+
+        if isinstance(max_evaluation, int):
+            self.max_evaluation = max_evaluation
+        else:
+            raise TypeError("The expected type of `max_evaluation` is `int`")
 
-        self.max_evaluation = max_evaluation
         self.number_of_objective = self.problem.number_of_objective
-        self.t = number_of_weight_neighborhood
+
+        if isinstance(number_of_weight_neighborhood, int):
+            self.t = number_of_weight_neighborhood
+        else:
+            raise TypeError("The expected type of `number_of_weight_neighborhood` is `int`")
+
         self.ep = []
 
         self.weights = generate_weight_vectors(weight_file, shuffle=False)
@@ -78,20 +108,36 @@ def __init__(self, problem, max_evaluation, number_of_weight_neighborhood,
         if sps_strategy is None:
             self.sps_strategy = SpsAllSubproblems(algorithm_instance=self)
         else:
-            self.sps_strategy = sps_strategy(algorithm_instance=self)
+            if issubclass(sps_strategy, SpsStrategy):
+                self.sps_strategy = sps_strategy(algorithm_instance=self)
+            else:
+                raise TypeError("The expected type of `sps_strategy` is `SpsStrategy`")
 
         if mating_pool_selector is None:
             self.mating_pool_selector = ClosestNeighborsSelector(algorithm_instance=self)
         else:
-            self.mating_pool_selector = mating_pool_selector(algorithm_instance=self)
+            if issubclass(mating_pool_selector, MatingPoolSelector):
+                self.mating_pool_selector = mating_pool_selector(algorithm_instance=self)
+            else:
+                raise TypeError("The expected type of `mating_pool_selector` is `MatingPoolSelector`")
 
-        self.genetic_operator = genetic_operator
-        self.parent_selector = parent_selector
+        if issubclass(genetic_operator, GeneticOperator):
+            self.genetic_operator = genetic_operator
+        else:
+            raise TypeError("The expected type of `genetic_operator` is `GeneticOperator`")
+
+        if issubclass(parent_selector, ParentSelector):
+            self.parent_selector = parent_selector(algorithm=self)
+        else:
+            raise TypeError("The expected type of `parent_selector` is `ParentSelector`")
 
         if offspring_generator is None:
             self.offspring_generator = OffspringGeneratorGeneric(algorithm_instance=self)
         else:
-            self.offspring_generator = offspring_generator(algorithm_instance=self)
+            if issubclass(offspring_generator, OffspringGenerator):
+                self.offspring_generator = offspring_generator(algorithm_instance=self)
+            else:
+                raise TypeError("The expected type of `offspring_generator` is `OffspringGenerator`")
 
     def run(self, checkpoint=None):
         """