kauri 1.0.0__py3-none-any.whl

kauri/__init__.py

@@ -0,0 +1,19 @@
+"""
+Algebraic manipulation of rooted trees for the analysis of B-series and Runge-Kutta schemes.
+"""
+from .trees import Tree, Forest, ForestSum, TensorProductSum
+from .maps import Map, ident, sign, exact_weights, omega
+from .display import display
+from .gentrees import trees_of_order, trees_up_to_order
+from .rk import RK, rk_symbolic_weight, rk_order_cond
+
+from .rk_methods import (euler, heun_rk2, midpoint, kutta_rk3, heun_rk3,
+                         ralston_rk3, rk4, ralston_rk4, nystrom_rk5, backward_euler,
+                         implicit_midpoint, crank_nicolson, gauss6, radau_iia, lobatto6)
+
+from .bseries import BSeries, elementary_differential
+
+from .trees import EMPTY_TREE, EMPTY_FOREST, EMPTY_FOREST_SUM, ZERO_FOREST_SUM
+
+import kauri.bck
+import kauri.cem

kauri/bck/__init__.py

@@ -0,0 +1,28 @@
+"""
+The ``kauri.bck`` sub-package implements the Butcher-Connes-Kreimer (BCK) :cite:`connes1999hopf` Hopf algebra
+:math:`(H, \\Delta_{BCK}, \\mu, \\varepsilon_{BCK}, \\emptyset, S_{BCK})`, defined as follows.
+
+- :math:`H` is the set of all non-planar rooted trees.
+- The unit :math:`\\emptyset` is the empty forest.
+- The counit map is defined by :math:`\\varepsilon_{BCK}(\\emptyset) = 1`,
+  :math:`\\varepsilon_{BCK}(t) = 0` for all :math:`\\emptyset \\neq t \\in H`.
+- Multiplication :math:`\\mu : H \\otimes H \\to H` is defined as the
+  commutative juxtaposition of two forests.
+- Comultiplication :math:`\\Delta : H \\to H \\otimes H` is defined as
+
+  .. math::
+
+      \\Delta_{BCK}(t) = t \\otimes \\emptyset + \\emptyset \\otimes t + \\sum_{s \\subset t} [t \\setminus s] \\otimes s
+
+  where the sum runs over all proper rooted subtrees :math:`s` of :math:`t`, and :math:`[t \\setminus s]`
+  is the forest of all trees remaining after erasing :math:`s` from :math:`t`.
+- The antipode :math:`S_{BCK}` is defined by :math:`S_{BCK}(\\bullet) = -\\bullet` and
+
+  .. math::
+
+      S_{BCK}(t) = -t - \\sum_{s \\subset t} (-1)^{n(t \\setminus s)} S_{BCK}([t \\setminus s]) s,
+
+  where :math:`n(t \\setminus s)` is the number of trees in the forest :math:`[t \\setminus s]`.
+"""
+
+from .bck import antipode, counit, coproduct, map_power, map_product

kauri/bck/bck.py

