Settings

This page contains information about the member functions of the ToddCoxeter that control various settings that influence the congruence enumeration process.

There are a fairly large number of settings, they can profoundly alter the run time of a congruence enumeration process, but it is hard to predict what settings will work best for any particular input.

See also Runner for further settings.

ToddCoxeter.def_max(*args, **kwargs)

Overloaded function.

def_max(self: ToddCoxeter) → int

Get the current value of the setting for the maximum number of definitions.

Returns:: The current value of the setting.
Return type:: int

def_max(self: ToddCoxeter, val: int) → ToddCoxeter

Set the maximum number of definitions in the stack.

This setting specifies the maximum number of definitions that can be in the stack at any given time. What happens if there are the maximum number of definitions in the stack and a new definition is generated is governed by ToddCoxeter.def_policy.

The default value of this setting is 2000.

Parameters:: val (int) – the maximum size of the definition stack.
Returns:: self.
Return type:: ToddCoxeter

ToddCoxeter.def_policy(*args, **kwargs)

Overloaded function.

def_policy(self: ToddCoxeter) → ToddCoxeter.options.def_policy

Get the current value of the definition policy. This function returns the current value of the definition policy which specifies how to handle definitions. For details see options.def_policy.

Returns:: The current value of the setting, a value of type options.def_policy.
Return type:: ToddCoxeter.options.def_policy

def_policy(self: ToddCoxeter, val: ToddCoxeter.options.def_policy) → ToddCoxeter

Set the definition policy.

This function can be used to specify how to handle definitions. For details see options.def_policy. The default value of this setting is options.def_policy.no_stack_if_no_space.

Parameters:: val (ToddCoxeter.options.def_policy) – the policy to use.
Returns:: self.
Return type:: ToddCoxeter

ToddCoxeter.def_version(*args, **kwargs)

Overloaded function.

def_version(self: ToddCoxeter) → ToddCoxeter.options.def_version

The current value of the definition policy setting.

Returns:: The current value of the setting.
Return type:: ToddCoxeter.options.def_version

def_version(self: ToddCoxeter, val: ToddCoxeter.options.def_version) → ToddCoxeter

This function can be used to specify how which version of definition handling to use. For details see options.def_version.

The default value of this setting is options.def_version.two.

Parameters:: val (ToddCoxeter.options.def_version) – the version to use.
Returns:: self.
Return type:: ToddCoxeter

ToddCoxeter.f_defs(*args, **kwargs)

Overloaded function.

f_defs(self: ToddCoxeter) → int

Get the number of Felsch style definitions in ACE strategies. This function returns the approx number of Felsch style definitions in each phase of the ACE style strategies:

options.strategy.CR;
options.strategy.R_over_C;
options.strategy.R_over_C;
options.strategy.Cr; and
options.strategy.Rc.

If the strategy is not one of those listed above, then this setting is ignored.

The default value of this setting is 10 ** 5.

Returns:: The current value of the setting.
Return type:: int

f_defs(self: ToddCoxeter, val: int) → ToddCoxeter

Set the number of Felsch style definitions in ACE strategies.

This function can be used to set the approx number of Felsch style definitions in each phase of the ACE style strategies:

options.strategy.CR;
options.strategy.R_over_C;
options.strategy.R_over_C;
options.strategy.Cr; and
options.strategy.Rc.

If the strategy is not one of those listed above, then this setting is ignored.

The default value of this setting is 10 ** 5.

Parameters:: val (int) – the value to use.
Returns:: self.
Return type:: ToddCoxeter
Raises:: LibsemigroupsError – if val is 0.

ToddCoxeter.hlt_defs(*args, **kwargs)

Overloaded function.

hlt_defs(self: ToddCoxeter) → int

Get the number of HLT style definitions in ACE strategies. This function returns the approx number of HLT style definitions in each phase of the ACE style strategies:

options.strategy.CR;
options.strategy.R_over_C;
options.strategy.R_over_C;
options.strategy.Cr; and
options.strategy.Rc.

If the strategy is not one of those listed above, then this setting is ignored.

The default value of this setting is 10 ** 5.

Returns:: The current value of the setting.
Return type:: int

hlt_defs(self: ToddCoxeter, val: int) → ToddCoxeter

Set the number of HLT style definitions in ACE strategies.

