feat: add some docstrings

golem/core/optimisers/common_optimizer/common_optimizer.py

@@ -22,6 +22,7 @@
 
 @dataclass
 class CommonOptimizerParameters:
+    """ This class is for storing a state of all CommonOptimizer parameters """
     _run: bool
     generations: List[PopulationT]
     population: PopulationT
@@ -37,6 +38,16 @@ class CommonOptimizerParameters:
 
 
 class CommonOptimizer(PopulationalOptimizer):
+    """
+    This class implements a common optimizer.
+
+    Args:
+        objective: objective for optimization
+        initial_graphs: graphs which were initialized outside the optimizer
+        requirements: implementation-independent requirements for graph optimizer
+        graph_generation_params: parameters for new graph generation
+        graph_optimizer_params: parameters for specific implementation of graph optimizer
+    """
     __parameters_attrs = ('objective', 'initial_graphs', 'requirements', 'graph_generation_params',
                           'graph_optimizer_params', 'history', 'stages', '_run',
                           'generations', 'population', 'evaluator')
@@ -82,6 +93,7 @@ def parameters(self, parameters: CommonOptimizerParameters):
     #             self.parameters = self.stages[i_stage].run(self.parameters)
 
     def _initial_population(self, evaluator: EvaluationOperator):
+        """ Initializes the initial population """
         self._update_population(evaluator(self.initial_individuals), 'initial_assumptions')
 
     def _evolve_population(self, evaluator: EvaluationOperator) -> PopulationT:

golem/core/optimisers/common_optimizer/node.py

@@ -6,7 +6,14 @@
 
 @dataclass
 class Node:
-    """ Node with operation """
+    """
+    Represents a lightweight node in a computational graph.
+    Implemented to support an adaptive approach to task completion.
+
+    Args:
+        name: node identificator
+        operation: action performed within the node call
+    """
 
     def __init__(self, name: str, operation: Callable[[Task], Union[Task, List[Task]]]):
         self.name = name

golem/core/optimisers/common_optimizer/runner.py

@@ -19,6 +19,18 @@
 
 @dataclass
 class Worker:
+    """
+    Represents a worker that executes tasks within the optimization process.
+
+    Args:
+        scheme: optimization scheme of nodes execution.
+        origin_task: task to start the execution from.
+        node_map: mapping of node names to Node objects.
+        queued_tasks: queue to store the queued tasks.
+        processed_tasks: queue to store the processed tasks.
+        sleep_time: sleep time in seconds between each task execution.
+    """
+
     scheme: Scheme
     origin_task: Task
     node_map: Dict[str, Node]
@@ -45,12 +57,23 @@ def __call__(self, seed: int):
 
 
 class Runner:
+    """
+    Abstract base class for runners in the optimization process.
+    """
     @abstractmethod
     def run(self, scheme: Scheme, task: Task, nodes: List[Node], stop_fun: Callable):
         raise NotImplementedError('It is abstract method')
 
 
 class ParallelRunner(Runner):
