plaid.utils.cgns_helper¶

Utility functions for working with CGNS trees and nodes.

Functions¶

`get_base_names`(→ list[str])	Get a list of base names from a CGNSTree.
`get_time_values`(→ numpy.ndarray)	Get consistent time values from CGNSBase_t nodes in a CGNSTree.
`show_cgns_tree`(pyTree[, pre])	Pretty print for CGNS Tree.
`fix_cgns_tree_types`(→ plaid.types.CGNSTree)	Recursively fix the data types of a CGNS tree node and its children.
`compare_cgns_trees`(→ bool)	Recursively compare two CGNS trees for exact equality, ignoring the order of children.
`compare_leaves`(→ bool)	Compare two leaf values in a CGNS tree or flattened structure, handling arrays and scalars.
`compare_cgns_trees_no_types`(→ bool)	Recursively compare two CGNS trees ignoring the order of children and relaxing strict type checks.
`summarize_cgns_tree`(→ str)	Provide a summary of a CGNS tree's contents.
`flatten_cgns_tree`(→ tuple[dict[str, object], dict[str, ...)	Flatten a CGNS tree into dictionaries of primitives.
`nodes_to_tree`(→ Optional[plaid.types.CGNSTree])	Reconstruct a CGNS tree from a dictionary of nodes keyed by their paths.
`unflatten_cgns_tree`(→ plaid.types.CGNSTree)	Reconstruct a CGNS tree from flattened dictionaries of data and types.
`update_features_for_CGNS_compatibility`(features, ...)	Expand a list of feature paths to include all CGNS hierarchy nodes and metadata required for compatibility.

Module Contents¶

get_base_names(tree: plaid.types.CGNSTree, full_path: bool = False, unique: bool = False) → list[str][source]¶

Get a list of base names from a CGNSTree.

Parameters:

tree (CGNSTree) – The CGNSTree containing the CGNSBase_t nodes.
full_path (bool, optional) – If True, return full base paths including ‘/’ separators. Defaults to False.
unique (bool, optional) – If True, return unique base names. Defaults to False.

Returns:

A list of base names.

Return type:

list[str]

get_time_values(tree: plaid.types.CGNSTree) → numpy.ndarray[source]¶

Get consistent time values from CGNSBase_t nodes in a CGNSTree.

Parameters:: tree (CGNSTree) – The CGNSTree containing CGNSBase_t nodes.
Returns:: An array of consistent time values.
Return type:: np.ndarray
Raises:: AssertionError – If the time values across bases are not consistent.

show_cgns_tree(pyTree: plaid.types.CGNSTree, pre: str = '')[source]¶

Pretty print for CGNS Tree.

Parameters:

pyTree (CGNSTree) – CGNS tree to print
pre (str, optional) – indentation of print. Defaults to ‘’.

fix_cgns_tree_types(tree: plaid.types.CGNSTree) → plaid.types.CGNSTree[source]¶

Recursively fix the data types of a CGNS tree node and its children.

This function ensures that data arrays match the expected CGNS types:

“IndexArray_t”: converted to integer arrays and stacked
“Zone_t”: stacked as numpy arrays
“Elements_t”, “CGNSBase_t”, “BaseIterativeData_t”: converted to integer arrays

Parameters:: tree (CGNSTree) – A CGNS tree of the form [name: str, data: Any, children: List[CGNSTree], cgns_type: str].
Returns:: A new CGNS tree node with corrected data types and recursively fixed children.
Return type:: CGNSTree

Example

>>> node = ["Zone1", [[1, 2], [3, 4]], [], "Zone_t"]
>>> fixed_node = fix_cgns_tree_types(node)
>>> fixed_node[1].shape
(2, 2)

compare_cgns_trees(tree1: plaid.types.CGNSTree, tree2: plaid.types.CGNSTree, path: str = 'CGNSTree') → bool[source]¶

Recursively compare two CGNS trees for exact equality, ignoring the order of children.

This function checks:

Node names
Node data (numpy arrays or scalars) with exact dtype and values
Number and names of children nodes
CGNS type (stored as the extra field)

It prints informative messages whenever a mismatch is found, including the path in the tree where the mismatch occurs.

Parameters:

tree1 (CGNSTree) – The first CGNS tree node to compare.
tree2 (CGNSTree) – The second CGNS tree node to compare.
path (str, optional) – The current path in the tree for error messages. Defaults to “CGNSTree”.

Returns:

True if the trees are identical (including node names, data, types,: and children), False otherwise.

Return type:

bool

Example

>>> identical = compare_cgns_trees(tree1, tree2)
>>> if identical:
>>>     print("The trees are identical")
>>> else:
>>>     print("The trees differ")

compare_leaves(d1: Any, d2: Any) → bool[source]¶

Compare two leaf values in a CGNS tree or flattened structure, handling arrays and scalars.

This function supports:

NumPy arrays, including byte arrays (converted to str)
Floating-point arrays or scalars (compared with tolerance)
Integer arrays or scalars (exact comparison)
Strings and None

Parameters:

d1 (Any) – First value to compare (scalar or np.ndarray).
d2 (Any) – Second value to compare (scalar or np.ndarray).

Returns:

True if the values are considered equal, False otherwise.

Return type:

bool

Note

Floating-point comparisons use np.allclose or np.isclose with rtol=1e-7 and atol=0.
Byte arrays (dtype.kind == “S”) are converted to string before comparison.

Examples

>>> compare_leaves(np.array([1.0, 2.0]), np.array([1.0, 2.0]))
True
>>> compare_leaves(3.0, 3.00000001)
True
>>> compare_leaves(np.array([1, 2]), np.array([2, 1]))
False

compare_cgns_trees_no_types(tree1: plaid.types.CGNSTree, tree2: plaid.types.CGNSTree, path: str = 'CGNSTree') → bool[source]¶

Recursively compare two CGNS trees ignoring the order of children and relaxing strict type checks.

This function is useful for heterogeneous or nested CGNS samples, such as those encountered in Hugging Face Arrow datasets. It compares: - Node names - Node data using compare_leaves (supports arrays, scalars, strings) - CGNS type (extra field) - Children nodes by name, ignoring their order

Parameters:

tree1 (CGNSTree) – The first CGNS tree node to compare.
tree2 (CGNSTree) – The second CGNS tree node to compare.
path (str, optional) – Path for error reporting. Defaults to “CGNSTree”.

Returns:

True if the trees are considered equivalent, False otherwise.

Return type:

bool

Example

>>> identical = compare_cgns_trees_no_types(tree1, tree2)
>>> if identical:
>>>     print("The trees match ignoring types")
>>> else:
>>>     print("The trees differ")

summarize_cgns_tree(pyTree: plaid.types.CGNSTree, verbose=True) → str[source]¶

Provide a summary of a CGNS tree’s contents.

Parameters:

pyTree (CGNSTree) – The CGNS tree to summarize.
verbose (bool, optional) – If True, include detailed field information. Defaults to True.

Example

>>> summarize_cgns_tree(pyTree)
Number of Bases: 2
Number of Zones: 5
Number of Nodes: 20
Number of Elements: 10
Number of Fields: 8

Fields:: ‘Base1/Zone1/Solution1/Field1’ ‘Base1/Zone1/Solution1/Field2’ ‘Base2/Zone2/Solution2/Field1’ …

flatten_cgns_tree(pyTree: plaid.types.CGNSTree) → tuple[dict[str, object], dict[str, str]][source]¶

Flatten a CGNS tree into dictionaries of primitives.

Parameters:

pyTree (CGNSTree) – The CGNS tree to flatten.

Returns:

flat: dict of paths to primitive values
cgns_types: dict of paths to CGNS type strings

Return type:

tuple[dict[str, object], dict[str, str]]

nodes_to_tree(nodes: dict[str, plaid.types.CGNSTree]) → plaid.types.CGNSTree | None[source]¶

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”.

Parameters:: nodes (Dict[str, CGNSTree]) – A dictionary mapping node paths to CGNSTree nodes.
Returns:: The root CGNSTree node with all children linked, or None if the input dictionary is empty.
Return type:: 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.

unflatten_cgns_tree(flat: dict[str, object], cgns_types: dict[str, str]) → plaid.types.CGNSTree[source]¶

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.

Parameters:

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

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]

Return type:

CGNSTree

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)

