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.

Functions
size_t	def_max () const noexcept
	Get the current value of the setting for the maximum number of definitions.
ToddCoxeter &	def_max (size_t val) noexcept
	Set the maximum number of definitions in the stack.
options::def_policy	def_policy () const noexcept
	Get the current value of the definition policy.
ToddCoxeter &	def_policy (options::def_policy val)
	Set the definition policy.
options::def_version	def_version () const noexcept
	Get the current value of the definition version setting.
ToddCoxeter &	def_version (options::def_version val)
	Set the value of the definition version setting.
size_t	f_defs () const noexcept
	Get the number of Felsch style definitions in ACE strategies.
ToddCoxeter &	f_defs (size_t val)
	Set the number of Felsch style definitions in ACE strategies.
size_t	hlt_defs () const noexcept
	Get the number of HLT style definitions in ACE strategies.
ToddCoxeter &	hlt_defs (size_t val)
	Set the number of HLT style definitions in ACE strategies.
size_t	large_collapse () const noexcept
	Get the current size of a large collapse.
ToddCoxeter &	large_collapse (size_t val) noexcept
	Set the size of a large collapse.
options::lookahead_extent	lookahead_extent () const noexcept
	Get the current value of the lookahead extent.
ToddCoxeter &	lookahead_extent (options::lookahead_extent val) noexcept
	Set the lookahead extent.
float	lookahead_growth_factor () const noexcept
	Get the current value of the lookahead growth factor.
ToddCoxeter &	lookahead_growth_factor (float val)
	Set the lookahead growth factor.
size_t	lookahead_growth_threshold () const noexcept
	Get the current value of the lookahead growth threshold.
ToddCoxeter &	lookahead_growth_threshold (size_t val) noexcept
	Set the lookahead growth threshold.
size_t	lookahead_min () const noexcept
	Get the current value of the minimum lookahead setting.
ToddCoxeter &	lookahead_min (size_t val) noexcept
	Set the minimum value of lookahead_next.
size_t	lookahead_next () const noexcept
	Get the current value of the lookahead next setting.
ToddCoxeter &	lookahead_next (size_t val) noexcept
	Set the threshold that will trigger a lookahead.
std::chrono::nanoseconds	lookahead_stop_early_interval () const noexcept
	Get the current value of the lookahead stop early interval.
ToddCoxeter &	lookahead_stop_early_interval (std::chrono::nanoseconds val) noexcept
	Set the lookahead stop early interval.
float	lookahead_stop_early_ratio () const noexcept
	Get the current value of the lookahead stop early ratio.
ToddCoxeter &	lookahead_stop_early_ratio (float val)
	Set the lookahead stop early ratio.
options::lookahead_style	lookahead_style () const noexcept
	Get the current value of the lookahead style.
ToddCoxeter &	lookahead_style (options::lookahead_style val) noexcept
	Set the style of lookahead.
size_t	lower_bound () const noexcept
	Get the current value of the lower bound.
ToddCoxeter &	lower_bound (size_t val) noexcept
	Specify the minimum number of classes that may permit any enumeration early stop.
bool	save () const noexcept
	Get the current value of the save setting.
ToddCoxeter &	save (bool val) noexcept
	Set whether or not to process definitions during HLT.
options::strategy	strategy () const noexcept
	Get the current value of the strategy setting.
ToddCoxeter &	strategy (options::strategy val) noexcept
	Specify the congruence enumeration strategy.
bool	use_relations_in_extra () const noexcept
	Get the current value of the "use relations in extra" setting.
ToddCoxeter &	use_relations_in_extra (bool val) noexcept
	Set whether or not to perform an HLT-style push of the defining relations at the identity.

Function Documentation

def_max() [1/2]

size_t def_max ( ) const

nodiscardnoexcept

Returns

The current value of the setting, a value of type size_t.

Exceptions

This function is noexcept and is guaranteed never to throw.

def_max() [2/2]

ToddCoxeter & def_max ( size_t val )

noexcept

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 def_policy.

The default value of this setting is 2'000.

Parameters

val	the maximum size of the definition stack.

Returns

A reference to *this.

Exceptions

This function is noexcept and is guaranteed never to throw.

def_policy() [1/2]

options::def_policy def_policy ( ) const

nodiscardnoexcept

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

Returns

The current value of the setting, a value of type def_policy.

Exceptions

This function is noexcept and is guaranteed never to throw.

def_policy() [2/2]

ToddCoxeter & def_policy

(

options::def_policy

val

)

This function can be used to specify how to handle definitions. For details see def_policy.

The default value of this setting is no_stack_if_no_space.

Parameters