@@ -0,0 +1,119 @@
+"""
+Front-end for the BCK module
+"""
+from ..bck_impl import _counit, _coproduct, _antipode
+from ..maps import Map
+from ..trees import Tree, TensorProductSum
+
+counit = Map(_counit)
+counit.__doc__ = """
+The counit :math:`\\varepsilon_{BCK}` of the BCK Hopf algebra.
+
+:type: Map
+
+Example usage::
+    
+    import kauri as kr
+    import kauri.bck as bck
+
+    bck.counit(kr.Tree(None)) # Returns 1
+    bck.counit(kr.Tree([])) # Returns 0
+"""
+
+antipode = Map(_antipode)
+antipode.__doc__ = """
+The antipode :math:`S_{BCK}` of the BCK Hopf algebra.
+
+:type: Map
+
+Example usage::
+
+    import kauri as kr
+    import kauri.bck as bck
+
+    t = kr.Tree([[[]],[]])
+    bck.antipode(t)
+"""
+
+def coproduct(t : Tree) -> TensorProductSum:
+    """
+    The coproduct :math:`\\Delta_{BCK}` of the BCK Hopf algebra.
+
+    :param t: tree
+    :type t: Tree
+    :rtype: TensorProductSum
+
+    Example usage::
+
+        import kauri as kr
+        import kauri.bck as bck
+
+        bck.coproduct(kr.Tree([])) # Returns 1 ∅ ⊗ []+1 [] ⊗ ∅
+        bck.coproduct(kr.Tree([[]])) # Returns 1 [[]] ⊗ ∅+1 ∅ ⊗ [[]]+1 [] ⊗ []
+    """
+    if not isinstance(t, Tree):
+        raise TypeError("Argument to bck.coproduct must be a Tree, not " + str(type(t)))
+    return _coproduct(t)
+
+def map_product(f : Map, g : Map) -> Map:
+    """
+    Returns the product of maps in the BCK Hopf algebra, defined by
+
+    .. math::
+
+        (f \\cdot g)(t) := \\mu \\circ (f \\otimes g) \\circ \\Delta_{BCK} (t)
+
+    .. note::
+        `bck.map_product(f,g)` is equivalent to the Map operator `f * g`
+
+    :param f: f
+    :type f: Map
+    :param g: g
+    :type g: Map
+    :rtype: Map
+
+    Example usage::
+
+        import kauri as kr
+        import kauri.bck as bck
+
+        ident = kr.Map(lambda x : x)
+        counit = bck.map_product(ident, bck.antipode) # Equivalent to indent * bck.antipode
+    """
+    if not (isinstance(f, Map) and isinstance(g, Map)):
+        raise TypeError("Arguments in bck.map_product must be of type Map, not " + str(type(f)) + " and " + str(type(g)))
+    return f * g
+
+def map_power(f : Map, exponent : int) -> Map:
+    """
+    Returns the power of a map in the BCK Hopf algebra, where the product of functions is defined by
+
+    .. math::
+
+        (f \\cdot g)(t) := \\mu \\circ (f \\otimes g) \\circ \\Delta_{BCK} (t)
+
+    and negative powers are defined as :math:`f^{-n} = f^n \\circ S_{BCK}`,
+    where :math:`S_{BCK}` is the BCK antipode.
+
+    .. note::
+        `bck.map_power(f, n)` is equivalent to the Map operator `f ** n`
+
+    :param f: f
+    :type f: Map
+    :param exponent: exponent
+    :type exponent: int
+
+    Example usage::
+
+        import kauri as kr
+        import kauri.bck as bck
+
+        ident = kr.Map(lambda x : x)
+        S = bck.map_power(ident, -1) # antipode, equivalent to ident ** (-1)
+        ident_sq = bck.map_power(ident, 2) # identity squared, equivalent to ident ** 2
+    """
+    if not isinstance(f, Map):
+        raise TypeError("f must be a Map, not " + str(type(f)))
+    if not isinstance(exponent, int):
+        raise TypeError("exponent must be an int, not " + str(type(exponent)))
+    return f ** exponent

kauri/bck_impl/__init__.py

@@ -0,0 +1,4 @@
+"""
+Back-end for the BCK module
+"""
+from .bck_impl import _antipode, _counit, _coproduct

kauri/bck_impl/bck_impl.py

