Skip to content

Commit fd22688

Browse files
Joseph-EdwardsJoseph-Edwards
committed
doc: Document ToddCoxeter enums like tril
1 parent 252b70a commit fd22688

1 file changed

Lines changed: 134 additions & 74 deletions

File tree

‎src/todd-coxeter-impl.cpp‎

Lines changed: 134 additions & 74 deletions
Original file line numberDiff line numberDiff line change
@@ -49,89 +49,122 @@ namespace libsemigroups {
4949
This class containing various options that can be used to control the
5050
behaviour of Todd-Coxeter.)pbdoc");
5151

52+
py::options enum_settings;
53+
enum_settings.disable_enum_members_docstring();
54+
5255
py::enum_<ToddCoxeterImpl_::options::strategy> strategy(options,
5356
"strategy",
5457
R"pbdoc(
55-
:sig=(self: ToddCoxeter.options.strategy, value: int) -> None:
58+
:sig=(self: ToddCoxeter.options.strategy, value: int):
5659
5760
Values for defining the strategy.
5861
5962
The values in this enum can be used as the argument for the method
6063
:py:meth:`ToddCoxeter.strategy` to specify which strategy should be
6164
used when performing a coset enumeration.
65+
66+
The valid values are :
67+
68+
.. py:attribute:: strategy.hlt
69+
:value: <strategy.hlt: 0>
70+
71+
This value indicates that the HLT (Hazelgrove-Leech-Trotter) strategy should be used. This is analogous to ACE's R-style.
72+
73+
.. py:attribute:: strategy.felsch
74+
:value: <strategy.felsch: 1>
75+
76+
This value indicates that the Felsch strategy should be used. This is analogous to ACE's C-style.
77+
78+
.. py:attribute:: strategy.CR
79+
:value: <strategy.CR: 2>
80+
81+
This strategy is meant to mimic the ACE strategy of the same name. The Felsch is run until at least :any:`f_defs` nodes are defined, then the HLT strategy is run until at least :any:`hlt_defs` divided by :math:`N` nodes have been defined, where :math:`N` is the sum of the lengths of the words in the presentation and generating pairs. These steps are repeated until the enumeration terminates.
82+
83+
.. py:attribute:: strategy.R_over_C
84+
:value: <strategy.R_over_C: 3>
85+
86+
This strategy is meant to mimic the ACE strategy R/C. The HLT strategy is run until the first lookahead is triggered (when :the number of nodes active is at least :any:`lookahead_next`). A full lookahead is then performed, and then the CR strategy is used.
87+
88+
.. py:attribute:: strategy.Cr
89+
:value: <strategy.Cr: 4>
90+
91+
This strategy is meant to mimic the ACE strategy Cr. The Felsch strategy is run until at least :any:`f_defs` new nodes have been defined, then the HLT strategy is run until at least :any:`hlt_defs` divided by :math:`N` nodes have been defined, where :math:`N` is the sum of the lengths of the words in the presentation and generating pairs. Then the Felsch strategy is run.
92+
93+
.. py:attribute:: strategy.Rc
94+
:value: <strategy.Rc: 5>
95+
96+
This strategy is meant to mimic the ACE strategy Rc. The HLT strategy is run until at least :any:`hlt_defs` divided by :math:`N` new nodes have been defined (where :math:`N` is the sum of the lengths of the words in the presentation and generating pairs) the Felsch strategy is then run until at least :any:`f_defs` new nodes are defined, and then the HLT strategy is run.
97+
98+
99+
62100
)pbdoc");
63-
strategy
64-
.value(
65-
"hlt",
66-
ToddCoxeterImpl_::options::strategy::hlt,
67-
R"pbdoc( This value indicates that the HLT (Hazelgrove-Leech-Trotter) strategy should be used. This is analogous to ACE's R-style.)pbdoc")
68-
.value(
69-
"felsch",
70-
ToddCoxeterImpl_::options::strategy::felsch,
71-
R"pbdoc( This value indicates that the Felsch strategy should be used. This is analogous to ACE's C-style.)pbdoc")
72-
.value(
73-
"CR",
74-
ToddCoxeterImpl_::options::strategy::CR,
75-
R"pbdoc(This strategy is meant to mimic the ACE strategy of the same name. The Felsch is run until at least :any:`f_defs` nodes are defined, then the HLT strategy is run until at least :any:`hlt_defs` divided by :math:`N` nodes have been defined, where :math:`N` is the sum of the lengths of the words in the presentation and generating pairs. These steps are repeated until the enumeration terminates.)pbdoc")
76-
.value(
77-
"R_over_C",
78-
ToddCoxeterImpl_::options::strategy::R_over_C,
79-
R"pbdoc(This strategy is meant to mimic the ACE strategy R/C. The HLT strategy is run until the first lookahead is triggered (when :the number of nodes active is at least :any:`lookahead_next`). A full lookahead is then performed, and then the CR strategy is used.)pbdoc")
80-
.value(
81-
"Cr",
82-
ToddCoxeterImpl_::options::strategy::Cr,
83-
R"pbdoc(This strategy is meant to mimic the ACE strategy Cr. The Felsch strategy is run until at least :any:`f_defs` new nodes have been defined, then the HLT strategy is run until at least :any:`hlt_defs` divided by :math:`N` nodes have been defined, where :math:`N` is the sum of the lengths of the words in the presentation and generating pairs. Then the Felsch strategy is run.)pbdoc")
84-
.value(
85-
"Rc",
86-
ToddCoxeterImpl_::options::strategy::Rc,
87-
R"pbdoc(This strategy is meant to mimic the ACE strategy Rc. The HLT strategy is run until at least :any:`hlt_defs` divided by :math:`N` new nodes have been defined (where :math:`N` is the sum of the lengths of the words in the presentation and generating pairs) the Felsch strategy is then run until at least :any:`f_defs` new nodes are defined, and then the HLT strategy is run.)pbdoc")
101+
strategy.value("hlt", ToddCoxeterImpl_::options::strategy::hlt)
102+
.value("felsch", ToddCoxeterImpl_::options::strategy::felsch)
103+
.value("CR", ToddCoxeterImpl_::options::strategy::CR)
104+
.value("R_over_C", ToddCoxeterImpl_::options::strategy::R_over_C)
105+
.value("Cr", ToddCoxeterImpl_::options::strategy::Cr)
106+
.value("Rc", ToddCoxeterImpl_::options::strategy::Rc)
88107
.export_values();
89108

