passagemath-combinat 10.6.42__cp314-cp314t-win_amd64.whl

sage/dynamics/finite_dynamical_system.py

@@ -0,0 +1,1249 @@
+# sage_setup: distribution = sagemath-combinat
+r"""
+Discrete dynamical systems
+==========================
+
+A *discrete dynamical system* (henceforth *DDS*) is a pair
+`(X, \phi)` of a set `X` and a map `\phi : X \to X`.
+(This is one of several things known as a "discrete dynamical
+system" in mathematics.)
+
+This file implements the following classes for discrete
+dynamical systems:
+
+- :class:`DiscreteDynamicalSystem`: general discrete dynamical
+  system, as above.
+  Inherit from this class if the ground set of your DDS is
+  infinite or large enough that you want to avoid it getting
+  stored as a list.
+  See the doc of this class for further details.
+
+- :class:`FiniteDynamicalSystem`: finite discrete dynamical
+  system.
+  This can be instantiated by calling
+  :class:`DiscreteDynamicalSystem` with the parameter
+  ``is_finite`` set to ``True``.
+
+- :class:`InvertibleDiscreteDynamicalSystem`: invertible
+  discrete dynamical system.
+  This implements an ``inverse_evolution`` method for `\phi^{-1}`
+  (the default implementation simply applies `\phi` over and
+  over until the original value is revisited; the last value
+  before that is then taken to be the result).
+  This can be instantiated by calling
+  :class:`DiscreteDynamicalSystem` with the parameter
+  ``inverse`` provided.
+
+- :class:`InvertibleFiniteDynamicalSystem`: invertible
+  finite discrete dynamical system.
+  This can be instantiated by calling
+  :class:`DiscreteDynamicalSystem` with the parameter
+  ``is_finite`` set to ``True`` and the parameter
+  ``inverse`` provided.
+
+.. TODO::
+
+    - Implement some more functionality for homomesy and
+      invariance testing:
+      Checking invariance on a sublist;
+      computing the first `k` entries of an orbit (useful
+      when orbits can be too large);
+      orbits_iterator (for when there are too many orbits to
+      list);
+      etc.
+
+    - Further examples for non-auto functionality: e.g.,
+      infection on a chessboard; Conway's game of life.
+
+    - Subclasses for DDSes whose ground set is an enumerated set.
+      Should we have those?
+
+    - Implement caching for orbits (can be useful: some DDSes
+      have a complicated evolution that shouldn't be recomputed
+      every time).
+      Does this require a whole new class?
+
+    - Further functionality for non-invertible DDSes:
+      is_recurrent, recurrent_entries, idempotent_power, etc.
+
+    - Wrap (some of) the cyclic_sieving_phenomenon.py methods
+      (:mod:`sage.combinat.cyclic_sieving_phenomenon`).
+
+    - Interact with sage.dynamics. This requires someone who
+      knows the latter part of the Sage library well.
+"""
+# ****************************************************************************
+#       Copyright (C) 2018 Darij Grinberg <darijgrinberg@gmail.com>,
+#                     2018 Tom Roby <tomrobyuconn@gmail.com>
+#
+#  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:
+#
+#                  https://www.gnu.org/licenses/
+# ****************************************************************************
+from sage.categories.sets_cat import Sets
+from sage.structure.sage_object import SageObject
+from sage.misc.classcall_metaclass import ClasscallMetaclass, typecall
+
+
+class DiscreteDynamicalSystem(SageObject, metaclass=ClasscallMetaclass):
+    r"""
+    A discrete dynamical system.
+
+    A *discrete dynamical system* (henceforth *DDS*) is a
+    pair `(X, \phi)` of a set `X` and a map `\phi : X \to X`.
+    The set `X` is called the *ground set* of the DDS;
+    the map `\phi` is called the *evolution* of the DDS;
+    the inverse map `\phi^{-1}` (when it exists) is called the
+    *inverse evolution* of the DDS.
+
+    The DDS is called *finite* if `X` is finite.
+    The DDS is called *invertible* if the map `\phi` is
+    invertible.
+
+    Given a DDS `(X, \phi)`, we can study
+
+    * its orbits (i.e., the lists
+      `(s, \phi(s), \phi^2(s), \phi^3(s), \ldots)` for `s \in X`),
+
+    * its invariants (i.e., maps `f : X \to Y` satisfying
+      `f \circ \phi = f`),
+
+    * its cycles (i.e., lists `(u_1, u_2, \ldots, u_k)` of elements
+      of `X` such that `\phi(u_i) = u_{i+1}` for each `i \leq k`,
+      where we set `u_{k+1} = u_1`),
+
+    * its homomesies (i.e., maps `h : X \to A` to a
+      `\QQ`-vector space `A` such that the average of the values
+      of `h` on each cycle is the same),
+
+    and various other features.
+    (Some of these require `X` to be finite or at least to have
+    finite orbits.)
+
+    INPUT:
+
+    - ``X`` -- set, list, tuple, or another iterable, or
+      ``None`` (default: ``None``); the ground set for the DDS.
+      This can be ``None`` (in which case Sage will not know
+      the ground set, but can still apply evolution to any
+      elements that are provided to it).
+      Make sure to set the ``create_tuple`` argument to
+      ``True`` if the ``X`` you provide is an iterator or
+      a list, as otherwise your ``X`` would be exposed
+      (and thus subject to mutation or exhaustion).
+
+    - ``phi`` -- function, or callable that acts like a
+      function; the evolution of the DDS
+
+    - ``cache_orbits`` -- boolean (default: ``False``);
+      whether or not the orbits should be cached once they
+      are computed.
+      This currently does nothing, as we are not caching
+      orbits yet.
+
+    - ``create_tuple`` -- boolean (default: ``False``);
+      whether or not the input ``X`` should be translated
+      into a tuple. Set this to ``True`` to prevent
+      mutation if ``X`` is a list, and to prevent
+      exhaustion if ``X`` is an iterator.
+
+    - ``inverse`` -- function, or callable that acts like a
+      function, or boolean or ``None`` (default: ``None``);
+      the inverse evolution of the DDS, if the DDS is
+      invertible. Set this to ``None`` or ``False``
+      if the DDS is not invertible (or you don't want Sage
+      to treat it as such).
+      Alternatively, by setting this argument to ``True``,
+      you can signal that the DDS is invertible
+      without providing the inverse evolution. (In this case,
+      Sage will compute the inverse, assuming the orbits
+      to be finite.)
+
+    - ``is_finite`` -- boolean or ``None`` (default: ``None``);
+      whether the DDS is finite. The default option ``None``
+      leaves this to Sage to decide.
+      Only set this to ``True`` if you provide the ground
+      set ``X``.
+
+    EXAMPLES:
+
+    The following discrete dynamical system is neither
+    finite nor invertible::
+
+        sage: D = DiscreteDynamicalSystem(NN, lambda x: x + 2)
+        sage: D.ground_set()
+        Non negative integer semiring
+        sage: D.evolution()(5)
+        7
+        sage: D.evolution_power(7)(5)
+        19
+        sage: D.evolution_power(0)(5)
+        5
+
+    The necessity of ``create_tuple=True``::
+
+        sage: X = [0, 1, 2, 3, 4]
+        sage: D_wrong = DiscreteDynamicalSystem(X, lambda x: (x**3) % 5)
+        sage: D_right = DiscreteDynamicalSystem(X, lambda x: (x**3) % 5, create_tuple=True)
+        sage: X[4] = 666 # evil
+        sage: D_wrong.ground_set()
+        [0, 1, 2, 3, 666]
+        sage: D_right.ground_set()
+        (0, 1, 2, 3, 4)
+
+    Here is an invertible (but infinite) discrete dynamical
+    system whose orbits are finite::
+
+        sage: D = DiscreteDynamicalSystem(NN, lambda x: (x + 2 if x % 6 < 4 else x - 4), inverse=True)
+        sage: D.ground_set()
+        Non negative integer semiring
+        sage: D.evolution()(5)
+        1
+        sage: D.evolution()(1)
+        3
+        sage: D.evolution()(3)
+        5
+        sage: D.evolution_power(2)(5)
+        3
+        sage: D.evolution_power(3)(5)
+        5
+        sage: D.evolution_power(-2)(5)
+        1
+        sage: D.inverse_evolution()(4)
+        2
+        sage: D.orbit(3)
+        [3, 5, 1]
+
+    Setting the ``inverse`` parameter to ``None`` or ``False``
+    would give the same system without the functionality that
+    relies on invertibility::
+
+        sage: D = DiscreteDynamicalSystem(NN, lambda x: (x + 2 if x % 6 < 4 else x - 4), inverse=False)
+        sage: D.ground_set()
+        Non negative integer semiring
+        sage: D.evolution()(5)
+        1
+        sage: D.inverse_evolution()(4)
+        Traceback (most recent call last):
+        ...
+        AttributeError: 'DiscreteDynamicalSystem' object has no attribute 'inverse_evolution'...
+        sage: D.orbit(3)
+        [3, 5, 1]
+
+        sage: D = DiscreteDynamicalSystem(NN, lambda x: (x + 2 if x % 6 < 4 else x - 4), inverse=None)
+        sage: D.ground_set()
+        Non negative integer semiring
+        sage: D.evolution()(5)
+        1
+        sage: D.inverse_evolution()(4)
+        Traceback (most recent call last):
+        ...
+        AttributeError: 'DiscreteDynamicalSystem' object has no attribute 'inverse_evolution'...
+        sage: D.orbit(3)
+        [3, 5, 1]
+
+    Next, let us try out a finite non-invertible DDS::
+
+        sage: D = DiscreteDynamicalSystem(tuple(range(13)), lambda x: (x**2) % 13)
+        sage: D.ground_set()
+        (0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12)
+        sage: D.evolution()(4)
+        3
+        sage: D.orbit(4)
+        [4, 3, 9]
+        sage: D.orbit(1)
+        [1]
+        sage: D.orbit(3)
+        [3, 9]
+
+    Note that the finiteness is automatically being inferred here,
+    since the (finite) tuple ``tuple(range(13))`` has been
+    provided as the ground set.
+
+    Finally, here is a finite invertible DDS::
+
+        sage: X = cartesian_product([[0, 1]]*8)
+        sage: Y = [s for s in X if sum(s) == 4]
+        sage: rot = lambda s : s[1:] + (s[0],)
+        sage: D = DiscreteDynamicalSystem(Y, rot, inverse=True)
+        sage: D.evolution()((0, 1, 1, 0, 1, 0, 0, 1))
+        (1, 1, 0, 1, 0, 0, 1, 0)
+        sage: D.inverse_evolution()((0, 1, 1, 0, 1, 0, 0, 1))
+        (1, 0, 1, 1, 0, 1, 0, 0)
+        sage: sorted(D.orbit_lengths())
+        [2, 4, 8, 8, 8, 8, 8, 8, 8, 8]
+
+    We could have just as well provided its inverse explicitly::
+
+        sage: rot7 = lambda s: (s[-1],) + s[:-1]
+        sage: D = DiscreteDynamicalSystem(Y, rot, inverse=rot7)
+        sage: D.evolution()((0, 1, 1, 0, 1, 0, 0, 1))
+        (1, 1, 0, 1, 0, 0, 1, 0)
+        sage: D.inverse_evolution()((0, 1, 1, 0, 1, 0, 0, 1))
+        (1, 0, 1, 1, 0, 1, 0, 0)
+    """
+    @staticmethod
+    def __classcall_private__(cls, X, phi, cache_orbits=False, create_tuple=False, inverse=None, is_finite=None):
+        """
+        Return the correct object based on input.
+
+        The main purpose of this method is to decide which
+        subclass the object will belong to based on the
+        ``inverse`` and ``is_finite`` arguments.
+
+        EXAMPLES::
+
+            sage: D = DiscreteDynamicalSystem(NN, lambda x: x + 1)
+            sage: parent(D)
+            <class 'sage.dynamics.finite_dynamical_system.DiscreteDynamicalSystem'>
+
+            sage: f1 = lambda x: (x + 2 if x % 6 < 4 else x - 4)
+
+            sage: D = DiscreteDynamicalSystem(NN, f1, inverse=False)
+            sage: parent(D)
+            <class 'sage.dynamics.finite_dynamical_system.DiscreteDynamicalSystem'>
+
+            sage: D = DiscreteDynamicalSystem(NN, f1, inverse=None)
+            sage: parent(D)
+            <class 'sage.dynamics.finite_dynamical_system.DiscreteDynamicalSystem'>
+
+            sage: D = DiscreteDynamicalSystem(NN, f1, inverse=True)
+            sage: parent(D)
+            <class 'sage.dynamics.finite_dynamical_system.InvertibleDiscreteDynamicalSystem'>
+
+            sage: D = DiscreteDynamicalSystem(NN, lambda x: x + 1, is_finite=False)
+            sage: parent(D)
+            <class 'sage.dynamics.finite_dynamical_system.DiscreteDynamicalSystem'>
+
+            sage: f2 = lambda x: (x + 1 if x < 3 else 1)
+            sage: f3 = lambda x: (x - 1 if x > 3 else 3)
+
+            sage: D = DiscreteDynamicalSystem([1, 2, 3], f2)
+            sage: parent(D)
+            <class 'sage.dynamics.finite_dynamical_system.FiniteDynamicalSystem'>
+
+            sage: D = DiscreteDynamicalSystem([1, 2, 3], f2, inverse=True)
+            sage: parent(D)
+            <class 'sage.dynamics.finite_dynamical_system.InvertibleFiniteDynamicalSystem'>
+
+            sage: D = DiscreteDynamicalSystem([1, 2, 3], f2, inverse=f3)
+            sage: parent(D)
+            <class 'sage.dynamics.finite_dynamical_system.InvertibleFiniteDynamicalSystem'>
+
+            sage: D = DiscreteDynamicalSystem([1, 2, 3], f2, inverse=False)
+            sage: parent(D)
+            <class 'sage.dynamics.finite_dynamical_system.FiniteDynamicalSystem'>
+
+            sage: D = DiscreteDynamicalSystem([1, 2, 3], f2, inverse=None)
+            sage: parent(D)
+            <class 'sage.dynamics.finite_dynamical_system.FiniteDynamicalSystem'>
+        """
+        if is_finite is None:
+            is_finite = (X in Sets().Finite() or isinstance(X, (list,tuple,set,frozenset)))
+        if inverse:
+            if inverse is True: # invertibility claimed, but inverse not provided
+                # This is how the input for these subclasses work
+                inverse = None
+            ret_cls = (InvertibleFiniteDynamicalSystem if is_finite
+                   else InvertibleDiscreteDynamicalSystem)
+            return ret_cls(X, phi, cache_orbits=cache_orbits,
+                           create_tuple=create_tuple, inverse=inverse)
+        if is_finite:
+            return FiniteDynamicalSystem(X, phi, cache_orbits=cache_orbits,
+                                         create_tuple=create_tuple)
+        return typecall(cls, X, phi, cache_orbits=cache_orbits, create_tuple=create_tuple)
+
+    def __init__(self, X, phi, cache_orbits=False, create_tuple=False):
+        r"""
+        Initialize ``self``.
+
+        EXAMPLES::
+
+            sage: D = DiscreteDynamicalSystem([1, 3, 4], lambda x: (3 if x == 4 else 1), create_tuple=True)
+            sage: TestSuite(D).run(skip ='_test_pickling') # indirect doctest
+            sage: D = DiscreteDynamicalSystem([1, 3, 4], lambda x: (3 if x == 4 else 1), create_tuple=True, is_finite=False)
+            sage: TestSuite(D).run(skip ='_test_pickling') # indirect doctest
+            sage: D = DiscreteDynamicalSystem(NN, lambda x: (3 if x == 4 else 1))
+            sage: TestSuite(D).run(skip ='_test_pickling') # indirect doctest
+            sage: D = DiscreteDynamicalSystem(None, lambda x: (3 if x == 4 else 1))
+            sage: TestSuite(D).run(skip ='_test_pickling') # indirect doctest
+            sage: D = DiscreteDynamicalSystem([1, 3, 4], lambda x: x, create_tuple=True)
+            sage: TestSuite(D).run(skip ='_test_pickling') # indirect doctest
+        """
+        if create_tuple:
+            X = tuple(X)
+        self._X = X
+        self._phi = phi
+        self._cache_orbits = cache_orbits
+
+    def ground_set(self):
+        r"""
+        Return the ground set of ``self``.
+
+        This will return ``None`` if no ground set was
+        provided in the construction of ``self``.
+
+        .. WARNING::
+
+            Unless ``self`` has been constructed with the
+            ``create_tuple`` parameter set to ``True``,
+            this method will return whatever ground set was
+            provided to the constructor.
+            In particular, if a list was provided, then this
+            precise list will be returned; mutating this list
+            will then corrupt ``self``.
+
+        EXAMPLES::
+
+            sage: D = DiscreteDynamicalSystem([1, 3, 4], lambda x: (3 if x == 4 else 1), create_tuple=True)
+            sage: D.ground_set()
+            (1, 3, 4)
+        """
+        return self._X
+
+    def evolution(self):
+        r"""
+        Return the evolution of ``self``.
+
+        EXAMPLES::
+
+            sage: D = DiscreteDynamicalSystem([1, 3, 4], lambda x: (3 if x == 4 else 1), create_tuple=True)
+            sage: ev = D.evolution()
+            sage: ev(1)
+            1
+            sage: ev(4)
+            3
+        """
+        return self._phi
+
+    def evolution_power(self, n):
+        r"""
+        Return the `n`-th power (with respect to composition)
+        of the evolution of ``self``.
+
+        This requires `n` to be a nonnegative integer.
+
+        EXAMPLES::
+
+            sage: D = DiscreteDynamicalSystem(range(10), lambda x: (x + 3) % 10, create_tuple=True)
+            sage: ev3 = D.evolution_power(3)
+            sage: ev3(1)
+            0
+            sage: ev3(2)
+            1
+            sage: ev0 = D.evolution_power(0)
+            sage: ev0(1)
+            1
+            sage: ev0(2)
+            2
+            sage: D.evolution_power(-1)
+            Traceback (most recent call last):
+            ...
+            ValueError: the n-th power of evolution is only defined for nonnegative integers n
+        """
+        from sage.rings.semirings.non_negative_integer_semiring import NN
+        if n not in NN:
+            raise ValueError("the n-th power of evolution is only defined for nonnegative integers n")
+        ev = self.evolution()
+
+        def evn(x):
+            y = x
+            for _ in range(n):
+                y = ev(y)
+            return y
+        return evn
+
+    def __iter__(self):
+        r"""
+        Iterate over the ground set of ``self``.
+
+        This assumes that an iterable ground set of ``self``
+        has been provided.
+
+        EXAMPLES::
+
+            sage: D = DiscreteDynamicalSystem(NN, lambda x: x + 2)
+            sage: D[:3]
+            [0, 1, 2]
+        """
+        return iter(self._X)
+
+    def __getitem__(self, i):
+        r"""
+        Accessor for the ``i``-th entry of the ground set of
+        ``self``, assuming that the latter ground set was
+        provided as a list or tuple when ``self`` was constructed.
+
+        EXAMPLES::
+
+            sage: X = (5, 6, 7, 8)
+            sage: D = DiscreteDynamicalSystem(X, lambda x: (x**3) % 4 + 5)
+            sage: X[3]
+            8
+            sage: X[2]
+            7
+        """
+        return self._X[i]
+
+    def _repr_(self):
+        r"""
+        String representation of ``self``.
+
+        EXAMPLES::
+
+            sage: D = DiscreteDynamicalSystem(NN, lambda x: x + 2)
+            sage: D # indirect doctest
+            A discrete dynamical system with ground set
+             Non negative integer semiring
+            sage: D = DiscreteDynamicalSystem(None, lambda x: x + 2)
+            sage: D # indirect doctest
+            A discrete dynamical system with unspecified ground set
+        """
+        if self._X is None:
+            return "A discrete dynamical system with unspecified ground set"
+        return "A discrete dynamical system with ground set " \
+               + repr(self._X)
+
+    def orbit(self, x, preperiod=False):
+        r"""
+        Return the orbit of the element ``x`` of the ground set
+        of ``self`` under the evolution `\phi` of ``self``.
+
+        This orbit is a list beginning with ``x`` and ending
+        with the last element that is not a repetition of a
+        previous element.
+        If the orbit is infinite, then this method does not
+        terminate!
+
+        If the optional argument ``preperiod`` is set to
+        ``True``, then this method returns a pair ``(o, k)``,
+        where ``o`` is the orbit of ``self``, while `k` is the
+        smallest nonnegative integer such that
+        `\phi^k(x) \in \left\{ \phi^i(x) \mid i > k \right\}`.
+
+        The orbit of the element ``x`` is also called the
+        "rho" of ``x``, due to its shape when it is depicted
+        as a directed graph.
+
+        EXAMPLES::
+
+            sage: D = DiscreteDynamicalSystem(tuple(range(11)), lambda x: (x ** 2) % 11)
+            sage: D.orbit(6)
+            [6, 3, 9, 4, 5]
+            sage: D.orbit(6, preperiod=True)
+            ([6, 3, 9, 4, 5], 1)
+            sage: D.orbit(3)
+            [3, 9, 4, 5]
+            sage: D.orbit(3, preperiod=True)
+            ([3, 9, 4, 5], 0)
+            sage: D.orbit(9)
+            [9, 4, 5, 3]
+            sage: D.orbit(0)
+            [0]
+        """
+        orb = [x]
+        phi = self._phi
+        curr = phi(x)
+        while curr not in orb:
+            orb.append(curr)
+            curr = phi(curr)
+        if not preperiod:
+            return orb
+        return (orb, orb.index(curr))
+
+    def is_homomesic(self, h, average=None, find_average=False, elements=None):
+        r"""
+        Check if ``h`` (a map from the ground set of ``self`` to
+        a `\QQ`-vector space) is homomesic with respect to ``self``.
+
+        If the optional argument ``average`` is provided, then
+        this also checks that the averages are equal to ``average``.
+
+        If the optional argument ``find_average`` is set to
+        ``True``, then this method returns the average of ``h``
+        in case ``h`` is homomesic (instead of returning ``True``).
+
+        If the optional argument ``elements`` (an iterable of
+        elements of the ground set of ``self``) is provided, then
+        this method only checks homomesy for the cycles in the
+        orbits of the elements given in the list ``elements``.
+        Note that ``elements`` must be provided if the ground set of
+        ``self`` is infinite (or cannot be iterated through for any
+        other reason), since there is no way to check all the cycles
+        in this case.
+
+        This method will fail to terminate if any element of
+        ``elements`` has an infinite orbit.
+
+        Let us recall the definition of homomesy:
+        Let `(X, \phi)` be a DDS.
+        A *cycle* of `(X, \phi)` is a finite list
+        `u = (u_1, u_2, \ldots, u_k)` of elements of `X` such
+        that `\phi(u_i) = u_{i+1}` for each `i \leq k`, where we
+        set `u_{k+1} = u_1`.
+        Note that any element of `X` whose orbit is finite has a
+        cycle in its orbit.
+        Now, let `h` be a map from `X` to a `\QQ`-vector space `A`.
+        If `u = (u_1, u_2, \ldots, u_k)` is any cycle of
+        `(X, \phi)`, then the *average* of `h` on this cycle is
+        defined to be the element
+        `(h(u_1) + h(u_2) + \cdots + h(u_k)) / k` of `A`.
+        We say that `h` is *homomesic* (with respect to the DDS
+        `(X, \phi)`) if and only if the averages of `h` on all
+        cycles of `(X, \phi)` are equal.
+
+        EXAMPLES::
+
+            sage: W = Words(2, 5)
+            sage: F = DiscreteDynamicalSystem(W, lambda x: x[1:] + Word([x[0]]), is_finite=True, inverse=True)
+            sage: F.is_homomesic(lambda w: sum(w))
+            False
+            sage: F.is_homomesic(lambda w: 1, average=1)
+            True
+            sage: F.is_homomesic(lambda w: 1, average=0)
+            False
+            sage: F.is_homomesic(lambda w: 1)
+            True
+            sage: F.is_homomesic(lambda w: 1, find_average=True)
+            1
+            sage: F.is_homomesic(lambda w: w[0] - w[1], average=0)
+            True
+            sage: F.is_homomesic(lambda w: w[0] - w[1], find_average=True)
+            0
+
+        Now, let us check homomesy restricted to specific cycles::
+
+            sage: F = finite_dynamical_systems.bitstring_rotation(7)
+            sage: descents = lambda x: sum(1 for i in range(6) if x[i] > x[i+1])
+            sage: F.is_homomesic(descents)
+            False
+            sage: F.is_homomesic(descents, elements=[(1, 0, 1, 0, 0, 0, 0), (1, 0, 0, 1, 0, 0, 0)])
+            True
+            sage: F.is_homomesic(descents, elements=[(1, 0, 1, 0, 0, 0, 0), (1, 1, 0, 0, 0, 0, 0)])
+            False
+            sage: F.is_homomesic(descents, elements=[(1, 0, 1, 0, 0, 0, 0)])
+            True
+            sage: F.is_homomesic(descents, elements=[])
+            True
+
+        And here is a non-invertible finite dynamical system::
+
+            sage: F = finite_dynamical_systems.one_line([9, 1, 1, 6, 5, 4, 5, 5, 1])
+            sage: F.is_homomesic(lambda i: i)
+            True
+            sage: F.is_homomesic(lambda i: i % 2)
+            False
+            sage: F.is_homomesic(lambda i: i % 2, elements=[2, 9, 7])
+            True
+            sage: F.is_homomesic(lambda i: i % 2, elements=[2, 9, 4])
+            False
+            sage: F.is_homomesic(lambda i: i % 2, elements=[2, 9, 5, 7, 8, 2])
+            True
+        """
+        from sage.rings.rational_field import QQ
+        orbavgs = [] # This will be the list of all averages on cycles.
+        if elements is None:
+            # The user has not provided elements, so we need to
+            # check all cycles of the DDS.
+            for cyc in self.cycles():
+                l = len(cyc)
+                avg = ~(QQ(l)) * sum(h(i) for i in cyc)
+                if avg not in orbavgs:
+                    if orbavgs:
+                        return False
+                    orbavgs.append(avg)
+        else:
+            # Checking only the cycles of the elements provided
+            # by the user.
+            for element in elements:
+                (orb, ix) = self.orbit(element, preperiod=True)
+                cyc = orb[ix:] # the cycle in the orbit of element
+                l = len(cyc)
+                avg = ~(QQ(l)) * sum(h(i) for i in cyc)
+                if avg not in orbavgs:
+                    if orbavgs:
+                        return False
+                    orbavgs.append(avg)
+        if not orbavgs:
+            return True
+        if average is None:
+            if find_average:
+                return orbavgs[0]
+            return True
+        return orbavgs[0] == average
+
+
+class InvertibleDiscreteDynamicalSystem(DiscreteDynamicalSystem):
+    r"""
+    An invertible discrete dynamical system.
+
+    A *discrete dynamical system* (henceforth *DDS*) is a
+    pair `(X, \phi)` of a set `X` and a map `\phi : X \to X`.
+    This set `X` is called the *ground set* of the DDS, while
+    the map `\phi` is called the *evolution* of the DDS.
+    An *invertible DDS* is a DDS `(X, \phi)` whose evolution
+    `\phi` is invertible.
+    In that case, `\phi^{-1}` is called the *inverse evolution*
+    of the DDS.
+
+    See :class:`DiscreteDynamicalSystem` for details.
+
+    INPUT:
+
+    - ``X`` -- set, list, tuple, or another iterable, or
+      ``None``; the ground set for the DDS. This can be
+      ``None`` in case of a
+      :class:`DiscreteDynamicalSystem` or a
+      :class:`InvertibleDiscreteDynamicalSystem`.
+      Make sure to set the ``create_tuple`` argument to
+      ``True`` if you provide an iterator or a list for
+      ``X``, as otherwise the input would be exposed.
+
+    - ``phi`` -- function, or callable that acts like a
+      function; the evolution of the DDS
+
+    - ``inverse`` -- function, or callable that acts like a
+      function; the inverse evolution of the DDS. (A
+      default implementation is implemented when this
+      argument is not provided; but it assumes the orbits
+      to be finite.)
+
+    - ``cache_orbits`` -- boolean (default: ``False``);
+      whether or not the orbits should be cached once they
+      are computed.
+
+    - ``create_tuple`` -- boolean (default: ``False``);
+      whether or not the input ``X`` should be translated
+      into a tuple (set this to ``True`` to prevent
+      mutation if ``X`` is a list, and to prevent
+      exhaustion if ``X`` is an iterator).
+
+    EXAMPLES::
+
+        sage: from sage.dynamics.finite_dynamical_system import InvertibleDiscreteDynamicalSystem
+        sage: D = InvertibleDiscreteDynamicalSystem(NN, lambda x: (x + 2 if x % 4 < 2 else x - 2))
+        sage: D.ground_set()
+        Non negative integer semiring
+        sage: D.evolution()(5)
+        7
+        sage: D.evolution()(6)
+        4
+        sage: D.evolution()(4)
+        6
+        sage: D.inverse_evolution()(4)
+        6
+
+    The necessity of ``create_tuple=True``::
+
+        sage: X = [0, 1, 2, 3, 4]
+        sage: D_wrong = InvertibleDiscreteDynamicalSystem(X, lambda x: (x**3) % 5)
+        sage: D_right = InvertibleDiscreteDynamicalSystem(X, lambda x: (x**3) % 5, create_tuple=True)
+        sage: X[4] = 666 # evil
+        sage: D_wrong.ground_set()
+        [0, 1, 2, 3, 666]
+        sage: D_right.ground_set()
+        (0, 1, 2, 3, 4)
+    """
+    def __init__(self, X, phi, inverse=None, cache_orbits=False, create_tuple=False):
+        r"""
+        Initialize ``self``.
+
+        EXAMPLES::
+
+            sage: D = DiscreteDynamicalSystem([1, 3, 4], lambda x: x, create_tuple=True, inverse=True)
+            sage: TestSuite(D).run(skip ='_test_pickling') # indirect doctest
+            sage: D = DiscreteDynamicalSystem([1, 3, 4], lambda x: x, create_tuple=True, is_finite=False, inverse=True)
+            sage: TestSuite(D).run(skip ='_test_pickling') # indirect doctest
+            sage: D = DiscreteDynamicalSystem(NN, lambda x: x, inverse=True)
+            sage: TestSuite(D).run(skip ='_test_pickling') # indirect doctest
+            sage: D = DiscreteDynamicalSystem(None, lambda x: x, inverse=True)
+            sage: TestSuite(D).run(skip ='_test_pickling') # indirect doctest
+        """
+        if create_tuple:
+            X = tuple(X)
+        self._X = X
+        self._phi = phi
+        if inverse is None:
+            self._inverse = self.inverse_evolution_default
+        else:
+            self._inverse = inverse
+        self._cache_orbits = cache_orbits
+
+    def evolution_power(self, n):
+        r"""
+        Return the `n`-th power (with respect to composition)
+        of the evolution of ``self``.
+
+        This requires `n` to be an integer.
+
+        EXAMPLES::
+
+            sage: D = DiscreteDynamicalSystem(range(10), lambda x: (x + 3) % 10, create_tuple=True, inverse=True)
+            sage: ev3 = D.evolution_power(3)
+            sage: ev3(1)
+            0
+            sage: ev3(2)
+            1
+            sage: ev0 = D.evolution_power(0)
+            sage: ev0(1)
+            1
+            sage: ev0(2)
+            2
+            sage: evm1 = D.evolution_power(-1)
+            sage: evm1(1)
+            8
+            sage: evm1(2)
+            9
+            sage: evm2 = D.evolution_power(-2)
+            sage: evm2(1)
+            5
+            sage: evm2(2)
+            6
+        """
+        from sage.rings.integer_ring import ZZ
+        if n not in ZZ:
+            raise ValueError("the n-th power of evolution is only defined for integers n")
+        if n >= 0:
+            ev = self.evolution()
+        else:
+            ev = self.inverse_evolution()
+            n = -n
+
+        def evn(x):
+            y = x
+            for _ in range(n):
+                y = ev(y)
+            return y
+        return evn
+
+    def _repr_(self):
+        r"""
+        String representation of ``self``.
+
+        EXAMPLES::
+
+            sage: D = DiscreteDynamicalSystem(NN, lambda x: (x + 2 if x % 4 < 2 else x - 2), inverse=True)
+            sage: D # indirect doctest
+            An invertible discrete dynamical system with ground set
+             Non negative integer semiring
+            sage: D = DiscreteDynamicalSystem(None, lambda x: x + 2, inverse=True)
+            sage: D # indirect doctest
+            An invertible discrete dynamical system with unspecified ground set
+        """
+        if self._X is None:
+            return "An invertible discrete dynamical system with unspecified ground set"
+        return "An invertible discrete dynamical system with ground set " \
+               + repr(self._X)
+
+    def inverse_evolution(self):
+        r"""
+        Return the inverse evolution of ``self`` (as a map
+        from the ground set of ``self`` to itself).
+
+        EXAMPLES::
+
+            sage: D = DiscreteDynamicalSystem(tuple(range(8)), lambda x: (x + 2) % 8, inverse=True)
+            sage: D.inverse_evolution()(1)
+            7
+            sage: D.inverse_evolution()(3)
+            1
+
+            sage: D = DiscreteDynamicalSystem(ZZ, lambda x: (x + 2) % 8, inverse=True)
+            sage: D.inverse_evolution()(1)
+            7
+            sage: D.inverse_evolution()(3)
+            1
+        """
+        return self._inverse
+
+    def verify_inverse_evolution(self, x=None):
+        r"""
+        Verify that the composition of evolution and
+        inverse evolution on ``self`` is the identity
+        (both ways).
+
+        The optional argument ``x``, if provided, restricts
+        the testing to the element ``x`` only.
+        Otherwise, all elements of the ground set are
+        tested (if they can be enumerated).
+
+        This is mostly used to check the correctness of
+        self-implemented inverse evolution methods.
+
+        EXAMPLES::
+
+            sage: D = DiscreteDynamicalSystem(tuple(range(8)), lambda x: (x + 2) % 8, inverse=True)
+            sage: D.verify_inverse_evolution()
+            True
+            sage: D.verify_inverse_evolution(3)
+            True
+            sage: fake_inverse = lambda x: x
+            sage: D = DiscreteDynamicalSystem(tuple(range(8)), lambda x: (x + 2) % 8, inverse=fake_inverse)
+            sage: D.verify_inverse_evolution()
+            False
+            sage: D.verify_inverse_evolution(3)
+            False
+        """
+        ev = self.evolution()
+        iev = self.inverse_evolution()
+        if x is None:
+            els = self.ground_set()
+        else:
+            els = [x]
+        for y in els:
+            if ev(iev(y)) != y:
+                return False
+            if iev(ev(y)) != y:
+                return False
+        return True
+
+    def orbit(self, x, preperiod=False):
+        r"""
+        Return the orbit of the element ``x`` of the ground set
+        of ``self``.
+
+        This orbit is a list beginning with ``x`` and ending
+        with the last element until ``x`` reappears.
+        If ``x`` never reappears, then this will not terminate!
+
+        If the optional argument ``preperiod`` is set to
+        ``True``, then this method returns a pair ``(o, k)``,
+        where ``o`` is the orbit of ``self``, while `k` is the
+        smallest nonnegative integer such that
+        `\phi^k(x) \in \left\{ \phi^i(x) \mid i > k \right\}`.
+        Note that `k` is necessarily `0`, since the DDS
+        ``self`` is invertible!
+
+        EXAMPLES::
+
+            sage: D = DiscreteDynamicalSystem(tuple(range(8)), lambda x: (x + 2) % 8, inverse=True)
+            sage: D.ground_set()
+            (0, 1, 2, 3, 4, 5, 6, 7)
+            sage: D.orbit(2)
+            [2, 4, 6, 0]
+            sage: D.orbit(5)
+            [5, 7, 1, 3]
+            sage: D.orbit(5, preperiod=True)
+            ([5, 7, 1, 3], 0)
+
+            sage: D = DiscreteDynamicalSystem(ZZ, lambda x: (x + 2) % 8, inverse=True)
+            sage: D.ground_set()
+            Integer Ring
+            sage: D.orbit(2)
+            [2, 4, 6, 0]
+            sage: D.orbit(5)
+            [5, 7, 1, 3]
+            sage: D.orbit(5, preperiod=True)
+            ([5, 7, 1, 3], 0)
+        """
+        orb = [x]
+        phi = self._phi
+        curr = phi(x)
+        while curr != x:
+            orb.append(curr)
+            curr = phi(curr)
+        if not preperiod:
+            return orb
+        return (orb, 0)
+
+    def inverse_evolution_default(self, x):
+        r"""
+        Return the inverse evolution of ``self``, applied
+        to the element ``x`` of the ground set of ``self``.
+
+        This is the default implementation, assuming that
+        the orbit of ``x`` is finite.
+
+        EXAMPLES::
+
+            sage: D = DiscreteDynamicalSystem(tuple(range(8)), lambda x: (x + 2) % 8, inverse=True)
+            sage: D.inverse_evolution_default(1)
+            7
+            sage: D.inverse_evolution_default(3)
+            1
+        """
+        return self.orbit(x)[-1]
+
+
+class FiniteDynamicalSystem(DiscreteDynamicalSystem):
+    r"""
+    A finite discrete dynamical system.
+
+    A *finite discrete dynamical system* (henceforth *FDDS*) is a
+    pair `(X, \phi)` of a finite set `X` and a map `\phi : X \to X`.
+    This set `X` is called the *ground set* of the FDDS, while
+    the map `\phi` is called the *evolution* of the FDDS.
+
+    The ground set `X` should always be provided as an
+    iterable when defining a :class:`FiniteDynamicalSystem`.
+
+    EXAMPLES::
+
+        sage: from sage.dynamics.finite_dynamical_system import FiniteDynamicalSystem
+        sage: D = FiniteDynamicalSystem(tuple(range(11)), lambda x: (x**2) % 11)
+        sage: D.ground_set()
+        (0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10)
+        sage: D.evolution()(4)
+        5
+        sage: D.orbit(4)
+        [4, 5, 3, 9]
+        sage: D.orbit(1)
+        [1]
+        sage: D.orbit(2)
+        [2, 4, 5, 3, 9]
+
+        sage: X = cartesian_product([[0, 1]]*8)
+        sage: Y = [s for s in X if sum(s) == 4]
+        sage: rot = lambda s : s[1:] + (0,)
+        sage: D = FiniteDynamicalSystem(Y, rot)
+        sage: D.evolution()((1, 1, 1, 0, 1, 0, 0, 1))
+        (1, 1, 0, 1, 0, 0, 1, 0)
+    """
+    def _repr_(self):
+        r"""
+        String representation of ``self``.
+
+        EXAMPLES::
+
+            sage: D = DiscreteDynamicalSystem(tuple(range(11)), lambda x: (x**2) % 11)
+            sage: D
+            A finite discrete dynamical system with ground set
+            (0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10)
+        """
+        return "A finite discrete dynamical system with ground set " \
+               + repr(self._X)
+
+    def is_invariant(self, f):
+        r"""
+        Check if ``f`` is an invariant of ``self``.
+
+        Let `(X, \phi)` be a discrete dynamical system.
+        Let `Y` be any set. Let `f : X \to Y` be any map.
+        Then, we say that `f` is an *invariant* of `(X, \phi)`
+        if and only if `f \circ \phi = f`.
+
+        EXAMPLES::
+
+            sage: W = Words(2, 5)
+            sage: F = DiscreteDynamicalSystem(W, lambda x: x[1:] + Word([x[0]]), is_finite=True)
+            sage: F.is_invariant(lambda w: sum(w))
+            True
+            sage: F.is_invariant(lambda w: 1)
+            True
+            sage: F.is_invariant(lambda w: w[0] - w[1])
+            False
+            sage: F.is_invariant(lambda w: sum(i**2 for i in w))
+            True
+
+        Invariants and non-invariants of a permutation::
+
+            sage: F = finite_dynamical_systems.permutation([3, 4, 5, 6, 1, 2])
+            sage: F.is_invariant(lambda i: i % 2)
+            True
+            sage: F.is_invariant(lambda i: i % 3)
+            False
+            sage: F.is_invariant(lambda i: i > 1)
+            False
+            sage: F.is_invariant(lambda i: i % 2 == 0)
+            True
+        """
+        phi = self._phi
+        return all(f(phi(i)) == f(i) for i in self._X)
+
+    def cycles(self):
+        r"""
+        Return a list of all cycles of ``self``, up to
+        cyclic rotation.
+
+        We recall the definition of cycles:
+        Let `(X, \phi)` be a DDS.
+        A *cycle* of `(X, \phi)` is a finite list
+        `u = (u_1, u_2, \ldots, u_k)` of elements of `X` such
+        that `\phi(u_i) = u_{i+1}` for each `i \leq k`, where we
+        set `u_{k+1} = u_1`.
+        Note that any element of `X` whose orbit is finite has a
+        cycle in its orbit.
+
+        EXAMPLES::
+
+            sage: BS = finite_dynamical_systems.bulgarian_solitaire
+            sage: BS(8).cycles()
+            [[[4, 3, 1], [3, 3, 2], [3, 2, 2, 1], [4, 2, 1, 1]],
+             [[4, 2, 2], [3, 3, 1, 1]]]
+            sage: BS(6).cycles()
+            [[[3, 2, 1]]]
+
+            sage: D = DiscreteDynamicalSystem(tuple(range(6)), lambda x: (x + 2) % 6)
+            sage: D.cycles()
+            [[5, 1, 3], [4, 0, 2]]
+            sage: D = DiscreteDynamicalSystem(tuple(range(6)), lambda x: (x ** 2) % 6)
+            sage: D.cycles()
+            [[1], [4], [3], [0]]
+            sage: D = DiscreteDynamicalSystem(tuple(range(11)), lambda x: (x ** 2 - 1) % 11)
+            sage: D.cycles()
+            [[10, 0], [8], [4]]
+
+            sage: F = finite_dynamical_systems.one_line([4, 7, 2, 6, 2, 10, 9, 11, 5, 6, 12, 12, 12, 6])
+            sage: F.cycles()
+            [[6, 10], [12], [9, 5, 2, 7]]
+        """
+        l = list(self)
+        cycs = []
+        while l:
+            start = l[-1]
+            (orb, ix) = self.orbit(start, preperiod=True)
+            if orb[ix] in l:
+                # This means we've actually found a new cycle,
+                # not just a new path to an old cycle.
+                cycs.append(orb[ix:])
+            for j in orb:
+                try:
+                    l.remove(j)
+                except ValueError:
+                    # Here we break out of the for-loop, because
+                    # if ``j`` has already been removed from
+                    # ``l``, then all later elements of the orbit
+                    # must have been removed from ``l`` as well
+                    # (indeed, the set of elements that have been
+                    # removed from ``l`` is closed under ``phi``).
+                    break
+        return cycs
+
+
+class InvertibleFiniteDynamicalSystem(InvertibleDiscreteDynamicalSystem, FiniteDynamicalSystem):
+    r"""
+    An invertible finite discrete dynamical system.
+
+    A *finite discrete dynamical system* (henceforth *FDDS*) is a
+    pair `(X, \phi)` of a finite set `X` and a map `\phi : X \to X`.
+    This set `X` is called the *ground set* of the FDDS, while
+    the map `\phi` is called the *evolution* of the FDDS.
+    An FDDS `(X, \phi)` is called *invertible* if the map `\phi`
+    is invertible; in this case, `\phi^{-1}` is called the
+    *inverse evolution* of the FDDS.
+
+    The ground set `X` should always be provided as an
+    iterable when defining a :class:`FiniteDynamicalSystem`.
+
+    EXAMPLES::
+
+        sage: from sage.dynamics.finite_dynamical_system import InvertibleFiniteDynamicalSystem
+        sage: D = InvertibleFiniteDynamicalSystem(tuple(range(5)), lambda x: (x + 2) % 5)
+        sage: D.ground_set()
+        (0, 1, 2, 3, 4)
+        sage: D.evolution()(4)
+        1
+        sage: D.orbits()
+        [[4, 1, 3, 0, 2]]
+        sage: D.inverse_evolution()(2)
+        0
+        sage: D.inverse_evolution()(1)
+        4
+        sage: D.evolution_power(-1)(1)
+        4
+        sage: D.evolution_power(-2)(1)
+        2
+
+        sage: X = cartesian_product([[0, 1]]*8)
+        sage: Y = [s for s in X if sum(s) == 4]
+        sage: rot = lambda s : s[1:] + (s[0],)
+        sage: D = InvertibleFiniteDynamicalSystem(Y, rot)
+        sage: D.evolution()((0, 1, 1, 0, 1, 0, 0, 1))
+        (1, 1, 0, 1, 0, 0, 1, 0)
+        sage: D.inverse_evolution()((0, 1, 1, 0, 1, 0, 0, 1))
+        (1, 0, 1, 1, 0, 1, 0, 0)
+        sage: sorted(D.orbit_lengths())
+        [2, 4, 8, 8, 8, 8, 8, 8, 8, 8]
+    """
+    def _repr_(self):
+        r"""
+        String representation of ``self``.
+
+        EXAMPLES::
+
+            sage: D = DiscreteDynamicalSystem(tuple(range(5)), lambda x: (x + 2) % 5, inverse=True)
+            sage: D
+            An invertible finite discrete dynamical system with ground set
+            (0, 1, 2, 3, 4)
+        """
+        return "An invertible finite discrete dynamical system with ground set " \
+               + repr(self._X)
+
+    def orbits(self):
+        r"""
+        Return a list of all orbits of ``self``, up to
+        cyclic rotation.
+
+        EXAMPLES::
+
+            sage: D = DiscreteDynamicalSystem(tuple(range(6)), lambda x: (x + 2) % 6, inverse=True)
+            sage: D.orbits()
+            [[5, 1, 3], [4, 0, 2]]
+            sage: D = DiscreteDynamicalSystem(tuple(range(6)), lambda x: (x + 3) % 6, inverse=True)
+            sage: D.orbits()
+            [[5, 2], [4, 1], [3, 0]]
+        """
+        phi = self._phi
+        l = list(self)
+        orbs = []
+        while l:
+            start = l.pop()
+            orb = [start]
+            curr = phi(start)
+            while curr != start:
+                l.remove(curr)
+                orb.append(curr)
+                curr = phi(curr)
+            orbs.append(orb)
+        return orbs
+
+    def cycles(self):
+        r"""
+        Return a list of all cycles of ``self``, up to
+        cyclic rotation.
+
+        We recall the definition of cycles:
+        Let `(X, \phi)` be a DDS.
+        A *cycle* of `(X, \phi)` is a finite list
+        `u = (u_1, u_2, \ldots, u_k)` of elements of `X` such
+        that `\phi(u_i) = u_{i+1}` for each `i \leq k`, where we
+        set `u_{k+1} = u_1`.
+        Note that any element of `X` whose orbit is finite has a
+        cycle in its orbit.
+
+        Since ``self`` is invertible, the cycles of ``self``
+        are the same as its orbits.
+
+        EXAMPLES::
+
+            sage: D = DiscreteDynamicalSystem(tuple(range(6)), lambda x: (x + 2) % 6, inverse=True)
+            sage: D.cycles()
+            [[5, 1, 3], [4, 0, 2]]
+            sage: D = DiscreteDynamicalSystem(tuple(range(6)), lambda x: (x + 3) % 6, inverse=True)
+            sage: D.cycles()
+            [[5, 2], [4, 1], [3, 0]]
+        """
+        return self.orbits()
+
+    def orbit_lengths(self):
+        r"""
+        Return a list of the lengths of all orbits of
+        ``self``.
+
+        EXAMPLES::
+
+            sage: D = DiscreteDynamicalSystem(tuple(range(6)), lambda x: (x + 2) % 6, inverse=True)
+            sage: D.orbit_lengths()
+            [3, 3]
+            sage: D = DiscreteDynamicalSystem(tuple(range(6)), lambda x: (x + 3) % 6, inverse=True)
+            sage: D.orbit_lengths()
+            [2, 2, 2]
+        """
+        return [len(orb) for orb in self.orbits()]