@@ -0,0 +1,101 @@
+"""
+Back-end for the BCK module
+"""
+from functools import cache
+import itertools
+from ..trees import (Tree, Forest, TensorProductSum,
+                     EMPTY_TREE, EMPTY_FOREST, EMPTY_FOREST_SUM)
+from ..generic_algebra import _forest_apply
+
+def _counit(t):
+    # Return 1 if t is the empty tree, otherwise 0
+    return 1 if t.list_repr is None else 0
+
+@cache
+def _antipode(t):
+    if t.list_repr is None:
+        return EMPTY_FOREST_SUM # Antipode of empty tree is the empty tree
+    if t.list_repr == tuple():
+        return -t # Antipode of singleton is the negative singleton
+
+    cp = _coproduct(t)
+    out = -t.as_forest_sum() # First term, -t
+    for c, branches, subtree_ in cp: # Remaining terms
+        subtree = subtree_[0] # Convert from Forest to Tree
+        if subtree.equals(t) or subtree.equals(EMPTY_TREE):
+            continue # We've already included the -t term at the start, so move on
+        out = out - c * _forest_apply(branches, _antipode) * subtree
+
+    return out.simplify()
+
+@cache
+def _coproduct_helper_2(t):
+    # This returns the coproduct as a list of (Forest, Tree) tuples
+    # The function _coproduct then converts this to a tensor product sum
+    # and simplifies.
+
+    # We compute the coproduct for a tree t = [t_1, t_2, ..., t_k] recursively.
+    # As per https://www2.mathematik.hu-berlin.de/~kreimer/wp-content/uploads/Foissy.pdf,
+    # the coproduct can be written as a sum over admissible cuts, defined as cuts
+    # where every walk from the root to a leaf contains at most one cut edge.
+    # The coproduct is then a sum of tensor products, where each term is the
+    # product of the forest of branches resulting from a cut and the remaining tree
+    # connected to the root. Denote these by P_c(t) and R_c(t) respectively, for a
+    # cut c.
+
+    # The recursion works on the idea that P_c(t) is the union of P_c(t_i),
+    # and R_c(t) = [R_c(t_1), R_c(t_2), ..., R_c(t_k)]. This allows us to use the
+    # coproducts of t_i to compute the coproduct of t.
+
+    # Caching of this function makes it fairly efficient for large computations.
+
+    if t.list_repr is None: # Empty tree
+        return [(EMPTY_FOREST, EMPTY_TREE)]
+    if t.list_repr == tuple(): # Singleton tree
+        return [(EMPTY_FOREST, t), (t.as_forest(), EMPTY_TREE)]
+
+    # Compute the coproducts of t_1, t_2, ..., t_k
+    subtree_coproducts = []
+    for rep in t.list_repr[:-1]: # Recall last element is the root label, so take [:-1]
+        subtree = Tree(rep)
+        subtree_coproducts.append(_coproduct_helper_2(subtree))
+
+    t_coproduct = [(Forest((t,)), EMPTY_TREE)] # First term of coproduct, t x empty tree
+
+    # Remaining terms, compute these recursively
+    for p in itertools.product(*subtree_coproducts):
+        R_c_repr = []
+        P_c_tree_list = []
+        for f, s in p:
+            if s.list_repr is not None:
+                R_c_repr += [s.list_repr]
+            P_c_tree_list += f.tree_list
+        R_c_repr += [t.list_repr[-1]] #Add label of root
+        t_coproduct.append((Forest(P_c_tree_list), Tree(R_c_repr)))
+
+    return t_coproduct
+
+def _coproduct_2(t):
+    cp = _coproduct_helper_2(t)
+    return TensorProductSum(tuple((1, x[0], x[1]) for x in cp)).simplify()
+
+@cache
+def _coproduct(t):
+    # This follows the recursive definition of https://arxiv.org/pdf/hep-th/9808042
+    # using B_- and B_+
+    if t == Tree(None):
+        return TensorProductSum(( (1, EMPTY_FOREST, EMPTY_FOREST), )) # Tree(None) @ Tree(None)
+    if len(t.list_repr) == 1:
+        return TensorProductSum(( (1, EMPTY_FOREST, t.as_forest()), (1, t.as_forest(), EMPTY_FOREST) )) # Tree(None) @ t + t @ Tree(None)
+
+    root_color = t.list_repr[-1]
+    branches = t.unjoin()
+
+    cp_prod = 1
+    for subtree in branches:
+        cp = _coproduct(subtree)
+        cp_prod = cp_prod * cp
+
+    # Return t \otimes \emptyset + (id \otimes B_+)[\Delta(B_-(t))]
+    out = t @ Tree(None) + TensorProductSum(tuple((c, f1, f2.join(root_color)) for c, f1, f2 in cp_prod))
+    return out.simplify()

kauri/bseries.py

