passagemath-combinat 10.6.42__cp314-cp314-musllinux_1_2_x86_64.whl

sage/combinat/crystals/all.py

@@ -0,0 +1,22 @@
+# sage_setup: distribution = sagemath-combinat
+r"""
+Crystals
+
+- :ref:`sage.combinat.crystals.crystals`
+- The `Lie Methods and Related Combinatorics <../../../../../thematic_tutorials/lie.html>`_ thematic tutorial
+- :ref:`sage.combinat.crystals.catalog`
+
+See also the categories for crystals: :class:`Crystals`,
+:class:`HighestWeightCrystals`, :class:`FiniteCrystals`,
+:class:`ClassicalCrystals`, :class:`RegularCrystals`,
+:class:`~sage.categories.regular_supercrystals.RegularSuperCrystals`
+"""
+# install the docstring of this module to the containing package
+from sage.misc.namespace_package import install_doc
+install_doc(__package__, __doc__)
+
+from sage.misc.lazy_import import lazy_import
+
+lazy_import('sage.combinat.crystals', 'catalog', 'crystals')
+del lazy_import
+del install_doc

sage/combinat/crystals/bkk_crystals.py

@@ -0,0 +1,141 @@
+# sage_setup: distribution = sagemath-combinat
+# sage.doctest: needs sage.combinat sage.graphs sage.modules
+"""
+Benkart-Kang-Kashiwara crystals for the general-linear Lie superalgebra
+"""
+
+# ****************************************************************************
+#       Copyright (C) 2017 Franco Saliola <saliola@gmail.com>
+#                     2017 Travis Scrimshaw <tcscrims at gmail.com>
+#                     2017 Anne Schilling <anne@math.ucdavis.edu>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 2 of the License, or
+# (at your option) any later version.
+#                  https://www.gnu.org/licenses/
+# ****************************************************************************
+
+from sage.structure.parent import Parent
+from sage.categories.regular_supercrystals import RegularSuperCrystals
+from sage.combinat.partition import _Partitions
+from sage.combinat.root_system.cartan_type import CartanType
+from sage.combinat.crystals.letters import CrystalOfBKKLetters
+from sage.combinat.crystals.tensor_product import CrystalOfWords
+from sage.combinat.crystals.tensor_product_element import CrystalOfBKKTableauxElement
+
+
+class CrystalOfBKKTableaux(CrystalOfWords):
+    r"""
+    Crystal of tableaux for type `A(m|n)`.
+
+    This is an implementation of the tableaux model of the
+    Benkart-Kang-Kashiwara crystal [BKK2000]_ for the Lie
+    superalgebra `\mathfrak{gl}(m+1,n+1)`.
+
+    INPUT:
+
+    - ``ct`` -- a super Lie Cartan type of type `A(m|n)`
+    - ``shape`` -- shape specifying the highest weight; this should be
+      a partition contained in a hook of height `n+1` and width `m+1`
+
+    EXAMPLES::
+
+        sage: T = crystals.Tableaux(['A', [1,1]], shape = [2,1])
+        sage: T.cardinality()
+        20
+    """
+    @staticmethod
+    def __classcall_private__(cls, ct, shape):
+        """
+        Normalize input to ensure a unique representation.
+
+        TESTS::
+
+            sage: crystals.Tableaux(['A', [1, 2]], shape=[2,1])
+            Crystal of BKK tableaux of shape [2, 1] of gl(2|3)
+            sage: crystals.Tableaux(['A', [1, 1]], shape=[3,3,3])
+            Traceback (most recent call last):
+            ...
+            ValueError: invalid hook shape
+        """
+        ct = CartanType(ct)
+        shape = _Partitions(shape)
+        if len(shape) > ct.m + 1 and shape[ct.m + 1] > ct.n + 1:
+            raise ValueError("invalid hook shape")
+        return super().__classcall__(cls, ct, shape)
+
+    def __init__(self, ct, shape):
+        r"""
+        Initialize ``self``.
+
+        TESTS::
+
+            sage: T = crystals.Tableaux(['A', [1,1]], shape = [2,1]); T
+            Crystal of BKK tableaux of shape [2, 1] of gl(2|2)
+            sage: TestSuite(T).run()
+        """
+        self._shape = shape
+        self._cartan_type = ct
+        m = ct.m + 1
+        C = CrystalOfBKKLetters(ct)
+        tr = shape.conjugate()
+        mg = []
+        for i, col_len in enumerate(tr, start=1):
+            mg.extend(C(i) for j in range(col_len - m))
+            mg.extend(C(-j - 1) for j in range(max(0, m - col_len), m))
+        mg = list(reversed(mg))
+        Parent.__init__(self, category=RegularSuperCrystals())
+        self.module_generators = (self.element_class(self, mg),)
+
+    def _repr_(self) -> str:
+        """
+        Return a string representation of ``self``.
+
+        TESTS::
+
+            sage: crystals.Tableaux(['A', [1, 2]], shape=[2,1])
+            Crystal of BKK tableaux of shape [2, 1] of gl(2|3)
+        """
+        m = self._cartan_type.m + 1
+        n = self._cartan_type.n + 1
+        return "Crystal of BKK tableaux of shape {} of gl({}|{})".format(self.shape(), m, n)
+
+    def shape(self):
+        r"""
+        Return the shape of ``self``.
+
+        EXAMPLES::
+
+            sage: T = crystals.Tableaux(['A', [1, 2]], shape=[2,1])
+            sage: T.shape()
+            [2, 1]
+        """
+        return self._shape
+
+    def genuine_highest_weight_vectors(self, index_set=None):
+        """
+        Return a tuple of genuine highest weight elements.
+
+        A *fake highest weight vector* is one which is annihilated by
+        `e_i` for all `i` in the index set, but whose weight is not
+        bigger in dominance order than all other elements in the
+        crystal. A *genuine highest weight vector* is a highest
+        weight element that is not fake.
+
+        EXAMPLES::
+
+            sage: B = crystals.Tableaux(['A', [1,1]], shape=[3,2,1])
+            sage: B.genuine_highest_weight_vectors()
+            ([[-2, -2, -2], [-1, -1], [1]],)
+            sage: B.highest_weight_vectors()
+            ([[-2, -2, -2], [-1, -1], [1]],
+             [[-2, -2, -2], [-1, 2], [1]],
+             [[-2, -2, 2], [-1, -1], [1]])
+        """
+        if index_set is None or index_set == self.index_set():
+            return self.module_generators
+        return super().genuine_highest_weight_vectors(index_set)
+
+    class Element(CrystalOfBKKTableauxElement):
+        pass