val	the policy to use.

Returns

A reference to *this.

Exceptions

This function guarantees not to throw a LibsemigroupsException.

def_version() [1/2]

options::def_version def_version ( ) const

nodiscardnoexcept

This function returns the current version of the definition version setting.

Returns

The current value of the setting, a value of type def_version.

Exceptions

This function is noexcept and is guaranteed never to throw.

def_version() [2/2]

ToddCoxeter & def_version

(

options::def_version

val

)

There are two versions of definition processing represented by the values one and two. The first version is simpler, but may involve following the same path that leads nowhere multiple times. The second version is more complex, and attempts to avoid following the same path multiple times if it is found to lead nowhere once.

Parameters

val	the version to use.

Returns

A reference to *this.

f_defs() [1/2]

size_t f_defs ( ) const

nodiscardnoexcept

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

• CR;
• R_over_C;
• R_over_C;
• Cr; and
• Rc.

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

The default value of this setting is 100'000.

Returns

The current value of the setting, a value of type size_t.

Exceptions

This function is noexcept and is guaranteed never to throw.

f_defs() [2/2]

ToddCoxeter & f_defs

(

size_t

val

)

This function can be used to set the approximate number of nodes defined in Felsch style in each phase of the ACE style strategies:

• CR;
• R_over_C;
• R_over_C;
• Cr; and
• Rc.

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

The default value of this setting is 100'000.

Parameters

val	the value to use.

Returns

A reference to *this.

Exceptions

LibsemigroupsException

if val is 0.

hlt_defs() [1/2]

size_t hlt_defs ( ) const

nodiscardnoexcept

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

• CR;
• R_over_C;
• R_over_C;
• Cr; and
• Rc.

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

The default value of this setting is 100'000.

Returns

The current value of the setting, a value of type size_t.

Exceptions

This function is noexcept and is guaranteed never to throw.

hlt_defs() [2/2]

ToddCoxeter & hlt_defs

(

size_t

val

)

This function can be used to set the approximate number nodes defined in HLT style in each phase of the ACE style strategies:

• CR;
• R_over_C;
• R_over_C;
• Cr; and
• Rc.

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

The default value of this setting is 200'000.

Parameters

val	the value to use.

Returns

A reference to *this.

Exceptions

LibsemigroupsException

if val is 0.

large_collapse() [1/2]

size_t large_collapse ( ) const

nodiscardnoexcept

This function can be used to get what is currently considered a "large" collapse. See large_collapse(size_t) for the meaning of this setting.

The default value of this setting is 100'000.

Returns

The current value of the setting, a value of type size_t.

Exceptions

This function is noexcept and is guaranteed never to throw.

large_collapse() [2/2]

ToddCoxeter & large_collapse ( size_t val )

noexcept

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 100'000.

Parameters

val	the value to use.

Returns

A reference to *this.

Exceptions

This function is noexcept and is guaranteed never to throw.

lookahead_extent() [1/2]

options::lookahead_extent lookahead_extent ( ) const

nodiscardnoexcept

This function returns the current value of the lookahead extent setting.

The default value of this setting is partial.

Returns

The current lookahead extent.

Exceptions

This function is noexcept and is guaranteed never to throw.

lookahead_extent() [2/2]

ToddCoxeter & lookahead_extent ( options::lookahead_extent val )

noexcept

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

The default value of this setting is partial.

Parameters

val	the extent.

Returns

A reference to *this.

Exceptions

This function is noexcept and is guaranteed never to throw.

lookahead_growth_factor() [1/2]

float lookahead_growth_factor ( ) const

nodiscardnoexcept

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

Returns

The lookahead growth factor.

Exceptions

This function is noexcept and is guaranteed never to throw.

lookahead_growth_factor() [2/2]

ToddCoxeter & lookahead_growth_factor

(

float

val

)

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	the value indicating the lookahead growth factor.

Returns

A reference to *this.

Exceptions

LibsemigroupsException

if val is less than 1.0.

lookahead_growth_threshold() [1/2]

size_t lookahead_growth_threshold ( ) const

nodiscardnoexcept

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

Returns

A value of type size_t.

Exceptions

This function is noexcept and is guaranteed never to throw.

lookahead_growth_threshold() [2/2]

ToddCoxeter & lookahead_growth_threshold ( size_t val )

noexcept

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	the value indicating the lookahead growth threshold.

Returns

A reference to *this.

Exceptions

This function is noexcept and is guaranteed never to throw.

lookahead_min() [1/2]

size_t lookahead_min ( ) const

nodiscardnoexcept

This function returns the current value of the minimum lookahead. See lookahead_min(size_t) for a full description of this setting.