@@ -0,0 +1,296 @@
+"""
+This module allows for the symbolic manipulation and evaluation of truncated
+B-Series on unlabelled trees, for an ODE of the form
+
+.. math::
+
+    \\frac{dy}{ds} = f(y).
+
+Given a weights function :math:`\\varphi`, the associated truncated B-Series is
+
+.. math::
+
+    B_h(\\varphi, y_0) := \\sum_{|t| \\leq n} \\frac{h^{|t|}}{\\sigma(t)} \\varphi(t) F(t)(y_0),
+
+where the sum runs over all trees of order at most :math:`n`, :math:`\\sigma(t)` is the symmetry factor
+of a tree, and :math:`F(t)(y_0)` are the elementary differentials, defined recursively on trees by:
+
+.. math::
+
+    F(\\emptyset) = y,
+.. math::
+
+    F(\\bullet) = f(y),
+.. math::
+
+    F([t_1, t_2, \\ldots, t_k])(y) = f^{(k)}(y)(F(t_1)(y), F(t_2)(y), \\ldots, F(t_k)(y)).
+
+The main objective of this module is to evaluate existing B-series. For more complicated operations,
+it is recommended to work with the underlying character (or elementary weights function) and then
+construct a B-series from the result. For example, take the following B-series corresponding to
+the Euler and RK4 schemes:
+
+.. code-block:: python
+
+    import kauri as kr
+
+    y1 = sp.symbols('y1')
+    y = sp.Matrix([y1])
+    f = sp.Matrix([y1 ** 2])
+
+    bs1 = kr.BSeries(y, f, kr.euler.elementary_weights_map(), 5)
+    bs2 = kr.BSeries(y, f, kr.rk4.elementary_weights_map(), 5)
+
+At the level of the underlying characters, the composition of two B-series is given by the BCK product
+of the characters, so one can get the composition by doing
+
+.. code-block:: python
+
+    bs_composition = kr.BSeries(y, f, bs2.weights * bs1.weights, 5)
+
+Similarly the inverse B-series for the Euler scheme is given by
+
+.. code-block:: python
+
+    bs_inverse = kr.BSeries(y, f, bs1.weights ** (-1), 5)
+
+and the symmetric-adjoint method is given by
+
+.. code-block:: python
+
+    bs_adjoint = kr.BSeries(y, f, bs1.weights ** (-1) & kr.sign, 5)
+
+where `kr.sign` is the :class:`Map` sending `t` to `-t`.
+
+"""
+import itertools
+from functools import cache
+from typing import Union
+
+import sympy as sp
+
+from kauri import Tree, trees_up_to_order, Map
+
+def _check_f_y(f, y):
+    # Checks that f and y are correctly specified
+
+    if not isinstance(y, sp.Matrix):
+        raise TypeError("y must be of type sympy.Matrix, not " + str(type(y)))
+    if not isinstance(f, sp.Matrix):
+        raise TypeError("The vector field f must be of type sympy.Matrix, not " + str(type(f)))
+
+    # Make sure f, y are vectors of the same dimensions
+    if not (f.shape[1] == 1 and y.shape[1] == 1 and f.shape[0] == y.shape[0]):
+        raise ValueError("""f, y must be column vectors, both of shape (d, 1) for some d.
+            Instead, got f of shape """ + str(f.shape) + " and y of shape " + str(y.shape))
+
+    # Make sure f is in terms of y and nothing else
+    allowed_symbols = set(y)
+    f_symbols = set().union(*(expr.free_symbols for expr in f))
+    if not f_symbols <= allowed_symbols:
+        raise ValueError("""The vector field f contains unknown symbols which are not contained in y.
+            If these are constants, please add them to the ODE with a derivative of 0. If these represent
+            time, please add them to the ODE with a derivative of 1.""")
+
+@cache
+def _elementary_differential(tree : Tree,
+                             f : sp.ImmutableDenseMatrix,
+                             y_vars : sp.ImmutableDenseMatrix):
+    if tree.list_repr is None:
+        return y_vars # y
+    if len(tree.list_repr) == 1:
+        return f # f(y)
+
+    # tree = [t_1, ..., t_k], sub_diffs = [F(t_1), ..., F(t_k)]
+    sub_diffs = tuple(_elementary_differential(subtree, f, y_vars) for subtree in tree.unjoin())
+
+    # Now compute f^(k) (F(t_1), ..., F(t_k))
+    # which equals \sum_{i_j = 1,...,d} F(t_1)_{i_1} ... F(t_k)_{i_k} ( d^k f / dy_{i_1} ... dy_{i_k} )
+    result = sp.zeros(*sp.shape(y_vars))
+    dim = len(y_vars)
+    k = len(tree.list_repr) - 1
+
+    for idx in itertools.product(range(dim), repeat=k):
+        # Compute the derivative d^k f / dy_{i_1} ... dy_{i_k} first
+        term = f
+        for i in idx:
+            term = sp.diff(term, y_vars[i])
+
+        # Now multiply by F(t_1)_{i_1} ... F(t_k)_{i_k}
+        for j, i in enumerate(idx):
+            term *= sub_diffs[j][i]
+        result += term
+
+    return result
+
+def elementary_differential(tree : Tree,
+                            f : sp.Matrix,
+                            y : sp.Matrix
+                            ) -> sp.Matrix:
+    """
+    Returns the elementary differential of a vector field.
+    These are defined recursively on trees by:
+
+    .. math::
+
+        F(\\emptyset) = y,
+    .. math::
+
+
+        F(\\bullet) = f(y),
+    .. math::
+
+
+        F([t_1, t_2, \\ldots, t_k])(y) = f^{(k)}(y)(F(t_1)(y), F(t_2)(y), \\ldots, F(t_k)(y)).
+
+    :param tree: Unlabelled tree corresponding to the elementary differential
+    :type tree: Tree
+    :param f: Vector field
+    :type f: sympy.Matrix
+    :param y: Symbolic variables y
+    :type y: sympy.Matrix
+
+    Example usage::
+
+            import kauri as kr
+            import sympy as sp
+
+            y1, y2 = sp.symbols('y1 y2')
+            y = sp.Matrix([y1, y2])
+            f = sp.Matrix([y1 ** 2, y1 * y2])
+
+            t = kr.Tree([[[]],[]])
+            elementary_differential(t, f, y) # Returns sp.Matrix([[4 * y1**5 ], [ 4 * y1**4 * y2]])
+    """
+    if not isinstance(tree, Tree):
+        raise TypeError("The argument 'tree' must be of type Tree, not " + str(type(tree)))
+    if tree.colors() > 1:
+        raise ValueError("Tree passed to elementary differential must be unlabelled.")
+
+    _check_f_y(f, y)
+
+    return _elementary_differential(tree, sp.ImmutableDenseMatrix(f), sp.ImmutableDenseMatrix(y))
+
+
+class BSeries:
+    """
+    This class allows for the symbolic manipulation and evaluation of truncated
+    B-Series on unlabelled trees, for a given vector field f. Given a weights
+    function :math:`\\varphi`, the associated truncated B-Series is
+
+    .. math::
+
+        B_h(\\varphi, y_0) := \\sum_{|t| \\leq n} \\frac{h^{|t|}}{\\sigma(t)} \\varphi(t) F(t)(y_0),
+
+    where the sum runs over all trees of order at most :math:`n`.
+
+    :param y: Symbolic variables y
+    :type y: sympy.Matrix
+    :param f: Vector field
+    :type f: sympy.Matrix
+    :param weights: The weights function :math:`\\varphi` corresponding to the B-Series.
+    :type weights: kauri.Map
+    :param order: The truncation order of the B-Series
+    :type order: int
+
+    Example usage::
+
+            import kauri as kr
+            import sympy as sp
+
+            y1 = sp.symbols('y1')
+            y = sp.Matrix([y1])
+            f = sp.Matrix([y1 ** 2])
+
+            m = kr.rk4.elementary_weights_map()
+            bs = BSeries(y, f, m, 5)
+
+            print(bs.series()) # Print the B-Series as a sympy expression
+            print(bs(1, 0.1)) # Evaluate the B-Series at y = 1, h = 0.1
+    """
+
+    def __init__(self, y : sp.Matrix, f : sp.Matrix, weights : Map, order : int):
+        if not isinstance(weights, Map):
+            raise TypeError("weights must be a Map, not " + str(type(weights)))
+        if not isinstance(order, int):
+            raise TypeError("order must be an int, not " + str(type(order)))
+        if order < 0:
+            raise ValueError("order cannot be negative")
+
+        _check_f_y(f, y)
+
+        self.f = f
+        self.y = y
+        self.f_imm = sp.ImmutableDenseMatrix(f) #Immutable for cache in elementary_differential
+        self.y_imm = sp.ImmutableDenseMatrix(y) #Immutable for cache in elementary_differential
+        self.h = sp.symbols('h')
+        self.order = order
+        self.weights = weights
+        self.dim = len(y)
+        self.symbolic_expr = sp.zeros(*sp.shape(y))
+        for t in trees_up_to_order(order):
+            self.symbolic_expr = self.symbolic_expr + self.h ** t.nodes() * weights(t) * _elementary_differential(t, self.f_imm, self.y_imm) / t.sigma()
+
+    def __call__(self, y : list, h : Union[int, float]) -> list:
+        """
+        Evalutes the B-series at the given values for y and h.
+
+        :param y: List of values to substitute for y
+        :type y: list
+        :param h: Value to substitute for the step size h
+        :type h: int | float
+        :return: Value of the B-series evaluated for the given values of y and h
+        :rtype: list
+
+        """
+        if not isinstance(y, list):
+            raise ValueError("y must be a list, not " + str(type(y)))
+        if len(y) != self.dim:
+            raise ValueError("List of values for y is of incorrect length. Expected " + str(self.dim) + " got " + str(len(y)))
+        if not isinstance(h, (int, float)):
+            raise ValueError("h must be an int or float, not " + str(type(h)))
+
+        out = self.symbolic_expr.subs(self.h, h)
+        for i in range(self.dim):
+            out = out.subs(self.y[i], y[i])
+        return [float(x) for x in out]
+
+    def series(self) -> sp.Matrix:
+        """
+        Returns the truncated B-series as a sympy Matrix.
+
+        :rtype: sympy.Matrix
+        """
+        return self.symbolic_expr
+
+    def __repr__(self):
+        return repr(self.symbolic_expr)
+
+    # def __and__(self, other : 'BSeries') -> 'BSeries':
+    #     """
+    #     Returns the composition of two B-Series, assuming they are with respect
+    #     to the same variables and vector field. That is, given two B-Series:
+    #
+    #     .. math::
+    #
+    #         B_h(\\varphi, y_0) := \\sum_{|t| \\leq n} \\frac{h^{|t|}}{\\sigma(t)} \\varphi(t) F(t)(y_0),
+    #
+    #     .. math::
+    #
+    #         B_h(\\psi, y_0) := \\sum_{|t| \\leq n} \\frac{h^{|t|}}{\\sigma(t)} \\psi(t) F(t)(y_0),
+    #
+    #     returns their composition :math:`B_h(\\psi, B_h(\\varphi, y_0)) = B_h(\\varphi * \\psi, y_0)`,
+    #     where the product is the BCK product of characters. The truncation order of the resulting B-series
+    #     is the minimum of the truncation orders of the original two.
+    #
+    #     :param other: other
+    #     :type other: BSeries
+    #     """
+    #     if not isinstance(other, BSeries):
+    #         raise TypeError("Cannot multiply BSeries and object of type " + str(type(other)))
+    #     if self.y != other.y:
+    #         raise ValueError("Cannot compose B-Series: symbolic variables y of the two series do not match")
+    #     if self.f != other.f:
+    #         raise ValueError("Cannot compose B-Series: vector fields of the two series do not match")
+    #
+    #     return BSeries(self.y, self.f, self.weights * other.weights, min(self.order, other.order))

