# HG changeset patch
# User Travis Scrimshaw <tscrim@ucdavis.edur>
# Date 1370108567 25200
# Node ID 4170de4ee06d49d4c58172dd2c491932678444a2
# Parent a8eaf420567d0d93d30190ca99c82e3cc2bd9921
#10193: review patch.
diff git a/doc/en/reference/categories/index.rst b/doc/en/reference/categories/index.rst
a

b

Examples of parents using categories 
163  163  sage/categories/examples/semigroups_cython 
164  164  sage/categories/examples/sets_cat 
165  165  sage/categories/examples/with_realizations 
 166  sage/categories/examples/sets_with_grading 
166  167  
167  168  Miscellaneous 
168  169  ============= 
diff git a/sage/categories/examples/sets_with_grading.py b/sage/categories/examples/sets_with_grading.py
a

b


1  1  r""" 
2   An example of graded set: nonnegative integers graded by themselves. 
 2  Example of a set with grading 
3  3  """ 
4  4  
5  5  from sage.structure.parent import Parent 
diff git a/sage/categories/sets_with_grading.py b/sage/categories/sets_with_grading.py
a

b

class SetsWithGrading(Category): 
19  19  r""" 
20  20  The category of sets with a grading. 
21  21  
22   An *set with a grading* is a set `S` equipped with a 
23   grading by some other set `I` (by default the set `\NN` of the non 
24   negative integers): 
 22  A *set with a grading* is a set `S` equipped with a 
 23  grading by some other set `I` (by default the set `\NN` of the 
 24  nonnegative integers): 
25  25  
26   .. math:: 
 26  .. MATH:: 
27  27  
28  28  S = \biguplus_{i\in I} S_i 
29  29  
… 
… 
class SetsWithGrading(Category): 
31  31  sets. The *grading* function maps each element `s` of 
32  32  `S` to its *grade* `i`, so that `s\in S_i`. 
33  33  
34   From implementation point of vue, if the graded set is enumerated then each 
35   graded component should be enumerated (there is a check in the method 
 34  From implementation point of view, if the graded set is enumerated then 
 35  each graded component should be enumerated (there is a check in the method 
36  36  :meth:`~SetsWithGrading.ParentMethods._test_graded_components`). The 
37  37  contrary needs not be true. 
38  38  
 39  To implement this category, a parent must either implement 
 40  :meth:`~SetsWithGrading.ParentMethods.graded_component()` or 
 41  :meth:`~SetsWithGrading.ParentMethods.subset()`. If only 
 42  :meth:`~SetsWithGrading.ParentMethods.subset()` is implemented, the first 
 43  argument must be the grading for compatibility with 
 44  :meth:`~SetsWithGrading.ParentMethods.graded_component()`. Additionally 
 45  either the parent must implement 
 46  :meth:`~SetsWithGrading.ParentMethods.grading()` or its elements must 
 47  implement a method ``grade()``. See the example 
 48  :class:`sage.categories.examples.sets_with_grading.NonNegativeIntegers`. 
 49  
 50  Finally, if the graded set is enumerated (see 
 51  :class:`~sage.categories.enumerated_sets.EnumeratedSets`) then each graded 
 52  component should be enumerated. The contrary needs not be true. 
 53  
39  54  EXAMPLES: 
40  55  
41   A typical example of set with grading is the set of nonnegative integers 
42   graded by themselves:: 
 56  A typical example of a set with a grading is the set of nonnegative 
 57  integers graded by themselves:: 
43  58  
44  59  sage: N = SetsWithGrading().example(); N 
45  60  Non negative integers 
46  61  sage: N.category() 
47  62  Category of facade sets with grading 
48   
49   It is graded by `\NN`:: 
50   
51  63  sage: N.grading_set() 
52  64  Non negative integers 
53  65  
… 
… 
class SetsWithGrading(Category): 
78  90  
79  91  .. TODO:: 
80  92  
81    This should be moved to Sets().WithGrading() 
 93   This should be moved to ``Sets().WithGrading()``. 
82  94   Should the grading set be a parameter for this category? 
83  95   Does the enumeration need to be compatible with the grading? Be 
84  96  careful that the fact that graded components are allowed to be finite 
… 
… 
class SetsWithGrading(Category): 
106  118  r""" 
107  119  Test that some graded components of ``self`` are parent with 
108  120  initialized category and that the parent has a properly implemented 
109   ``grading`` method. 
 121  ``grading()`` method. 
110  122  
111  123  EXAMPLES:: 
112  124  
… 
… 
class SetsWithGrading(Category): 
124  136  
125  137  def grading_set(self): 
126  138  """ 
127   Returns the set ``self`` is graded by. By default, this is 
128   the set of non negative integers. 
 139  Return the set ``self`` is graded by. By default, this is 
 140  the set of nonnegative integers. 
129  141  
130  142  EXAMPLES:: 
131  143  
… 
… 
class SetsWithGrading(Category): 
141  153  @abstract_method(optional=True) 
142  154  def subset(self, *args, **options): 
143  155  """ 
144   Returns the subset of ``self`` described by the given parameters 
 156  Return the subset of ``self`` described by the given parameters. 
145  157  
146   See also: :meth:`graded_component` 
 158  .. SEEALSO:: 
 159  
 160  :meth:`graded_component()` 
147  161  
148  162  EXAMPLES:: 
149  163  
… 
… 
class SetsWithGrading(Category): 
157  171  """ 
158  172  Return the graded component of ``self`` with grade ``grade``. 
159  173  
160   The default implementation just calls the method :meth:`subset` with 
161   the argument ``grade``. 
 174  The default implementation just calls the method :meth:`subset()` 
 175  with the first argument ``grade``. 
162  176  
163  177  EXAMPLES:: 
164  178  
… 
… 
class SetsWithGrading(Category): 
171  185  
172  186  def grading(self, elt): 
173  187  """ 
174   Return the grading of the element ``elt`` of self.` 
 188  Return the grading of the element ``elt`` of ``self``. 
175  189  
176  190  This default implementation calls ``elt.grade()``. 
177  191  
… 
… 
class SetsWithGrading(Category): 
188  202  """ 
189  203  Default implementation for generating series. 
190  204  
191   OUTPUT: a series, indexed by the grading set 
 205  OUTPUT: 
 206  
 207  A series, indexed by the grading set. 
192  208  
193  209  EXAMPLES:: 
194  210  