From b47254c9474514fcab2fa8096b050539d1a12284 Mon Sep 17 00:00:00 2001 From: Demetry Pascal Date: Sat, 13 Apr 2024 19:48:32 +0300 Subject: [PATCH] update some docstrings --- geneticalgorithm2/geneticalgorithm2.py | 38 ++++++++++----------- geneticalgorithm2/population_initializer.py | 10 ++++-- 2 files changed, 27 insertions(+), 21 deletions(-) diff --git a/geneticalgorithm2/geneticalgorithm2.py b/geneticalgorithm2/geneticalgorithm2.py index 8bc623b..d8a5ee3 100644 --- a/geneticalgorithm2/geneticalgorithm2.py +++ b/geneticalgorithm2/geneticalgorithm2.py @@ -1,12 +1,11 @@ -from typing import Callable, List, Tuple, Optional, Dict, Any, Union, Sequence, Set, Literal +from typing import Callable, List, Tuple, Optional, Dict, Any, Union, Sequence, Literal, Iterable from typing_extensions import TypeAlias import collections import warnings import operator - import sys import time import random @@ -14,6 +13,9 @@ import numpy as np +from OppOpPopInit.initialiser import CreatorFunc +from OppOpPopInit.oppositor import OppositorFunc + #region INTERNAL IMPORTS from .utils.aliases import array1D, array2D @@ -23,7 +25,7 @@ from .data_types.generation import GenerationConvertible, Generation from .data_types.result import GAResult -from .population_initializer import get_population_initializer +from .population_initializer import get_population_initializer, PopulationModifier from .utils.plotting import plot_pop_scores, plot_several_lines from .utils.funcs import can_be_prob, is_numpy, is_current_gen_number, fast_min, random_indexes_pair @@ -400,7 +402,7 @@ def _simulate(self, sample: array1D): return obj, eval_time - def _set_mutation_indexes(self, mutation_indexes: Optional[Sequence[int]]): + def _set_mutation_indexes(self, mutation_indexes: Optional[Iterable[int]]): if mutation_indexes is None: self.indexes_float_mut = self.indexes_float @@ -427,20 +429,20 @@ def run( apply_function_to_parents: bool = False, start_generation: GenerationConvertible = Generation(), studEA: bool = False, - mutation_indexes: Optional[Union[Sequence[int], Set[int]]] = None, + mutation_indexes: Optional[Iterable[int]] = None, - init_creator: Optional[Callable[[], array1D]] = None, - init_oppositors: Optional[Sequence[Callable[[array1D], array1D]]] = None, + init_creator: Optional[CreatorFunc] = None, + init_oppositors: Optional[Sequence[OppositorFunc]] = None, - duplicates_oppositor: Optional[Callable[[array1D], array1D]] = None, + duplicates_oppositor: Optional[OppositorFunc] = None, remove_duplicates_generation_step: Optional[int] = None, - revolution_oppositor: Optional[Callable[[array1D], array1D]] = None, + revolution_oppositor: Optional[OppositorFunc] = None, revolution_after_stagnation_step: Optional[int] = None, revolution_part: float = 0.3, population_initializer: Tuple[ - int, Callable[[array2D, array1D], Tuple[array2D, array1D]] + int, PopulationModifier ] = get_population_initializer(select_best_of=1, local_optimization_step='never', local_optimizer=None), stop_when_reached: Optional[float] = None, @@ -460,17 +462,13 @@ def run( progress_bar_stream: 'stdout', 'stderr' or None to disable progress bar - disable_progress_bar: + disable_progress_bar: deprecated - set_function : 2D-array -> 1D-array function, - which applyes to matrix of population (size (samples, dimention)) - to estimate their values + set_function: set function to be used instead of usual function - apply_function_to_parents: apply function to parents from previous generation (if it's needed) + apply_function_to_parents: whether to apply function to parents from previous generation (if it's needed) - start_generation: Generation object or a dictionary with structure - {'variables':2D-array of samples, 'scores': function values on samples} - or path to .npz file (str) with saved generation; if 'scores' value is None the scores will be compute + start_generation: initial generation object of any `GenerationConvertible` type studEA: using stud EA strategy (crossover with best object always) @@ -479,10 +477,12 @@ def run( init_creator: the function creates population samples. By default -- random uniform for real variables and random uniform for int init_oppositors: the list of oppositors creates oppositions for base population. No by default + duplicates_oppositor: oppositor for applying after duplicates removing. By default -- using just random initializer from creator remove_duplicates_generation_step: step for removing duplicates (have a sense with discrete tasks). No by default + revolution_oppositor: oppositor for revolution time. No by default revolution_after_stagnation_step: create revolution after this generations of stagnation. No by default revolution_part: float, the part of generation to being oppose. By default is 0.3 @@ -495,7 +495,7 @@ def run( callbacks: sequence of callback functions with structure: (generation_number, report_list, last_population, last_scores) -> do some action - middle_callbacks: sequence of functions made MiddleCallbacks class + middle_callbacks: sequence of functions made `MiddleCallback` class time_limit_secs: limit time of working (in seconds) diff --git a/geneticalgorithm2/population_initializer.py b/geneticalgorithm2/population_initializer.py index 85703a3..5a195b6 100644 --- a/geneticalgorithm2/population_initializer.py +++ b/geneticalgorithm2/population_initializer.py @@ -6,6 +6,12 @@ from .utils.aliases import TypeAlias, array1D, array2D +PopulationModifier: TypeAlias = Callable[[array2D, array1D], Tuple[array2D, array1D]] +""" +function (population matrix, population scores) -> (new matrix, new scores) +which will perform the bests selection and local optimization and other population transformations +""" + LOCAL_OPTIMIZATION_STEP_CASE: TypeAlias = Literal['before_select', 'after_select', 'never'] """ When the local optimization (candidates enhancing) must be performed: @@ -25,7 +31,7 @@ def get_population_initializer( Tuple[array1D, float] ] ] = None -) -> Tuple[int, Callable[[array2D, array1D], Tuple[array2D, array1D]]]: +) -> Tuple[int, PopulationModifier]: """ Args: select_best_of: determines population size to select 1/select_best_of best part of start population. @@ -36,7 +42,7 @@ def get_population_initializer( local_optimizer: the local optimization function (object array, its score) -> (modified array, its score) Returns: - select_best_of, function which will perform the selection and local optimization + select_best_of, population modifier """ assert select_best_of > 0 and isinstance(select_best_of, int), (select_best_of, type(select_best_of))