This function can be used to set the approx number of HLT style definitions in each phase of the ACE style strategies:

options.strategy.CR;
options.strategy.R_over_C;
options.strategy.R_over_C;
options.strategy.Cr; and
options.strategy.Rc.

If the strategy is not one of those listed above, then this setting is ignored.

The default value of this setting is 2 * 10 ** 5.

Parameters:: val (int) – the value to use.
Returns:: self.
Return type:: ToddCoxeter
Raises:: LibsemigroupsError – if val is 0.

ToddCoxeter.large_collapse(*args, **kwargs)

Overloaded function.

large_collapse(self: ToddCoxeter) → int

Get the current size of a large collapse. This function can be used to get what is currently considered a “large” collapse. See large_collapse for the meaning of this setting.

The default value of this setting is 10 ** 5.

Returns:: The current value of the setting.
Return type:: int

large_collapse(self: ToddCoxeter, val: int) → ToddCoxeter

Set the size of a large collapse.

This function can be used to set what should be considered a “large” collapse.By default when processing coincidences nodes are merged in the word graph one pair at a time, and the in-neighbours of the surviving node are updated at the same time. If the number of coincidences is large, then it might be that a pair of nodes are merged at one step, then the surviving node is merged with another node at a future step, and this may happen many many times. This results in the in-neighbours of the surviving nodes being repeatedly traversed, which can result in a significant performance penalty. It can be beneficial to stop updating the in-neighbours as nodes are merged, and to just rebuild the entire in-neighbours data structure by traversing the entire word graph after all coincidences have been processed. This is beneficial if the number of surviving nodes is relatively small in comparison to the number of nodes merged. The purpose of this setting is to specify what should be considered a “large” collapse, or more precisely, what number of coincidences in the stack will trigger a change from updating the in-neighbours one-by-one to traversing the entire graph once after all coincidences have been processed.

The default value of this setting is 100000.

Parameters:: val (int) – the value to use.
Returns:: self.
Return type:: ToddCoxeter

ToddCoxeter.lookahead_extent(*args, **kwargs)

Overloaded function.

lookahead_extent(self: ToddCoxeter) → ToddCoxeter.options.lookahead_extent

Get the current value of the lookahead extent. This function returns the current value of the lookahead extent setting. The default value of this setting is options.lookahead_extent.partial.

Returns:: The current lookahead extent.
Return type:: ToddCoxeter.options.lookahead_extent

lookahead_extent(self: ToddCoxeter, val: ToddCoxeter.options.lookahead_extent) → ToddCoxeter

Set the lookahead extent.

This function can be used to specify the extent of any lookaheads that might take place in a congruence enumeration. The possible values are options.lookahead_extent.partial or options.lookahead_extent.full. The default value of this setting is options.lookahead_extent.partial.

Parameters:: val (ToddCoxeter.options.lookahead_extent) – the extent.
Returns:: self.
Return type:: ToddCoxeter

ToddCoxeter.lookahead_growth_factor(*args, **kwargs)

Overloaded function.

lookahead_growth_factor(self: ToddCoxeter) → float

Get the current value of the lookahead growth factor. This function returns the current value of the lookahead growth factor. See lookahead_growth_factor for a full explanation of this setting.

Returns:: The lookahead growth factor.
Return type:: float

lookahead_growth_factor(self: ToddCoxeter, val: float) → ToddCoxeter

Set the lookahead growth factor.

This setting determines by what factor the number of nodes required to trigger a lookahead grows. More specifically, at the end of any lookahead if the number of active nodes already exceeds the value of lookahead_next or the number of nodes killed during the lookahead is less than the number of active nodes divided by lookahead_growth_threshold, then the value of lookahead_next is increased by a multiple of val. The default value is of this setting is 2.0.

Parameters:: val (float) – the value indicating the lookahead growth factor.
Returns:: self.
Return type:: ToddCoxeter
Raises:: LibsemigroupsError – if val is less than 1.0.

ToddCoxeter.lookahead_growth_threshold(*args, **kwargs)

Overloaded function.

lookahead_growth_threshold(self: ToddCoxeter) → int

Get the current value of the lookahead growth threshold. This function returns the current value of the lookahead growth threshold. See lookahead_growth_threshold for a full description of this setting.

Returns:: The current value of the lookahead growth threshold.
Return type:: int

