ForestSum

class ForestSum(term_list: tuple | list = (), count: Counter = None, hash_: int = None)[source]

A linear combination of forests. Works with both non-planar (CommutativeForest) and planar (NoncommutativeForest) forests, but all terms in a single ForestSum must use the same forest type.

OrderedForestSum is an alias for ForestSum.

Parameters:: term_list – A list or tuple containing tuples of coefficients and forests representing terms of the sum. If a term contains a tree, it will be converted to a forest on initialisation.

Example usage:

t1 = Tree([])
t2 = Tree([[]])
t3 = Tree([[[]],[]])
s = ForestSum([(1, t1), (-2, t1*t2), (1, t2*t3)])
kr.display(s)

ForestSum also works with planar trees:

p1 = PlanarTree([])
p2 = PlanarTree([[]])
s = ForestSum([(1, p1), (-2, p1*p2)])
kr.display(s)

__add__(other: int | float | Tree | CommutativeForest | ForestSum) → ForestSum[source]

Adds a ForestSum to a scalar, Tree, Forest or ForestSum.

Parameters:: other – A scalar, Tree, Forest or ForestSum
Return type:: ForestSum

Example usage:

s = ForestSum([(1, Tree([])), (-2, Tree([[],[]]))])
kr.display(2 + Tree([[]]) + s)

__eq__(other: ForestSum) → bool[source]

Compares the forest sum with another forest sum and returns true if they represent the same forest sum, regardless of possible reorderings of trees.

Parameters:: other – ForestSum
Return type:: bool

Example usage:

t1 = Tree([])
t2 = Tree([[]])
t3 = Tree([[[]],[]])
t4 = Tree([[],[[]]])
print(t1 * t2 + t3 == t3 + t2 * t1)
print(t1 * t2 + t3 == t1 * t2 + t4)

True
True

__matmul__(other: int | float | Tree | CommutativeForest | ForestSum) → TensorProductSum[source]

Returns the tensor product of a ForestSum and a scalar, Tree, Forest or ForestSum.

Parameters:: other (int | float | Tree | Forest | ForestSum) – Other
Returns:: Tensor product
Return type:: TensorProductSum

Example usage:

tp = Tree([]) @ (Tree([[]]) + Tree([]) * Tree([[],[]]))
kr.display(tp)

__mul__(other: int | float | Tree | CommutativeForest | ForestSum) → ForestSum[source]

Multiplies a ForestSum by a scalar, Tree, Forest or ForestSum, returning a ForestSum.

Parameters:: other – A scalar, Tree, Forest or ForestSum
Return type:: ForestSum

Example usage:

s = ForestSum([(1, Tree([])), (-2, Tree([[],[]]))])
kr.display(2 * Tree([[]]) * s)

__pow__(n: int) → ForestSum[source]

Returns the \(n^{th}\) power of a forest sum for a positive integer \(n\).

Parameters:: n – Exponent, a positive integer
Return type:: ForestSum

Example usage:

t = ( Tree([]) * Tree([[]]) + Tree([[],[]]) ) ** 3
kr.display(t)

colors() → int[source]

Returns the number of colors/labels in the forest sum. Since the labels are indexed starting from 0, this is equivalent to one more than the maximum label.

Returns:: Number of colors
Return type:: int

Example usage:

print((Tree([[9],0]) * Tree([3]) + Tree([2])).colors())

factorial() → int[source]

Apply the tree factorial to the forest sum as a multiplicative linear map. For a forest sum \(\sum_{i=1}^m c_i \prod_{j=1}^{k_i} t_{ij}\), returns \(\sum_{i=1}^m c_i \prod_{j=1}^{k_i} t_{ij}!\).

Returns:: \(\sum_{i=1}^m c_i \prod_{j=1}^{k_i} t_{ij}!\)
Return type:: int

Example usage:

s = Tree([[],[[]]]) * Tree([]) + Tree([[]])
print(s.factorial())

nodes() → int[source]

For a forest sum \(\sum_{i=1}^m c_i \prod_{j=1}^{k_i} t_{ij}\), returns the total number of nodes in the forest sum, \(\sum_{i=1}^m \sum_{j=1}^{k_i} |t_{ij}|\).

Returns:: Number of nodes
Return type:: int

Example usage:

f = Tree([]) * Tree([[]]) + 2 * Tree([[],[]])
print(f.nodes())

num_forests() → int[source]

For a forest sum \(\sum_{i=1}^m c_i \prod_{j=1}^{k_i} t_{ij}\), returns the total number of forests in the forest sum, \(m\).

Returns:: Number of forests
Return type:: int

Example usage:

f = Tree([]) * Tree([[]]) + 2 * Tree([[],[]])
print(f.num_forests())

num_trees() → int[source]

For a forest sum \(\sum_{i=1}^m c_i \prod_{j=1}^{k_i} t_{ij}\), returns the total number of trees in the forest sum, \(\sum_{i=1}^m k_i\).

Returns:: Number of trees
Return type:: int

Example usage:

f = Tree([]) * Tree([[]]) + 2 * Tree([[],[]])
print(f.num_trees())

sign() → ForestSum[source]

Returns the forest sum where every forest is replaced by its signed value, \((-1)^{|f|} f\).

Returns:: Signed forest sum
Return type:: ForestSum

Example usage:

s = Tree([[[]],[]]) * Tree([[]]) + 2 * Tree([])
kr.display(s.sign())

simplify() → ForestSum[source]

Simplify the forest sum by removing redundant empty trees and cancelling terms where applicable.

Returns:: Reduced forest sum
Return type:: ForestSum

Example usage:

s1 = Tree([[],[[]]]) * Tree(None) + Tree([]) + Tree([[]]) - Tree([[]])
s2 = s1.simplify() # Tree([[],[[]]]) + Tree([])

singleton_reduced() → ForestSum[source]

Removes redundant occurrences of the single-node tree in each forest of the forest sum. If the forest contains a tree with more than one node, removes all occurences of the single-node tree. Otherwise, replaces it with the single-node tree.

Returns:: Singleton-reduced forest sum
Return type:: ForestSum

Example usage:

s1 = Tree([]) * Tree([[],[]]) + Tree([]) * Tree([]) * Tree([])
kr.display(s1, '→', s1.singleton_reduced())