Univariate Hensel lifting now uses upoly.
[ginac.git] / ginac / idx.h
1 /** @file idx.h
2  *
3  *  Interface to GiNaC's indices. */
4
5 /*
6  *  GiNaC Copyright (C) 1999-2008 Johannes Gutenberg University Mainz, Germany
7  *
8  *  This program is free software; you can redistribute it and/or modify
9  *  it under the terms of the GNU General Public License as published by
10  *  the Free Software Foundation; either version 2 of the License, or
11  *  (at your option) any later version.
12  *
13  *  This program is distributed in the hope that it will be useful,
14  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
15  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
16  *  GNU General Public License for more details.
17  *
18  *  You should have received a copy of the GNU General Public License
19  *  along with this program; if not, write to the Free Software
20  *  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
21  */
22
23 #ifndef __GINAC_IDX_H__
24 #define __GINAC_IDX_H__
25
26 #include "ex.h"
27 #include "numeric.h"
28
29 namespace GiNaC {
30
31
32 /** This class holds one index of an indexed object. Indices can
33  *  theoretically consist of any symbolic expression but they are usually
34  *  only just a symbol (e.g. "mu", "i") or numeric (integer). Indices belong
35  *  to a space with a certain numeric or symbolic dimension. */
36 class idx : public basic
37 {
38         GINAC_DECLARE_REGISTERED_CLASS(idx, basic)
39
40         // other constructors
41 public:
42         /** Construct index with given value and dimension.
43          *
44          *  @param v Value of index (numeric or symbolic)
45          *  @param dim Dimension of index space (numeric or symbolic)
46          *  @return newly constructed index */
47         explicit idx(const ex & v, const ex & dim);
48
49         // functions overriding virtual functions from base classes
50 public:
51         bool info(unsigned inf) const;
52         size_t nops() const;
53         ex op(size_t i) const;
54         ex map(map_function & f) const;
55         ex evalf(int level = 0) const;
56         ex subs(const exmap & m, unsigned options = 0) const;
57         void archive(archive_node& n) const;
58         void read_archive(const archive_node& n, lst& syms);
59 protected:
60         ex derivative(const symbol & s) const;
61         bool match_same_type(const basic & other) const;
62         unsigned calchash() const;
63
64         // new virtual functions in this class
65 public:
66         /** Check whether the index forms a dummy index pair with another index
67          *  of the same type. */
68         virtual bool is_dummy_pair_same_type(const basic & other) const;
69
70         // non-virtual functions in this class
71 public:
72         /** Get value of index. */
73         ex get_value() const {return value;}
74
75         /** Check whether the index is numeric. */
76         bool is_numeric() const {return is_exactly_a<numeric>(value);}
77
78         /** Check whether the index is symbolic. */
79         bool is_symbolic() const {return !is_exactly_a<numeric>(value);}
80
81         /** Get dimension of index space. */
82         ex get_dim() const {return dim;}
83
84         /** Check whether the dimension is numeric. */
85         bool is_dim_numeric() const {return is_exactly_a<numeric>(dim);}
86
87         /** Check whether the dimension is symbolic. */
88         bool is_dim_symbolic() const {return !is_exactly_a<numeric>(dim);}
89
90         /** Make a new index with the same value but a different dimension. */
91         ex replace_dim(const ex & new_dim) const;
92
93         /** Return the minimum of the dimensions of this and another index.
94          *  If this is undecidable, throw an exception. */
95         ex minimal_dim(const idx & other) const;
96
97 protected:
98         void print_index(const print_context & c, unsigned level) const;
99         void do_print(const print_context & c, unsigned level) const;
100         void do_print_csrc(const print_csrc & c, unsigned level) const;
101         void do_print_latex(const print_latex & c, unsigned level) const;
102         void do_print_tree(const print_tree & c, unsigned level) const;
103
104 protected:
105         ex value; /**< Expression that constitutes the index (numeric or symbolic name) */
106         ex dim;   /**< Dimension of space (can be symbolic or numeric) */
107 };
108 GINAC_DECLARE_UNARCHIVER(idx); 
109
110
111 /** This class holds an index with a variance (co- or contravariant). There
112  *  is an associated metric tensor that can be used to raise/lower indices. */
113 class varidx : public idx
114 {
115         GINAC_DECLARE_REGISTERED_CLASS(varidx, idx)
116
117         // other constructors
118 public:
119         /** Construct index with given value, dimension and variance.
120          *
121          *  @param v Value of index (numeric or symbolic)
122          *  @param dim Dimension of index space (numeric or symbolic)
123          *  @param covariant Make covariant index (default is contravariant)
124          *  @return newly constructed index */
125         varidx(const ex & v, const ex & dim, bool covariant = false);
126
127         // functions overriding virtual functions from base classes
128 public:
129         bool is_dummy_pair_same_type(const basic & other) const;
130         void archive(archive_node& n) const;
131         void read_archive(const archive_node& n, lst& syms);
132 protected:
133         bool match_same_type(const basic & other) const;
134
135         // non-virtual functions in this class
136 public:
137         /** Check whether the index is covariant. */
138         bool is_covariant() const {return covariant;}
139
140         /** Check whether the index is contravariant (not covariant). */
141         bool is_contravariant() const {return !covariant;}
142
143         /** Make a new index with the same value but the opposite variance. */
144         ex toggle_variance() const;
145
146 protected:
147         void do_print(const print_context & c, unsigned level) const;
148         void do_print_tree(const print_tree & c, unsigned level) const;
149
150         // member variables
151 protected:
152         bool covariant; /**< x.mu, default is contravariant: x~mu */
153 };
154 GINAC_DECLARE_UNARCHIVER(varidx);
155
156
157 /** This class holds a spinor index that can be dotted or undotted and that
158  *  also has a variance. This is used in the Weyl-van-der-Waerden formalism
159  *  where the dot indicates complex conjugation. There is an associated
160  *  (asymmetric) metric tensor that can be used to raise/lower spinor
161  *  indices. */
162 class spinidx : public varidx
163 {
164         GINAC_DECLARE_REGISTERED_CLASS(spinidx, varidx)
165
166         // other constructors
167 public:
168         /** Construct index with given value, dimension, variance and dot.
169          *
170          *  @param v Value of index (numeric or symbolic)
171          *  @param dim Dimension of index space (numeric or symbolic)
172          *  @param covariant Make covariant index (default is contravariant)
173          *  @param dotted Make covariant dotted (default is undotted)
174          *  @return newly constructed index */
175         spinidx(const ex & v, const ex & dim = 2, bool covariant = false, bool dotted = false);
176
177         // functions overriding virtual functions from base classes
178 public:
179         bool is_dummy_pair_same_type(const basic & other) const;
180         // complex conjugation
181         ex conjugate() const { return toggle_dot(); }
182         void archive(archive_node& n) const;
183         void read_archive(const archive_node& n, lst& syms);
184 protected:
185         bool match_same_type(const basic & other) const;
186
187         // non-virtual functions in this class
188 public:
189         /** Check whether the index is dotted. */
190         bool is_dotted() const {return dotted;}
191
192         /** Check whether the index is not dotted. */
193         bool is_undotted() const {return !dotted;}
194
195         /** Make a new index with the same value and variance but the opposite
196          *  dottedness. */
197         ex toggle_dot() const;
198
199         /** Make a new index with the same value but opposite variance and
200          *  dottedness. */
201         ex toggle_variance_dot() const;
202
203 protected:
204         void do_print(const print_context & c, unsigned level) const;
205         void do_print_latex(const print_latex & c, unsigned level) const;
206         void do_print_tree(const print_tree & c, unsigned level) const;
207
208         // member variables
209 protected:
210         bool dotted;
211 };
212 GINAC_DECLARE_UNARCHIVER(spinidx);
213
214
215 // utility functions
216
217 /** Check whether two indices form a dummy pair. */
218 bool is_dummy_pair(const idx & i1, const idx & i2);
219
220 /** Check whether two expressions form a dummy index pair. */
221 bool is_dummy_pair(const ex & e1, const ex & e2);
222
223 /** Given a vector of indices, split them into two vectors, one containing
224  *  the free indices, the other containing the dummy indices (numeric
225  *  indices are neither free nor dummy ones).
226  *
227  *  @param it Pointer to start of index vector
228  *  @param itend Pointer to end of index vector
229  *  @param out_free Vector of free indices (returned, sorted)
230  *  @param out_dummy Vector of dummy indices (returned, sorted) */
231 void find_free_and_dummy(exvector::const_iterator it, exvector::const_iterator itend, exvector & out_free, exvector & out_dummy);
232
233 /** Given a vector of indices, split them into two vectors, one containing
234  *  the free indices, the other containing the dummy indices (numeric
235  *  indices are neither free nor dummy ones).
236  *
237  *  @param v Index vector
238  *  @param out_free Vector of free indices (returned, sorted)
239  *  @param out_dummy Vector of dummy indices (returned, sorted) */
240 inline void find_free_and_dummy(const exvector & v, exvector & out_free, exvector & out_dummy)
241 {
242         find_free_and_dummy(v.begin(), v.end(), out_free, out_dummy);
243 }
244
245 /** Given a vector of indices, find the dummy indices.
246  *
247  *  @param v Index vector
248  *  @param out_dummy Vector of dummy indices (returned, sorted) */
249 inline void find_dummy_indices(const exvector & v, exvector & out_dummy)
250 {
251         exvector free_indices;
252         find_free_and_dummy(v.begin(), v.end(), free_indices, out_dummy);
253 }
254
255 /** Count the number of dummy index pairs in an index vector. */
256 inline size_t count_dummy_indices(const exvector & v)
257 {
258         exvector free_indices, dummy_indices;
259         find_free_and_dummy(v.begin(), v.end(), free_indices, dummy_indices);
260         return dummy_indices.size();
261 }
262
263 /** Count the number of dummy index pairs in an index vector. */
264 inline size_t count_free_indices(const exvector & v)
265 {
266         exvector free_indices, dummy_indices;
267         find_free_and_dummy(v.begin(), v.end(), free_indices, dummy_indices);
268         return free_indices.size();
269 }
270
271 /** Return the minimum of two index dimensions. If this is undecidable,
272  *  throw an exception. Numeric dimensions are always considered "smaller"
273  *  than symbolic dimensions. */
274 ex minimal_dim(const ex & dim1, const ex & dim2);
275
276 } // namespace GiNaC
277
278 #endif // ndef __GINAC_IDX_H__