90109
py::enum_<ToddCoxeterImpl_::options::lookahead_extent>(options,
91110
"lookahead_extent",
92111
R"pbdoc(
93-
:sig=(self: ToddCoxeter.options.lookahead_extent, value: int) -> None:
112+
:sig=(self: ToddCoxeter.options.lookahead_extent, value: int):
94113
95114
Enum for specifying the extent of any lookahead performed.
96115
97116
The values in this enum can be used as the argument for
98117
:any:`ToddCoxeter.lookahead_extent` to specify the extent of any lookahead that
99-
should be performed.)pbdoc")
100-
.value(
101-
"full",
102-
ToddCoxeterImpl_::options::lookahead_extent::full,
103-
R"pbdoc(Perform a full lookahead from every node in the word graph. Full lookaheads are therefore sometimes slower but may detect more coincidences than a partial lookahead.)pbdoc")
104-
.value(
105-
"partial",
106-
ToddCoxeterImpl_::options::lookahead_extent::partial,
107-
R"pbdoc(Perform a partial lookahead starting from the current node in the word graph. Partial lookaheads are sometimes faster but may not detect as many coincidences as a full lookahead.)pbdoc")
118+
should be performed.
119+
120+
The valid values are :
121+
122+
.. py:attribute:: lookahead_extent.full
123+
:value: <lookahead_extent.full: 0>
124+
125+
Perform a full lookahead from every node in the word graph. Full lookaheads are therefore sometimes slower but may detect more coincidences than a partial lookahead.
126+
127+
.. py:attribute:: lookahead_extent.partial
128+
:value: <lookahead_extent.partial: 1>
129+
130+
Perform a partial lookahead starting from the current node in the word graph. Partial lookaheads are sometimes faster but may not detect as many coincidences as a full lookahead.
131+
)pbdoc")
132+
.value("full", ToddCoxeterImpl_::options::lookahead_extent::full)
133+
.value("partial", ToddCoxeterImpl_::options::lookahead_extent::partial)
108134
.export_values();
109135

