CGNS.MAP

The MAP module is one of the most important modules of pyCGNS. MAP is the translator to get CGNS/Python trees from a CGNS/HDF5 file and back, to save CGNS/Python trees as a CGNS/HDF5 file. MAP uses CHLone and has no dependancy to CGNS/MLL or CGNS/ADF.

Quick start

The MAPper is a module implementing the CGNS/Python mapping. There are only two functions in the module: the load and the save. A simple exemple to load a CGNS/HDF5 file as a CGNS/Python tree:

import CGNS.MAP

(tree,links,paths)=CGNS.MAP.load("T0.cgns")

The tree value contains the actual CGNS/Python tree, links value is a list of links found during the HDF5 file parse. The default behavior of the load is to follow linked-to files. The paths has the list of linked-to nodes that failed. Now we can use the CGNS.PAT module to handle this tree. For example you can print the whole tree path hierarchy:

import CGNS.MAP
import CGNS.PAT.cgnsutils as CGU

(tree,links,paths)=CGNS.MAP.load("T0.cgns")

for p in CGU.getAllPaths(tree): print p

See the CGNS.PAT documentation on how to browse, modify such a GCNS/Python tree.

User interface

MAP is a lightweight module, its purpose is to be as small as possible in order to be embedded separatly in an application (not yet available). It uses the CHLone library and its Python binding. MAP is a powerful reader/writer of CGNS/HDF5 and CGNS/Python trees. The use of CGNS.PAT and the flags combination can help to achieve complex operations on a CGNS tree with a fast access and a low memory footprint. See the examples.

Functions

There are two functions: the load and the save. The load reads a CGNS/HDF5 file and produces a CGNS/Python tree. The save takes a CGNS/Python tree and writes the contents in a CGNS/HDF5 file:

(tree,links,paths)=CGNS.MAP.load(filename,flags,depth,maxdata,subtree,linkpaths,updatepaths)

status=CGNS.MAP.save(filename,tree,links,flags,depth,linkpaths,updatepaths,skiplist)

The load and save arguments are python named arguments, you have to set them with the correct key. Except filename for load and filename and tree for save, all others arguments are optional. The arguments and the return values are:

• tree: The tree is the list representing the CGNS/Python tree. The structure of a tree list is detailled in SIDS-to-Python. There is no link information in this tree either for load or for save.

  During the load, the links are silently replaced by the linked-to tree they are referring. The links value keeps track of these link references found while parsing the CGNS/HDF5 file.

  During the save, the tree is splitted into separate files/nodes depending on the references found in the links value.

• links: The links is a list with the link node information. It is returned by a load and used as command parameters during the save. You can write your own links list or change the list you obtain after a load. The structure of a links list is detailled in SIDS-to-Python. See also ‘about links’

• filename: The name of the target file, to read or to write. The filename can be absolute or relative, it should be accessible in read/write depending on the action you perform on it. The file extension is unused.

• flags: You can control the behavior of a load/save using the flags. You have to look a these carefully, the same tree can load/save in a completely different way depending on these flags.

• maxdata: Sets the threshold for array creation. If the array size (ndarray.size) is greater than maxdata, the returned node value is None and the path is added into the paths return of the load.

• depth: This positive integer value sets the level of children the load/save takes into account. For example, a depth of 2 would stop load/save the CGNS tree once the children of the children of the start node is reached. This level two child is used, its children are not. If you want to have all the children, use a 0 depth which means no limit on depth.

• subtree: This path defines the start node of the load/save. It should be an absolute path of an existing node in the argument filename. All the nodes along this path are taken into account for load/save actions.

• linkpaths: The load may need a link files search path if your linked-to files are not in the current directory. The linkpath argument is a list of strings, during the load CGNS.MAP will look for linked-to files using this list: it is parsed from the first element to the last, the selected file is the first found in this directory list.

• updatepaths: A dictionnary of paths (string) as keys and CGNS/Python nodes as values. When the load reaches a node with the path in the keys, the numpy value is updated instead of creating a new array. You can pass your own array with an already allocated memory zone or update and already loaded numpy.

• skiplist: A list of paths of nodes that should not be updated. For exemple if you load a tree without data, you do not want the save to overwrite actual data on disk with empty arrays. This list can be retrieved from the paths return of the load function.

Warning

The current directory is not in the link search path. So if your linked-to file is in current directory, you should add . in the link search path list. If the filename is an absolute path name (not recommended !) then you should add and empty path in the search path list.

Flags

The flags are integers that can be OR-ed or XOR-ed to set/unset specific behavior during the load and the save. The boolean operators are used for the flag settings:

flags=CGNS.MAP.S2P_FOLLOWLINKS|CGNS.MAP.S2P_TRACE

flags =flags&~CGNS.MAP.S2P_TRACE
flags&=~CGNS.MAP.S2P_TRACE

The table below gives the CGNS.MAP flags.

Flag variable	Function
S2P_NONE	Clear all flags, set to zero.
S2P_ALL	Set all flags, set to one.
S2P_TRACE	Set the trace on, messages are sent to ‘stdout’
S2P_FOLLOWLINKS	Continue to parse the linked-to tree (1)
S2P_MERGELINKS	Forget all link specifications. (2)
S2P_COMPRESS	Sets the compress flag for ‘DataArray_t’ (2)
S2P_NOOWNDATA	Forces the numpy flag \~NPY_OWNDATA (1) (3)
S2P_NODATA	Do not load large ‘DataArray_t’ (1)
S2P_UPDATE	Save updates existing file (6)
S2P_DELETEMISSING	not used

The S2P_DEFAULT flag corresponds to S2P_NONE | S2P_FOLLOWLINKS & S2P_REVERSEDIMS.

There is no requirements or check on which flag can or cannot be associated with another flag.

Remarks:

1. Only when you are loading a tree.

2. Only when you are saving a tree.

3. Which means all DataArray_t actual memory zones will NOT be released by Python.

3. The term large has to be defined. The save will NOT check if the CGNS/Python tree was performed with the S2P_NODATA flag on, then you have to check by yourself that your save will not overwrite an existing file with empty data!

4. The default behavior is to transpose array and dimensions of an array if this is not a NPY_FORTRAN array. If you set this flag to 1, no transpose would be performed and the array and its dimensions would be stored without modification even if the NY_FORTRAN flag is not there.

6. The file should exist, all new nodes are added, thus modifying the children list of their parents. Existing nodes are updated only in the case of value change. There no children removal, name or label change.

SIDS-to-Python Mapping

• CGNS/Python Tree
  • Commitment with CGNS standard
  • The node structure
  • Textual representation
  • Numpy array mapping
  • Data types
• Specific CGNS/Python topics
  • The CGNSTree_t type
  • Legacy CGNS types alternative
  • Links
  • C API
• Examples and tips
  • IndexRange_t
  • IndexArray_t
  • DimensionalUnits_t
  • Zone_t
  • Sub-tree imports
  • Sub-tree share

Examples

• About links
• MAP Examples
  • Complete load of a CGNS/HDF5 file
  • Complete save of a CGNS/Python tree
  • Partial load of a CGNS/HDF file
  • Load of a CGNS/HDF file layout
  • Update a nodata node from a CGNS/HDF file
  • Load a tree without links
  • Save with links
  • Save with new links
  • Update a file
  • Merge all or some linked-to files
  • Some usual issues

Glossary

cgns.org

The official CGNS web site, by extension any document on this web site has an official taste…

CGNS

The specific purpose of the CFD General Notation System (CGNS) project is to provide a standard for recording and recovering computer data associated with the numerical solution of the equations of fluid dynamics. See also the How to?.

CGNS/SIDS

The Standard Interface Data Structure is the specification of the data model. This public document describes the syntax and the semantics of all tree-structured data required or proposed for a CFD simulation.

CGNS/MLL

The Mid-Level Library is an example implementation of CGNS/SIDS on top of CGNS/ADF and CGNS/HDF5 mappings. This library has a C and a Fortran API.

CGNS/ADF

The Advanced Data Format *CGNS/SIDS* implementation. A binary storage format and its companion library, developped by Boeing.

CGNS/HDF5

The Hierarchical Data Format *CGNS/SIDS* implementation. A binary storage format and its companion library (see below).

CGNS/Python

The Python programming language *CGNS/SIDS* implementation.

CHLone

A CGNS/HDF5 compliant implementation. The CHLone library is available on SourceForge.

HDF5

A powerful storage system for large data. The HDF5 library should be seen as a middleware system with a lot of powerful features related to efficient, portable and trustable storage mean.

python

An object oriented interpreted programming language.

cython

A compiler tool that translate Python/Numpy into C code for performance purpose.

numpy

The numerical library for Python. Numpy is used to store the data in Python arrays which have a direct memory mapping to actual C or Fortran memory.

VTK

A visualization toolkit used to display 3D objects in CGNS.NAV.

PySide

The Python interface for the Qt toolkit. PySide

Qt

A powerful graphical toolkit available under GPL v3, LGPL v2 and a commercial license. The current use of Qt is under LGPL v2 in pyCGNS.

MAP Index

• Index