Reader¶

Proxy Class to read files.

Parameters¶

base: Base
Base in which the data read should be added. If this key is not used, the reader will create a new Base object, else the input base will be modified.

example: If no key base:
reader = antares.Reader(<format>) ... base = reader.read()
base will contain the data read from the file.

example: If base is not None:
reader = antares.Reader(<format>) reader['base'] = input_base ... reader.read()
input_base will be complemented with the data read from the file.
filename: str
The name of the file(s). To match several files, two tags can be used:
- <zone>, to match the names of the zones and,
- <instant>, to match the names of the instants. This tag can appear more than once.
example: If the files are named:
Visu_4000_0000_t00, Visu_4000_0001_t00, Visu_4000_0000_t01, Visu_4000_0001_t01
then the key filename could be Visu_4000_<zone>_<instant>.
shared: bool, default= False
if True, the data read are added to the shared Instant. The tag <instant> can not be used in the filename key if this key is True.
topology_file: str
If one wants to attach topological information to the base, a file giving the topology must be read.

Warning

The name of the zone read must match the name of the topology_file blocks. This means that one might need to set the attribute zone_prefix. Moreover, the shape of the zones on the topology_file must match the shape of the numpy arrays of each zone/instant located at nodes (if any)
topology_format: str, default= ‘elsa’
The format of the topology file.
bndphys_file: str
To be used in combination with topology_file
zone_prefix: str, default= ‘’
The prefix to add in front of the zone name.
zone_suffix: str, default= ‘’
The suffix to add back of the zone name.
zone_regex: str, default= ‘.*’
To interpret the zone name defined by the tag <zone> of the attribute filename, Antares uses regular expressions. Take a look at the regex module to properly change this argument.

example: to match a 4-digit number.
reader['zone_regex'] = '\\\\d{4}'
instant_regex: str or tuple(int, int) or tuple(int, int, int), default= ‘.*’
Same as zone_regex, but for <instant> tag. Only for python >= 2.7, if tuple, then the regex matches the interval between the first and the second integer. If given, the third integer corresponds to the number of digits, and may generate leading zeroes.’)

example: (0, 3, 1)
instant_step: int, default= 1
Take every instant_step file into account. This only works when tag <instant> or instant_regex represent data that can be ordered
location: str in LOCATIONS, default= ‘node’
Location of the variables.

Main functions¶

class antares.io.Reader.Reader(file_format=None, **kwargs)¶

Proxy class for file readers.

__init__(file_format=None, **kwargs)¶

Create the Reader object.

Parameters:: file_format (str) – the format of the file(s).

read()¶

Create the base from the given information.

Note

Post-execution of set_coordinate_names() to set the names of coordinates.

Returns:: the antares Base filled with the data from file.
Return type:: Base

For each format below, the associated keys supplement the above shared settable keys.

Binary Tecplot¶

Description¶

Read files with tecplot binary format (v75, v112).

Parameters¶

n_hbt: int, default= None
If one wants to read HBT/TSM files, put here the number of harmonics.
shared_mesh: bool, default= False
True if the connectivity and the coordinates of nodes change from an instant to another.

Preconditions¶

Postconditions¶

The Tecplot ZoneTitle is used for the Antares zone name. Therefore, for an unstructured mesh, if two tecplot zones have the same ZoneTitle and the same StrandID, but different element types, this will lead to a single Antares zone in the output base.

The Tecplot title of the header section is set in Base.attrs with the key TecplotHeaderTitle.

The tecplot parameter FileType is set in Base.attrs with the key TecplotFileType. (see also antares.io.writer.WriterTecplotBinary.WriterTecplotBinary)

The entry Time is set in Instant.attrs. The value of this solution time is a 64-bit floating-point number.

Example¶

The following example shows how to read one file.

import antares
myr = antares.Reader('bin_tp')
myr['filename'] = 'file.plt'
base = myr.read()

