:py:mod:`fragile.algorithms.jump_best` ====================================== .. py:module:: fragile.algorithms.jump_best Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: fragile.algorithms.jump_best.DummyFMCPolicy fragile.algorithms.jump_best.EnvSwarm fragile.algorithms.jump_best.JumpToBestTree fragile.algorithms.jump_best.JumpToBestEnv fragile.algorithms.jump_best.WalkersSwarm fragile.algorithms.jump_best.JumpToBest fragile.algorithms.jump_best.FMCSwarm .. py:class:: DummyFMCPolicy(inner_swarm, **kwargs) Bases: :py:obj:`fragile.core.api_classes.PolicyAPI` The policy is in charge of calculating the interactions with the :class:`Environment`. The PolicyAPI class is responsible for defining the policy that determines the actions for interacting with the :class:`Environment` in a swarm simulation. This is an abstract base class, and specific policy implementations should inherit from this class and implement the 'select_actions' method. .. py:method:: select_actions(**kwargs) Select actions for each walker in the swarm based on the current state. This method must be implemented by subclasses. :param \*\*kwargs: Additional keyword arguments required for selecting actions. :returns: The selected actions as a Tensor or a StateData dictionary. :rtype: Union[Tensor, StateData] .. py:method:: act(inplace = True, **kwargs) Calculate SwarmState containing the data needed to interact with the environment. :param inplace: If True, updates the swarm state with the selected actions. If False, returns the selected actions. Defaults to True. :type inplace: bool, optional :param \*\*kwargs: Additional keyword arguments required for selecting actions. :returns: None if inplace is True. Otherwise, a StateData dictionary containing the selected actions. :rtype: Union[None, StateData] .. py:class:: EnvSwarm(swarm) Bases: :py:obj:`fragile.core.api_classes.EnvironmentAPI` The Environment is in charge of stepping the walkers, acting as a state transition function. For every different problem, a new Environment needs to be implemented following the :class:`EnvironmentAPI` interface. .. py:method:: __getattr__(item) .. py:method:: inputs() :property: Return a dictionary containing the data that this component needs to function. .. py:method:: outputs() :property: Return a tuple containing the names of the data attribute that the component outputs. .. py:method:: param_dict() :property: Return the dictionary defining all the data attributes that the component requires. .. py:method:: make_transitions(inplace = True, **kwargs) Return the data corresponding to the new state of the environment after using the input data to make the corresponding state transition. :param inplace: If ``False`` return the new data. If ``True``, update the state of the Swarm. :param inactives: Whether to update the walkers marked as inactive. :param \*\*kwargs: Keyword arguments passed if the returned value from the ``states_to_data`` function of the class was a dictionary. :returns: Dictionary containing the data representing the state of the environment after the state transition. The keys of the dictionary are the names of the data attributes and its values are arrays representing a batch of new values for that attribute. The :class:`StatesEnv` returned by ``step`` will contain the returned data. .. py:method:: step(**kwargs) Return the data corresponding to the new state of the environment after using the input data to make the corresponding state transition. .. py:class:: JumpToBestTree(names = None, prune = False, root_id = DEFAULT_ROOT_ID, node_names = None, edge_names = ('actions', 'dt'), next_prefix = NetworkxTree.DEFAULT_NEXT_PREFIX, **kwargs) Bases: :py:obj:`fragile.callbacks.tree.HistoryTree` Tree data structure that keeps track of the visited states. It allows to save the :class:`Swarm` data after every iteration and methods to recover the sampled data after the algorithm run. The data that will be stored in the graph it's defined in the ``names`` parameter. For example: - If names is ``["observs", "actions"]``, the observations of every visited state will be stored as node attributes, and actions will be stored as edge attributes. - If names if ``["observs", "actions", "next_observs"]`` the same data will be stored, but when the data generator methods are called the observation corresponding to the next state will also be returned. The attribute ``names`` also defines the order of the data returned by the generator. As long as the data is stored in the graph (passing a valid ``names`` list at initialization, the order of the data can be redefined passing the ``names`` parameter to the generator method. For example, if the ``names`` passed at initialization is ``["states", "rewards"]``, you can call the generator methods with ``names=["rewards", "states", "next_states"]`` and the returned data will be a tuple containing (rewards, states, next_states). .. py:method:: __len__() .. py:method:: after_evolve() .. py:method:: after_env() .. py:method:: update_tree() .. py:class:: JumpToBestEnv(swarm) Bases: :py:obj:`EnvSwarm` The Environment is in charge of stepping the walkers, acting as a state transition function. For every different problem, a new Environment needs to be implemented following the :class:`EnvironmentAPI` interface. .. py:method:: make_transitions(inplace = True, **kwargs) Return the data corresponding to the new state of the environment after using the input data to make the corresponding state transition. :param inplace: If ``False`` return the new data. If ``True``, update the state of the Swarm. :param inactives: Whether to update the walkers marked as inactive. :param \*\*kwargs: Keyword arguments passed if the returned value from the ``states_to_data`` function of the class was a dictionary. :returns: Dictionary containing the data representing the state of the environment after the state transition. The keys of the dictionary are the names of the data attributes and its values are arrays representing a batch of new values for that attribute. The :class:`StatesEnv` returned by ``step`` will contain the returned data. .. py:method:: reset(inplace = True, root_walker = None, states = None, **kwargs) Reset the internal state of the :class:`SwarmComponent`. :param inplace: If ``False`` return the new data. If ``True``, update the state of the Swarm. Defaults to ``True``. :type inplace: bool, optional :param root_walker: _description_. Defaults to None. :type root_walker: Optional[StateData], optional :param states: _description_. Defaults to None. :type states: Optional[StateData], optional :param inactives: Whether to update the walkers marked as inactive. Defaults to ``True``. :type inactives: bool, optional :param kwargs: Other arguments passed to make_transitions. :returns: Dictionary containing the data representing the state of the environment after the state transition. The keys of the dictionary are the names of the data attributes and its values are arrays representing a batch of new values for that attribute. The :class:`StatesEnv` returned by ``step`` will contain the returned data. :rtype: Union[None, StateData] .. py:class:: WalkersSwarm(inner_swarm, **kwargs) Bases: :py:obj:`fragile.core.api_classes.WalkersAPI` The WalkersAPI class defines the base functionality for managing walkers in a swarm simulation. This class inherits from the SwarmComponent class. .. py:method:: param_dict() :property: Return the dictionary defining all the data attributes that the component requires. .. py:method:: __getattr__(item) .. py:method:: run_epoch(inplace = True, **kwargs) Implement the functionality for running an epoch in the derived class. This method is called during the balance operation. :param inplace: If `True`, updates the swarm state with the data generated during the epoch. If False, returns the data. Defaults to `True`. :type inplace: bool, optional :param \*\*kwargs: Additional keyword arguments required for running the epoch. :returns: A dictionary containing the data generated during the epoch if inplace is False. Otherwise, returns None. :rtype: StateData .. py:method:: reset(inplace = True, **kwargs) Reset the internal state of the Walkers class. This method should be implemented in the derived class. :param inplace: Unused. Defaults to True. :type inplace: bool, optional :param \*\*kwargs: Additional keyword arguments required for resetting the component. :returns: None .. py:class:: JumpToBest(inner_swarm, **kwargs) Bases: :py:obj:`WalkersSwarm` The WalkersAPI class defines the base functionality for managing walkers in a swarm simulation. This class inherits from the SwarmComponent class. .. py:method:: run_epoch(inplace = True, **kwargs) Implement the functionality for running an epoch in the derived class. This method is called during the balance operation. :param inplace: If `True`, updates the swarm state with the data generated during the epoch. If False, returns the data. Defaults to `True`. :type inplace: bool, optional :param \*\*kwargs: Additional keyword arguments required for running the epoch. :returns: A dictionary containing the data generated during the epoch if inplace is False. Otherwise, returns None. :rtype: StateData .. py:method:: reset(inplace = True, **kwargs) Reset the internal state of the Walkers class. This method should be implemented in the derived class. :param inplace: Unused. Defaults to True. :type inplace: bool, optional :param \*\*kwargs: Additional keyword arguments required for resetting the component. :returns: None .. py:class:: FMCSwarm(swarm, policy = None, env = None, callbacks = None, minimize = False, max_epochs = 1e+100) Bases: :py:obj:`fragile.core.swarm.Swarm` 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:attribute:: walkers_last :annotation: = False .. py:method:: swarm() :property: .. py:method:: n_walkers() :property: Return the number of walkers in the swarm. .. py:method:: inputs_from_swarm(name)