sage/combinat/crystals/catalog.py

@@ -0,0 +1,115 @@
+# sage_setup: distribution = sagemath-combinat
+r"""
+Catalog of crystals
+
+Let `I` be an index set and let `(A,\Pi,\Pi^\vee,P,P^\vee)` be a Cartan datum
+associated with generalized Cartan matrix `A = (a_{ij})_{i,j\in I}`.  An
+*abstract crystal* associated to this Cartan datum is a set `B` together with
+maps
+
+.. MATH::
+
+    e_i,f_i \colon B \to B \cup \{0\}, \qquad
+    \varepsilon_i,\varphi_i\colon B \to \ZZ \cup \{-\infty\}, \qquad
+    \mathrm{wt}\colon B \to P,
+
+subject to the following conditions:
+
+    1. `\varphi_i(b) = \varepsilon_i(b) + \langle h_i, \mathrm{wt}(b) \rangle` for all `b \in B` and `i \in I`;
+    2. `\mathrm{wt}(e_ib) = \mathrm{wt}(b) + \alpha_i` if `e_ib \in B`;
+    3. `\mathrm{wt}(f_ib) = \mathrm{wt}(b) - \alpha_i` if `f_ib \in B`;
+    4. `\varepsilon_i(e_ib) = \varepsilon_i(b) - 1`, `\varphi_i(e_ib) = \varphi_i(b) + 1` if `e_ib \in B`;
+    5. `\varepsilon_i(f_ib) = \varepsilon_i(b) + 1`, `\varphi_i(f_ib) = \varphi_i(b) - 1` if `f_ib \in B`;
+    6. `f_ib = b'` if and only if `b = e_ib'` for `b,b' \in B` and `i\in I`;
+    7. if `\varphi_i(b) = -\infty` for `b\in B`, then `e_ib = f_ib = 0`.
+
+.. SEEALSO::
+
+    - :mod:`sage.categories.crystals`
+    - :mod:`sage.combinat.crystals.crystals`
+
+Catalog
+-------
+
+This is a catalog of crystals that are currently implemented in Sage:
+
+* :class:`~sage.combinat.crystals.affine.AffineCrystalFromClassical`
+* :class:`~sage.combinat.crystals.affine.AffineCrystalFromClassicalAndPromotion`
+* :class:`AffineFactorization <sage.combinat.crystals.affine_factorization.AffineFactorizationCrystal>`
+* :class:`AffinizationOf <sage.combinat.crystals.affinization.AffinizationOfCrystal>`
+* :class:`AlcovePaths <sage.combinat.crystals.alcove_path.CrystalOfAlcovePaths>`
+* :class:`FastRankTwo <sage.combinat.crystals.fast_crystals.FastCrystal>`
+* :class:`FullyCommutativeStableGrothendieck
+  <sage.combinat.crystals.fully_commutative_stable_grothendieck.FullyCommutativeStableGrothendieckCrystal>`
+* :class:`GeneralizedYoungWalls
+  <sage.combinat.crystals.generalized_young_walls.CrystalOfGeneralizedYoungWalls>`
+* :func:`HighestWeight <sage.combinat.crystals.highest_weight_crystals.HighestWeightCrystal>`
+* :class:`Induced <sage.combinat.crystals.induced_structure.InducedCrystal>`
+* :class:`KacModule <sage.combinat.crystals.kac_modules.CrystalOfKacModule>`
+* :func:`KirillovReshetikhin <sage.combinat.crystals.kirillov_reshetikhin.KirillovReshetikhinCrystal>`
+* :class:`KleshchevPartitions <sage.combinat.partition_kleshchev.KleshchevPartitions_all>`
+* :class:`KyotoPathModel <sage.combinat.crystals.kyoto_path_model.KyotoPathModel>`
+* :class:`Letters <sage.combinat.crystals.letters.CrystalOfLetters>`
+* :class:`LSPaths <sage.combinat.crystals.littelmann_path.CrystalOfLSPaths>`
+* :class:`Minimaj <sage.combinat.multiset_partition_into_sets_ordered.MinimajCrystal>`
+* :class:`NakajimaMonomials <sage.combinat.crystals.monomial_crystals.CrystalOfNakajimaMonomials>`
+* :class:`OddNegativeRoots <sage.combinat.crystals.kac_modules.CrystalOfOddNegativeRoots>`
+* :class:`ProjectedLevelZeroLSPaths
+  <sage.combinat.crystals.littelmann_path.CrystalOfProjectedLevelZeroLSPaths>`
+* :class:`RiggedConfigurations
+  <sage.combinat.rigged_configurations.rc_crystal.CrystalOfRiggedConfigurations>`
+* :class:`ShiftedPrimedTableaux
+  <sage.combinat.shifted_primed_tableau.ShiftedPrimedTableaux_shape>`
+* :class:`Spins <sage.combinat.crystals.spins.CrystalOfSpins>`
+* :class:`SpinsPlus <sage.combinat.crystals.spins.CrystalOfSpinsPlus>`
+* :class:`SpinsMinus <sage.combinat.crystals.spins.CrystalOfSpinsMinus>`
+* :class:`Tableaux <sage.combinat.crystals.tensor_product.CrystalOfTableaux>`
+
+Subcatalogs:
+
+* :ref:`sage.combinat.crystals.catalog_infinity_crystals`
+* :ref:`sage.combinat.crystals.catalog_elementary_crystals`
+* :ref:`sage.combinat.crystals.catalog_kirillov_reshetikhin`
+
+Functorial constructions:
+
+* :class:`DirectSum <sage.combinat.crystals.direct_sum.DirectSumOfCrystals>`
+* :class:`TensorProduct <sage.combinat.crystals.tensor_product.TensorProductOfCrystals>`
+"""
+
+from .letters import CrystalOfLetters as Letters
+from .spins import CrystalOfSpins as Spins
+from .spins import CrystalOfSpinsPlus as SpinsPlus
+from .spins import CrystalOfSpinsMinus as SpinsMinus
+from .tensor_product import CrystalOfTableaux as Tableaux
+from .fast_crystals import FastCrystal as FastRankTwo
+from .affine import AffineCrystalFromClassical as AffineFromClassical
+from .affine import AffineCrystalFromClassicalAndPromotion as AffineFromClassicalAndPromotion
+from .affine_factorization import AffineFactorizationCrystal as AffineFactorization
+from .fully_commutative_stable_grothendieck import FullyCommutativeStableGrothendieckCrystal as FullyCommutativeStableGrothendieck
+from sage.combinat.crystals.affinization import AffinizationOfCrystal as AffinizationOf
+from .highest_weight_crystals import HighestWeightCrystal as HighestWeight
+from .alcove_path import CrystalOfAlcovePaths as AlcovePaths
+from .littelmann_path import CrystalOfLSPaths as LSPaths
+from .littelmann_path import CrystalOfProjectedLevelZeroLSPaths as ProjectedLevelZeroLSPaths
+from .kyoto_path_model import KyotoPathModel
+from .generalized_young_walls import CrystalOfGeneralizedYoungWalls as GeneralizedYoungWalls
+from .monomial_crystals import CrystalOfNakajimaMonomials as NakajimaMonomials
+from sage.combinat.rigged_configurations.tensor_product_kr_tableaux import TensorProductOfKirillovReshetikhinTableaux
+from sage.combinat.crystals.kirillov_reshetikhin import KirillovReshetikhinCrystal as KirillovReshetikhin
+from sage.combinat.rigged_configurations.rc_crystal import CrystalOfRiggedConfigurations as RiggedConfigurations
+from sage.combinat.shifted_primed_tableau import ShiftedPrimedTableaux_shape as ShiftedPrimedTableaux
+from sage.combinat.partition_kleshchev import KleshchevPartitions
+from sage.combinat.multiset_partition_into_sets_ordered import MinimajCrystal as Minimaj
+
+from sage.combinat.crystals.induced_structure import InducedCrystal as Induced
+
+from sage.combinat.crystals.kac_modules import CrystalOfKacModule as KacModule
+from sage.combinat.crystals.kac_modules import CrystalOfOddNegativeRoots as OddNegativeRoots
+
+from .tensor_product import TensorProductOfCrystals as TensorProduct
+from .direct_sum import DirectSumOfCrystals as DirectSum
+
+from . import catalog_kirillov_reshetikhin as kirillov_reshetikhin
+from . import catalog_infinity_crystals as infinity
+from . import catalog_elementary_crystals as elementary