The default value is 10'000.

Returns

The current value of the minimum lookahead.

Exceptions

This function is noexcept and is guaranteed never to throw.

lookahead_min() [2/2]

ToddCoxeter & lookahead_min ( size_t val )

noexcept

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'000.

Parameters

val	value indicating the minimum value of lookahead_next.

Returns

A reference to *this.

Exceptions

This function is noexcept and is guaranteed never to throw.

lookahead_next() [1/2]

size_t lookahead_next ( ) const

nodiscardnoexcept

This function returns the current value of the lookahead next setting. See lookahead_next(size_t) for a full description of this setting.

Returns

The number of active nodes that will trigger the next lookahead.

Exceptions

This function is noexcept and is guaranteed never to throw.

lookahead_next() [2/2]

ToddCoxeter & lookahead_next ( size_t val )

noexcept

If the number of active nodes exceeds the value set by this function, then a lookahead of style lookahead_style and extent lookahead_extent will be triggered.

The default value is 5 million.

Parameters

val	value indicating the initial threshold.

Returns

A reference to *this.

Exceptions

This function is noexcept and is guaranteed never to throw.

lookahead_stop_early_interval() [1/2]

std::chrono::nanoseconds lookahead_stop_early_interval ( ) const

noexcept

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

Returns

The length of the interval in nanoseconds.

Exceptions

This function is noexcept and is guaranteed never to throw.

lookahead_stop_early_interval() [2/2]

ToddCoxeter & lookahead_stop_early_interval ( std::chrono::nanoseconds val )

noexcept

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	the new value for the interval.

Returns

A reference to *this.

Exceptions

This function is noexcept and is guaranteed never to throw.

lookahead_stop_early_ratio() [1/2]

float lookahead_stop_early_ratio ( ) const

noexcept

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

Returns

The ratio.

Exceptions

This function is noexcept and is guaranteed never to throw.

lookahead_stop_early_ratio() [2/2]

ToddCoxeter & lookahead_stop_early_ratio

(

float

val

)

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	the proportion of active nodes.

Returns

A reference to *this.

Exceptions

LibsemigroupsException

if val is not in the interval \([0, 1)\).

lookahead_style() [1/2]

options::lookahead_style lookahead_style ( ) const

nodiscardnoexcept

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

Returns

The current lookahead style.

Exceptions

This function is noexcept and is guaranteed never to throw.

lookahead_style() [2/2]

ToddCoxeter & lookahead_style ( options::lookahead_style val )

noexcept

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

The default value of this setting is hlt.

Parameters

val	the style of lookahead to use.

Returns

A reference to *this.

Exceptions

This function is noexcept and is guaranteed never to throw.

lower_bound() [1/2]

size_t lower_bound ( ) const

nodiscardnoexcept

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

Returns

The current lower bound.

Exceptions

This function is noexcept and is guaranteed never to throw.

lower_bound() [2/2]

ToddCoxeter & lower_bound ( size_t val )

noexcept

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 ( 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	value indicating the lower bound.

Returns

A reference to *this.

Exceptions

This function is noexcept and is guaranteed never to throw.

save() [1/2]

bool save ( ) const

nodiscardnoexcept

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

Returns

The current value.

Exceptions

This function is noexcept and is guaranteed never to throw.

save() [2/2]

ToddCoxeter & save ( bool val )

noexcept

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	value indicating whether or not to process deductions.

Returns

A reference to *this.

Exceptions

This function is noexcept and is guaranteed never to throw.

strategy() [1/2]

options::strategy strategy ( ) const

nodiscardnoexcept

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

Returns

The current value.

Exceptions

This function is noexcept and is guaranteed never to throw.

strategy() [2/2]

ToddCoxeter & strategy ( options::strategy val )

noexcept

The strategy used during the enumeration can be specified using this function.

The default value is hlt.

Parameters

val	value indicating which strategy to use.

Returns

A reference to *this.

Exceptions

This function is noexcept and is guaranteed never to throw.

use_relations_in_extra() [1/2]

bool use_relations_in_extra ( ) const

nodiscardnoexcept

This function returns the current value of the "use relations in extra" setting. See use_relations_in_extra(bool) for a fuller description of this setting.

Returns

The current value.

Exceptions

This function is noexcept and is guaranteed never to throw.

use_relations_in_extra() [2/2]

ToddCoxeter & use_relations_in_extra ( bool val )

noexcept

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. The setting specifies whether or not to do this.

The default value of this setting is false.

Parameters

val	the boolean value.

Returns

A reference to *this.

Exceptions

This function is noexcept and is guaranteed never to throw.