110136
py::enum_<ToddCoxeterImpl_::options::lookahead_style>(options,
111137
"lookahead_style",
112138
R"pbdoc(
113-
:sig=(self: ToddCoxeter.options.lookahead_style, value: int) -> None:
139+
:sig=(self: ToddCoxeter.options.lookahead_style, value: int):
114140
115141
Enum class for specifying the style of any lookahead performed.
116142
117143
The values in this enum can be used as the argument for
118144
:any:`ToddCoxeter.lookahead_style` to specify the style of any lookahead that
119-
should be performed.)pbdoc")
120-
.value(
121-
"hlt",
122-
// JDM couldn't get the links to work in the following doc string.
123-
ToddCoxeterImpl_::options::lookahead_style::hlt,
124-
R"pbdoc(The lookahead will be done in HLT style by following the paths labelled by every relation from every node in the range specified by ``options.lookahead_extent.full`` or ``options.lookahead_extent.partial``.)pbdoc")
125-
.value(
126-
"felsch",
127-
ToddCoxeterImpl_::options::lookahead_style::felsch,
128-
R"pbdoc(The lookahead will be done in Felsch style where every edge is considered in every path labelled by a relation in which it occurs.)pbdoc")
145+
should be performed.
146+
147+
The valid values are :
148+
149+
.. py:attribute:: lookahead_style.hlt
150+
:value: <lookahead_style.hlt: 0>
151+
152+
The lookahead will be done in HLT style by following the paths labelled by every relation from every node in the range specified by :any:`lookahead_extent.full` or :any:`lookahead_extent.partial`.
153+
154+
.. py:attribute:: lookahead_style.felsch
155+
:value: <lookahead_style.hlt: 0>
156+
157+
The lookahead will be done in Felsch style where every edge is considered in every path labelled by a relation in which it occurs.
158+
159+
)pbdoc")
160+
.value("hlt", ToddCoxeterImpl_::options::lookahead_style::hlt)
161+
.value("felsch", ToddCoxeterImpl_::options::lookahead_style::felsch)
129162
.export_values();
130163

