Ticket #12961: trac_12961.patch

File trac_12961.patch, 6.5 KB (added by ncohen, 8 years ago)
  • sage/combinat/posets/posets.py

    # HG changeset patch
    # User Nathann Cohen <nathann.cohen@gmail.com>
    # Date 1337265592 -7200
    # Node ID 110a0124a616e025b926f2bb9d18cc8cd4127ad7
    # Parent  4196c0242945b3e49ed356b1ad5c4749bffa24eb
    #12961: Documentation of the facade argument in Poset constructor
    
    diff --git a/sage/combinat/posets/posets.py b/sage/combinat/posets/posets.py
    a b  
    11# -*- coding: utf-8 -*-
    22r"""
    33Posets
     4
     5This module implements finite partialy ordered sets. The main
     6constructor is :meth:`Poset`.
    47"""
    58#*****************************************************************************
    69#       Copyright (C) 2008 Peter Jipsen <jipsen@chapman.edu>,
    from sage.combinat.posets.elements impor 
    3841
    3942def Poset(data=None, element_labels=None, cover_relations=False, linear_extension=False, category = None, facade = None, key = None):
    4043    r"""
    41     Construct a poset from various forms of input data.
     44    Construct a finite poset from various forms of input data.
    4245
    4346    INPUT:
    4447
    45     1. A two-element list or tuple (E, R), where E is a collection of
    46        elements of the poset and R is the set of relations.  Elements
    47        of R are two-element lists/tuples/iterables.  If
    48        cover_relations=True, then R is assumed to be the cover
    49        relations of the poset. If E is empty, then E is taken to be
    50        the set of elements appearing in the relations R.
    51 
    52     2. A two-element list or tuple (E, f), where E is the set of
    53        elements of the poset and f is a function such that f(x,y) is
    54        True if x <= y and False otherwise for all pairs of elements in
    55        E. If cover_relations=True, then f(x,y) should be True if and
    56        only if x is covered by y, and False otherwise.
    57 
    58     3. A dictionary, list or tuple of upper covers: data[x] is an
    59        list of the elements that cover the element x in the poset.
    60 
    61        .. note::
    62 
    63           If data is a list or tuple of length 2, then it is handled
    64           by the above cases.
    65 
    66     4. An acyclic, loop-free and multi-edge free DiGraph. If
    67        cover_relations is True, then the edges of the digraph
    68        correspond to cover relations in the poset. If cover_relations
    69        is False, then the cover relations are computed.
    70 
    71     5. A previously constructed poset (the poset itself is returned).
    72 
    73 
    74     - ``element_labels`` -- (default: None) an optional list or
     48    - ``data`` -- different input are accepted by this constructor:
     49
     50        1. A two-element list or tuple `(E, R)`, where `E` is a
     51           collection of elements of the poset and `R` is a collection
     52           of relations `x<=y`, each represented as a two-element
     53           lists/tuples/iterables such as [x,y]. The poset is then the
     54           transitive closure of the provided relations. If
     55           ``cover_relations=True``, then `R` is assumed to contain
     56           exactly the cover relations of the poset. If `E` is empty,
     57           then `E` is taken to be the set of elements appearing in
     58           the relations `R`.
     59
     60        2. A two-element list or tuple `(E, f)`, where `E` is the set
     61           of elements of the poset and `f` is a function such that,
     62           for any pair `x,y` of elements of `E`, `f(x,y)` returns
     63           whether `x <= y`. If ``cover_relations=True``, then
     64           `f(x,y)` should return whether `x` is covered by `y`.
     65
     66        3. A dictionary, list or tuple of upper covers: ``data[x]`` is
     67           a list of the elements that cover the element `x` in the
     68           poset.
     69
     70           .. WARNING::
     71
     72              If data is a list or tuple of length `2`, then it is
     73              handled by the above case..
     74
     75        4. An acyclic, loop-free and multi-edge free ``DiGraph``. If
     76           ``cover_relations`` is ``True``, then the edges of the
     77           digraph are assumed to correspond to the cover relations of
     78           the poset. Otherwise, the cover relations are computed.
     79
     80        5. A previously constructed poset (the poset itself is returned).
     81
     82    - ``element_labels`` -- (default: None); an optional list or
    7583      dictionary of objects that label the poset elements.
    7684
    7785    - ``cover_relations`` -- a boolean (default: False); whether the
    def Poset(data=None, element_labels=None 
    8391      use the provided list of elements as default linear extension
    8492      for the poset; otherwise a linear extension is computed.
    8593
     94    - ``facade`` -- a boolean (default: False); whether the Poset's
     95      elements should be wrapped to make them aware of the Poset they
     96      belong to. See below for details.
     97
    8698    OUTPUT:
    8799
    88         FinitePoset -- an instance of the FinitePoset class.
     100        ``FinitePoset`` -- an instance of the ``FinitePoset`` class.
    89101
    90102    If ``category`` is specified, then the poset is created in this
    91103    category instead of :class:`FinitePosets`.
    def Poset(data=None, element_labels=None 
    223235        sage: c < a
    224236        True
    225237
    226     As an experimental feature, one can construct instead facade posets::
     238    However, this may have surprising effects::
     239
     240        sage: my_elements = ['a','b','c','d']
     241        sage: any(x in my_elements for x in P)
     242        False
     243
     244    and can be anoying when one wants to manipulate the elements of
     245    the poset::
     246
     247        sage: a + b
     248        Traceback (most recent call last):
     249        ...
     250        TypeError: unsupported operand type(s) for +: 'FinitePoset_with_category.element_class' and 'FinitePoset_with_category.element_class'
     251        sage: a.element + b.element
     252        'ac'
     253
     254    Alternatively, one can construct instead facade posets::
    227255
    228256        sage: P = Poset(DiGraph({'d':['c','b'],'c':['a'],'b':['a']}),
    229257        ...             facade = True)
    def Poset(data=None, element_labels=None 
    321349        sage: P = Poset([[1,2],[3],[3]])
    322350        sage: type(hash(P))
    323351        <type 'int'>
     352
     353    Bad input::
     354
     355        sage: Poset([1,2,3], lambda x,y : x<y)
     356        Traceback (most recent call last):
     357        ...
     358        ValueError: elements_label should be a dict or a list if different from None. (Did you intend data to be equal to a pair ?)
    324359    """
     360    # Avoiding some errors from the user when data should be a pair
     361    if (element_labels is not None and
     362        not isinstance(element_labels, dict) and
     363        not isinstance(element_labels, list)):
     364        raise ValueError("elements_label should be a dict or a list if "+
     365                         "different from None. (Did you intend data to be "+
     366                         "equal to a pair ?)")
     367
    325368    #Convert data to a DiGraph
    326369    elements = None
    327370    D = {}