d2ce4e94a769dbc32e2188e45fa63dbab7c92272
[ginac.git] / ginac / symmetry.h
1 /** @file symmetry.h
2  *
3  *  Interface to GiNaC's symmetry definitions. */
4
5 /*
6  *  GiNaC Copyright (C) 1999-2005 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_SYMMETRY_H__
24 #define __GINAC_SYMMETRY_H__
25
26 #include <set>
27
28 #include "ex.h"
29
30 namespace GiNaC {
31
32
33 class sy_is_less;
34 class sy_swap;
35
36 /** This class describes the symmetry of a group of indices. These objects
37  *  can be grouped into a tree to form complex mixed symmetries. */
38 class symmetry : public basic
39 {
40         friend class sy_is_less;
41         friend class sy_swap;
42         friend int canonicalize(exvector::iterator v, const symmetry &symm);
43
44         GINAC_DECLARE_REGISTERED_CLASS(symmetry, basic)
45
46         // types
47 public:
48         /** Type of symmetry */
49         typedef enum {
50                 none,          /**< no symmetry properties */
51                 symmetric,     /**< totally symmetric */
52                 antisymmetric, /**< totally antisymmetric */
53                 cyclic         /**< cyclic symmetry */
54         } symmetry_type;
55
56         // other constructors
57 public:
58         /** Create leaf node that represents one index. */
59         symmetry(unsigned i);
60
61         /** Create node with two children. */
62         symmetry(symmetry_type t, const symmetry &c1, const symmetry &c2);
63
64         // non-virtual functions in this class
65 public:
66         /** Get symmetry type. */
67         symmetry_type get_type() const {return type;}
68
69         /** Set symmetry type. */
70         void set_type(symmetry_type t) {type = t;}
71
72         /** Add child node, check index sets for consistency. */
73         symmetry &add(const symmetry &c);
74
75         /** Verify that all indices of this node are in the range [0..n-1].
76          *  This function throws an exception if the verification fails.
77          *  If the top node has a type != none and no children, add all indices
78          *  in the range [0..n-1] as children. */
79         void validate(unsigned n);
80
81         /** Check whether this node actually represents any kind of symmetry. */
82         bool has_symmetry() const {return type != none || !children.empty(); }
83
84 protected:
85         void do_print(const print_context & c, unsigned level) const;
86         void do_print_tree(const print_tree & c, unsigned level) const;
87
88         // member variables
89 private:
90         /** Type of symmetry described by this node. */
91         symmetry_type type;
92
93         /** Sorted union set of all indices handled by this node. */
94         std::set<unsigned> indices;
95
96         /** Vector of child nodes. */
97         exvector children;
98 };
99
100
101 // global functions
102
103 inline symmetry sy_none() { return symmetry(); }
104 inline symmetry sy_none(const symmetry &c1, const symmetry &c2) { return symmetry(symmetry::none, c1, c2); }
105 inline symmetry sy_none(const symmetry &c1, const symmetry &c2, const symmetry &c3) { return symmetry(symmetry::none, c1, c2).add(c3); }
106 inline symmetry sy_none(const symmetry &c1, const symmetry &c2, const symmetry &c3, const symmetry &c4) { return symmetry(symmetry::none, c1, c2).add(c3).add(c4); }
107
108 inline symmetry sy_symm() { symmetry s; s.set_type(symmetry::symmetric); return s; }
109 inline symmetry sy_symm(const symmetry &c1, const symmetry &c2) { return symmetry(symmetry::symmetric, c1, c2); }
110 inline symmetry sy_symm(const symmetry &c1, const symmetry &c2, const symmetry &c3) { return symmetry(symmetry::symmetric, c1, c2).add(c3); }
111 inline symmetry sy_symm(const symmetry &c1, const symmetry &c2, const symmetry &c3, const symmetry &c4) { return symmetry(symmetry::symmetric, c1, c2).add(c3).add(c4); }
112
113 inline symmetry sy_anti() { symmetry s; s.set_type(symmetry::antisymmetric); return s; }
114 inline symmetry sy_anti(const symmetry &c1, const symmetry &c2) { return symmetry(symmetry::antisymmetric, c1, c2); }
115 inline symmetry sy_anti(const symmetry &c1, const symmetry &c2, const symmetry &c3) { return symmetry(symmetry::antisymmetric, c1, c2).add(c3); }
116 inline symmetry sy_anti(const symmetry &c1, const symmetry &c2, const symmetry &c3, const symmetry &c4) { return symmetry(symmetry::antisymmetric, c1, c2).add(c3).add(c4); }
117
118 inline symmetry sy_cycl() { symmetry s; s.set_type(symmetry::cyclic); return s; }
119 inline symmetry sy_cycl(const symmetry &c1, const symmetry &c2) { return symmetry(symmetry::cyclic, c1, c2); }
120 inline symmetry sy_cycl(const symmetry &c1, const symmetry &c2, const symmetry &c3) { return symmetry(symmetry::cyclic, c1, c2).add(c3); }
121 inline symmetry sy_cycl(const symmetry &c1, const symmetry &c2, const symmetry &c3, const symmetry &c4) { return symmetry(symmetry::cyclic, c1, c2).add(c3).add(c4); }
122
123 // These return references to preallocated common symmetries (similar to
124 // the numeric flyweights).
125 const symmetry & not_symmetric();
126 const symmetry & symmetric2();
127 const symmetry & symmetric3();
128 const symmetry & symmetric4();
129 const symmetry & antisymmetric2();
130 const symmetry & antisymmetric3();
131 const symmetry & antisymmetric4();
132
133 /** Canonicalize the order of elements of an expression vector, according to
134  *  the symmetry properties defined in a symmetry tree.
135  *
136  *  @param v Start of expression vector
137  *  @param symm Root node of symmetry tree
138  *  @return the overall sign introduced by the reordering (+1, -1 or 0)
139  *          or INT_MAX if nothing changed */
140 extern int canonicalize(exvector::iterator v, const symmetry &symm);
141
142 /** Symmetrize expression over a set of objects (symbols, indices). */
143 ex symmetrize(const ex & e, exvector::const_iterator first, exvector::const_iterator last);
144
145 /** Symmetrize expression over a set of objects (symbols, indices). */
146 inline ex symmetrize(const ex & e, const exvector & v)
147 {
148         return symmetrize(e, v.begin(), v.end());
149 }
150
151 /** Antisymmetrize expression over a set of objects (symbols, indices). */
152 ex antisymmetrize(const ex & e, exvector::const_iterator first, exvector::const_iterator last);
153
154 /** Antisymmetrize expression over a set of objects (symbols, indices). */
155 inline ex antisymmetrize(const ex & e, const exvector & v)
156 {
157         return antisymmetrize(e, v.begin(), v.end());
158 }
159
160 /** Symmetrize expression by cyclic permuation over a set of objects
161  *  (symbols, indices). */
162 ex symmetrize_cyclic(const ex & e, exvector::const_iterator first, exvector::const_iterator last);
163
164 /** Symmetrize expression by cyclic permutation over a set of objects
165  *  (symbols, indices). */
166 inline ex symmetrize_cyclic(const ex & e, const exvector & v)
167 {
168         return symmetrize(e, v.begin(), v.end());
169 }
170
171 // utility functions
172
173 /** Specialization of is_exactly_a<symmetry>(obj) for symmetry objects. */
174 template<> inline bool is_exactly_a<symmetry>(const basic & obj)
175 {
176         return obj.tinfo()==TINFO_symmetry;
177 }
178
179 } // namespace GiNaC
180
181 #endif // ndef __GINAC_SYMMETRY_H__