Implementation of decorator for combinatorial maps

[stumpc5]

This patch implements decorators for combinatorial maps. The aim is to be able to ask for all combinatorial maps for a given combinatorial class.

Depends on #13074

CC: @sagetrac-chrisjamesberg @saliola @zabrocki @hivert

Component: combinatorics

Keywords: combinatorial statistic

Author: Christian Stump

Reviewer: Mike Zabrocki

Merged: sage-5.7.beta1

Issue created by migration from https://trac.sagemath.org/ticket/11641

[stumpc5]

Description changed:

--- 
+++ 
@@ -1 +1,23 @@
-tba
+An example:
+
+```
+sage: I = [ p,p.major_index()+2*p.number_of_inversions()-34*p.number_of_descents()) for p in Permutations(3) ]
+
+sage: find_combinatorial_statistic(I)
+The tested combinatorial statistics on Standard permutations with values in Integer Ring where 
+imajor_index
+longest_increasing_subsequence_length
+major_index
+number_of_descents
+number_of_fixed_points
+number_of_idescents
+number_of_inversions
+number_of_peaks
+number_of_saliances
+
+((0, 0, 1, -34, 0, 0, 2, 0, 0), Free module of degree 9 and rank 3 over Integer Ring
+Echelon basis matrix:
+[ 3  0  0  0  2 -4  5  3 -6]
+[ 0  1  3  0 -1 -3 -1 -3  0]
+[ 0  0  0  1  0 -1  0  0  0])
+```

[stumpc5]

Description changed:

--- 
+++ 
@@ -1,7 +1,7 @@
 An example:
 
 ```
-sage: I = [ p,p.major_index()+2*p.number_of_inversions()-34*p.number_of_descents()) for p in Permutations(3) ]
+sage: I = [ (p,p.major_index()+2*p.number_of_inversions()-34*p.number_of_descents()) for p in Permutations(3) ]
 
 sage: find_combinatorial_statistic(I)
 The tested combinatorial statistics on Standard permutations with values in Integer Ring where 

[stumpc5]

Description changed:

--- 
+++ 
@@ -1,23 +1 @@
-An example:
-
-```
-sage: I = [ (p,p.major_index()+2*p.number_of_inversions()-34*p.number_of_descents()) for p in Permutations(3) ]
-
-sage: find_combinatorial_statistic(I)
-The tested combinatorial statistics on Standard permutations with values in Integer Ring where 
-imajor_index
-longest_increasing_subsequence_length
-major_index
-number_of_descents
-number_of_fixed_points
-number_of_idescents
-number_of_inversions
-number_of_peaks
-number_of_saliances
-
-((0, 0, 1, -34, 0, 0, 2, 0, 0), Free module of degree 9 and rank 3 over Integer Ring
-Echelon basis matrix:
-[ 3  0  0  0  2 -4  5  3 -6]
-[ 0  1  3  0 -1 -3 -1 -3  0]
-[ 0  0  0  1  0 -1  0  0  0])
-```
+This patch implements decorators for combinatorial statistics and maps. The aim is to be able to ask for all combinatorial statistics/maps for a given combinatorial class.

[stumpc5]

Changed author from Chris Berg, Franco Saliola, Christian Stump to Christian Stump

[stumpc5]

Changed work issues from make it nice and smooth to none

[sagetrac-sluther]

comment:4

1. Please don't use assert, raise ValueError instead.

2. When returning self._black_list in black_list(), make a copy. i.e. return self._back_list[:]. Otherwise modifications to the returned list will also modify self._black_list.

3. return self._f(self._inst,*args,**kwds) has missing white space between the arguments

4. In combinatorial_maps_in_class(), you search a unsorted list on every iteration. Either make 'result' a set and possibly convert it into a list on return
   or if the order matters, use a set next to the list.

5. In the first doc string "defined a map between two combinatorial objects." defined should be defines.

These two classes share a lot of code. Have you though about a way to avoid this duplication?

[saliola]

comment:5

Thanks for taking a look at the patch and the helpful suggestions. One question:

Replying to @sagetrac-sluther:

1. Please don't use assert, raise ValueError instead.

Why shouldn't one use assert?

[nbruin]

comment:6

Replying to @saliola:

Thanks for taking a look at the patch and the helpful suggestions. One question:

Replying to @sagetrac-sluther:

1. Please don't use assert, raise ValueError instead.

Why shouldn't one use assert?

• If input parameters are of the wrong type, it's usual to raise a TypeError. It's good to raise errors that obey conventions, because that helps writing appropriate try ... except clauses when needed.
• assert statements can be optimized away if python -O is selected, so they are only suitable to assert conditions that are supposed to hold anyway (and raise an early error if they don't, to help debugging)