sage/combinat/crystals/catalog_elementary_crystals.py

@@ -0,0 +1,18 @@
+# sage_setup: distribution = sagemath-combinat
+"""
+Catalog of elementary crystals
+
+See :mod:`~sage.combinat.crystals.elementary_crystals`.
+
+* :class:`Component <sage.combinat.crystals.elementary_crystals.ComponentCrystal>`
+* :class:`Elementary <sage.combinat.crystals.elementary_crystals.ElementaryCrystal>`
+  or :class:`B <sage.combinat.crystals.elementary_crystals.ElementaryCrystal>`
+* :class:`R <sage.combinat.crystals.elementary_crystals.RCrystal>`
+* :class:`T <sage.combinat.crystals.elementary_crystals.TCrystal>`
+"""
+
+from .elementary_crystals import TCrystal as T
+from .elementary_crystals import RCrystal as R
+from .elementary_crystals import ElementaryCrystal as Elementary
+from .elementary_crystals import ElementaryCrystal as B
+from .elementary_crystals import ComponentCrystal as Component

sage/combinat/crystals/catalog_infinity_crystals.py

@@ -0,0 +1,33 @@
+# sage_setup: distribution = sagemath-combinat
+r"""
+Catalog of crystal models For `B(\infty)`
+
+We currently have the following models:
+
+* :class:`AlcovePaths
+  <sage.combinat.crystals.alcove_path.InfinityCrystalOfAlcovePaths>`
+* :class:`GeneralizedYoungWalls
+  <sage.combinat.crystals.generalized_young_walls.InfinityCrystalOfGeneralizedYoungWalls>`
+* :class:`LSPaths <sage.combinat.crystals.littelmann_path.InfinityCrystalOfLSPaths>`
+* :class:`Multisegments <sage.combinat.crystals.multisegments.InfinityCrystalOfMultisegments>`
+* :class:`MVPolytopes <sage.combinat.crystals.mv_polytopes.MVPolytopes>`
+* :class:`NakajimaMonomials <sage.combinat.crystals.monomial_crystals.InfinityCrystalOfNakajimaMonomials>`
+* :class:`PBW <sage.combinat.crystals.pbw_crystal.PBWCrystal>`
+* :class:`PolyhedralRealization <sage.combinat.crystals.polyhedral_realization.InfinityCrystalAsPolyhedralRealization>`
+* :class:`RiggedConfigurations
+  <sage.combinat.rigged_configurations.rc_infinity.InfinityCrystalOfRiggedConfigurations>`
+* :class:`Star <sage.combinat.crystals.star_crystal.StarCrystal>`
+* :class:`Tableaux <sage.combinat.crystals.infinity_crystals.InfinityCrystalOfTableaux>`
+"""
+
+from .generalized_young_walls import InfinityCrystalOfGeneralizedYoungWalls as GeneralizedYoungWalls
+from .multisegments import InfinityCrystalOfMultisegments as Multisegments
+from .monomial_crystals import InfinityCrystalOfNakajimaMonomials as NakajimaMonomials
+from sage.combinat.rigged_configurations.rc_infinity import InfinityCrystalOfRiggedConfigurations as RiggedConfigurations
+from .infinity_crystals import InfinityCrystalOfTableaux as Tableaux
+from sage.combinat.crystals.polyhedral_realization import InfinityCrystalAsPolyhedralRealization as PolyhedralRealization
+from sage.combinat.crystals.pbw_crystal import PBWCrystal as PBW
+from sage.combinat.crystals.mv_polytopes import MVPolytopes
+from sage.combinat.crystals.star_crystal import StarCrystal as Star
+from sage.combinat.crystals.littelmann_path import InfinityCrystalOfLSPaths as LSPaths
+from sage.combinat.crystals.alcove_path import InfinityCrystalOfAlcovePaths as AlcovePaths

