Yaml parsing

maia.pytree does not come with any tool to read or write CGNS databases from ADF or HDF files. This choice has been made in order to maintain a light and portable library, assuming that users will rely on an external software (such as maia) to perfom IO operations.

Nevertheless, for development and debug purpose, we provide a converter mapping CGNS trees to YAML files. This is especially useful to prepare sample trees for unit testing in convenient and visual way.

Format description

To illustrate how the yaml format is used to store CGNSTrees, let’s consider this example file:

Base Base_t [2,2]:
  Zone Zone_t [[9,4,0]]:
    ZoneType ZoneType_t "Unstructured":
    GridCoordinates GridCoordinates_t:
      CoordinateX DataArray_t R8 [0, 0.5, 1,  0,   0.5, 1.,  0, 0.5, 1]:
      CoordinateY DataArray_t R8 [0, 0,   0,  0.5, 0.5, 0.5, 1, 1,   1]:
    QUAD Elements_t [7, 0]: # This is a comment
      ElementRange IndexRange_t [1, 4]:
      ElementConnectivity DataArray_t:
        I4 : [1,2,5,4,  2,3,6,5,
              4,5,8,7,  5,6,9,8]

The following rules must be observed to have a valid description of a CGNSTree:

Comments: short line comment can be used thanks to the # character (line 7).

Hierarchic structure: indentation is used to indicate that a node is the child of another node (line 3).

Node definition: a node is defined by the pattern {name} {label} {value_kind} {value}:. Note the importance of the :, which acts as a end-of-line marker. The value, as well as its kind value_kind, are optional (line 2, line 4).

Values: if a value is provided, it can be a string or a sequence of numbers (line 3, line 1). Nested sequences can be used to describe dimensional arrays (line 2). value can be ommited if the node has no value (line 4).

Values kind : if value_kind is not provided, values are converted using set_value() rules (line 2). Otherwise, value_kind should be one of the CGNS value identifiers (eg. I4, R8, etc.) and will be used to enforce the requested kind (line 5). value_kind can not exist if value is not provided.

Long node definition: alternatively, nodes can be defined by the pattern shown on lines 9-11: this is especially useful when values are long arrays. When this pattern is used, value_kind is mandatory. Note the additional indentation for the value definition and the lack of : at the end of the value sequence (this is because end of value is now detected throught the indentation level).

YAML-CGNS converter

Attention

The functions documented here are exposed in the maia.pytree.yaml module.

From YAML to CGNS

to_node(yaml_stream)

Convert a yaml stream into a python CGNSTree.

Tree is parsed recursively, but must start from a single root node.

Parameters

yaml_stream (str or filename) – Yaml description of the node

Returns

CGNSTree – python representation of the node

Example

>>> node = PT.yaml.to_node('''
... BC BC_t:
...   GridLocation GridLocation_t "FaceCenter":
...   PointList IndexArray_t [[1,2,3]]:
... ''')
>>> PT.print_tree(node)
BC BC_t
├───GridLocation GridLocation_t "FaceCenter"
└───PointList IndexArray_t I4 [[1 2 3]]

to_nodes(yaml_stream)

Convert a yaml stream into a list of python CGNSTree.

This function is similar to to_node(), but allows to declare several root nodes at the yaml top level, which are parsed independently.

Parameters

yaml_stream (str or filename) – Yaml description of the nodes

Returns

list of CGNSTree – python representation of each root node

Example

>>> nodes = PT.yaml.to_nodes('''
... BC1 BC_t:
...   GridLocation GridLocation_t "FaceCenter":
...   PointList IndexArray_t [[1,2,3]]:
... BC2 BC_t:
...   GridLocation GridLocation_t "Vertex":
...   PointList IndexArray_t [[1,2,3]]:
... ''')
>>> len(nodes)
2

to_cgns_tree(yaml_stream)

Convert a yaml stream into a top level python CGNSTree.

This function is similar to to_node() or to_nodes(), but it also automatically create the top level (CGNSTree_t, CGNSBase_t and CGNSLibraryVersion_t) nodes if necessary.

This function should not be called on nodes lower than Zone_t.

Parameters

yaml_stream (str or filename) – Yaml description of the tree

Returns

CGNSTree – python representation of the tree

Example

>>> tree = PT.yaml.to_cgns_tree('''
... Zone Zone_t:
...   ZoneType ZoneType_t "Structured":
... ''')
>>> PT.print_tree(tree)
CGNSTree CGNSTree_t
├───Base CGNSBase_t I4 [3 3]
│   └───Zone Zone_t
│       └───ZoneType ZoneType_t "Structured"
└───CGNSLibraryVersion CGNSLibraryVersion_t R4 [4.2]

From CGNS to YAML

to_yaml(t, max_line_size=120, write_root=True)

Convert a python CGNSTree to a yaml string.

Parameters

• t (CGNSTree) – input python CGNSTree

• max_line_size (int) – Maximum line lenght using when rendering arrays. Defaults to 120.

• write_root (bool) – if False, top_level node is ignored

Returns

list of str – yaml representation of the tree

Example

>>> node = PT.new_Zone(type='Unstructured', size=[[9,4,0]], family='ROW')
>>> lines = PT.yaml.to_yaml(node)
>>> for l in lines:
...    print(l)
Zone Zone_t I4 [[9, 4, 0]]:
  ZoneType ZoneType_t 'Unstructured':
  FamilyName FamilyName_t 'ROW':