kauri 2.2.0__tar.gz → 2.3.0__tar.gz

{kauri-2.2.0 → kauri-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kauri
-Version: 2.2.0
+Version: 2.3.0
 Summary: Hopf algebras, B-series, and Runge-Kutta methods on rooted trees
 Author-email: Daniil Shmelev <daniil.shmelev23@imperial.ac.uk>
 License: Apache-2.0

{kauri-2.2.0 → kauri-2.3.0}/kauri/__init__.py

@@ -17,7 +17,7 @@
 Algebraic manipulation of rooted trees for the analysis of B-series and Runge-Kutta schemes.
 """
 
-__version__ = "2.2.0"
+__version__ = "2.3.0"
 
 __all__ = [
     # Core types
@@ -35,6 +35,10 @@ __all__ = [
     "planar_trees_of_order", "planar_trees_up_to_order",
     "colored_planar_trees_of_order", "colored_planar_trees_up_to_order",
     "colored_planar_tree_to_idx", "idx_to_colored_planar_tree",
+    "ordered_forests_of_order", "ordered_forests_up_to_order",
+    "colored_ordered_forests_of_order", "colored_ordered_forests_up_to_order",
+    "colored_ordered_forests", "colored_ordered_forest_to_idx",
+    "idx_to_colored_ordered_forest",
     "planar_canonical_to_recursive_permutation", "planar_recursive_to_canonical_permutation",
     # Display
     "display",
@@ -68,6 +72,10 @@ from .gentrees import (trees_of_order, trees_up_to_order,
                        planar_trees_of_order, planar_trees_up_to_order,
                        colored_planar_trees_of_order, colored_planar_trees_up_to_order,
                        colored_planar_tree_to_idx, idx_to_colored_planar_tree,
+                       ordered_forests_of_order, ordered_forests_up_to_order,
+                       colored_ordered_forests_of_order, colored_ordered_forests_up_to_order,
+                       colored_ordered_forests, colored_ordered_forest_to_idx,
+                       idx_to_colored_ordered_forest,
                        planar_canonical_to_recursive_permutation,
                        planar_recursive_to_canonical_permutation)
 from .rk import RK, rk_symbolic_weight, rk_order_cond

{kauri-2.2.0 → kauri-2.3.0}/kauri/cf_methods.py

@@ -1,100 +1,100 @@
-# Copyright 2026 Daniil Shmelev
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#    http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-# =========================================================================
-"""
-Named commutator-free (CF) Lie group integrators.
-
-Every method is a :class:`~kauri.cf.CFMethod` instance with a published
-Butcher-like tableau.  Use ``method.lb_character()`` for the numerical
-Lie-Butcher character and ``method.symbolic_lb_character()`` for the
-same character expressed in sympy rationals.
-
-``lie_euler``, ``lie_midpoint``, ``cfree_rk3`` and ``cfree_rk4`` follow
-the classical RKMK family with a single exponential per step
-(``J = 1``); their LB characters coincide with the elementary weights of
-the underlying Runge--Kutta method on planar trees.  These are the
-order-1, 2, 3 and 4 "base" commutator-free methods that fit the
-single-exponential-per-stage structure of :class:`CFMethod`.
-
-The genuinely multi-exponential schemes introduced in Celledoni,
-Marthinsen and Owren (2003) "Commutator-free Lie group methods" rely on
-flow reuse across stages (e.g. :math:`Y_4 = \\exp(k_3 - \\tfrac{1}{2}k_1)
-\\circ Y_2`), which the current :class:`CFMethod` API does not model:
-every stage is assumed to use a single exponential applied to
-:math:`y_n`.  Users who need those methods should construct a bespoke
-:class:`CFMethod` with a larger stage count or wait for multi-exponential
-stage support.
-"""
-from fractions import Fraction as _F
-
-from .cf import CFMethod
-
-# ---------------------------------------------------------------------------
-# J = 1 ("RKMK") instances
-# ---------------------------------------------------------------------------
-
-lie_euler = CFMethod(
-    a=[[_F(0)]],
-    betas=[[_F(1)]],
-    name="Lie-Euler",
-)
-lie_euler.__doc__ = """
-Lie-Euler method: ``y_{n+1} = exp(h f(y_n)) . y_n``.
-
-One stage, one exponential (J = 1).  Planar order 1.
-"""
-
-lie_midpoint = CFMethod(
-    a=[[_F(0), _F(0)],
-       [_F(1, 2), _F(0)]],
-    betas=[[_F(0), _F(1)]],
-    name="Lie-Midpoint",
-)
-lie_midpoint.__doc__ = """
-Implicit Lie-midpoint in its explicit RKMK form: evaluate ``f`` at a
-half-step and take one full-step exponential.
-
-Two stages, one exponential (J = 1).  Planar order 2.
-"""
-
-cfree_rk3 = CFMethod(
-    # Kutta's third-order method
-    a=[[_F(0), _F(0), _F(0)],
-       [_F(1, 2), _F(0), _F(0)],
-       [_F(-1), _F(2), _F(0)]],
-    betas=[[_F(1, 6), _F(2, 3), _F(1, 6)]],
-    name="CFree-RK3",
-)
-cfree_rk3.__doc__ = """
-RKMK variant of Kutta's third-order Runge--Kutta method.
-
-Three stages, one exponential (J = 1).  Planar order 3.
-"""
-
-cfree_rk4 = CFMethod(
-    # Classical fourth-order Runge--Kutta tableau
-    a=[[_F(0), _F(0), _F(0), _F(0)],
-       [_F(1, 2), _F(0), _F(0), _F(0)],
-       [_F(0), _F(1, 2), _F(0), _F(0)],
-       [_F(0), _F(0), _F(1), _F(0)]],
-    betas=[[_F(1, 6), _F(1, 3), _F(1, 3), _F(1, 6)]],
-    name="CFree-RK4",
-)
-cfree_rk4.__doc__ = """
-RKMK variant of the classical fourth-order Runge--Kutta method.
-
-Four stages, one exponential (J = 1).  Planar order 4.
-"""
-
-
+# Copyright 2026 Daniil Shmelev
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# =========================================================================
+"""
+Named commutator-free (CF) Lie group integrators.
+
+Every method is a :class:`~kauri.cf.CFMethod` instance with a published
+Butcher-like tableau.  Use ``method.lb_character()`` for the numerical
+Lie-Butcher character and ``method.symbolic_lb_character()`` for the
+same character expressed in sympy rationals.
+
+``lie_euler``, ``lie_midpoint``, ``cfree_rk3`` and ``cfree_rk4`` follow
+the classical RKMK family with a single exponential per step
+(``J = 1``); their LB characters coincide with the elementary weights of
+the underlying Runge--Kutta method on planar trees.  These are the
+order-1, 2, 3 and 4 "base" commutator-free methods that fit the
+single-exponential-per-stage structure of :class:`CFMethod`.
+
+The genuinely multi-exponential schemes introduced in Celledoni,
+Marthinsen and Owren (2003) "Commutator-free Lie group methods" rely on
+flow reuse across stages (e.g. :math:`Y_4 = \\exp(k_3 - \\tfrac{1}{2}k_1)
+\\circ Y_2`), which the current :class:`CFMethod` API does not model:
+every stage is assumed to use a single exponential applied to
+:math:`y_n`.  Users who need those methods should construct a bespoke
+:class:`CFMethod` with a larger stage count or wait for multi-exponential
+stage support.
+"""
+from fractions import Fraction as _F
+
+from .cf import CFMethod
+
+# ---------------------------------------------------------------------------
+# J = 1 ("RKMK") instances
+# ---------------------------------------------------------------------------
+
+lie_euler = CFMethod(
+    a=[[_F(0)]],
+    betas=[[_F(1)]],
+    name="Lie-Euler",
+)
+lie_euler.__doc__ = """
+Lie-Euler method: ``y_{n+1} = exp(h f(y_n)) . y_n``.
+
+One stage, one exponential (J = 1).  Planar order 1.
+"""
+
+lie_midpoint = CFMethod(
+    a=[[_F(0), _F(0)],
+       [_F(1, 2), _F(0)]],
+    betas=[[_F(0), _F(1)]],
+    name="Lie-Midpoint",
+)
+lie_midpoint.__doc__ = """
+Implicit Lie-midpoint in its explicit RKMK form: evaluate ``f`` at a
+half-step and take one full-step exponential.
+
+Two stages, one exponential (J = 1).  Planar order 2.
+"""
+
+cfree_rk3 = CFMethod(
+    # Kutta's third-order method
+    a=[[_F(0), _F(0), _F(0)],
+       [_F(1, 2), _F(0), _F(0)],
+       [_F(-1), _F(2), _F(0)]],
+    betas=[[_F(1, 6), _F(2, 3), _F(1, 6)]],
+    name="CFree-RK3",
+)
+cfree_rk3.__doc__ = """
+RKMK variant of Kutta's third-order Runge--Kutta method.
+
+Three stages, one exponential (J = 1).  Planar order 3.
+"""
+
+cfree_rk4 = CFMethod(
+    # Classical fourth-order Runge--Kutta tableau
+    a=[[_F(0), _F(0), _F(0), _F(0)],
+       [_F(1, 2), _F(0), _F(0), _F(0)],
+       [_F(0), _F(1, 2), _F(0), _F(0)],
+       [_F(0), _F(0), _F(1), _F(0)]],
+    betas=[[_F(1, 6), _F(1, 3), _F(1, 3), _F(1, 6)]],
+    name="CFree-RK4",
+)
+cfree_rk4.__doc__ = """
+RKMK variant of the classical fourth-order Runge--Kutta method.
+
+Four stages, one exponential (J = 1).  Planar order 4.
+"""
+
+

{kauri-2.2.0 → kauri-2.3.0}/kauri/gentrees.py

@@ -284,6 +284,129 @@ def colored_planar_trees_up_to_order(order: int, d: int):
         yield from colored_planar_trees_of_order(current_order, d)
 
 
+def ordered_forests_of_order(order: int):
+    """
+    Yields ordered forests of planar rooted trees with a fixed total order.
+
+    Order 0 contains only the empty ordered forest.
+    """
+    from .trees import validate_order
+
+    validate_order(order)
+    yield from _ordered_forest_list_exact_cached(order)
+
+
+@cache
+def _planar_tree_node_pairs(max_order: int) -> tuple:
+    return tuple(
+        (tree, tree.nodes()) for tree in planar_trees_up_to_order(max_order)
+        if tree.nodes() != 0
+    )
+
+
+@cache
+def _ordered_forest_list_exact_cached(order: int) -> tuple:
+    return _ordered_forest_strata_cached(order)[order]
+
+
+@cache
+def _ordered_forest_strata_cached(max_order: int) -> tuple:
+    from .trees import EMPTY_ORDERED_FOREST, OrderedForest
+
+    tree_pairs = _planar_tree_node_pairs(max_order)
+    strata = [(EMPTY_ORDERED_FOREST,)]
+    for order in range(1, max_order + 1):
+        out = []
+        for tree, nodes in tree_pairs:
+            if nodes > order:
+                break
+            remaining = order - nodes
+            if remaining == 0:
+                out.append(OrderedForest((tree,)))
+            else:
+                for suffix in strata[remaining]:
+                    out.append(OrderedForest((tree,) + suffix.tree_list))
+        strata.append(tuple(out))
+    return tuple(strata)
+
+
+def ordered_forests_up_to_order(order: int):
+    """
+    Yields ordered forests of planar rooted trees up to a given total order.
+    """
+    from .trees import validate_order
+
+    validate_order(order)
+    yield from _ordered_forest_list_cached(order)
+
+
+@cache
+def _ordered_forest_list_cached(max_order: int) -> tuple:
+    return tuple(
+        forest
+        for stratum in _ordered_forest_strata_cached(max_order)
+        for forest in stratum
+    )
+
+
+def colored_ordered_forests_of_order(order: int, d: int):
+    """
+    Yields colored ordered forests with a fixed total order and *d* colors.
+
+    Each node is decorated with a color from {0, ..., d-1}.
+    """
+    from .trees import validate_order
+
+    validate_order(order)
+    _validate_num_colors(d)
+    yield from _colored_ordered_forest_list_exact_cached(order, d)
+
+
+@cache
+def _colored_planar_tree_node_pairs(max_order: int, d: int) -> tuple:
+    return tuple(
+        (tree, tree.nodes()) for tree in _colored_planar_tree_list_cached(max_order, d)
+        if tree.nodes() != 0
+    )
+
+
+@cache
+def _colored_ordered_forest_list_exact_cached(order: int, d: int) -> tuple:
+    return _colored_ordered_forest_strata_cached(order, d)[order]
+
+
+@cache
+def _colored_ordered_forest_strata_cached(max_order: int, d: int) -> tuple:
+    from .trees import EMPTY_ORDERED_FOREST, OrderedForest
+
+    tree_pairs = _colored_planar_tree_node_pairs(max_order, d)
+    strata = [(EMPTY_ORDERED_FOREST,)]
+    for order in range(1, max_order + 1):
+        out = []
+        for tree, nodes in tree_pairs:
+            if nodes > order:
+                break
+            remaining = order - nodes
+            if remaining == 0:
+                out.append(OrderedForest((tree,)))
+            else:
+                for suffix in strata[remaining]:
+                    out.append(OrderedForest((tree,) + suffix.tree_list))
+        strata.append(tuple(out))
+    return tuple(strata)
+
+
+def colored_ordered_forests_up_to_order(order: int, d: int):
+    """
+    Yields colored ordered forests up to a given total order with *d* colors.
+    """
+    from .trees import validate_order
+
+    validate_order(order)
+    _validate_num_colors(d)
+    yield from _colored_ordered_forest_list_cached(order, d)
+
+
 # ---------------------------------------------------------------------------
 # Colored tree indexing
 # ---------------------------------------------------------------------------
@@ -314,6 +437,23 @@ def _colored_planar_tree_lookup_cached(max_order: int, d: int) -> dict:
     return {t: i for i, t in enumerate(trees)}
 
 
+@cache
+def _colored_ordered_forest_list_cached(max_order: int, d: int) -> tuple:
+    """Cached tuple of all colored ordered forests up to max_order with d colors."""
+    return tuple(
+        forest
+        for stratum in _colored_ordered_forest_strata_cached(max_order, d)
+        for forest in stratum
+    )
+
+
+@cache
+def _colored_ordered_forest_lookup_cached(max_order: int, d: int) -> dict:
+    """Cached dict mapping OrderedForest -> index."""
+    forests = _colored_ordered_forest_list_cached(max_order, d)
+    return {f: i for i, f in enumerate(forests)}
+
+
 def colored_trees(d: int, max_order: int) -> list[Tree]:
     """
     Returns all distinct colored rooted trees up to a given order with *d* colors,
@@ -419,6 +559,62 @@ def idx_to_colored_planar_tree(idx: int, d: int, max_order: int):
     return trees[idx]
 
 
+def colored_ordered_forests(d: int, max_order: int) -> list:
+    """
+    Returns all colored ordered forests up to a given total order with *d* colors,
+    starting with the empty ordered forest.
+
+    :param d: Number of colors.
+    :type d: int
+    :param max_order: Maximum total number of nodes.
+    :type max_order: int
+    :return: List of colored ordered forests.
+    :rtype: list[OrderedForest]
+    """
+    _validate_num_colors(d)
+    return list(_colored_ordered_forest_list_cached(max_order, d))
+
+
+def colored_ordered_forest_to_idx(forest, d: int, max_order: int) -> int:
+    """
+    Returns the index of a colored ordered forest in the canonical enumeration.
+
+    :param forest: A colored ordered forest.
+    :type forest: OrderedForest
+    :param d: Number of colors.
+    :type d: int
+    :param max_order: Maximum total number of nodes.
+    :type max_order: int
+    :return: Index in the enumeration.
+    :rtype: int
+    """
+    _validate_num_colors(d)
+    lookup = _colored_ordered_forest_lookup_cached(max_order, d)
+    if forest not in lookup:
+        raise ValueError(f"Ordered forest {forest} not found in enumeration for d={d}, max_order={max_order}")
+    return lookup[forest]
+
+
+def idx_to_colored_ordered_forest(idx: int, d: int, max_order: int):
+    """
+    Returns the colored ordered forest at a given index in the canonical enumeration.
+
+    :param idx: Index, with 0 the empty ordered forest.
+    :type idx: int
+    :param d: Number of colors.
+    :type d: int
+    :param max_order: Maximum total number of nodes.
+    :type max_order: int
+    :return: The colored ordered forest at the given index.
+    :rtype: OrderedForest
+    """
+    _validate_num_colors(d)
+    forests = _colored_ordered_forest_list_cached(max_order, d)
+    if idx < 0 or idx >= len(forests):
+        raise ValueError(f"idx {idx} out of range [0, {len(forests)}) for d={d}, max_order={max_order}")
+    return forests[idx]
+
+
 # ---------------------------------------------------------------------------
 # Recursive tree ordering and canonical-recursive permutation
 #

{kauri-2.2.0 → kauri-2.3.0}/kauri/lb_substitution.py

@@ -1,295 +1,295 @@
-# Copyright 2026 Daniil Shmelev
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#    http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-# =========================================================================
-"""Ordered-forest substitution for Lie--Butcher series.
-
-The core operation implemented here is the ordered-forest coaction
-``Delta_W`` from Lundervold--Munthe-Kaas: given a logarithmic linear map
-``psi`` on ordered forests and a basis-aware outer character ``beta``,
-``substitute(psi, beta)`` returns the substituted character
-``psi star_W beta = (psi tensor beta) Delta_W``.
-
-This is the LB-series analogue of ordinary B-series substitution used by
-the reused-stage CF methods.
-"""
-from __future__ import annotations
-
-from collections import Counter
-from functools import lru_cache
-from itertools import permutations, product
-
-from .maps import Map
-from .trees import (
-    EMPTY_ORDERED_FOREST,
-    ForestSum,
-    OrderedForest,
-    PlanarTree,
-)
-from .generic_algebra import mkw_apply, mkw_base_char_func
-from .mkw.mkw import (
-    _as_basis_aware_map,
-    _basis_aware_func,
-)
-
-
-def _nonempty_trees(forest: OrderedForest) -> tuple[PlanarTree, ...]:
-    return tuple(t for t in forest.tree_list if t.list_repr is not None)
-
-
-def _forest_from_trees(trees: tuple[PlanarTree, ...]) -> OrderedForest:
-    return OrderedForest(trees) if trees else EMPTY_ORDERED_FOREST
-
-
-def _flatten_forest(forest: OrderedForest):
-    """Return vertex records for a planar forest in preorder."""
-    records = []
-    root_ids = []
-
-    def visit(tree: PlanarTree, parent, child_index):
-        node_id = len(records)
-        records.append(
-            {
-                "parent": parent,
-                "child_index": child_index,
-                "children": [],
-            }
-        )
-        if parent is None:
-            root_ids.append(node_id)
-        else:
-            records[parent]["children"].append(node_id)
-        for i, child_repr in enumerate(tree.list_repr[:-1]):
-            visit(PlanarTree(child_repr), node_id, i)
-
-    for i, tree in enumerate(_nonempty_trees(forest)):
-        visit(tree, None, i)
-    return tuple(records), tuple(root_ids)
-
-
-def _set_partitions(items: tuple[int, ...]):
-    if not items:
-        yield ()
-        return
-
-    first, rest = items[0], items[1:]
-    for partition in _set_partitions(rest):
-        yield (frozenset((first,)),) + partition
-        for i, block in enumerate(partition):
-            yield (
-                partition[:i]
-                + (frozenset((*block, first)),)
-                + partition[i + 1 :]
-            )
-
-
-def _block_roots(block: frozenset[int], records) -> tuple[int, ...]:
-    return tuple(v for v in block if records[v]["parent"] not in block)
-
-
-def _sibling_list(parent, records, root_ids):
-    return root_ids if parent is None else tuple(records[parent]["children"])
-
-
-def _is_consecutive(values: list[int]) -> bool:
-    return bool(values) and max(values) - min(values) + 1 == len(values)
-
-
-def _is_admissible_block(block: frozenset[int], records, root_ids) -> bool:
-    roots = _block_roots(block, records)
-    parents = {records[root]["parent"] for root in roots}
-    if len(parents) != 1:
-        return False
-
-    parent = next(iter(parents))
-    siblings = _sibling_list(parent, records, root_ids)
-    root_positions = [siblings.index(root) for root in roots]
-    if not _is_consecutive(root_positions):
-        return False
-
-    for vertex in block:
-        children = records[vertex]["children"]
-        for index, child in enumerate(children):
-            if child in block:
-                if any(
-                    right_child not in block
-                    for right_child in children[index + 1 :]
-                ):
-                    return False
-    return True
-
-
-def _induced_forest(block: frozenset[int], records) -> OrderedForest:
-    roots = sorted(_block_roots(block, records))
-
-    def build_tree(vertex: int) -> PlanarTree:
-        children = [
-            build_tree(child).list_repr
-            for child in records[vertex]["children"]
-            if child in block
-        ]
-        return PlanarTree(tuple(children) + (0,))
-
-    return _forest_from_trees(tuple(build_tree(root) for root in roots))
-
-
-def _linear_extensions(items: tuple[int, ...], constraints: set[tuple[int, int]]):
-    for candidate in permutations(items):
-        positions = {item: i for i, item in enumerate(candidate)}
-        if all(positions[left] < positions[right] for left, right in constraints):
-            yield candidate
-
-
-def _quotient_forests(
-    partition: tuple[frozenset[int], ...],
-    records,
-    root_ids,
-) -> Counter:
-    block_of = {
-        vertex: block_index
-        for block_index, block in enumerate(partition)
-        for vertex in block
-    }
-    parent_of: dict[int, int | None] = {}
-    attachment_site: dict[int, int | None] = {}
-    roots_by_block: dict[int, tuple[int, ...]] = {}
-
-    for block_index, block in enumerate(partition):
-        roots = _block_roots(block, records)
-        roots_by_block[block_index] = roots
-        parent = records[roots[0]]["parent"]
-        attachment_site[block_index] = parent
-        parent_of[block_index] = None if parent is None else block_of[parent]
-
-    children_by_parent: dict[int | None, list[int]] = {None: []}
-    for block_index, parent_index in parent_of.items():
-        children_by_parent.setdefault(parent_index, [])
-        children_by_parent.setdefault(block_index, [])
-        if parent_index is None:
-            children_by_parent[None].append(block_index)
-        else:
-            children_by_parent[parent_index].append(block_index)
-
-    choices = []
-    for parent_index, children in children_by_parent.items():
-        child_tuple = tuple(children)
-        constraints: set[tuple[int, int]] = set()
-        for left in child_tuple:
-            for right in child_tuple:
-                if left == right:
-                    continue
-                if attachment_site[left] != attachment_site[right]:
-                    continue
-                site = attachment_site[left]
-                siblings = _sibling_list(site, records, root_ids)
-                left_pos = min(siblings.index(root) for root in roots_by_block[left])
-                right_pos = min(siblings.index(root) for root in roots_by_block[right])
-                if left_pos < right_pos:
-                    constraints.add((left, right))
-        choices.append(
-            (
-                parent_index,
-                tuple(_linear_extensions(child_tuple, constraints)),
-            )
-        )
-
-    out = Counter()
-    for selected_orders in product(*(orders for _, orders in choices)):
-        order_by_parent = {
-            parent: order
-            for (parent, _), order in zip(choices, selected_orders)
-        }
-
-        def build_tree(block_index: int) -> PlanarTree:
-            children = [
-                build_tree(child_index).list_repr
-                for child_index in order_by_parent[block_index]
-            ]
-            return PlanarTree(tuple(children) + (0,))
-
-        roots = tuple(build_tree(block_index) for block_index in order_by_parent[None])
-        out[_forest_from_trees(roots)] += 1
-    return out
-
-
-@lru_cache(maxsize=None)
-def delta_w_terms(forest: OrderedForest):
-    """Return terms of the ordered-forest contraction coaction ``Delta_W``.
-
-    Each term is ``(coeff, left_factors, right_forest)``, where
-    ``left_factors`` is the symmetric product of admissible subforests.
-    """
-    forest = forest.simplify()
-    trees = _nonempty_trees(forest)
-    if not trees:
-        return ((1, (), EMPTY_ORDERED_FOREST),)
-
-    records, root_ids = _flatten_forest(forest)
-    terms = []
-    vertices = tuple(range(len(records)))
-    for partition in _set_partitions(vertices):
-        ordered_partition = tuple(sorted(partition, key=lambda block: min(block)))
-        if not all(
-            _is_admissible_block(block, records, root_ids)
-            for block in ordered_partition
-        ):
-            continue
-        left_factors = tuple(
-            _induced_forest(block, records)
-            for block in ordered_partition
-        )
-        for right_forest, coeff in _quotient_forests(
-            ordered_partition, records, root_ids
-        ).items():
-            terms.append((coeff, left_factors, right_forest))
-    return tuple(terms)
-
-
-def substitute(logarithmic: Map, character: Map) -> Map:
-    """Return the substituted character ``logarithmic star_W character``."""
-    outer = _basis_aware_func(character)
-
-    def _subst(x):
-        if isinstance(x, ForestSum):
-            return mkw_apply(x, _subst)
-        forest = x.as_ordered_forest() if isinstance(x, PlanarTree) else x
-        total = 0
-        for coeff, left_factors, right_forest in delta_w_terms(forest):
-            left_value = 1
-            for factor in left_factors:
-                left_value *= logarithmic(factor)
-            total += coeff * left_value * outer(right_forest)
-        return total
-
-    return _as_basis_aware_map(_subst)
-
-
-def frozen_exponential_character(weight) -> Map:
-    """The pullback character of one frozen exponential ``exp(weight * F)``.
-
-    On ordered trees this is the bullet-only character:
-
-    - ``alpha(empty) = 1``,
-    - ``alpha(bullet) = weight``,
-    - ``alpha(t) = 0`` for every tree with more than one node.
-    """
-
-    return _as_basis_aware_map(
-        mkw_base_char_func(
-            lambda tree, coeff=weight: (
-                1
-                if tree.list_repr is None
-                else (coeff if len(tree.list_repr) == 1 else 0)
-            )
-        )
-    )
+# Copyright 2026 Daniil Shmelev
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# =========================================================================
+"""Ordered-forest substitution for Lie--Butcher series.
+
+The core operation implemented here is the ordered-forest coaction
+``Delta_W`` from Lundervold--Munthe-Kaas: given a logarithmic linear map
+``psi`` on ordered forests and a basis-aware outer character ``beta``,
+``substitute(psi, beta)`` returns the substituted character
+``psi star_W beta = (psi tensor beta) Delta_W``.
+
+This is the LB-series analogue of ordinary B-series substitution used by
+the reused-stage CF methods.
+"""
+from __future__ import annotations
+
+from collections import Counter
+from functools import lru_cache
+from itertools import permutations, product
+
+from .maps import Map
+from .trees import (
+    EMPTY_ORDERED_FOREST,
+    ForestSum,
+    OrderedForest,
+    PlanarTree,
+)
+from .generic_algebra import mkw_apply, mkw_base_char_func
+from .mkw.mkw import (
+    _as_basis_aware_map,
+    _basis_aware_func,
+)
+
+
+def _nonempty_trees(forest: OrderedForest) -> tuple[PlanarTree, ...]:
+    return tuple(t for t in forest.tree_list if t.list_repr is not None)
+
+
+def _forest_from_trees(trees: tuple[PlanarTree, ...]) -> OrderedForest:
+    return OrderedForest(trees) if trees else EMPTY_ORDERED_FOREST
+
+
+def _flatten_forest(forest: OrderedForest):
+    """Return vertex records for a planar forest in preorder."""
+    records = []
+    root_ids = []
+
+    def visit(tree: PlanarTree, parent, child_index):
+        node_id = len(records)
+        records.append(
+            {
+                "parent": parent,
+                "child_index": child_index,
+                "children": [],
+            }
+        )
+        if parent is None:
+            root_ids.append(node_id)
+        else:
+            records[parent]["children"].append(node_id)
+        for i, child_repr in enumerate(tree.list_repr[:-1]):
+            visit(PlanarTree(child_repr), node_id, i)
+
+    for i, tree in enumerate(_nonempty_trees(forest)):
+        visit(tree, None, i)
+    return tuple(records), tuple(root_ids)
+
+
+def _set_partitions(items: tuple[int, ...]):
+    if not items:
+        yield ()
+        return
+
+    first, rest = items[0], items[1:]
+    for partition in _set_partitions(rest):
+        yield (frozenset((first,)),) + partition
+        for i, block in enumerate(partition):
+            yield (
+                partition[:i]
+                + (frozenset((*block, first)),)
+                + partition[i + 1 :]
+            )
+
+
+def _block_roots(block: frozenset[int], records) -> tuple[int, ...]:
+    return tuple(v for v in block if records[v]["parent"] not in block)
+
+
+def _sibling_list(parent, records, root_ids):
+    return root_ids if parent is None else tuple(records[parent]["children"])
+
+
+def _is_consecutive(values: list[int]) -> bool:
+    return bool(values) and max(values) - min(values) + 1 == len(values)
+
+
+def _is_admissible_block(block: frozenset[int], records, root_ids) -> bool:
+    roots = _block_roots(block, records)
+    parents = {records[root]["parent"] for root in roots}
+    if len(parents) != 1:
+        return False
+
+    parent = next(iter(parents))
+    siblings = _sibling_list(parent, records, root_ids)
+    root_positions = [siblings.index(root) for root in roots]
+    if not _is_consecutive(root_positions):
+        return False
+
+    for vertex in block:
+        children = records[vertex]["children"]
+        for index, child in enumerate(children):
+            if child in block:
+                if any(
+                    right_child not in block
+                    for right_child in children[index + 1 :]
+                ):
+                    return False
+    return True
+
+
+def _induced_forest(block: frozenset[int], records) -> OrderedForest:
+    roots = sorted(_block_roots(block, records))
+
+    def build_tree(vertex: int) -> PlanarTree:
+        children = [
+            build_tree(child).list_repr
+            for child in records[vertex]["children"]
+            if child in block
+        ]
+        return PlanarTree(tuple(children) + (0,))
+
+    return _forest_from_trees(tuple(build_tree(root) for root in roots))
+
+
+def _linear_extensions(items: tuple[int, ...], constraints: set[tuple[int, int]]):
+    for candidate in permutations(items):
+        positions = {item: i for i, item in enumerate(candidate)}
+        if all(positions[left] < positions[right] for left, right in constraints):
+            yield candidate
+
+
+def _quotient_forests(
+    partition: tuple[frozenset[int], ...],
+    records,
+    root_ids,
+) -> Counter:
+    block_of = {
+        vertex: block_index
+        for block_index, block in enumerate(partition)
+        for vertex in block
+    }
+    parent_of: dict[int, int | None] = {}
+    attachment_site: dict[int, int | None] = {}
+    roots_by_block: dict[int, tuple[int, ...]] = {}
+
+    for block_index, block in enumerate(partition):
+        roots = _block_roots(block, records)
+        roots_by_block[block_index] = roots
+        parent = records[roots[0]]["parent"]
+        attachment_site[block_index] = parent
+        parent_of[block_index] = None if parent is None else block_of[parent]
+
+    children_by_parent: dict[int | None, list[int]] = {None: []}
+    for block_index, parent_index in parent_of.items():
+        children_by_parent.setdefault(parent_index, [])
+        children_by_parent.setdefault(block_index, [])
+        if parent_index is None:
+            children_by_parent[None].append(block_index)
+        else:
+            children_by_parent[parent_index].append(block_index)
+
+    choices = []
+    for parent_index, children in children_by_parent.items():
+        child_tuple = tuple(children)
+        constraints: set[tuple[int, int]] = set()
+        for left in child_tuple:
+            for right in child_tuple:
+                if left == right:
+                    continue
+                if attachment_site[left] != attachment_site[right]:
+                    continue
+                site = attachment_site[left]
+                siblings = _sibling_list(site, records, root_ids)
+                left_pos = min(siblings.index(root) for root in roots_by_block[left])
+                right_pos = min(siblings.index(root) for root in roots_by_block[right])
+                if left_pos < right_pos:
+                    constraints.add((left, right))
+        choices.append(
+            (
+                parent_index,
+                tuple(_linear_extensions(child_tuple, constraints)),
+            )
+        )
+
+    out = Counter()
+    for selected_orders in product(*(orders for _, orders in choices)):
+        order_by_parent = {
+            parent: order
+            for (parent, _), order in zip(choices, selected_orders)
+        }
+
+        def build_tree(block_index: int) -> PlanarTree:
+            children = [
+                build_tree(child_index).list_repr
+                for child_index in order_by_parent[block_index]
+            ]
+            return PlanarTree(tuple(children) + (0,))
+
+        roots = tuple(build_tree(block_index) for block_index in order_by_parent[None])
+        out[_forest_from_trees(roots)] += 1
+    return out
+
+
+@lru_cache(maxsize=None)
+def delta_w_terms(forest: OrderedForest):
+    """Return terms of the ordered-forest contraction coaction ``Delta_W``.
+
+    Each term is ``(coeff, left_factors, right_forest)``, where
+    ``left_factors`` is the symmetric product of admissible subforests.
+    """
+    forest = forest.simplify()
+    trees = _nonempty_trees(forest)
+    if not trees:
+        return ((1, (), EMPTY_ORDERED_FOREST),)
+
+    records, root_ids = _flatten_forest(forest)
+    terms = []
+    vertices = tuple(range(len(records)))
+    for partition in _set_partitions(vertices):
+        ordered_partition = tuple(sorted(partition, key=lambda block: min(block)))
+        if not all(
+            _is_admissible_block(block, records, root_ids)
+            for block in ordered_partition
+        ):
+            continue
+        left_factors = tuple(
+            _induced_forest(block, records)
+            for block in ordered_partition
+        )
+        for right_forest, coeff in _quotient_forests(
+            ordered_partition, records, root_ids
+        ).items():
+            terms.append((coeff, left_factors, right_forest))
+    return tuple(terms)
+
+
+def substitute(logarithmic: Map, character: Map) -> Map:
+    """Return the substituted character ``logarithmic star_W character``."""
+    outer = _basis_aware_func(character)
+
+    def _subst(x):
+        if isinstance(x, ForestSum):
+            return mkw_apply(x, _subst)
+        forest = x.as_ordered_forest() if isinstance(x, PlanarTree) else x
+        total = 0
+        for coeff, left_factors, right_forest in delta_w_terms(forest):
+            left_value = 1
+            for factor in left_factors:
+                left_value *= logarithmic(factor)
+            total += coeff * left_value * outer(right_forest)
+        return total
+
+    return _as_basis_aware_map(_subst)
+
+
+def frozen_exponential_character(weight) -> Map:
+    """The pullback character of one frozen exponential ``exp(weight * F)``.
+
+    On ordered trees this is the bullet-only character:
+
+    - ``alpha(empty) = 1``,
+    - ``alpha(bullet) = weight``,
+    - ``alpha(t) = 0`` for every tree with more than one node.
+    """
+
+    return _as_basis_aware_map(
+        mkw_base_char_func(
+            lambda tree, coeff=weight: (
+                1
+                if tree.list_repr is None
+                else (coeff if len(tree.list_repr) == 1 else 0)
+            )
+        )
+    )

{kauri-2.2.0 → kauri-2.3.0}/kauri.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kauri
-Version: 2.2.0
+Version: 2.3.0
 Summary: Hopf algebras, B-series, and Runge-Kutta methods on rooted trees
 Author-email: Daniil Shmelev <daniil.shmelev23@imperial.ac.uk>
 License: Apache-2.0

{kauri-2.2.0 → kauri-2.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "kauri"
-version = "2.2.0"
+version = "2.3.0"
 description = "Hopf algebras, B-series, and Runge-Kutta methods on rooted trees"
 readme = "README.md"
 requires-python = ">=3.9"