readme; debug

pyrimidine/deco.py

@@ -2,6 +2,11 @@
 
 """
 Decorators
+
+Two main kinds of decorators:
+1. cache decorator: store the information of previous computing, to seep up the algorithm.
+         Should clear it to suppress the side effect. It is used with `@side-effect` decorator.
+2. memory decorator: As cache, it record some information, but it will chage the behavior of the algorithms.
 """
 
 from types import MethodType
@@ -10,6 +15,8 @@
 
 
 def clear_cache(func):
+    # clear the cache coersively
+
     def mthd(obj, *args, **kwargs):
         result = func(obj, *args, **kwargs)
         obj.clear_cache()
@@ -203,7 +210,7 @@ class add_memory:
     And it is not affected by the genetic operations.
 
     _memory {dict[str]} -- the memory for an object;
-                        In general, the key is the property of the object.
+                        In general, the keys are the attributes of the object.
     """
 
     def __init__(self, memory={}):
@@ -223,14 +230,15 @@ def _set_memory(obj, **d):
 
         cls.set_memory = _set_memory
 
-        def fitness(obj):
-            # get fitness from memory by default
-            if obj.memory['fitness'] is None:
-                return obj._fitness()
-            else:
-                return obj.memory['fitness']
+        if hasattr(cls, '_fitness'):
+            def fitness(obj):
+                # get fitness from memory by default
+                if obj.memory['fitness'] is None:
+                    return obj._fitness()
+                else:
+                    return obj.memory['fitness']
 
-        cls.fitness = property(fitness)
+            cls.fitness = property(fitness)
 
         for a in cls._memory:
             if a == 'fitness': continue
@@ -239,8 +247,7 @@ def f(obj):
                 where the best solution is stored
                 """
                 if obj._memory[a] is None:      
-                    v = getattr(super(cls, obj), a)
-                    return v
+                    return getattr(super(cls, obj), a)
                 else:
                     return obj._memory[a]
             setattr(cls, a, property(f))
@@ -293,16 +300,19 @@ def _init(obj):
 usual_side_effect = ['mutate', 'extend', 'pop', 'remove', '__setitem__', '__setattr__', '__setstate__']
 
 def method_cache(func, a):
-    """cache for methods
+    """make cache for the method
 
-    Pre-define `_cache` as an attribute of the obj.
+    If the attribute a is in the cache, then access it from the cache directly,
+    else compute it again, and store it in the cache
+
+    Please pre-define `_cache` as an attribute of the obj.
     
     Args:
         func (TYPE): the original method
         a (TYPE): an attribute (or any value) computed by the method
     
     Returns:
-        MethodType
+        function: new method
     """
 
     def mthd(obj):
@@ -317,6 +327,7 @@ def mthd(obj):
 
 
 class regester_map:
+    # To regester the map method for the class requiring `map` method
 
     def __init__(self, mappings, map_=map):
         """

pyrimidine/mixin.py

@@ -310,7 +310,7 @@ def clone(self):
 class CollectiveMixin(IterativeMixin):
     # mixin class for swarm intelligent algorithm
 
-    map = map
+    map = map  # use the biuld-in `map` function by default
 
     def init(self, *args, **kwargs):
         for element in self:
@@ -408,6 +408,14 @@ def max_fitness(self):
 
     @property
     def stat_fitness(self, s=np.max):
+        """Do statistics for the fitnesses of individuals in the population
+        
+        Args:
+            s (a function or a tuple of functions): a statistic
+        
+        Returns:
+            number or a tuple of numbers
+        """
         f = self.get_all_fitness()
         if isinstance(s, tuple):
             return tuple(si(f) for si in  s)
@@ -421,7 +429,7 @@ def get_best_element(self, copy=False):
             copy (bool, optional): return the copy of the selected element, if `copy=True`
         
         Returns:
-            An element
+            An element: the element with max fitness
         """
 
         k = np.argmax(self.get_all_fitness())
@@ -491,6 +499,7 @@ def get_worst_elements(self, n=1, copy=False):
 
     @property
     def worst_element(self):
+        # like worst_element
         k = np.argmin(self.get_all_fitness())
         return self[k]
 

tests/test_sa.py

@@ -3,7 +3,7 @@
 
 from pyrimidine.individual import MonoIndividual
 from pyrimidine.chromosome import FloatChromosome
-from pyrimidine.local_search.simulated_annealing import *
+from pyrimidine.local_search.simulated_annealing import SimulatedAnnealing
 
 from pyrimidine.benchmarks.special import rosenbrock