sage/combinat/crystals/catalog_kirillov_reshetikhin.py

@@ -0,0 +1,18 @@
+# sage_setup: distribution = sagemath-combinat
+"""
+Catalog of crystal models for Kirillov-Reshetikhin crystals
+
+We currently have the following models:
+
+* :func:`KashiwaraNakashimaTableaux
+  <sage.combinat.crystals.kirillov_reshetikhin.KashiwaraNakashimaTableaux>`
+* :class:`~sage.combinat.rigged_configurations.kr_tableaux.KirillovReshetikhinTableaux`
+* :func:`LSPaths <sage.combinat.crystals.kirillov_reshetikhin.KirillovReshetikhinCrystalFromLSPaths>`
+* :func:`RiggedConfigurations
+  <sage.combinat.rigged_configurations.rigged_configurations.KirillovReshetikhinCrystal>`
+"""
+
+from .kirillov_reshetikhin import KashiwaraNakashimaTableaux
+from .kirillov_reshetikhin import KirillovReshetikhinCrystalFromLSPaths as LSPaths
+from sage.combinat.rigged_configurations.kr_tableaux import KirillovReshetikhinTableaux
+from sage.combinat.rigged_configurations.rigged_configurations import KirillovReshetikhinCrystal as RiggedConfigurations