131164
py::enum_<ToddCoxeterImpl_::options::def_policy>(options,
132165
"def_policy",
133166
R"pbdoc(
134-
:sig=(self: ToddCoxeter.options.def_policy, value: int) -> None:
167+
:sig=(self: ToddCoxeter.options.def_policy, value: int):
135168
136169
Enum class containing values for specifying how to handle edge
137170
definitions.
@@ -152,41 +185,68 @@ edge described by a definition.
152185
153186
The values in this enum represent what to do if the number of
154187
definitions in the stack exceeds the value :any:`ToddCoxeter.def_max`.
188+
189+
The valid values are:
190+
191+
.. py:attribute:: def_policy.no_stack_if_no_space
192+
:value: <def_policy.no_stack_if_no_space: 0>
193+
194+
Do not put newly generated definitions in the stack if the stack already has size :any:`def_max`.
195+
196+
.. py:attribute:: def_policy.purge_from_top
197+
:value: <def_policy.purge_from_top: 1>
198+
199+
If the definition stack has size :any:`def_max` and a new definition is generated, then definitions with dead source node are are popped from the top of the stack (if any).
200+
201+
.. py:attribute:: def_policy.purge_all
202+
:value: <def_policy.purge_all: 2>
203+
204+
If the definition stack has size :any:`def_max` and a new definition is generated, then definitions with dead source node are are popped from the entire of the stack (if any).
205+
206+
.. py:attribute:: def_policy.discard_all_if_no_space
207+
:value: <def_policy.discard_all_if_no_space: 3>
208+
209+
If the definition stack has size :any:`def_max` and a new definition is generated, then all definitions in the stack are discarded.
210+
211+
.. py:attribute:: def_policy.unlimited
212+
:value: <def_policy.unlimited: 4>
213+
214+
There is no limit to the number of definitions that can be put in the stack.
215+
155216
)pbdoc")
156-
.value(
157-
"no_stack_if_no_space",
158-
ToddCoxeterImpl_::options::def_policy::no_stack_if_no_space,
159-
R"pbdoc(Do not put newly generated definitions in the stack if the stack already has size :any:`def_max`.)pbdoc")
160-
.value(
161-
"purge_from_top",
162-
ToddCoxeterImpl_::options::def_policy::purge_from_top,
163-
R"pbdoc(If the definition stack has size :any:`def_max` and a new definition is generated, then definitions with dead source node are are popped from the top of the stack (if any).)pbdoc")
164-
.value(
165-
"purge_all",
166-
ToddCoxeterImpl_::options::def_policy::purge_all,
167-
R"pbdoc(If the definition stack has size :any:`def_max` and a new definition is generated, then definitions with dead source node are are popped from the entire of the stack (if any).)pbdoc")
168-
.value(
169-
"discard_all_if_no_space",
170-
ToddCoxeterImpl_::options::def_policy::discard_all_if_no_space,
171-
R"pbdoc(If the definition stack has size :any:`def_max` and a new definition is generated, then all definitions in the stack are discarded.)pbdoc")
172-
.value(
173-
"unlimited",
174-
ToddCoxeterImpl_::options::def_policy::unlimited,
175-
R"pbdoc(There is no limit to the number of definitions that can be put in the stack.)pbdoc")
217+
.value("no_stack_if_no_space",
218+
ToddCoxeterImpl_::options::def_policy::no_stack_if_no_space)
219+
.value("purge_from_top",
220+
ToddCoxeterImpl_::options::def_policy::purge_from_top)
221+
.value("purge_all", ToddCoxeterImpl_::options::def_policy::purge_all)
222+
.value("discard_all_if_no_space",
223+
ToddCoxeterImpl_::options::def_policy::discard_all_if_no_space)
224+
.value("unlimited", ToddCoxeterImpl_::options::def_policy::unlimited)
176225
.export_values();
177226

178227
py::enum_<ToddCoxeterImpl_::word_graph_type::options::def_version>(
179228
options,
180229
"def_version",
181230
R"pbdoc(
182-
:sig=(self: ToddCoxeter.options.def_version, value: int) -> None:
183-
Values for specifying how to handle definitions.)pbdoc")
231+
:sig=(self: ToddCoxeter.options.def_version, value: int):
232+
Values for specifying how to handle definitions.
233+
234+
The valid values are:
235+
236+
.. py:attribute:: def_version.one
237+
:value: <def_version.one: 0>
238+
239+
Version 1 definition processing.
240+
241+
.. py:attribute:: def_version.two
242+
:value: <def_version.two: 1>
243+
244+
Version 2 definition processing.
245+
)pbdoc")
184246
.value("one",
185-
ToddCoxeterImpl_::word_graph_type::options::def_version::one,
186-
R"pbdoc(Version 1 definition processing.)pbdoc")
247+
ToddCoxeterImpl_::word_graph_type::options::def_version::one)
187248
.value("two",
188-
ToddCoxeterImpl_::word_graph_type::options::def_version::two,
189-
R"pbdoc(Version 2 definition processing.)pbdoc")
249+
ToddCoxeterImpl_::word_graph_type::options::def_version::two)
190250
.export_values();
191251

192252
//////////////////////////////////////////////////////////////////////////

0 commit comments

Comments
 (0)