Stop Conditions

There are three types of stop conditions:

• Local Stop Conditions (LSC) - used to stop a single deme,

• Global Stop Conditions (GSC) - used to stop the whole HMS,

• Universal Stop Conditions (USC) - these conditions can be used as both LSC and GSC.

Local Stop Conditions

An interface for LSC is defined in the LocalStopCondition class. It has a single method, LocalStopCondition.__call__(), which takes a single argument, a deme (AbstractDeme). The method should return a boolean value indicating whether the deme should stop.

class LocalStopCondition(ABC):
    @abstractmethod
    def __call__(self, deme: "AbstractDeme") -> bool:
        raise NotImplementedError()

A simple example of LSC is AllChildrenStopped:

class AllChildrenStopped(LocalStopCondition):
"""
LSC is true if all children of the deme are stopped.
"""

def __call__(self, deme: "AbstractDeme") -> bool:
    if not deme.children:
        return False

    return all(not child.is_active for child in deme.children)

It’s easy to create a custom LSC by extending LocalStopCondition and implementing the LocalStopCondition.__call__() method.

Supported Local Stop Conditions

class pyhms.stop_conditions.lsc.FitnessSteadiness(max_deviation: float = 0.001, n_metaepochs: int = 5)

LSC is true if the average fitness of the last n_metaepochs is within max_deviation of the minimum fitness.

class pyhms.stop_conditions.lsc.AllChildrenStopped

LSC is true if all children of the deme are stopped.

Global Stop Conditions

An interface for GSC is defined in the GlobalStopCondition class. It has a single method, GlobalStopCondition.__call__(), which takes a single argument, a DemeTree.

class GlobalStopCondition(ABC):
    @abstractmethod
    def __call__(self, tree: "DemeTree") -> bool:
        raise NotImplementedError()

A simple example of GSC is RootStopped:

class RootStopped(GlobalStopCondition):
"""
GSC is true if the root is not active.
"""

def __call__(self, tree: "DemeTree") -> bool:
    return not tree.root.is_active

Supported Global Stop Conditions

class pyhms.stop_conditions.gsc.RootStopped

GSC is true if the root is not active.

class pyhms.stop_conditions.gsc.AllStopped

GSC is true if there are no active demes in the tree.

class pyhms.stop_conditions.gsc.FitnessEvalLimitReached(limit: int, weights: list[float] | WeightingStrategy | None = WeightingStrategy.EQUAL)

GSC is true if the total number of fitness evaluations in the tree is greater than or equal to the limit. It supports different weighting strategies for the evaluations at different levels of the tree. It should be used if different levels of the tree use different problems, otherwise use SingularProblemEvalLimitReached.

The class can be initialized with a limit and an optional weighting strategy. The weighting strategy determines how evaluations at different levels contribute to the total count. Supported strategies are “equal” and “root”, with “equal” being the default. If the strategy is “equal”, all levels contribute equally to the total count. If the strategy is “root”, only the root level contributes to the total count.

Parameters:

• limit (int) – The threshold number of evaluations to check against.

• weights (list[float] or WeightingStrategy or None) – A list of weights corresponding to each level in the tree or a WeightingStrategy.

Note:

By default WeightingStrategy.EQUAL is used.

class pyhms.stop_conditions.gsc.SingularProblemEvalLimitReached(limit: int)

GSC is true if the total number of fitness evaluations in the tree is greater than or equal to the limit. It assumes that the same problem is used at all levels of the tree.

Parameters:

limit (int) – The threshold number of evaluations to check against.

class pyhms.stop_conditions.gsc.SingularProblemPrecisionReached(problem: PrecisionCutoffProblem)

GSC is true if the precision of the problem is reached.

Parameters:

PrecisionCutoffProblem (problem) – The problem to check the precision for.

class pyhms.stop_conditions.gsc.NoActiveNonrootDemes(n_metaepochs: int = 5)

GSC is true if there are no active non-root demes in the tree for a certain number of metaepochs.

Parameters:

n_metaepochs (int) – The number of metaepochs to wait before the condition is satisfied. Default: 5.

Universal Stop Conditions

USC can be used as LSC and GSC. An interface for USC is defined in the UniversalStopCondition class. It has a single method, UniversalStopCondition.__call__(), which takes a single argument, a deme (AbstractDeme) or tree (DemeTree). The method should return a boolean value indicating whether the deme or tree should stop.

class UniversalStopCondition(ABC):
    @abstractmethod
    def __call__(self, obj: Union["DemeTree", "AbstractDeme"]) -> bool:
        raise NotImplementedError()

Supported Universal Stop Conditions

class pyhms.stop_conditions.usc.MetaepochLimit(limit: int)

class pyhms.stop_conditions.usc.DontStop

class pyhms.stop_conditions.usc.DontRun