:py:mod:`fragile.core.swarm`
============================

.. py:module:: fragile.core.swarm


Module Contents
---------------

Classes
~~~~~~~

.. autoapisummary::

   fragile.core.swarm.Swarm
   fragile.core.swarm.FunctionMapper




.. py:class:: Swarm(n_walkers, env, policy, walkers, callbacks = None, minimize = False, max_epochs = 1e+100)

   Bases: :py:obj:`fragile.core.api_classes.SwarmAPI`

   The Swarm implements the iteration logic to make the :class:`Walkers` evolve.

   It contains the necessary logic to use an Environment, a Model, and a     Walkers instance to create the algorithm execution loop.

   This class defines a method called run() that receives two optional arguments,     root_walker and state, and has no return value. This method runs the fractal AI Swarm     evolution process until a stop condition is met.

   In its implementation, it calls several other methods:     (before_reset(), reset(), after_reset(), evolve(), before_evolve(), after_evolve(),     evolution_end(), before_env(), after_env(), before_policy(), after_policy(),     before_walkers(), after_walkers(), run_end()) defined within the same class,     which are mainly used to manage different aspects of the search process or to     invoke user-defined callbacks.

   The evolve() method updates the states of the search environment and model,     makes the walkers undergo a perturbation process, and balances them. It also     invokes several other methods that trigger user-defined callbacks.

   The evolution_end() method returns ``True`` if any of the following conditions is met:
   1. The current epoch exceeds the maximum allowed epochs.
   2. All walkers are out of the problem domain.
   3. Any callback of the class has set the ``evolution_end`` flag to ``True``.

   .. attribute:: walkers_last

      If `True` indicates that the :class:`~fragile.Walkers`         class runs after acting on the environment. If `Fase`, the walkers run before         acting on the environment.

      :type: bool

   :param n_walkers: The number of walkers in the swarm.
   :type n_walkers: int
   :param env: An environment that simulates the objective function.
   :type env: :class:`EnvironmentAPI`
   :param policy: A policy that defines how the individuals evolve.
   :type policy: :class:`PolicyAPI`
   :param walkers: A set of motion rules to control a population of walkers.
   :type walkers: :class:`WalkersAPI`
   :param callbacks: A list of functions to call at each iteration.
   :type callbacks: Optional[Iterable[Callback]]
   :param minimize: If ``True``, take the minimum value of fitness, else take the maximum.
   :type minimize: bool
   :param max_epochs: Maximum number of epochs allowed before the swarm search is stopped.
   :type max_epochs: int

   .. py:method:: __repr__()

      Return repr(self).


   .. py:method:: to_html()


   .. py:method:: _state_stats_df()


   .. py:method:: _setup_inputs()


   .. py:method:: _setup_clone_names()


   .. py:method:: _setup_components()



.. py:class:: FunctionMapper(minimize = True, start_same_pos = False, **kwargs)

   Bases: :py:obj:`Swarm`

   It is a swarm adapted to minimize mathematical functions.

   .. py:method:: from_function(function, bounds, **kwargs)
      :classmethod:

      Initialize a :class:`FunctionMapper` using a python callable and a         :class:`Bounds` instance.

      :param function: Callable representing an arbitrary function to be optimized.
      :param bounds: Represents the domain of the function to be optimized.
      :param \*\*kwargs: Passed to :class:`FunctionMapper` __init__.

      :returns: Instance of :class:`FunctionMapper` that optimizes the target function.


   .. py:method:: __repr__()

      Return repr(self).


   .. py:method:: reset(root_walker = None, state = None)

      Reset the :class:`fragile.Walkers`, the :class:`Function` environment, the         :class:`Model` and clear the internal data to start a new search process.

      :param root_walker: Walker representing the initial state of the search.                          The walkers will be reset to this walker, and it will                          be added to the root of the :class:`StateTree` if any.
      :param state: StateData dictionary that define the initial state of the Swarm.