sage/combinat/crystals/crystals.py

@@ -0,0 +1,257 @@
+# sage_setup: distribution = sagemath-combinat
+# sage.doctest: needs sage.combinat sage.graphs sage.modules
+r"""
+An introduction to crystals
+===========================
+
+Informally, a crystal `\mathcal{B}` is an oriented graph with edges
+colored in some set `I` such that, for each `i\in I`, each node `x`
+has:
+
+- at most one `i`-successor, denoted `f_i x`;
+
+- at most one `i`-predecessor, denoted `e_i x`.
+
+By convention, one writes `f_i x=\emptyset` and `e_i x=\emptyset` when
+`x` has no successor resp. predecessor.
+
+One may think of `\mathcal{B}` as essentially a deterministic
+automaton whose dual is also deterministic; in this context, the
+`f_i`'s and `e_i`'s are respectively the transition functions of the
+automaton and of its dual, and `\emptyset` is the sink.
+
+A crystal comes further endowed with a weight function
+`\operatorname{wt} : \mathcal{B} \to L` which satisfies
+appropriate conditions.
+
+In combinatorial representation theory, crystals are used as
+combinatorial data to model representations of Lie algebra.
+
+Axiomatic definition
+--------------------
+
+Let `C` be a Cartan type (:class:`CartanType`) with index set `I`,
+and `L` be a realization of the weight lattice of the type `C`.
+Let `\alpha_i` and `\alpha^{\vee}_i` denote the simple roots and
+coroots respectively.
+
+A type `C` crystal is a non-empty set `\mathcal{B}` endowed with maps
+`\operatorname{wt} : \mathcal{B} \to L`,
+`e_i, f_i : \mathcal{B} \to \mathcal{B} \cup \{\emptyset\}`, and
+`\varepsilon_i, \varphi_i : \mathcal{B} \to \ZZ \cup \{-\infty\}`
+for `i \in I` satisfying the following properties for all `i \in I`:
+
+- for `b, b^{\prime} \in \mathcal{B}`, we have
+  `f_i b^{\prime} = b` if and only if `e_i b = b^{\prime}`;
+
+- if `e_i b \in \mathcal{B}`, then:
+
+  * `\operatorname{wt}(e_i b) = \operatorname{wt}(b) + \alpha_i`,
+  * `\varepsilon_i(e_i b) = \varepsilon_i(b) - 1`,
+  * `\varphi_i(e_i b) = \varphi_i(b) + 1`;
+
+- if `f_i b \in \mathcal{B}`, then:
+
+  * `\operatorname{wt}(f_i b) = \operatorname{wt}(b) - \alpha_i`,
+  * `\varepsilon_i(f_i b) = \varepsilon_i(b) + 1`,
+  * `\varphi_i(f_i b) = \varphi_i(b) - 1`;
+
+- `\varphi_i(b) = \varepsilon_i(b) + \langle \alpha^{\vee}_i,
+  \operatorname{wt}(b) \rangle`,
+
+- if `\varphi_i(b) = -\infty` for `b \in \mathcal{B}`,
+  then `e_i b = f_i b = \emptyset`.
+
+Some further conditions are required to guarantee that this data
+indeed models a representation of a Lie algebra. For finite simply
+laced types a complete characterization is given by Stembridge's local
+axioms [Ste2003]_.
+
+EXAMPLES:
+
+We construct the type `A_5` crystal on letters (or in representation
+theoretic terms, the highest weight crystal of type `A_5`
+corresponding to the highest weight `\Lambda_1`)::
+
+    sage: C = crystals.Letters(['A',5]); C
+    The crystal of letters for type ['A', 5]
+
+It has a single highest weight element::
+
+    sage: C.highest_weight_vectors()
+    (1,)
+
+A crystal is an enumerated set (see :class:`EnumeratedSets`); and we
+can count and list its elements in the usual way::
+
+    sage: C.cardinality()
+    6
+    sage: C.list()
+    [1, 2, 3, 4, 5, 6]
+
+as well as use it in for loops::
+
+    sage: [x for x in C]
+    [1, 2, 3, 4, 5, 6]
+
+Here are some more elaborate crystals (see their respective
+documentations)::
+
+    sage: Tens = crystals.TensorProduct(C, C)
+    sage: Spin = crystals.Spins(['B', 3])
+    sage: Tab  = crystals.Tableaux(['A', 3], shape = [2,1,1])
+    sage: Fast = crystals.FastRankTwo(['B', 2], shape = [3/2, 1/2])
+    sage: KR = crystals.KirillovReshetikhin(['A',2,1],1,1)
+
+One can get (currently) crude plotting via::
+
+    sage: Tab.plot()                                                                    # needs sage.plot
+    Graphics object consisting of 52 graphics primitives
+
+If dot2tex is installed, one can obtain nice latex pictures via::
+
+    sage: K = crystals.KirillovReshetikhin(['A',3,1], 1,1)
+    sage: view(K, pdflatex=True) # optional - dot2tex graphviz, not tested (opens external window)
+
+or with colored edges::
+
+    sage: K = crystals.KirillovReshetikhin(['A',3,1], 1,1)
+    sage: G = K.digraph()
+    sage: G.set_latex_options(color_by_label={0:"black", 1:"red", 2:"blue", 3:"green"})
+    sage: view(G, pdflatex=True) # optional - dot2tex graphviz, not tested (opens external window)
+
+For rank two crystals, there is an alternative method of getting
+metapost pictures. For more information see ``C.metapost?``.
+
+.. SEEALSO:: :ref:`The overview of crystal features in Sage<sage.combinat.crystals.all>`
+
+.. TODO::
+
+    -  Vocabulary and conventions:
+
+       -  For a classical crystal: connected / highest weight /
+          irreducible
+
+       -  ...
+
+    -  Layout instructions for plot() for rank 2 types
+
+    -  RestrictionOfCrystal
+
+
+The crystals library in Sage grew up from an initial implementation in
+MuPAD-Combinat (see <MuPAD-Combinat>/lib/COMBINAT/crystals.mu).
+"""
+
+#*****************************************************************************
+#       Copyright (C) 2007 Anne Schilling <anne at math.ucdavis.edu>
+#                          Nicolas Thiery <nthiery at users.sf.net>
+#
+#  Distributed under the terms of the GNU General Public License (GPL)
+#
+#    This code is distributed in the hope that it will be useful,
+#    but WITHOUT ANY WARRANTY; without even the implied warranty of
+#    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+#    General Public License for more details.
+#
+#  The full text of the GPL is available at:
+#
+#                  http://www.gnu.org/licenses/
+# ***************************************************************************
+# Acknowledgment: most of the design and implementation of this
+# library is heavily inspired from MuPAD-Combinat.
+# ***************************************************************************
+
+from sage.combinat.backtrack import GenericBacktracker
+
+
+class CrystalBacktracker(GenericBacktracker):
+    def __init__(self, crystal, index_set=None):
+        r"""
+        Time complexity: `O(nF)` amortized for each produced
+        element, where `n` is the size of the index set, and `F` is
+        the cost of computing `e` and `f` operators.
+
+        Memory complexity: `O(D)` where `D` is the depth of the crystal.
+
+        Principle of the algorithm:
+
+        Let `C` be a classical crystal. It's an acyclic graph where each
+        connected component has a unique element without predecessors (the
+        highest weight element for this component). Let's assume for
+        simplicity that `C` is irreducible (i.e. connected) with highest
+        weight element `u`.
+
+        One can define a natural spanning tree of `C` by taking
+        `u` as the root of the tree, and for any other element
+        `y` taking as ancestor the element `x` such that
+        there is an `i`-arrow from `x` to `y` with
+        `i` minimal. Then, a path from `u` to `y`
+        describes the lexicographically smallest sequence
+        `i_1,\dots,i_k` such that
+        `(f_{i_k} \circ f_{i_1})(u)=y`.
+
+        Morally, the iterator implemented below just does a depth first
+        search walk through this spanning tree. In practice, this can be
+        achieved recursively as follows: take an element `x`, and
+        consider in turn each successor `y = f_i(x)`, ignoring
+        those such that `y = f_j(x^{\prime})` for some `x^{\prime}` and
+        `j<i` (this can be tested by computing `e_j(y)`
+        for `j<i`).
+
+        EXAMPLES::
+
+            sage: from sage.combinat.crystals.crystals import CrystalBacktracker
+            sage: C = crystals.Tableaux(['B',3],shape=[3,2,1])
+            sage: CB = CrystalBacktracker(C)
+            sage: len(list(CB))
+            1617
+            sage: CB = CrystalBacktracker(C, [1,2])
+            sage: len(list(CB))
+            8
+        """
+        GenericBacktracker.__init__(self, None, None)
+        self._crystal = crystal
+        if index_set is None:
+            self._index_set = crystal.index_set()
+        else:
+            self._index_set = index_set
+
+    def _rec(self, x, state):
+        """
+        Return an iterator for the (immediate) children of ``x`` in the search
+        tree.
+
+        EXAMPLES::
+
+            sage: from sage.combinat.crystals.crystals import CrystalBacktracker
+            sage: C = crystals.Letters(['A', 5])
+            sage: CB = CrystalBacktracker(C)
+            sage: list(CB._rec(C(1), 'n/a'))
+            [(2, 'n/a', True)]
+        """
+        #We will signal the initial case by having a object and state
+        #of None and consider it separately.
+        if x is None and state is None:
+            for gen in self._crystal.highest_weight_vectors():
+                yield gen, "n/a", True
+            return
+
+        # Run through the children y of x
+        for i in self._index_set:
+            y = x.f(i)
+            if y is None:
+                continue
+            # Ignore those which can be reached by an arrow with smaller label
+            hasParent = False
+            for j in self._index_set:
+                if j == i:
+                    break
+                if y.e(j) is not None:
+                    hasParent = True
+                    break
+            if hasParent:
+                continue
+
+            # yield y and all elements further below
+            yield y, "n/a", True