plaid.storage.common.tree_handling
==================================

.. py:module:: plaid.storage.common.tree_handling

.. autoapi-nested-parse::

   Common tree handling utilities.

   This module provides utilities for flattening and unflattening CGNS trees,
   converting between hierarchical tree structures and flat dictionaries for
   storage and serialization purposes.



Functions
---------

.. autoapisummary::

   plaid.storage.common.tree_handling.flatten_cgns_tree
   plaid.storage.common.tree_handling.nodes_to_tree
   plaid.storage.common.tree_handling.unflatten_cgns_tree


Module Contents
---------------

.. py:function:: flatten_cgns_tree(pyTree: plaid.types.CGNSTree) -> tuple[dict[str, object], dict[str, str]]

   Flatten a CGNS tree into dictionaries of primitives.

   :param pyTree: The CGNS tree to flatten.
   :type pyTree: CGNSTree

   :returns:     - flat: dict of paths to primitive values
                 - cgns_types: dict of paths to CGNS type strings
   :rtype: tuple[dict[str, object], dict[str, str]]


.. py:function:: nodes_to_tree(nodes: dict[str, plaid.types.CGNSTree]) -> Optional[plaid.types.CGNSTree]

   Reconstruct a CGNS tree from a dictionary of nodes keyed by their paths.

   Each node is assumed to follow the CGNSTree format:
   [name: str, data: Any, children: List[CGNSTree], cgns_type: str]

   The dictionary keys are the full paths to each node, e.g. "Base1/Zone1/Field1".

   :param nodes: A dictionary mapping node paths to CGNSTree nodes.
   :type nodes: Dict[str, CGNSTree]

   :returns: The root CGNSTree node with all children linked,
             or None if the input dictionary is empty.
   :rtype: Optional[CGNSTree]

   .. note::

      - Nodes with a path of length 1 are treated as root-level nodes.
      - The root node is named "CGNSTree" with type "CGNSTree_t".
      - Parent-child relationships are reconstructed using path prefixes.


.. py:function:: unflatten_cgns_tree(flat: dict[str, object], cgns_types: dict[str, str]) -> plaid.types.CGNSTree

   Reconstruct a CGNS tree from flattened dictionaries of data and types.

   This function takes a "flat" representation of a CGNS tree, where each node
   is stored in a dictionary keyed by its full path (e.g., "Base1/Zone1/Field1"),
   and another dictionary mapping each path to its CGNS type. It rebuilds the
   original tree structure by creating nodes and linking them according to their paths.

   :param flat: Dictionary mapping node paths to their data values.
                The data can be a scalar, list, numpy array, or None.
   :type flat: dict[str, object]
   :param cgns_types: Dictionary mapping node paths to CGNS type strings
                      (e.g., "Zone_t", "FlowSolution_t").
   :type cgns_types: dict[str, str]

   :returns: The reconstructed CGNS tree with nodes properly nested according
             to their paths. Each node is a list in the format:
             [name: str, data: Any, children: List[CGNSTree], cgns_type: str]
   :rtype: CGNSTree

   .. rubric:: Example

   >>> flat = {
   >>>     "Base1": None,
   >>>     "Base1/Zone1": [10, 20],
   >>>     "Base1/Zone1/Field1": [1.0, 2.0]
   >>> }
   >>> cgns_types = {
   >>>     "Base1": "CGNSBase_t",
   >>>     "Base1/Zone1": "Zone_t",
   >>>     "Base1/Zone1/Field1": "FlowSolution_t"
   >>> }
   >>> tree = unflatten_cgns_tree(flat, cgns_types)