The following example shows how to read one file per zone with the tag ‘<zone>’.

import antares
myr = antares.Reader('bin_tp')
myr['filename'] = 'file_<zone>.plt'
base = myr.read()

The following example shows how to read one file per zone per instant with the tags ‘<zone>’ and ‘<instant>’.

import antares
myr = antares.Reader('bin_tp')
myr['filename'] = 'file_<zone>_<instant>.plt'
base = myr.read()

ASCII Tecplot¶

Description¶

Read files with Tecplot ASCII format.

The lazy loading pattern is not available for this format.

Parameters¶

see Common Parameters from Reader Proxy.

Preconditions¶

This reader handles structured and unstructured mesh.

The DATA PACKING can be POINT or BLOCK.

Postconditions¶

Example¶

The following example shows how to read one file.

import antares
myr = antares.Reader('fmt_tp')
myr['filename'] = 'file.dat'
base = myr.read()

HDF CGNS¶

Description¶

Read files with HDF CGNS format.

This reader ‘hdf_cgns’ supports MPI parallelism.

Parameters¶

bnd_filename: str
The name of the boundary file.
base_name: str, default= None
Name of the node that has the CGNSBase_t label.
rename_vars: bool, default= True
Rename CGNS variables with Antares names.
split: str in [‘always’, ‘never’] or None, default= None
Tell whether to split unstructured zones or not. None let the reader decide automatically. Parallel Only.
distribution: list(str) or None, default= None
In parallel, this parameter allows the user to impose the distribution of zones as a list of CGNS ‘blockname’. Each process should receive a different subset of names. All zones must be distributed. If no zones are given for one process, the value of this parameter should be an empty list ‘[]’. When this parameter is used, ‘split’ is not taken into account (unstructured zones are not splitted).
instant_names: list(str) or None, default= None
List of FlowSolution_t names that will be stored in different instants. Setting this option prevents from reading the BaseIterativeData_t node.
- example: instant_names = [‘FlowSolution#Init’] to read the FlowSolution_t data structure named ‘FlowSolution#Init’ in the file.
polyhedra_support: bool, default= False
If True, Elements_t nodes of ElementType_t NGON_n and NFACE_n are stored as face-based connectivity. If False, those elements are stored as standard elements with vertex-based connectivity if allowed by the elements.
follow_links: bool, default= False
If enabled, all CGNS links are followed, and corresponding CGNS nodes are read. Othewise, no CGNS links are taken into account.
force_serial: bool, default= False
If enabled during a parallel execution, each compute core will read the filename independently as for a serial process.
base_subregion: Base, default= None
Base where to collect zone subregions. If None, subregions are appended in the output base as standard zones.

Preconditions¶

To use polyhedra_support, the ‘poly’ extension of Antares must be installed. The implementation of ‘polyhedra_support’ is limited to CGNS version < 3.4.0. ParentElements nodes of NGON_n and NFACE_n nodes are ignored.

The library ngon2elt may have to be generated during the antares installation process for reading face-based connectivity. Refer to installation of ngon2elt.

Postconditions¶

Reading the BaseIterativeData_t data structure: The identifiers IterationValues and TimeValues are read. This is only available when the option instant_names is not used. The identifier IterationValues is preferentially used for the instant names. If the identifier TimeValues is available, then the Instant will hold the key ‘Time’ in its Instant.attrs. If the identifier IterationValues is available, then the Instant will hold the key ‘Iteration’ in its Instant.attrs.

Reading the ZoneIterativeData_t data structure: The identifier FlowSolutionPointers is read to get the solution field for each recorded time value or iteration. There is an implied one-to-one correspondence between each pointer and the associated TimeValues and/or IterationValues under BaseIterativeData_t.

Only one CGNS GridCoordinates_t data structure is read, and only cartesian coordinates.

Reading the FlowSolution_t data structure: If the symbol “#” is in the label name, what is next is called the suffix. If the suffix only contains digits, then the instant name is the suffix, else it is the global variable instant_name. If the label name only contains digits, then the instant name is this figure. Otherwise, the instant name is the global variable instant_name. If instant_names is set, then this sets the instant names.

When polyhedra_support is enabled, zone grid connectivities are not handled.

Reading the ZoneSubRegion_t data structure: It is stored in a Zone just as the Zone_t data structure. Each antares zone coming from a ZoneSubRegion is associated with a family name. It is then possible to separate ZSR zones from standard zones afterwards. The name of the ZSR and the family is defined by a prefix ‘ZSR’, the name of the CGNS ZoneSubRegion_t node, and a suffix that is the name of the zone including this ZSR, joined by the character ‘_’. Data from CGNS DataArray_t are stored in an Instant named ‘0’ of the antares zone.

Example¶

The following example shows how to read one file.

import antares
myr = antares.Reader('hdf_cgns')
myr['filename'] = 'file.cgns'
base = myr.read()

antares.io.reader.ReaderHdfCgns.get_base_node_names(filename)¶

returns the list of Base_t from a file.

Parameters:: filename (str) – HDF CGNS filename

## Reading the list of Base_t from a file

import os
from antares.io.reader.ReaderHdfCgns import get_base_node_names
names = get_base_node_names('all_cut.cgns')
print(names)

HDF Antares¶

Description¶

Read files with antares HDF5 format.

Parameters¶

n_hbt: int, default= None
If one wants to read HBT/TSM files, put here the number of harmonics.
format: str in [‘2015’, ‘2022’], default= ‘2015’
The file format version.
- format 2015: The zone/instant/variable ‘list_keys’ are read from h5 attrs.
- format 2022: The zone/instant/variable ‘list_keys’ are read from h5 datasets.

Preconditions¶

Postconditions¶

Example¶

The following example shows how to read one file.

import antares
myr = antares.Reader('hdf_antares')
myr['filename'] = 'file.hdf'
base = myr.read()

HDF LaBS¶

Description¶

Read files with HDF Labs format.

Format from Lattice-Boltzmann solver LaBs or ProLB

Parameters¶

velocity_components: list(str), default= [‘Vx’, ‘Vy’, ‘Vz’]
Velocity components stored in the instant.
velocityRMS_components: list(str), default= [‘VxRMS’, ‘VyRMS’, ‘VzRMS’]
RMS components of the velocity vector stored in the instant.
velocity_squared_components: list(str), default= [‘Vx2’, ‘Vy2’, ‘Vz2’]
Squared velocity components of the velocity vector stored in the instant.
shared_mesh: bool, default= False
If True, then the connectivity and the coordinates of nodes are shared between all instants. The mesh is fixed during the simulation.
Unknown_components: list(str), default= [‘UnknownX’, ‘UnknownY’, ‘UnknownZ’]
Unknown components found in the file. Writer need to be adapted.
version: str, default= ‘v2’
ProLB version used, either ‘v2’ or ‘v3’

Preconditions¶

Allowed elements: triangles and hexahedra.

Postconditions¶

Example¶

The following example shows how to read one file.

import antares
myr = antares.Reader('hdf_labs')
myr['filename'] = 'file.hdf'
base = myr.read()

VTK¶

VTK format.

Warning

dependency on VTK

Parameters¶

coordinates: list(str)
Names of variables that define the mesh when it is not specified in the file.
single_type: bool, default= False
Tell if the file contains only a unique type of elements for an unstructured grid.

CSV¶

Description¶

Read files with CSV (comma-separated values) format.

Parameters¶

separator: str, default= ‘;’
Separator between numbers.
cantera_avbp: bool, default= False
Specific for cantera_avbp format.

Preconditions¶

If any, the lines of the header must contain the name of variables separated by the separator string. Columns may have different sizes. Rows are composed of numbers (integer or floating-point) separated by the separator string.

Postconditions¶

Example¶

The following example shows how to read one file.

import antares
myr = antares.Reader('csv')
myr['filename'] = 'file.dat'
myr['separator'] = ','
base = myr.read()

Fluent¶

Description¶

Read Fluent files with Binary data.

The implementation is based on ANSYS Fluent Meshing User’s Guide Release 15.0 November 2013 and ANSYS Fluent Meshing User’s Guide Release 12.0 January 2009:

Parameters¶

filename: str
The mesh or solution file name. If base is not given, then filename must be the mesh file. If base is given, then the filename must be the solution file. The mesh file must have the extension ‘.cas’ and the solution file must have the extension ‘.dat’.
base: str, default= None
Input base used only if the mesh file has already been read.
xfile: str, default= None
Path name of the file xfile.h. It is compulsory if a solution filename is given. This file can be found in the user’s Fluent installation.

Precondition¶

The reader does not support multi-instant data and ASCII data.

The reader only supports face-based connectivity.

The library ngon2elt has to be generated during the antares installation process. Refer to installation of ngon2elt.

Precondition¶

A grid connectivity is stored in a Boundary object as a regular physical boundary condition.

Examples¶

The following example shows how to only read the mesh file.

import antares

# read mesh only
myr = antares.Reader('fluent')
myr['filename'] = 'file.cas'
base = myr.read()

The following example shows how to read both mesh and solution files.

import antares

# read mesh
myr = antares.Reader('fluent')
myr['filename'] = 'mesh_path/mesh.cas'
base = myr.read()
# read solution
myr['base'] = base
myr['filename'] = 'solution_path/solution.dat'
myr['xfile'] = 'xfile_path/xfile.h'
base = myr.read()

PYCGNS¶

Description¶

Read in-memory pyCGNS objects.

https://pycgns.github.io/

https://github.com/pyCGNS/pyCGNS

Parameters¶

object: object
Source object to be read.
polyhedra_support: bool, default= False
If enabled, Elements_t nodes of ElementType_t NGON_n and NFACE_n are stored as polyhedra. Otherwise, for cells allowing it, those elements are stored as canonical elements.
base_subregion: Base, default= None
Base where to collect zone subregions. If None, subregions are appended in the output base as standard zones.
skip_solution: bool, default= False
If enabled, do not read FlowSolution data, read only geometric information.

Preconditions¶

Zones must be structured, or unstructured with face-based connectivities. Element-based connectivities are not read for unstructured zones.

The library ngon2elt may have to be generated during the antares installation process for reading face-based connectivity. Refer to installation of ngon2elt.

Postconditions¶

Zone grids are stored in the shared instant. Zone solutions and BC data are stored in a unique instant named ‘0000’. BC data shall have the same geometric slicing as its parent boundary. Small CGNS parameter nodes (low memory usage) that are unknown to antares but that may be required for future applications are stored as is under antares attrs attribute of the bound object.

Reading the ZoneSubRegion_t data structure: It is stored in a Zone just as the Zone_t data structure if base_subregion is None. Each antares zone coming from a ZoneSubRegion is associated with a family name. It is then possible to separate ZSR zones from standard zones afterwards. The name of the ZSR and the family is defined by a prefix ‘ZSR’, the name of the CGNS ZoneSubRegion_t node, and a suffix that is the name of the zone including this ZSR, joined by the character ‘_’. Data from CGNS DataArray_t are stored in an Instant named ‘0’ of the antares zone.

Example¶

The following example shows how to read one object.

import antares
import CGNS.PAT.cgnskeywords as _ck
import CGNS.PAT.cgnsutils as _cu
import CGNS.MAP

tree, _, _ = CGNS.MAP.load('file.cgns')
cgns_bases = _cu.hasChildType(tree, _ck.CGNSBase_ts)

sp_reader = Reader('pycgns')
sp_reader['object'] = cgns_bases[0]
base = sp_reader.read()

HDF5 AVBP¶

Description¶

Read files from the AVBP code

More information on the format can be found here.

The root node of the hierarchical HDF5 data structure may contain groups, and groups may contain datasets.

Parameters¶

see Common Parameters from Reader Proxy.

filename:
It is not possible to read a mesh file and at least one solution file in one shot (see example below).
location:
Not used.
groups_vars: list or tuple
Select subsets of groups and variables from the solution file.
- example to read only some variables possibly stored under different groups:
  groups_vars = ['rhou', 'rhov']
- example to read ‘rhou’ and ‘rhov’ from group1, ‘pressure’ from group2, and all variables from group3:
  groups_vars = (('group1', ['rhou', 'rhov']), ('group2', ['pressure']), 'group3')

Preconditions¶

If the group ‘Coordinates’ exists, then the file is considered to be an AVBP mesh file. If one group among [‘Additionals’, ‘GaseousPhase’, ‘RhoSpecies’, ‘Reactions’, ‘LiquidPhase’, ‘FictiveSpecies’, ‘Sparkignition’, ‘RealGas’, ‘LiquidPhase_ptcl’, ‘Parameters_ptcl’] exists, then the file is considered to be an AVBP solution file.

Postconditions¶

Mesh File:¶

If the option shared is set to True, then the instant is the shared instant of the zone, else the instant is a regular instant.

Coordinates x, y and z in 3-D only, are lazy loaded.

All variables in the group ‘Parameters’ are read, and set in the Zone.attrs.

Volume connectivities, Instant.connectivity, are eager loaded.

All variables from the group ‘VertexData’ are lazy loaded. The name of variables are stored in the Instant.attrs to be able to separate mesh data from solution data in the AVBP writer for example.

If the group ‘Boundary’ exists, then some Boundary objects are created. The number of objects is the size of the dataset ‘bnode_lidx’. The name of boundaries are given by the dataset ‘PatchLabels’, otherwise they are named ‘Patch<number>’. Some datasets of the group ‘Boundary’ or groups at the root node are not used by antares, but they are still stored in the Boundary.container (for use in the AVBP writer for example). These groups are [‘Periodicity’, ‘Patch’] and these datasets are [‘PatchGeoType’, ‘Patch->area’, ‘bnode->normal’, ‘bnd_<elt_type>->face’, ‘bnd_<elt_type>->elem’]. All boundaries are gathered in a Family named ‘Patches’.

Solution File:¶

If the group ‘Average’ exists, then the key ‘status’ is set in the Instant.attrs with the value ‘Average’ to be able to separate average solution from instantaneous solution in the AVBP writer for example.

All datasets in all groups are read. If the shape of a dataset is equal to the shape of the instant, then the dataset is stored as a variable in the instant, else the dataset is stored in the Instant.attrs.

Example¶

The following example shows how to read one mesh file in the shared instant, and to read a whole solution file.

import antares
myr = antares.Reader('hdf_avbp')
myr['filename'] = 'file.mesh.h5'
myr['shared'] = True
base = myr.read()

myr = antares.Reader('hdf_avbp')
myr['filename'] = 'sol_ite0001000.h5'
myr['base'] = base
base = myr.read()

The following example shows how to read some specific groups and datasets from a solution file.

myr = antares.Reader('hdf_avbp')
myr['filename'] = 'sol_ite0001000.h5'
myr['groups_vars'] = ('GaseousPhase', ('Additionals', ['pressure']),
                      'RhoSpecies')
myr['base'] = base
base = myr.read()

Lazy Loading Pattern¶

The Lazy Loading Design Pattern is applied to antares Readers to defer the storage of variables in numpy arrays until the point at which they are required. Therefore, this can save reading time and memory if all the variables do not have to be read from the file. The opposite of lazy loading is eager loading where all variables of a file are read at once.

If all variables have to be read, then the lazy loading may imply a reading time overhead. In that case, you can activate the File Cache System.