Tensor Canonicalization#
- sympy.combinatorics.tensor_can.canonicalize(g, dummies, msym, *v)[source]#
canonicalize tensor formed by tensors
- Parameters:
g : permutation representing the tensor
dummies : list representing the dummy indices
it can be a list of dummy indices of the same type or a list of lists of dummy indices, one list for each type of index; the dummy indices must come after the free indices, and put in order contravariant, covariant [d0, -d0, d1,-d1,…]
msym : symmetry of the metric(s)
it can be an integer or a list; in the first case it is the symmetry of the dummy index metric; in the second case it is the list of the symmetries of the index metric for each type
v : list, (base_i, gens_i, n_i, sym_i) for tensors of type
base_i, gens_i : BSGS for tensors of this type.
The BSGS should have minimal base under lexicographic ordering; if not, an attempt is made do get the minimal BSGS; in case of failure, canonicalize_naive is used, which is much slower.
n_i : number of tensors of type
.
sym_i : symmetry under exchange of component tensors of type
.
- Both for msym and sym_i the cases are
None no symmetry
0 commuting
1 anticommuting
- Returns:
0 if the tensor is zero, else return the array form of
the permutation representing the canonical form of the tensor.
Algorithm
First one uses canonical_free to get the minimum tensor under lexicographic order, using only the slot symmetries. If the component tensors have not minimal BSGS, it is attempted to find it; if the attempt fails canonicalize_naive is used instead.
Compute the residual slot symmetry keeping fixed the free indices using tensor_gens(base, gens, list_free_indices, sym).
Reduce the problem eliminating the free indices.
Then use double_coset_can_rep and lift back the result reintroducing the free indices.
Examples
one type of index with commuting metric;
and
antisymmetric and commuting
order of the indices
g = [1, 3, 0, 5, 4, 2, 6, 7]
>>> from sympy.combinatorics.tensor_can import get_symmetric_group_sgs, canonicalize, bsgs_direct_product >>> from sympy.combinatorics import Permutation >>> base2a, gens2a = get_symmetric_group_sgs(2, 1) >>> t0 = (base2a, gens2a, 1, 0) >>> t1 = (base2a, gens2a, 2, 0) >>> g = Permutation([1, 3, 0, 5, 4, 2, 6, 7]) >>> canonicalize(g, range(6), 0, t0, t1) 0
same as above, but with
anticommuting
can = [0,2,1,4,3,5,7,6]
>>> t1 = (base2a, gens2a, 2, 1) >>> canonicalize(g, range(6), 0, t0, t1) [0, 2, 1, 4, 3, 5, 7, 6]
two types of indices
and
, in this order, both with commuting metric
antisymmetric, commuting
no symmetry, commuting
ord = [c,f,a,-a,b,-b,d,-d,e,-e,m,-m,n,-n]
g = [0,7,3, 1,9,5, 11,6, 10,4, 13,2, 12,8, 14,15]
The canonical tensor is
can = [0,2,4, 1,6,8, 10,3, 11,7, 12,5, 13,9, 15,14]
>>> base_f, gens_f = get_symmetric_group_sgs(3, 1) >>> base1, gens1 = get_symmetric_group_sgs(1) >>> base_A, gens_A = bsgs_direct_product(base1, gens1, base1, gens1) >>> t0 = (base_f, gens_f, 2, 0) >>> t1 = (base_A, gens_A, 4, 0) >>> dummies = [range(2, 10), range(10, 14)] >>> g = Permutation([0, 7, 3, 1, 9, 5, 11, 6, 10, 4, 13, 2, 12, 8, 14, 15]) >>> canonicalize(g, dummies, [0, 0], t0, t1) [0, 2, 4, 1, 6, 8, 10, 3, 11, 7, 12, 5, 13, 9, 15, 14]
- sympy.combinatorics.tensor_can.double_coset_can_rep(dummies, sym, b_S, sgens, S_transversals, g)[source]#
Butler-Portugal algorithm for tensor canonicalization with dummy indices.
- Parameters:
dummies
list of lists of dummy indices, one list for each type of index; the dummy indices are put in order contravariant, covariant [d0, -d0, d1, -d1, …].
- sym
list of the symmetries of the index metric for each type.
- possible symmetries of the metrics
0 symmetric
1 antisymmetric
None no symmetry
- b_S
base of a minimal slot symmetry BSGS.
- sgens
generators of the slot symmetry BSGS.
- S_transversals
transversals for the slot BSGS.
- g
permutation representing the tensor.
- Returns:
Return 0 if the tensor is zero, else return the array form of
the permutation representing the canonical form of the tensor.
Notes
A tensor with dummy indices can be represented in a number of equivalent ways which typically grows exponentially with the number of indices. To be able to establish if two tensors with many indices are equal becomes computationally very slow in absence of an efficient algorithm.
The Butler-Portugal algorithm [3] is an efficient algorithm to put tensors in canonical form, solving the above problem.
Portugal observed that a tensor can be represented by a permutation, and that the class of tensors equivalent to it under slot and dummy symmetries is equivalent to the double coset
(Note: in this documentation we use the conventions for multiplication of permutations p, q with (p*q)(i) = p[q[i]] which is opposite to the one used in the Permutation class)
Using the algorithm by Butler to find a representative of the double coset one can find a canonical form for the tensor.
To see this correspondence, let
be a permutation in array form; a tensor with indices
(the indices including both the contravariant and the covariant ones) can be written as
,
where
;
has size
, the last two indices for the sign of the tensor (trick introduced in [4]).
A slot symmetry transformation
is a permutation acting on the slots
A dummy symmetry transformation acts on
Being interested only in the transformations of the tensor under these symmetries, one can represent the tensor by
, which transforms as
, so it belongs to the coset
, or in other words to the set of all permutations allowed by the slot and dummy symmetries.
Let us explain the conventions by an example.
- Given a tensor
with the slot symmetries
and symmetric metric, find the tensor equivalent to it which is the lowest under the ordering of indices: lexicographic ordering
and then contravariant before covariant index; that is the canonical form of the tensor.
The canonical form is
obtained using
.
To convert this problem in the input for this function, use the following ordering of the index names (- for covariant for short)
corresponds to
where the last two indices are for the sign
sgens[0] is the slot symmetry
sgens[1] is the slot symmetry
The dummy symmetry group D is generated by the strong base generators
where the first three interchange covariant and contravariant positions of the same index (d1 <-> -d1) and the last two interchange the dummy indices themselves (d1 <-> d2).
The dummy symmetry acts from the left
exchange
which differs from
.
The slot symmetry acts from the right
exchanges slots 0 and 2 and changes sign
Example in which the tensor is zero, same slot symmetries as above:
under slot symmetry
;
under slot symmetry
;
symmetric metric;
since two of these lines have tensors differ only for the sign.
The double coset D*g*S consists of permutations
corresponding to equivalent tensors; if there are two
which are the same apart from the sign, return zero; otherwise choose as representative the tensor with indices ordered lexicographically according to
that is
rep = min(D*g*S) = min([d*g*s for d in D for s in S])
The indices are fixed one by one; first choose the lowest index for slot 0, then the lowest remaining index for slot 1, etc. Doing this one obtains a chain of stabilizers
and
where
[b0, b1, ...] = range(b)
is a base of the symmetric group; the strong baseof S is an ordered sublist of it; therefore it is sufficient to compute once the strong base generators of S using the Schreier-Sims algorithm; the stabilizers of the strong base generators are the strong base generators of the stabilizer subgroup.
dbase = [p0, p1, ...]
is not in general in lexicographic order, so that one must recompute the strong base generators each time; however this is trivial, there is no need to use the Schreier-Sims algorithm for D.The algorithm keeps a TAB of elements
where
satisfying
for
starting from
.
The equations
are solved in this order, choosing each time the lowest possible value of p_i
For
so that for dx in
and sx in
one has
Search for dx, sx such that this equation holds for
; it can be written as
for all j, so that
is the solution.
Add the found
to TAB1.
At the end of the iteration sort TAB1 with respect to the
; if there are two consecutive
in TAB1 which differ only for the sign, the tensor is zero, so return 0; if there are two consecutive
which are equal, keep only one.
Then stabilize the slot generators under
and the dummy generators under
.
Assign
at the end of the iteration step.
At the end
contains a unique
, since all the slots of the tensor
have been fixed to have the minimum value according to the symmetries. The algorithm returns
.
It is important that the slot BSGS has lexicographic minimal base, otherwise there is an
which does not belong to the slot base for which
is fixed by the dummy symmetry only, while
is not invariant from the slot stabilizer, so
is not in general the minimal value.
- This algorithm differs slightly from the original algorithm [3]:
the canonical form is minimal lexicographically, and the BSGS has minimal base under lexicographic order. Equal tensors
are eliminated from TAB.
Examples
>>> from sympy.combinatorics.permutations import Permutation >>> from sympy.combinatorics.tensor_can import double_coset_can_rep, get_transversals >>> gens = [Permutation(x) for x in [[2, 1, 0, 3, 4, 5, 7, 6], [4, 1, 2, 3, 0, 5, 7, 6]]] >>> base = [0, 2] >>> g = Permutation([4, 2, 0, 1, 3, 5, 6, 7]) >>> transversals = get_transversals(base, gens) >>> double_coset_can_rep([list(range(6))], [0], base, gens, transversals, g) [0, 1, 2, 3, 4, 5, 7, 6]
>>> g = Permutation([4, 1, 3, 0, 5, 2, 6, 7]) >>> double_coset_can_rep([list(range(6))], [0], base, gens, transversals, g) 0
- sympy.combinatorics.tensor_can.get_symmetric_group_sgs(n, antisym=False)[source]#
Return base, gens of the minimal BSGS for (anti)symmetric tensor
- Parameters:
n : rank of the tensor
antisym : bool
antisym = False
symmetric tensorantisym = True
antisymmetric tensor
Examples
>>> from sympy.combinatorics.tensor_can import get_symmetric_group_sgs >>> get_symmetric_group_sgs(3) ([0, 1], [(4)(0 1), (4)(1 2)])
- sympy.combinatorics.tensor_can.bsgs_direct_product(base1, gens1, base2, gens2, signed=True)[source]#
Direct product of two BSGS.
- Parameters:
base1 : base of the first BSGS.
gens1 : strong generating sequence of the first BSGS.
base2, gens2 : similarly for the second BSGS.
signed : flag for signed permutations.
Examples
>>> from sympy.combinatorics.tensor_can import (get_symmetric_group_sgs, bsgs_direct_product) >>> base1, gens1 = get_symmetric_group_sgs(1) >>> base2, gens2 = get_symmetric_group_sgs(2) >>> bsgs_direct_product(base1, gens1, base2, gens2) ([1], [(4)(1 2)])