source: git/ntl/doc/ZZ_pE.txt @ 6ce030f

spielwiese
Last change on this file since 6ce030f was 2cfffe, checked in by Hans Schönemann <hannes@…>, 21 years ago
This commit was generated by cvs2svn to compensate for changes in r6316, which included commits to RCS files with non-trunk default branches. git-svn-id: file:///usr/local/Singular/svn/trunk@6317 2c84dea3-7e68-4137-9b89-c4e89433aadc
  • Property mode set to 100644
File size: 8.8 KB
Line 
1
2
3/**************************************************************************\
4
5MODULE: ZZ_pE
6
7SUMMARY:
8
9The class ZZ_pE is used to represent polynomials in Z_p[X] modulo a
10polynomial P.  The modulus P may be any polynomial with deg(P) > 0,
11not necessarily irreducible.  The modulus p defining Z_p need
12not be prime either.
13
14Objects of the class ZZ_pE are represented as a ZZ_pX of degree < deg(P).
15
16An executing program maintains a "current modulus", which is set to P
17using ZZ_pE::init(P).  The current modulus *must* be initialized before
18any ZZ_pE constructors are invoked.
19
20The modulus may be changed, and a mechanism is provided for saving and
21restoring a modulus (see classes ZZ_pEBak and ZZ_pEContext below).
22
23
24\**************************************************************************/
25
26#include <NTL/ZZ_pX.h>
27
28class ZZ_pE {
29public:
30   
31   ZZ_pE(); // initial value 0
32
33   ZZ_pE(const ZZ_pE& a); // copy constructor
34   
35   ZZ_pE& operator=(const ZZ_pE& a); // assignment
36   ZZ_pE& operator=(const ZZ_p& a); // assignment
37   ZZ_pE& operator=(long a); // assignment
38   
39   ~ZZ_pE(); // destructor
40
41   void init(const ZZ_pX& P);
42   // ZZ_pE::init(P) initializes the current modulus to P;
43   // required: deg(P) >= 1.
44   
45   static const ZZ_pXModulus& modulus();
46   // ZZ_pE::modulus() yields read-only reference to the current modulus
47
48   static long degree();
49   // ZZ_pE::degree() returns deg(P)
50};
51
52
53const ZZ_pX& rep(const ZZ_pE& a); // read-only access to representation of a
54
55
56
57/**************************************************************************\
58
59                                  Comparison
60
61\**************************************************************************/
62
63long operator==(const ZZ_pE& a, const ZZ_pE& b);
64long operator!=(const ZZ_pE& a, const ZZ_pE& b);
65
66long IsZero(const ZZ_pE& a);  // test for 0
67long IsOne(const ZZ_pE& a);  // test for 1
68
69// PROMOTIONS: ==, != promote {long, ZZ_p} to ZZ_pE on (a, b).
70
71
72/**************************************************************************\
73
74                                    Addition
75
76\**************************************************************************/
77
78// operator notation:
79
80ZZ_pE operator+(const ZZ_pE& a, const ZZ_pE& b);
81
82ZZ_pE operator-(const ZZ_pE& a, const ZZ_pE& b);
83ZZ_pE operator-(const ZZ_pE& a);
84
85ZZ_pE& operator+=(ZZ_pE& x, const ZZ_pE& a);
86ZZ_pE& operator+=(ZZ_pE& x, const ZZ_p& a);
87ZZ_pE& operator+=(ZZ_pE& x, long a);
88
89ZZ_pE& operator++(ZZ_pE& x); // prefix
90void operator++(ZZ_pE& x, int); // postfix
91
92ZZ_pE& operator-=(ZZ_pE& x, const ZZ_pE& a);
93ZZ_pE& operator-=(ZZ_pE& x, const ZZ_p& a);
94ZZ_pE& operator-=(ZZ_pE& x, long a);
95
96ZZ_pE& operator--(ZZ_pE& x); // prefix
97void operator--(ZZ_pE& x, int); // postfix
98
99// procedural versions:
100
101void add(ZZ_pE& x, const ZZ_pE& a, const ZZ_pE& b); // x = a + b
102void sub(ZZ_pE& x, const ZZ_pE& a, const ZZ_pE& b); // x = a - b
103void negate(ZZ_pE& x, const ZZ_pE& a); // x = - a
104
105// PROMOTIONS: +, -, add, sub promote {long, ZZ_p} to ZZ_pE on (a, b).
106
107
108/**************************************************************************\
109
110                                  Multiplication
111
112\**************************************************************************/
113
114
115// operator notation:
116
117ZZ_pE operator*(const ZZ_pE& a, const ZZ_pE& b);
118
119ZZ_pE& operator*=(ZZ_pE& x, const ZZ_pE& a);
120ZZ_pE& operator*=(ZZ_pE& x, const ZZ_p& a);
121ZZ_pE& operator*=(ZZ_pE& x, long a);
122
123// procedural versions:
124
125
126void mul(ZZ_pE& x, const ZZ_pE& a, const ZZ_pE& b); // x = a * b
127
128void sqr(ZZ_pE& x, const ZZ_pE& a); // x = a^2
129ZZ_pE sqr(const ZZ_pE& a);
130
131// PROMOTIONS: *, mul promote {long, ZZ_p} to ZZ_pE on (a, b).
132
133
134
135/**************************************************************************\
136
137                                     Division
138
139\**************************************************************************/
140
141
142// operator notation:
143
144ZZ_pE operator/(const ZZ_pE& a, const ZZ_pE& b);
145
146ZZ_pE& operator/=(ZZ_pE& x, const ZZ_pE& a);
147ZZ_pE& operator/=(ZZ_pE& x, const ZZ_p& a);
148ZZ_pE& operator/=(ZZ_pE& x, long a);
149
150
151// procedural versions:
152
153void div(ZZ_pE& x, const ZZ_pE& a, const ZZ_pE& b);
154// x = a/b.  If b is not invertible, an error is raised.
155
156void inv(ZZ_pE& x, const ZZ_pE& a);
157ZZ_pE inv(const ZZ_pE& a);
158// x = 1/a
159
160PROMOTIONS: /, div promote {long, ZZ_p} to ZZ_pE on (a, b).
161
162
163/**************************************************************************\
164
165                                  Exponentiation
166
167\**************************************************************************/
168
169
170
171void power(ZZ_pE& x, const ZZ_pE& a, const ZZ& e);
172ZZ_pE power(const ZZ_pE& a, const ZZ& e);
173
174void power(ZZ_pE& x, const ZZ_pE& a, long e);
175ZZ_pE power(const ZZ_pE& a, long e);
176
177// x = a^e (e may be negative)
178
179
180
181/**************************************************************************\
182
183                               Random Elements
184
185\**************************************************************************/
186
187
188void random(ZZ_pE& x);
189ZZ_pE random_ZZ_pE();
190// x = random element in ZZ_pE.
191
192/**************************************************************************\
193
194                               Norms and Traces
195
196\**************************************************************************/
197
198
199
200void trace(ZZ_p& x, const ZZ_pE& a);  // x = trace of a
201ZZ_p trace(const ZZ_pE& a);
202
203void norm(ZZ_p& x, const ZZ_pE& a);   // x = norm of a
204ZZ_p norm(const ZZ_pE& a);
205
206
207
208/**************************************************************************\
209
210                                Input/Output
211
212\**************************************************************************/
213
214
215ostream& operator<<(ostream& s, const ZZ_pE& a);
216
217istream& operator>>(istream& s, ZZ_pE& x);
218// a ZZ_pX is read and reduced mod p
219
220
221/**************************************************************************\
222
223                       Modulus Switching
224
225A class ZZ_pEBak is provided for "backing up" the current modulus.
226
227Here is what you do to save the current modulus, temporarily
228set it to something new, and then restore it:
229
230   ZZ_pEBak bak;
231   bak.save();   // save current modulus (if any)
232
233   ZZ_pE::init(P);  // set modulus to desired value P
234
235      // ...
236
237   bak.restore(); // restore old modulus (if any)
238
239Note that between the save and restore, you may have several calls to
240ZZ_pE::init, each of which simply clobbers the previous modulus.
241
242The ZZ_pEBak interface is good for implementing simple stack-like
243modulus "context switching".  For more general context switching,
244see ZZ_pEContext below.
245
246..........................................................................
247
248When the current modulus is changed, there may be extant
249ZZ_pE objects. If the old modulus was saved and then later restored,
250these objects can be used again as if the modulus had never changed. 
251Note, however, that if a ZZ_pE object is created under one modulus
252and then used in any way (except destroyed) under another,
253program behavior is not predictable.  This condition is not
254explicitly checked for, but an error is likely to be raised.
255One should also not presume that things will work properly
256if the modulus is changed, but its value happens to be the same---
257one should restore the same "context", from either a ZZ_pEBak
258or a ZZ_pEContext object.  This is anyway more efficient.
259
260\**************************************************************************/
261
262
263
264
265class ZZ_pEBak {
266public:
267
268   // To describe this logic, think of a ZZ_pEBak object
269   // of having two components: a modulus Q (possibly "null") and
270   // an "auto-restore bit" b.
271
272   // There is also a global current modulus P (initially "null").
273
274   ZZ_pEBak();  // Q = "null", b = 0
275
276   ~ZZ_pEBak();  // if (b) P = Q
277
278   void save();  // Q = P, b = 1
279   void restore();  // P = Q, b = 0
280
281
282private:
283   ZZ_pEBak(const ZZ_pEBak&);  // copy disabled
284   void operator=(const ZZ_pEBak&);  // assignment disabled
285};
286
287
288// more general context switching:
289
290class ZZ_pEContext {
291
292// A ZZ_pEContext object has a modulus Q (possibly "null"),
293// but has no auto-restore bit like a ZZ_pEBak object.
294// However, these objects can be initialized and copied with
295// complete generality.
296
297// As above, P is the current global modulus (initially "null")
298
299public:
300
301ZZ_pEContext(); // Q = "null"
302ZZ_pEContext(const ZZ_pX& new_Q); // Q = new_Q
303
304void save(); // Q = P
305void restore() const; // P = Q
306
307ZZ_pEContext(const ZZ_pEContext&);  // copy
308ZZ_pEContext& operator=(const ZZ_pEContext&); // assignment
309~ZZ_pEContext(); // destructor
310
311
312};
313
314
315/**************************************************************************\
316
317                               Miscellany
318
319\**************************************************************************/
320
321void clear(ZZ_pE& x); // x = 0
322void set(ZZ_pE& x); // x = 1
323
324static const ZZ_pE& ZZ_pE::zero();
325// ZZ_pE::zero() yields a read-only reference to zero
326
327void swap(ZZ_pE& x, ZZ_pE& y);
328// swap x and y (done by "pointer swapping", if possible).
329
330static ZZ& ZZ_pE::cardinality();
331// yields the cardinality, i.e., p^{ZZ_pE::degree()}
332
Note: See TracBrowser for help on using the repository browser.