lookahead_growth_threshold(self: ToddCoxeter, val: int) → ToddCoxeter

Set the lookahead growth threshold.

This setting determines the threshold for the number of nodes required to trigger a lookahead. More specifically, at the end of any lookahead if the number of active nodes already exceeds the value of lookahead_next or the number of nodes killed during the lookahead is less than the number of active nodes divided by lookahead_growth_threshold, then the value of lookahead_next is increased. The default value is 4.

Parameters:: val (int) – the value indicating the lookahead growth threshold.
Returns:: self.
Return type:: ToddCoxeter

ToddCoxeter.lookahead_min(*args, **kwargs)

Overloaded function.

lookahead_min(self: ToddCoxeter) → int

Get the current value of the minimum lookahead setting. This function returns the current value of the minimum lookahead. See lookahead_min for a full description of this setting. The default value is 10 ** 4.

Returns:: The current value of the minimum lookahead.
Return type:: int

lookahead_min(self: ToddCoxeter, val: int) → ToddCoxeter

Set the minimum value of lookahead_next.

After a lookahead is performed the value of lookahead_next is modified depending on the outcome of the current lookahead. If the return value of lookahead_next is too small or too large, then the value is adjusted according to lookahead_growth_factor and lookahead_growth_threshold. This setting specified the minimum possible value for lookahead_next(). The default value is 10 ** 4.

Parameters:: val (int) – value indicating the minimum value of lookahead_next.
Returns:: self.
Return type:: ToddCoxeter

ToddCoxeter.lookahead_next(*args, **kwargs)

Overloaded function.

lookahead_next(self: ToddCoxeter) → int

Get the current value of the lookahead next setting. This function returns the current value of the lookahead next setting. See the other overload of this function for a full description of this setting.

Returns:: The number of active nodes that will trigger the next lookahead.
Return type:: int

lookahead_next(self: ToddCoxeter, val: int) → ToddCoxeter

Set the threshold that will trigger a lookahead.

If the number of active nodes exceeds the value set by this function, then a lookahead of style ToddCoxeter.lookahead_style and extent ToddCoxeter.lookahead_extent will be triggered. The default value is 5 * 10 ** 6.

Parameters:: val (int) – value indicating the initial threshold.
Returns:: self.
Return type:: ToddCoxeter

ToddCoxeter.lookahead_stop_early_interval(*args, **kwargs)

Overloaded function.

lookahead_stop_early_interval(self: ToddCoxeter) → datetime.timedelta

Get the current value of the lookahead stop early interval. This function returns the current value of the lookahead stop early interval. See lookahead_stop_early_interval for a full description of this setting.

Returns:: The length of the interval.
Return type:: datetime.timedelta

lookahead_stop_early_interval(self: ToddCoxeter, val: datetime.timedelta) → ToddCoxeter

Set the lookahead stop early interval.

During any lookaheads that are performed, it is periodically checked what proportion of the active nodes have been killed since the previous such check. This function can be used to set the interval between these checks. The purpose of this setting is to allow lookaheads to be stopped early if the number of nodes being killed is too small (for example, if \(<1%\) of nodes were killed in the previous second, then we might want to stop the lookahead early, since lookaheads take some time but may not result in many nodes being killed).

The default value is 1 second.

Parameters:: val (datetime.timedelta) – the new value for the interval.
Returns:: self.
Return type:: ToddCoxeter

ToddCoxeter.lookahead_stop_early_ratio(*args, **kwargs)

Overloaded function.

lookahead_stop_early_ratio(self: ToddCoxeter) → float

Get the current value of the lookahead stop early ratio. This function returns the current value of the lookahead stop early ratio. See lookahead_stop_early_ratio for a full description of this setting.

Returns:: The ratio.
Return type:: float

lookahead_stop_early_ratio(self: ToddCoxeter, val: float) → ToddCoxeter

Set the lookahead stop early ratio.

During any lookaheads that are performed, it is periodically checked what proportion of the active nodes have been killed since the previous such check. This function can be used to set the minimum proportion of the active nodes that must be killed every lookahead_stop_early_interval to avoid the lookahead being stopped early. The purpose of this setting is to allow lookaheads to be stopped early if the number of nodes being killed is too small (for example, if no nodes were killed in the previous second, then we might want to stop the lookahead early, since lookaheads take some time but may not result in many nodes being killed).

