1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
|
/*
This file contains docstrings for use in the Python bindings.
Do not edit! They were automatically extracted by ../gendoc.sh.
*/
#if defined(__GNUG__)
#pragma GCC diagnostic push
#pragma GCC diagnostic ignored "-Wunused-variable"
#endif
namespace regina::python::doc {
// Docstring regina::python::doc::HilbertPrimal
static const char *HilbertPrimal =
R"doc(Implements a modified primal algorithm for enumerating Hilbert bases.
This incorporates the primal algorithm described in "Normaliz:
Algorithms for affine monoids and rational cones", Winfried Bruns and
Bogdan Ichim, J. Algebra 324 (2010), 1098-1113, and has been modified
to allow for additional constraints (such as the quadrilateral
constraints from normal surface theory).
To summarise: the algorithm first enumerates extremal rays of the
rational cone, and then decomposes the admissible region of the cone
(where the extra constraints are satisfied) into maximal admissible
faces. It calls Normaliz directly to enumerate the Hilbert basis for
each maximal admissible faces, and finally combines these into a basis
for the entire space.
All routines of interest within this class are static; no object of
this class should ever be created.)doc";
namespace HilbertPrimal_ {
// Docstring regina::python::doc::HilbertPrimal_::enumerate
static const char *enumerate =
R"doc(Determines the Hilbert basis that generates all integer points in the
intersection of the *n*-dimensional non-negative orthant with some
linear subspace. The resulting basis elements will be of the class
*RayClass*, and will be passed into the given action function one at a
time.
The intersection of the non-negative orthant with this linear subspace
is a pointed polyhedral cone with apex at the origin, and this routine
requires the extremal rays of this cone to be provided as input. The
extremal rays can be computed using DoubleDescription::enumerate() in
general cases, though sometimes (such as with normal surface theory)
more efficient methods are available.
This routine computes the Hilbert basis of all integer points in this
cone. The resulting list of basis vectors will contain no duplicates
or redundancies.
The parameter *constraints* may contain a set of validity constraints,
in which case this routine will only return _valid_ basis elements.
Each validity constraint is of the form "at most one of these
coordinates may be non-zero"; see the ValidityConstraints class for
details. These contraints have the important property that, although
validity is not preserved under addition, _invalidity_ is.
An optional progress tracker may be passed. If so, this routine will
update the percentage progress and poll for cancellation requests. It
will be assumed that an appropriate stage has already been declared
via ProgressTracker::newStage() before this routine is called, and
that ProgressTracker::setFinished() will be called after this routine
returns.
For each of the resulting basis elements, this routine will call
*action* (which must be a function or some other callable object).
This action should return ``void``, and must take exactly one
argument, which will be the basis element stored using *RayClass*. The
argument will be passed as an rvalue; a typical *action* would take it
as an rvalue reference (RayClass&&) and move its contents into some
other more permanent storage.
Precondition:
If *constraints* is passed, then the given list of extremal rays
contains _only_ those extremal rays that satisfy all of the given
constraints.
Precondition:
The template argument RayClass is derived from (or equal to)
Vector<T>, where *T* is one of Regina's arbitrary-precision
integer classes (Integer or LargeInteger).
Precondition:
The template argument RayIterator is a forward iterator type, and
when dereferenced has the interface of a constant vector of
Regina's arbitrary-precision integers (i.e., the elements of the
vector must be of type Integer or LargeInteger). For example, it
might dereference to a (const Vector<Integer>&), or a (const
std::vector<LargeInteger>&). The vector interface required is
minimal (just a bracket operator and a size() function), and in
particular both std::vector and regina::Vector will suffice for
this.
.. warning::
If a progress tracker is passed, be aware that the present
implementation updates percentage progress very infrequently, and
may take a very long time to honour cancellation requests.
Exception ``UnsolvedCase``:
Normaliz was unable to compute the Hilbert basis for one or more
maximal admissible faces.
Python:
There are two versions of this function available in Python:
* ``enumerate(action, rays, constraints, tracker)``, which mirrors
the C++ function; here *action* may be a pure Python function.
* ``enumerate(rays, constraints, tracker)``, where the *action*
argument is missing, and instead the function returns a Python
list containing all Hilbert basis elements.
In both versions, the extremal rays must be passed as either:
* a Python list of VectorInt objects, which means the output type
*RayClass* will be VectorInt; or
* a NormalSurfaces or NormalHypersurfaces object, which meams the
output type *RayClass* will be VectorLarge, and the input list
of extremal rays will be the range from ``rays.beginVectors()``
to ``rays.endVectors()``.
The global interpreter lock will be released while this function
runs, so you can use it with Python-based multithreading.
Parameter ``action``:
a function (or other callable object) that will be called for each
basis element. This function must take a single argument, which
will be passed as an rvalue of type RayClass.
Parameter ``raysBegin``:
an iterator pointing to the beginning of the list of extremal
rays.
Parameter ``raysEnd``:
an iterator pointing past the end of the list of extremal rays.
Parameter ``constraints``:
a set of validity constraints as described above, or
ValidityConstraints::none if none should be imposed.
Parameter ``tracker``:
a progress tracker through which progress will be reported, or
``None`` if no progress reporting is required.)doc";
}
} // namespace regina::python::doc
#if defined(__GNUG__)
#pragma GCC diagnostic pop
#endif
|