kauri/cem/__init__.py

@@ -0,0 +1,43 @@
+"""
+The ``kauri.cem`` sub-package implements the Calaque, Ebrahimi-Fard and Manchon (CEM) :cite:`calaque2011two` Hopf algebra
+:math:`(\\widetilde{H}, \\Delta_{CEM}, \\mu, \\varepsilon_{CEM}, \\bullet, S_{CEM})`, defined as follows.
+
+- :math:`\\widetilde{H}` is the space of non-empty trees, defined as
+  :math:`\\widetilde{H} = H / J` where :math:`J` is the ideal
+  generated by :math:`\\bullet - \\emptyset`.
+- The unit is the single-node tree, :math:`\\bullet`.
+- The counit map is defined by :math:`\\varepsilon_{CEM}(\\bullet) = 1`,
+  :math:`\\varepsilon_{CEM}(t) = 0` for all :math:`\\bullet \\neq t \\in \\widetilde{H}`.
+- Multiplication :math:`\\mu : \\widetilde{H} \\otimes \\widetilde{H} \\to \\widetilde{H}` is defined as the
+  commutative juxtaposition of two forests.
+- Comultiplication :math:`\\Delta : \\widetilde{H} \\to \\widetilde{H} \\otimes \\widetilde{H}` is defined as
+
+  .. math::
+
+      \\Delta_{CEM}(t) = \\sum_{s \\subset t} s \\otimes t / s
+
+  where the sum runs over all possible subforests :math:`s` of :math:`t`, and
+  :math:`t / s` is the tree obtained by contracting each connected component of
+  :math:`s` onto a vertex :cite:`calaque2011two`.
+- The antipode :math:`S_{CEM}` is defined by :math:`S_{CEM}(\\bullet) = \\bullet` and
+
+  .. math::
+
+      S_{CEM}(t) = -t - \\sum_{t, \\bullet \\neq s \\subset t} S_{CEM}(s) \\, t / s.
+
+.. note::
+
+    We adopt the singleton-reduced coproduct, where the singleton tree :math:`\\bullet`
+    appears in each forest at most once. This defines a Hopf algebra
+    on :math:`\\widetilde{H} = H / J`. There are alternative forms of the
+    coproduct defined directly on :math:`H`, but these do not define a Hopf
+    algebra.
+
+.. note::
+
+    Since :math:`\\bullet` is the unit, characters :math:`\\phi` on the resulting
+    Hopf algebra must satisfy :math:`\\phi(\\bullet) = 1`.
+
+"""
+
+from .cem import antipode, counit, coproduct, map_power, map_product