Parameters:: val (float) – the proportion of active nodes.
Returns:: self.
Return type:: ToddCoxeter
Raises:: LibsemigroupsError – if val is not in the interval \([0, 1)\).

ToddCoxeter.lookahead_style(*args, **kwargs)

Overloaded function.

lookahead_style(self: ToddCoxeter) → ToddCoxeter.options.lookahead_style

Get the current value of the lookahead style. This function returns the current value of the lookahead style. See ToddCoxeter.lookahead_style for a full description of this setting.

Returns:: The current lookahead style.
Return type:: ToddCoxeter.options.lookahead_style

lookahead_style(self: ToddCoxeter, val: ToddCoxeter.options.lookahead_style) → ToddCoxeter

Set the style of lookahead.

This function can be used to set the style of any lookaheads that are performed during the congruence enumeration. The possible values are options.lookahead_style.hlt and options.lookahead_style.felsch.

The default value of this setting is options.lookahead_style.hlt.

Parameters:: val (ToddCoxeter.options.lookahead_style) – the style of lookahead to use.
Returns:: self.
Return type:: ToddCoxeter

ToddCoxeter.lower_bound(*args, **kwargs)

Overloaded function.

lower_bound(self: ToddCoxeter) → int

Get the current value of the lower bound. This function returns the current value of the lower bound. See lower_bound for a full description of this setting.

Returns:: The current lower bound.
Return type:: int

lower_bound(self: ToddCoxeter, val: int) → ToddCoxeter

Specify the minimum number of classes that may permit any enumeration early stop.

This function can be used to set a lower bound for the number of classes of the congruence represented by a ToddCoxeter instance. If the number of active nodes becomes at least the value of the argument, and the word graph is complete (word_graph.is_complete returns True), then the enumeration is terminated. When the given bound is equal to the number of classes, this may prevent following the paths labelled by relations at many nodes when there is no possibility of finding coincidences.The default value is UNDEFINED.

Parameters:: val (int) – value indicating the lower bound.
Returns:: self.
Return type:: ToddCoxeter

ToddCoxeter.save(*args, **kwargs)

Overloaded function.

save(self: ToddCoxeter) → bool

Get the current value of the save setting. This function returns the current value of the save setting. See save for a full description of this setting.

Returns:: The current value.
Return type:: bool

save(self: ToddCoxeter, val: bool) → ToddCoxeter

Set whether or not to process definitions during HLT.

If the argument of this function is True and the HLT strategy is being used, then definitions are processed during any enumeration. The default value is False.

Parameters:: val (bool) – value indicating whether or not to process deductions.
Returns:: self.
Return type:: ToddCoxeter

ToddCoxeter.strategy(*args, **kwargs)

Overloaded function.

strategy(self: ToddCoxeter) → ToddCoxeter.options.strategy

Get the current value of the strategy setting. This function returns the current value of the strategy setting. See options.strategy for a full description of this setting.

Returns:: The current value.
Return type:: ToddCoxeter.options.strategy

strategy(self: ToddCoxeter, val: ToddCoxeter.options.strategy) → ToddCoxeter

Specify the congruence enumeration strategy.

The strategy used during the enumeration can be specified using this function. The default value is options.strategy.

Parameters:: val (ToddCoxeter.options.strategy) – value indicating which strategy to use.
Returns:: self.
Return type:: ToddCoxeter

ToddCoxeter.use_relations_in_extra(*args, **kwargs)

Overloaded function.

use_relations_in_extra(self: ToddCoxeter) → bool

Get the current value of the “use relations in extra” setting. This function returns the current value of the “use relations in extra” setting. See the other overload of use_relations_in_extra for a fuller description of this setting.

Returns:: The current value.
Return type:: bool

use_relations_in_extra(self: ToddCoxeter, val: bool) → ToddCoxeter

Set whether or not to perform an HLT-style push of the defining relations at the identity.

If a ToddCoxeter instance is defined over a finitely presented semigroup or monoid and the Felsch strategy is being used, it can be useful to follow all the paths from the identity labelled by the underlying relations. This setting specifies whether or not to do this.The default value of this setting is False.

Parameters:: val (bool) – the boolean value.
Returns:: self.
Return type:: ToddCoxeter