update_features_for_CGNS_compatibility(features: list[str], context_constant_features: list[str], context_variable_features: list[str])[source]¶

Expand a list of feature paths to include all CGNS hierarchy nodes and metadata required for compatibility.

This function takes a list of requested features and expands it to include all necessary CGNS tree nodes, metadata, and temporal information (_times suffixes) needed to maintain a valid and complete CGNS structure. It handles different feature types (global, fields, coordinates, elements, boundary conditions) and ensures all parent nodes and related metadata are included.

Parameters:

features (list[str]) – List of feature paths to expand. Paths follow the CGNS hierarchy format (e.g., “Base/Zone/Solution/Field”, “Global/parameter”).
context_constant_features (list[str]) – Set of constant feature paths available in the context (e.g., grid coordinates, element connectivity).
context_variable_features (list[str]) – Set of variable feature paths available in the context (e.g., flow solution fields, time-varying parameters).

Returns:

Expanded list of feature paths including:

Original requested features
Parent nodes in the CGNS hierarchy
Associated metadata nodes (GridLocation, ZoneType, FamilyName)
Temporal information (_times suffix for all features)
Related structural elements (coordinates, elements, boundary conditions)

Return type:

list[str]

Raises:

KeyError – If any requested feature is not found in the combined context features.

Example

>>> context_const = {'Base/Zone', 'Base/Zone/GridCoordinates', ...}
>>> context_var = {'Base/Zone/GridCoordinates/CoordinateX', ...}
>>> features = ['Base/Zone/GridCoordinates/CoordinateX']
>>> expanded = update_features_for_CGNS_compatibility(
...     features, context_const, context_var
... )
>>> 'Base/Zone/GridCoordinates' in expanded
True
>>> 'Base/Zone/GridCoordinates/CoordinateX_times' in expanded
True

Note

The function creates a copy of the input features list to avoid modifying the original.
Features with type ‘field’ automatically include their parent FlowSolution node and GridLocation metadata.
Global features trigger inclusion of ‘Global’ and ‘Global_times’ nodes.
Spatial features (coordinates, elements, boundary conditions) include full zone hierarchy (Base, Zone, ZoneType, FamilyName) and related structural information.