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