+    """
+    Runner that executes tasks in parallel using multiple processes.
+    Args:
+        n_jobs: number of processes to use for parallel execution. Defaults to -1.
+        main_cycle_sleep_seconds: sleep time in seconds between each main cycle. Defaults to 1.
+        worker_cycle_sleep_seconds: sleep time in seconds between each worker cycle. Defaults to 0.02.
+    """
+
     # TODO test for same results from Parallel and OneThread
     def __init__(self,
                  *args,
@@ -83,6 +106,10 @@ def run(self, scheme: Scheme, task: Task, nodes: List[Node], stop_fun: Callable)
 
 
 class OneThreadRunner(Runner):
+    """
+    Runner that executes tasks in a single thread.
+    """
+
     def run(self, scheme: Scheme, task: Task, nodes: List[Node], stop_fun: Callable):
         origin_task = task
         node_map = {node.name: node for node in nodes}

golem/core/optimisers/common_optimizer/scheme.py

@@ -7,7 +7,10 @@
 
 
 class Scheme:
-    """ Contain pipeline for task flow between nodes """
+    """
+    Base class of a Scheme.
+    Specific scheme should define a pipeline for task flow between nodes.
+    """
     # TODO create real pipelines with `show` method
     # TODO support for multioutput
 
@@ -21,6 +24,10 @@ def next(self, task: Task):
 
 
 class SequentialScheme(Scheme):
+    """
+    Represents a scheme where nodes are executed sequentially.
+    """
+
     def __init__(self, *args, nodes: Optional[List[Union[str, Node]]] = None, **kwargs):
         if nodes is None:
             raise ValueError('nodes should be list with nodes')

golem/core/optimisers/common_optimizer/stage.py

@@ -10,10 +10,19 @@
 
 @dataclass
 class Stage:
-    """ Store data for runner
+    """
+    Represents a stage in runner and stores operations (nodes) and the operations execution scheme.
         task_builder - Task class
         stop_fun - see Runner docs
-        parameter_updater - callable that gets results of Runner call and parameters, returns updated parameters """
+        parameter_updater - callable that gets results of Runner call and parameters, returns updated parameters
+    Args:
+        runner: object responsible for executing tasks.
+        nodes: list of operations in the stage.
+        task_builder: Task class used to create tasks from parameters.
+        scheme: object defining the data flow between nodes.
+        stop_fun: stop function used by the runner.
+        parameter_updater: function that gets updated parameters from runner call and passed parameters.
+    """
     # TODO move to Runner
 
     runner: Runner
@@ -24,6 +33,7 @@ class Stage:
     parameter_updater: Callable[[List[Task], 'CommonOptimizerParameters'], 'CommonOptimizerParameters']
 
     def run(self, parameters: 'CommonOptimizerParameters'):
+        """  Executes the stage's runner with the specified parameters and returns the updated parameters. """
         task = self.task_builder(parameters)
         results = self.runner.run(nodes=self.nodes, task=task, scheme=self.scheme, stop_fun=self.stop_fun)
         return self.parameter_updater(results, parameters)

golem/core/optimisers/common_optimizer/task.py

@@ -12,6 +12,9 @@ class TaskStatusEnum(Enum):
 
 
 class TaskMixin:
+    """
+    Base class of task.
+    """
     def update_parameters(self, parameters: 'CommonOptimizerParameters'):
         return parameters
 
@@ -21,17 +24,20 @@ def copy(self):
 
 
 class Task(TaskMixin):
-    """ Task is used for extract/contain/inject data from/to CommonOptimizerParameters
-        Task is used as data container for scheme data flows
+    """
+    Provides functionality to extract, contain, and inject data from/to CommonOptimizerParameters.
+    Task is used as a data container for scheme data streams and is essentially a wrapper for the data.
 
-        __init__ is used for extract data, get `parameters` as argument
-        update_parameters is used for inject parameters from task to `parameters`
-        _stages contains history of scheme data flows
-        status - TaskStatusEnum
-        node - name of node
-        """
+    Methods:
+        __init__(parameters: CommonOptimizerParameters):
+            Extracts data from the CommonOptimizerParameters object.
+
+        update_parameters(task: Task):
+            Injects parameters from the task into the CommonOptimizerParameters object.
+    """
 
     def __init__(self, parameters: Optional['CommonOptimizerParameters'] = None):
+        # history of scheme data flows is stored in `self._stages`
         self._stages: List[Tuple[Optional[str], TaskStatusEnum]] = [(None, TaskStatusEnum.NEXT)]
 
     def __repr__(self):
@@ -42,20 +48,24 @@ def __repr__(self):
 
     @property
     def status(self):
+        """ Retrieve task status from current last stage of task """
         return self._stages[-1][-1]
 
     @status.setter
     def status(self, item: TaskStatusEnum):
+        """ Set specific task status to current last stage of task """
         if not isinstance(item, TaskStatusEnum):
             raise TypeError(f"status should be `TaskStatusEnum`, got {type(item)} instead")
         self._stages.append((self.node, item))
 
     @property
     def node(self):
+        """ Retrieve current node name from current last stage of task """
         return self._stages[-1][0]
 
     @node.setter
     def node(self, item: Optional[str]):
+        """ Set specific node name to current last stage of task """
         if not isinstance(item, str) and item is not None:
             raise TypeError(f"node should be `str` or `None`, got {type(item)} instead")
         self._stages.append((item, TaskStatusEnum.FINISH if item is None else TaskStatusEnum.NEXT))

golem/core/optimisers/common_optimizer/temp/adaptive.py

@@ -36,11 +36,22 @@ def update_parameters(self, parameters: CommonOptimizerParameters) -> CommonOpti
 
 
 class AdaptiveParameters(Node):
+    """
+    This class is a field-setter for a list of AdaptiveParametersTask,
+    new parameters should be passed in a form of double mested dictionaary with
+    OptimizationParameters, GraphGenerationParams or AlgorithmParameters specification.
+    :param parameters: dictionary with specified parameters and their values
+    """
     def __init__(self, name: str, parameters: Dict[str, Dict[str, Any]]):
         self.name = name
         self.parameters = parameters
 
     def update_parameters(self, task: AdaptiveParametersTask) -> List[AdaptiveParametersTask]:
+        """
+        Set the parameters in AdaptiveParametersTask state.
+        :param parameters: instance of AdaptiveParametersTask task to set new parameters
+        :return: updated AdaptiveParametersTask wrapped in a list
+        """
         if not isinstance(task, AdaptiveParametersTask):
             raise TypeError(f"task should be `AdaptiveParametersTask`, got {type(task)} instead")
         for attribute, values in self.parameters: