ginac/symmetry.h

   1 /** @file symmetry.h
   2  *
   3  *  Interface to GiNaC's symmetry definitions. */
   4
   5 /*
   6  *  GiNaC Copyright (C) 1999-2007 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         /** Check whether this node involves a cyclic symmetry. */
  84         bool has_cyclic() const;
  85
  86 protected:
  87         void do_print(const print_context & c, unsigned level) const;
  88         void do_print_tree(const print_tree & c, unsigned level) const;
  89         unsigned calchash() const;
  90
  91         // member variables
  92 private:
  93         /** Type of symmetry described by this node. */
  94         symmetry_type type;
  95
  96         /** Sorted union set of all indices handled by this node. */
  97         std::set<unsigned> indices;
  98
  99         /** Vector of child nodes. */
 100         exvector children;
 101 };
 102
 103
 104 // global functions
 105
 106 inline symmetry sy_none() { return symmetry(); }
 107 inline symmetry sy_none(const symmetry &c1, const symmetry &c2) { return symmetry(symmetry::none, c1, c2); }
 108 inline symmetry sy_none(const symmetry &c1, const symmetry &c2, const symmetry &c3) { return symmetry(symmetry::none, c1, c2).add(c3); }
 109 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); }
 110
 111 inline symmetry sy_symm() { symmetry s; s.set_type(symmetry::symmetric); return s; }
 112 inline symmetry sy_symm(const symmetry &c1, const symmetry &c2) { return symmetry(symmetry::symmetric, c1, c2); }
 113 inline symmetry sy_symm(const symmetry &c1, const symmetry &c2, const symmetry &c3) { return symmetry(symmetry::symmetric, c1, c2).add(c3); }
 114 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); }
 115
 116 inline symmetry sy_anti() { symmetry s; s.set_type(symmetry::antisymmetric); return s; }
 117 inline symmetry sy_anti(const symmetry &c1, const symmetry &c2) { return symmetry(symmetry::antisymmetric, c1, c2); }
 118 inline symmetry sy_anti(const symmetry &c1, const symmetry &c2, const symmetry &c3) { return symmetry(symmetry::antisymmetric, c1, c2).add(c3); }
 119 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); }
 120
 121 inline symmetry sy_cycl() { symmetry s; s.set_type(symmetry::cyclic); return s; }
 122 inline symmetry sy_cycl(const symmetry &c1, const symmetry &c2) { return symmetry(symmetry::cyclic, c1, c2); }
 123 inline symmetry sy_cycl(const symmetry &c1, const symmetry &c2, const symmetry &c3) { return symmetry(symmetry::cyclic, c1, c2).add(c3); }
 124 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); }
 125
 126 // These return references to preallocated common symmetries (similar to
 127 // the numeric flyweights).
 128 const symmetry & not_symmetric();
 129 const symmetry & symmetric2();
 130 const symmetry & symmetric3();
 131 const symmetry & symmetric4();
 132 const symmetry & antisymmetric2();
 133 const symmetry & antisymmetric3();
 134 const symmetry & antisymmetric4();
 135
 136 /** Canonicalize the order of elements of an expression vector, according to
 137  *  the symmetry properties defined in a symmetry tree.
 138  *
 139  *  @param v Start of expression vector
 140  *  @param symm Root node of symmetry tree
 141  *  @return the overall sign introduced by the reordering (+1, -1 or 0)
 142  *          or numeric_limits<int>::max() if nothing changed */
 143 extern int canonicalize(exvector::iterator v, const symmetry &symm);
 144
 145 /** Symmetrize expression over a set of objects (symbols, indices). */
 146 ex symmetrize(const ex & e, exvector::const_iterator first, exvector::const_iterator last);
 147
 148 /** Symmetrize expression over a set of objects (symbols, indices). */
 149 inline ex symmetrize(const ex & e, const exvector & v)
 150 {
 151         return symmetrize(e, v.begin(), v.end());
 152 }
 153
 154 /** Antisymmetrize expression over a set of objects (symbols, indices). */
 155 ex antisymmetrize(const ex & e, exvector::const_iterator first, exvector::const_iterator last);
 156
 157 /** Antisymmetrize expression over a set of objects (symbols, indices). */
 158 inline ex antisymmetrize(const ex & e, const exvector & v)
 159 {
 160         return antisymmetrize(e, v.begin(), v.end());
 161 }
 162
 163 /** Symmetrize expression by cyclic permuation over a set of objects
 164  *  (symbols, indices). */
 165 ex symmetrize_cyclic(const ex & e, exvector::const_iterator first, exvector::const_iterator last);
 166
 167 /** Symmetrize expression by cyclic permutation over a set of objects
 168  *  (symbols, indices). */
 169 inline ex symmetrize_cyclic(const ex & e, const exvector & v)
 170 {
 171         return symmetrize(e, v.begin(), v.end());
 172 }
 173
 174 } // namespace GiNaC
 175
 176 #endif // ndef __GINAC_SYMMETRY_H__