core Package¶

A package implementing a generic data platform for multimodal datasets.

`samples` Module¶

DataPlatform module for the management of multimodal mechanical datasets.

The samples module provides a base class SampleData implementing a generic data model and data paltform API, allowing to define by inheritance specific data platform classes for specific mechanical applications. It is designed to gather and manipulate easily multimodal datasets gathering data from 3D/4D imaging experiments and simulations of mechanical material samples. Such data consists in volumic data defined on 3D meshes/images, classical data arrays, and associated metadata.

class pymicro.core.samples.SampleData(filename='sample_data', sample_name='', sample_description=' ', verbose=False, overwrite_hdf5=False, autodelete=False, autorepack=False, after_file_open_args={})¶

Bases: object

Base class to store multi-modal datasets for material science.

SampleData is a high level API designed to create and interact with complex datasets collecting all the data generated for a material sample by material scientists (from experiments, numerical simulation or data processing).

Each dataset consist of a pair of files: one HDF5 file containing all data and metadata, and one XDMF data gathering metadata for all spatially origanized data (grids and fields). The class ensures creation and synchronization of both XDMF and HDF5 files.

The HDF5 and XDMF data tree structure and content in both files are accessible through the h5_dataset and xdmf_tree class attributes, that are respectively instances of classes imported from the Pytables and lxml packages.

SampleData Naming system

An index of the dataset content is stored into a dictionary content_index as an attribute of the class. Additional names can be defined by users for data items, and are stored in an alias dictionary. The content_index dic is synchronized with the hdf5 Group ‘/Index’. The aliases dic is synchronized with the ‘/Index/Aliases’ Group. When an existing dataset is opened to create a SampleData instance, these attributes are initialized from these Groups in the dataset HDF5 file. Each data item can be accessed in the API methods via:

path

it’s path in the HDF5 data tree

indexname

it’s name in the content_index dic (the key associated to it’s path)

alias

an alias of it’s indexname

name

its name as a HDF5 Node if it is unique

Data Compression

HDF5 compression algorithm are available through the Pytables package. SampleData offers an interface to it with the set_chunkshape_and_compression() method.

Arguments of the Class constructor

Filename: str basename of HDF5/XDMF files to create/read. A file pair is created if the filename do not match any existing file.
Sample_name: str, optional (‘’) name of the sample associated to data (metadata, dataset “title”). If the class is called to open a pre-existing filename, its sample name is not overwritten.
Sample_description: str, optional (‘’) short description of the mechanical sample (material, type of tests…. – metadata). If the class is called to open a pre-existing filename, its sample name is not overwritten.
Verbose: bool, optional (False) set verbosity flag
Overwrite_hdf5: bool, optional (False) set to True to overwrite existing HDF5/XDMF couple of files with the same filename.
Autodelete: bool, optional (False) set to True to remove HDF5/XDMF files when deleting SampleData instance.
Autorepack: bool, optional (False) if True, the HDF5 file is automatically repacked when deleting the SampleData instance, to recover the memory space freed up by data compression operations. See repack_h5file() for more details.

Class attributes

H5_file: basename of HDF5 file containing dataset (str)
H5_path: full path of the HDF5 dataset file
H5_dataset: tables.File instance associated to the h5_file
Xdmf_file: name of XDMF file associated with h5_file (str)
Xdmf_path: full path of XDMF file (str)
Xdmf_tree: lxml.etree XML tree associated with xdmf_file
Autodelete: autodelete flag (bool)
Autorepack: autorepack flag (bool)
After_file_open_args: command arguments for after_file_open (dict)
Content_index: Dictionnary of data items (nodes/groups) names and pathes in HDF5 dataset (dic)
Aliases: Dictionnary of list of aliases for each item in content_index (dic)

__init__(filename='sample_data', sample_name='', sample_description=' ', verbose=False, overwrite_hdf5=False, autodelete=False, autorepack=False, after_file_open_args={})¶: Sample Data constructor, see class documentation.

__del__()¶

Sample Data destructor.

Deletes SampleData instance and:

closes h5_file –> writes data structure into the .h5 file
writes the .xdmf file

__repr__()¶: Return a string representation of the dataset content.

__contains__(name)¶

Check if name refers to an existing HDF5 node in the dataset.

Parameters: name (str) – a string for the name / indexname / path
Return bool: True if the dataset has a node associated with this name, False if not.

__getitem__(key)¶: Implement dictionnary like access to hdf5 dataset items.

__getattribute__(name)¶: Implement attribute like access to hdf5 dataset items.

minimal_data_model()¶

Specify minimal data model to store in class instance.

This method is designed to construct derived classes from SampleData to serve as data platforms for a specific data model, that is specified by the two dictionaries returned.

The class constructor searches through these dictionaries to determine the name, pathes and types of data items constituting the data model of the class, and creates them at each instance creation. If the constructor is used to create an instance from an existing file, the compatibility with the data model is verified, and the missing data items are created if needed. The constructor ensures compatibility of previously created datasets with the class if the current data model of the class has been enriched. Note that the associated datasets can contain additional data items, those defined in this method are the minimal required content for this class of datasets.

The return dictionaries keys are the Index names of the data items of the data model. Their values are defined hereafter:

Return dic index_dic: Dictionary specifying the indexnames and pathes of data items in

the data model. Each entry must be of the form

{‘indexname’:’/data_item/path’}. The data item path is its path

in the HDF5 tree structure.
Return dic type_dic: Dictionary specifying the indexnames and types of data items in

the data model. Each entry must be of the form

{‘indexname’:’grouptype’}. ‘grouptype’ can be:
‘Group’: creates a classical HDF5 group (str)
‘3DImage’: creates a HDF5 group containing datasets (fields) defined on the same 3D image (str)
‘Mesh’: creates a HDF5 group containing datasets (fields) defined on the same mesh (str)
‘Array’: creates a HDF5 node containing a data array (str)
Table_description: creates a structured storage array (tables.Filters class) with the given Description. Table_description must be a subclass of tables.IsDescription class.

print_xdmf()¶: Print a readable version of xdmf_tree content.

write_xdmf()¶: Write xdmf_tree in .xdmf file with suitable XML declaration.

print_dataset_content(as_string=False, max_depth=3, to_file=None, short=False)¶

Print information on all nodes in the HDF5 file.

Parameters

as_string (bool) – If True solely returns string representation. If False, prints the string representation.
max_depth (int) – Only prints data item whose depth is equal or less than this value. The depth is the number of parents a data item has. The root Group has thus a depth of 0, its children a depth of 1, the children of its children a depth of 2…
to_file (str) – (optional) If not None, writes the dataset information to the provided text file name to_file. In that case, nothing is printed to the standard output.
short (bool) – If True, return a short description of the dataset content, reduced to hdf5 tree structure and node memory sizes.

Return str s

string representation of HDF5 nodes information

print_group_content(groupname, recursive=False, as_string=False, max_depth=1000, to_file=None, short=False)¶

Print information on all nodes in a HDF5 group.

Parameters

groupname (str) – Name, Path, Index name or Alias of the HDF5 group
recursive (bool) – If True, print content of children groups
as_string (bool) – If True solely returns string representation. If False, prints the string representation.
max_depth (int) – Only prints data item whose depth is equal or less than this value. The depth is the number of parents a data item has. The root Group has thus a depth of 0, its children a depth of 1, the children of its children a depth of 2… Note that this depth is an absolute depth. Thus, if you want for instance to print the content of a group with depth 3, with 2 levels of depth (its childrens and their childrens), you will need to specify a depth of 5 for this method.
to_file (str) – (optional) If not None, writes the group contentto the provided text file name to_file. In that case, nothing is printed to the standard output.
short (bool) – If True, return a short description of the dataset content, reduced to hdf5 tree structure and node memory sizes.

Return str s

string representation of HDF5 nodes information

print_node_info(nodename, as_string=False, short=False)¶

Print information on a node in the HDF5 tree.

Prints node name, content, attributes, compression settings, path, childrens list if it is a group.

Parameters

name (str) – Name, Path, Index name or Alias of the HDF5 Node
as_string (bool) – If True solely returns string representation. If False, prints the string representation.
short (bool) – If True, return a short description of the node content, reduced to name, hdf5 type and node memory sizs.

Return str s

string representation of HDF5 Node information

print_node_attributes(nodename, as_string=False)¶

Print the hdf5 attributes (metadata) of an array node.

:param str name:Name, Path, Index name or Alias of the HDF5 Node :param bool as_string: If True solely returns string representation. If False, prints the string representation. :return str s: string representation of HDF5 Node compression settings

print_node_compression_info(name, as_string=False)¶

Print the compression settings of an array node.

:param str name:Name, Path, Index name or Alias of the HDF5 Node :param bool as_string: If True solely returns string representation. If False, prints the string representation. :return str s: string representation of HDF5 Node compression settings

print_data_arrays_info(as_string=False, to_file=None, short=False)¶

Print information on all data array nodes in hdf5 file.

Mesh node and element sets are excluded from the output due to their possibly very high number.

Parameters

as_string (bool) – If True solely returns string representation. If False, prints the string representation.
to_file (str) – (optional) If not None, writes the dataset information to the provided text file name to_file. In that case, nothing is printed to the standard output.
short (bool) – If True, return a short description of the dataset content, reduced to hdf5 tree structure and node memory sizes.

Return str s

string representation of HDF5 nodes information

print_grids_info(as_string=False, to_file=None, short=False)¶

Print information on all grid groups in hdf5 file.

Parameters

as_string (bool) – If True solely returns string representation. If False, prints the string representation.
to_file (str) – (optional) If not None, writes the dataset information to the provided text file name to_file. In that case, nothing is printed to the standard output.
short (bool) – If True, return a short description of the dataset content, reduced to hdf5 tree structure and node memory sizes.

Return str s

string representation of HDF5 nodes information

print_index(as_string=False, max_depth=3, local_root='/')¶

Print a list of the data items in HDF5 file and their Index names.

Parameters

as_string (bool) – If True solely returns string representation. If False, prints the string representation.
max_depth (int) – Only prints data item whose depth is equal or less than this value. The depth is the number of parents a data item has. The root Group has thus a depth of 0, its children a depth of 1, the children of its children a depth of 2…
local_root (str) – prints only the Index for data items that are children of the provided local_root. The Name, Path, Indexname, or Alias of the local_root can be passed for this argument.

Return str s

string representation of HDF5 nodes information if as_string is True.

sync()¶

Synchronize and flush .h5 and .xdmf files with dataset content.

After using the sync method, the XDMF file can be opened in Paraview and 3DImage and/or Mesh data visualized, even if the files are still open in the class instance.

Important

Paraview >=5 cannot read data from synchronized files, you must close them first. In this case, use method pause_for_visualization().

pause_for_visualization(Vitables=False, Paraview=False, **keywords)¶

Flushes data, close files and pause interpreter for visualization.

This method pauses the interpreter until you press the <Enter> key. During the pause, the HDF5 file object is closed, so that it can be read by visualization softwares like Paraview or ViTables. Two optional arguments allow to directly open the dataset with Paraview and/or Vitables, as a subprocess of Python. In these cases, the Python interpreter is paused until you close the visualization software.

Paraview allows to visualize the volumic data that is stored in the SampleData dataset, i.e. Mesh and Images groups (geometry and stored fields). Vitables allows to visualize the content of the HDF5 dataset in term of data tree, arrays content and nodes attributes. If both are requested, Vitables is executed before Paraview.

Parameters

Vitables (bool) – set to True to launch Vitables on the HDF5 file of the instance HDF5 dataset.
Paraview (bool) – set to True to launch Paraview on the XDMF file of the instance.

switch_verbosity()¶: Change the verbosity flag to its opposite.

add_mesh(mesh_object=None, meshname='', indexname='', location='/', description=' ', replace=False, bin_fields_from_sets=True, file=None, compression_options={})¶

Create a Mesh group in the dataset from a MeshObject.

A Mesh group is a HDF5 Group that contains arrays describing mesh geometry, and fields defined on this mesh. The mesh geometry HDF5 nodes are: This methods adds a Mesh group to the dataset from a BasicTools UnstructuredMesh class instance.

Nodes

array of shape (Nnodes,Ndim) with path '/Mesh_Path/Geometry/Nodes' and Index name 'Meshname_Nodes'

Elements

array of shape (Nelements,Nelement_nodes) with path '/Mesh_Path/Geometry/Elements' and Index name 'Meshname_Elements'

Mesh group may also contain data array to describe fields, whose pathes, index names and content can be set using the class method add_data_array(). Fields defined on nodes must have a shape equal to (Nnodes,Field_dimension). Fields defined on integration points must have a shape equal to (Nintegration_points,Field_dimension).

Parameters

mesh_object – mesh to add to dataset. It is an instance from the pymicro.core.meshes.MeshObject class
meshname (str) – name used to create the Mesh group in dataset
indexname – Index name used to reference the Mesh group
description (str) – Description metadata for this mesh
replace (bool) – remove Mesh group in the dataset with the same name/location if True and such group exists
bin_fields_from_sets (bool) – If True, stores all Node and Element Sets in mesh_object as binary fields (1 on Set, 0 else)
compression_options (dict) – Dictionary containing compression options items, see set_chunkshape_and_compression method for more details.

Location str

Path, Name, Index Name or Alias of the parent group where the Mesh group is to be created

add_mesh_from_image(imagename, with_fields=True, ofTetras=False, meshname='', indexname='', location='/', description=' ', replace=False, bin_fields_from_sets=True, compression_options={})¶

Create a Mesh group in the dataset from an Image dataset.

The mesh group created can represent a mesh of tetrahedra or a mesh of hexaedra, of the image domain (square/triangles in 2D). The fields in the mesh groups are restored, with an adequate shape, and a suffix ‘_msh’ in their indexname.

Parameters

imagename (str) – Name, Path or Indexname of the mesh group to get
with_fields (bool) – If True, load the nodes and elements fields from the image group into the mesh object.
ofTetras (bool) – if True, returns a mesh with tetrahedron elements. If False, return a rectilinera mesh of hexaedron elements.
meshname (str) – name used to create the Mesh group in dataset
indexname – Index name used to reference the Mesh group
description (str) – Description metadata for this mesh
replace (bool) – remove Mesh group in the dataset with the same name/location if True and such group exists
bin_fields_from_sets (bool) – If True, stores all Node and Element Sets in mesh_object as binary fields
compression_options (dict) – Dictionary containing compression options items, see set_chunkshape_and_compression method for more details.

Location str

Path, Name, Index Name or Alias of the parent group where the Mesh group is to be created

add_image(image_object=None, imagename='', indexname='', location='/', description='', replace=False, field_indexprefix='', compression_options={})¶

Create a 2D/3D Image group in the dataset from an ImageObject.

An Image group is a HDF5 Group that contains arrays describing fields defined on an image (uniform grid of voxels/pixels). This methods adds an Image group to the dataset from a BasicTools ConstantRectilinearMesh class instance.This class represents regular meshes of square/cubes, i.e. pixels/voxels.

The image geometry and topology is defined by HDF5 attributes of the Image Group, that are:

nodes_dimension

np.array, number of grid points along each dimension of the Image. This number is array is equal to the dimension attribute array +1 for each value.

dimension

np.array, number of voxels along each dimension of the Image (Nx,Ny,Nz) or (Nx,Ny)

spacing

np.array, voxel size along each dimension (dx,dy,dz) or (dx, dy)

origin

np.array, coordinates of the image grid origin, corresponding to the first vertex of the voxel [0,0,0] or pixel [0,0]

The Image group may also contain arrays of field values on the image. These fields can be elementFields (defined at pixel/voxel centers) or nodefields (defined at pixel/voxel vertexes). Their pathes, index names and content can be set using the class method add_field(). Fields defined on nodes must have a shape equal to the nodes_dimension attribute. Fields defined on elements must have a shape equal to the dimension attribute. Both can have an additional last dimension if they have a higher dimensionality than scalar fields (for instance [Nx,Ny,Nz,3] for a vector field).

Parameters

image_object – image to add to dataset. It is an instance from the ConstantRectilinearMesh class of the BasicTools Python package.
imagename (str) – name used to create the Image group in dataset
indexname (str) – Index name used to reference the Image. If none is provided, imagename is used.
description (str) – Description metadata for this 3D image
replace (bool) – remove Image group in the dataset with the same name/location if True and such group exists
compression_options (dict) – Dictionary containing compression options items, see set_chunkshape_and_compression method for more details.

Location str

Path, Name, Index Name or Alias of the parent group where the Image group is to be created

add_image_from_field(field_array, fieldname, imagename='', indexname='', location='/', description=' ', replace=False, origin=None, spacing=None, is_scalar=True, is_elemField=True, compression_options={})¶

Create a 2D/3M Image group in the dataset from a field data array.

Construct an image object from the inputed field array. This array is interpreted by default as an element field of a pixelized/voxelized grid. Hence, if the field is of shape (Nx,Ny), the image group will store a (Nx,Ny) image (i.e. a regular grid of Nx+1,Ny+1 nodes). If specified, the field can be interpreted as a nodal field (values at pixels/voxels vertexes). In this case the method will create a (Nx-1,Ny-1) image of (Nx,Ny) nodes. The same applies in 3D.

If the field is not a scalar field, the last dimension of the field array is interpreted as the dimension containing the field components

Parameters

field_array (numpy.array) – data array of the field values on the image regular grid.
fieldname (str) – add the field to HDF5 dataset and image Group with this name.
imagename (str) – name used to create the Image group in dataset
indexname (str) – Index name used to reference the Image. If none is provided, imagename is used.
description (str) – Description metadata for this 3D image
replace (bool) – remove Image group in the dataset with the same name/location if True and such group exists
origin (np.array(3,)) – Coordinates of the first node of the regular grid of squares/cubes constituting the image geometry
spacing (np.array(3,)) – Size along each dimension of the pixels/voxels composing the image.
is_scalar (bool) – If True (default value), the field is considered as a scalar field to compute the image dimensions from the field array shape.
is_elemField (bool) – If True (default value), the array is considered as a pixel/voxel wise field value array. If False, the field is considered as a nodal value array.
compression_options (dict) – Dictionary containing compression options items, see set_chunkshape_and_compression method for more details.

Location str

Path, Name, Index Name or Alias of the parent group where the Image group is to be created

add_grid_time(gridname, time_list)¶

Add a list of time values to a grid data group.

If the grid has no time value, an xdmf grid temporal collection is created.

Parameters

gridname (str) – Path, name or indexname of the grid Group where to add time values.
time_list (list(float)) – List of times to add to the grid. Can also be passed as a numpy array.

add_group(groupname, location='/', indexname='', replace=False)¶

Create a standard HDF5 group at location with no grid properties.

If the group parents in location do not exist, they are created.

Parameters

groupname (str) – Name of the group to create
location (str) – Path where the group will be added in the HDF5 dataset
indexname (str) – Index name used to reference the Group. If none is provided, groupname is used.
replace (bool) – remove 3DImage group in the dataset with the same name/location if True and such group exists
createparents (bool) – if True, create parent nodes in path if they are not present in the dataset

add_field(gridname, fieldname, array=None, location=None, indexname=None, chunkshape=None, replace=False, visualisation_type='Elt_mean', compression_options={}, time=None, bulk_padding=True)¶

Add a field to a grid (Mesh or 2D/3DImage) group from a numpy array.

This methods checks the compatibility of the input field array with the grid dimensionality and geometry, adds it to the HDF5 dataset, and the XDMF file. Metadata describing the field type, dimensionality are stored as field HDF node attributes. The path of the field is added to the grid Group as a HDF5 attribute.

Parameters

gridname (str) – Path, name or indexname of the grid Group on which the field will be added
fieldname (str) – Name of the HDF5 node to create that will contain the field value array
array (np.array) – Array containing the field values to add in the dataset

;param str location: Path, name or indexname of the Group in which the: field array will be stored. This Group must be a children of the gridname Group. If not provided, the field is stored in the gridname Group.

Parameters

indexname (str) – Index name used to reference the field node
chunkshape (tuple) – The shape of the data chunk to be read or written in a single HDF5 I/O operation
replace (bool) – remove 3DImage group in the dataset with the same name/location if True and such group exists
filters (Filters) – instance of tables.Filters class specifying compression settings.
visualisation_type (str) – Type of visualisation used to represent integration point fields with an element wise constant field. Possibilities are ‘Elt_max’ (maximum value per element), ‘Elt_mean’ (mean value per element), ‘None’ (no visualisation field). Default value is ‘Elt_mean’
compression_options (dict) – Dictionary containing compression options items, see set_chunkshape_and_compression method for more details.
time (float) – Associate a time value for this field. IF a time value is provided, the suffix ‘_T{time_index}’ is appended to the fieldname and indexname
bulk_padding (bool) – If adding a field on a mesh that has as many bulk as boundary elements, forces field padding to bulk if True, or to boundary if false

add_data_array(location, name, array=None, indexname=None, chunkshape=None, replace=False, compression_options={})¶

Add a data array node at the given location in the HDF5 dataset.

The method uses the CArray and tables.Filters classes of the Pytables package to add data arrays in the dataset and control their chunkshape and compression settings.

Parameters

location (str) – Path where the array will be added in the dataset
name (str) – Name of the array to create
array (np.array) – Array to store in the HDF5 node
indexname (str) – Index name used to reference the node
chunkshape (tuple) – The shape of the data chunk to be read or written in a single HDF5 I/O operation
replace (bool) – remove 3DImage group in the dataset with the same name/location if True and such group exists
filters (Filters) – instance of tables.Filters class specifying compression settings.
empty (bool) – if True create the path, Index Name in dataset and store an empty array. Set the node attribute empty to True.
compression_options (dict) – Dictionary containing compression options items, see set_chunkshape_and_compression method for more details.

add_table(location, name, description, indexname=None, chunkshape=None, replace=False, data=None, compression_options={})¶

Add a structured storage table in HDF5 dataset.

Parameters

location (str) – Path where the array will be added in the dataset
name (str) – Name of the array to create
description (IsDescription) – Definition of the table rows, can be a numpy dtype.
indexname (str) –
Index name used to reference the node composition as a sequence of named fields (analogous to Numpy structured arrays). It must be an instance of the tables.IsDescription class from the Pytables package
chunkshape (tuple) – The shape of the data chunk to be read or written in a single HDF5 I/O operation
replace (bool) – remove 3DImage group in the dataset with the same name/location if True and such group exists
data (np.array(np.void)) – Array to store in the HDF5 node. dtype must be consistent with the table description.
filters (Filters) – instance of tables.Filters class specifying compression settings.
compression_options (dict) – Dictionary containing compression options items, see set_chunkshape_and_compression method for more details.

add_tablecols(tablename, description, data=None)¶

Add new columns to a table node.

Parameters

tablename (str) – Name, Path or Indexname of the table where the columns must be added.
description (np.dtype or tables.IsDescription) – Description of the fields constituting the new columns to add the table.
data (np.array, optional) – values to add into the new columns, defaults to None. The dtype of this array must be constitent with the description argument.

Raises

ValueError – If data.dtype and description do no match

add_string_array(name, location, indexname=None, replace=False, data=[])¶

Add an enlargeable array to store strings of max 255 characters.

String arrays are typically used to store large list of strings that are too large to be stored as HDF5 attributes into the dataset.

Warning

The string are stored as byte strings. You will need to use the str.decode() method to get the elements of the string_array as UTF-8 or ASCII formatted strings.

To manipulate a string array use the ‘get_node’ method to get the array, and then manipulate as a list of binary strings.

Parameters

name (str) – Name of the array to create
location (str) – Path where the array will be added in the dataset
indexname (str) –
Index name used to reference the node composition as a sequence of named fields (analogous to Numpy structured arrays). It must be an instance of the tables.IsDescription class from the Pytables package
replace (bool) – remove array in the dataset with the same name/location if True
data (list[str]) – List of strings to add to the string array upon creation.

append_string_array(name, data=[])¶

Append a list of strings to a string array node in the dataset.

Parameters

name (str) – Path, Indexname, Name or Alias of the string array to which append the list of strings.
data (list(str)) – List of strings to append to the string array.

append_table(name, data)¶

Append a numpy structured array to a table in the dataset.

Parameters

name (str) – Path, Indexname, Name or Alias of the string array to which append the list of strings.
data (numpy.ndarray) – array to append to the table? Its dtype must match de table description.

add_attributes(dic, nodename)¶

Add a dictionary entries as HDF5 Attributes to a Node or Group.

Parameters

dic (dic) – Python dictionary of items to store in HDF5 file as HDF5 Attributes
nodename (str) – Path, Index name or Alias of the HDF5 node or group receiving the Attributes

add_alias(aliasname, path=None, indexname=None)¶

Add alias name to reference Node with inputed path or index name.

Parameters

aliasname (str) – name to add as alias to reference the node
path (str) – Path of the node to reference with aliasname
indexname (str) – indexname of the node to reference with aliasname

add_to_index(indexname, path, colname=None)¶

Add path to index if indexname is not already in content_index.

Parameters

indexname (str) – name to add as indexname to reference the node
path (str) – Path of the node to reference with aliasname
colname (str) – if the node is a table node, set colname to reference a column (named field) of the table with this indexname

compute_mesh_elements_normals(meshname, element_tag, Normal_fieldname=None, align_vector=<Mock name='mock.random.rand()' id='139657949380112'>, as_nodal_field=False)¶

Compute the normals of a set of boundary elements of a mesh group.

The normals are stored as en element wise constant field in the mesh group.

Parameters

meshname (str) – Name, Path, Index name or Alias of the Mesh group in dataset
element_tag (str) – name of the element tag or element type whose normals must be computed
Normal_fieldname (TYPE, optional) – Name of the normals field to store on the mesh group. Defaults to ‘Normals_element_tag_name’
align_vector (np.array(3), optional) – All normals are oriented to have positive dot product with align_vector, defaults to [0,0,1]

Raises

ValueError – Can only process elements of bidimensional topology (surface elements, like triangles, quadrilaterals…)

get_indexname_from_path(node_path)¶

Return the Index name of the node at given path.

Parameters: node_path (str) – Path of the node in the HDF5 data tree
Returns: Returns the Index name of the node

get_mesh(meshname, with_tags=True, with_fields=True, as_numpy=True)¶

Return data of a mesh group as BasicTools UnstructuredMesh object.

This methods gathers the data of a 2DMesh or 3DMesh group, including nodes coordinates, elements types and connectivity and fields, into a BasicTools ConstantRectilinearMesh object.

Parameters

meshname (str) – Name, Path or Indexname of the mesh group to get
with_tags (bool) – If True, store the nodes and element tags (sets) into the mesh object
with_fields (bool, optional) – If True, store mesh group fields into the mesh_object, defaults to True

Returns

Mesh_object containing all data (nodes, elements, nodes and elements sets, fields), contained in the mesh data group.

Return type

BasicTools UnstructuredMesh object.

get_mesh_from_image(imagename, with_fields=True, ofTetras=False)¶

Return an UnstructuredMesh instance from an Image data group.

Parameters

imagename (str) – Name, Path or Indexname of the mesh group to get
with_fields (bool) – If True, load the nodes and elements fields from the image group into the mesh object.
ofTetras (bool) – if True, returns a mesh with tetrahedron elements. If False, return a rectilinera mesh of hexaedron elements.

Returns

Mesh_object containing all data (nodes, elements, nodes and elements sets, fields), corresponding to the Image data group content.

Return type

BasicTools UnstructuredMesh object.

get_mesh_nodes(meshname, as_numpy=False)¶

Return the mesh node coordinates as a HDF5 node or Numpy array.

Parameters

meshname (str) – Name, Path, Index name or Alias of the Mesh group in dataset
as_numpy (bool) – if True, returns the Node as a numpy.array. If False, returns the node as a Node or Group object.

Returns

Return the mesh Nodes coordinates array as a tables.Node object or a numpy.array

get_mesh_nodesID(meshname, as_numpy=False)¶

Return the mesh node ID as a HDF5 node or Numpy array.

Parameters

meshname (str) – Name, Path, Index name or Alias of the Mesh group in dataset
as_numpy (bool) – if True, returns the Node as a numpy.array. If False, returns the node as a Node or Group object.

Returns

Return the mesh Nodes ID array as a tables.Node object or a numpy.array

get_mesh_node_tag(meshname, node_tag, as_numpy=True)¶

Returns the node IDs of a node tag of the mesh group.

Parameters

meshname (str) – Name, Path, Index name or Alias of the Mesh group in dataset
node_tag (str) – name of the node tag whose IDs must be returned.
as_numpy (bool) – if True, returns arrays in elements container as numpy array

get_mesh_node_tag_coordinates(meshname, node_tag)¶

Returns the node coordinates of a node tag of the mesh group.

Parameters

meshname (str) – Name, Path, Index name or Alias of the Mesh group in dataset
node_tag (str) – name of the node tag whose IDs must be returned.
as_numpy (bool) – if True, returns arrays in elements container as numpy array

get_mesh_xdmf_connectivity(meshname, as_numpy=True)¶

Return the mesh elements connectivity as HDF5 node or Numpy array.

Parameters

meshname (str) – Name, Path, Index name or Alias of the Mesh group in dataset
as_numpy (bool) – if True, returns the Node as a numpy.array. If False, returns the node as a Node or Group object.

Returns

Return the mesh elements connectivity referenced in the XDMF file as a tables.Node object or a numpy.array

get_mesh_elements(meshname, with_tags=True, as_numpy=True, get_eltype_connectivity=None)¶

Return the mesh elements connectivity as HDF5 node or Numpy array.

Parameters

meshname (str) – Name, Path, Index name or Alias of the Mesh group in dataset
with_tags (bool) – if True, loads the element tags in the returned elements container
as_numpy (bool) – if True, returns arrays in elements container as numpy array
get_eltype_connectivity (str) – if this argument is set to the name of an element type contained in the mesh, the method retuns the connectivity array of these elements, and not the BasicTools elements container.

Returns

Return the mesh elements container as a BasicTools AllElements object

get_mesh_elem_types_and_number(meshname)¶

Returns the list and types of elements tags defined on a mesh.

Parameters: meshname (str) – Name, Path, Index name or Alias of the Mesh group in dataset
Return dict: keys are element types in the mesh and values are the number of elements for each element type.

get_mesh_elem_tag(meshname, element_tag, as_numpy=True, local_IDs=False)¶

Returns the elements IDs of an element tag of the mesh group.

Parameters

meshname (str) – Name, Path, Index name or Alias of the Mesh group in dataset
element_tag (str) – name of the element tag whose connectivity must be returned. Can also be one of the element types contained in the mesh. In this case, the complete global element IDs for these elements is return
as_numpy (bool) – if True, returns arrays in elements container as numpy array
local_IDs (bool) – if True, returns the local elements IDs for the element type, i.e. the indexes of elements in the local connectivity array that can be obtain with get_mesh_elements.

get_mesh_elem_tags_names(meshname)¶

Returns the list and types of elements tags defined on a mesh.

Parameters: meshname (str) – Name, Path, Index name or Alias of the Mesh group in dataset
Return dict: keys are element tag names in the mesh and values are the element type for each element tag.

get_mesh_elem_tag_connectivity(meshname, element_tag)¶

Returns the list and types of elements tags defined on a mesh.

Parameters

meshname (str) – Name, Path, Index name or Alias of the Mesh group in dataset
element_tag (str) – name of the element tag whose connectivity must be returned.

get_mesh_node_tags_names(meshname)¶

Returns the list of node tags defined on a mesh.

Parameters: meshname (str) – Name, Path, Index name or Alias of the Mesh group in dataset
Return list node_tags: list of node tag names defined on this mesh

get_image(imagename, with_fields=True)¶

Return data of an image group as a BasicTools mesh object.

This methods gathers the data of a 2DImage or 3DImage group, including grid geometry and fields, into a BasicTools ConstantRectilinearMesh object.

Parameters

imagename (str) – Name, Path or Indexname of the image group to get
with_fields (bool) – If True, load the nodes and elements fields from the image group into the mesh object.

Returns

Returns a BasicTools rectilinear mesh object with image group data.

Return type

ConstantRectilinearMesh

get_tablecol(tablename, colname)¶

Return a column of a table as a numpy array.

Parameters

tablename (str) – Name, Path, Index name or Alias of the table in dataset
colname (str) – Name of the column to get in the table (analogous to name of the field to get in a Numpy structured array)

Return numpy.array data

returns the queried column data as a numpy.array

get_table_description(tablename, as_dtype=False)¶: Get the description of the table as a description or Numpy dtype.

get_grid_field_list(gridname)¶

Return the list of fields stored on the grid.

Parameters: gridname (str) – Path, name or indexname of the grid Group on which the field will be added
Return str Field_list: List of the name of the fields dataset stored in the hdf5 file and defined on the grid.

get_field(fieldname, unpad_field=True, get_visualisation_field=False)¶

Return a padded or unpadded field from a grid data group as array.

Use this method to get a mesh element wise field in its original form, i.e. bulk element fields (defined on elements of the same dimensonality than the mesh) or a boundary field (defined on elements of a lower dimensionality than the mesh).

Parameters

fieldname (str) – Name, Path, Index, Alias or Node of the field in dataset
unpad_field (bool) – if True (default), remove the zeros added to to the field to comply with the mesh topology and return it with its original size (bulk or boundary field).

get_node(name, as_numpy=False)¶

Return a HDF5 node in the dataset.

The node is returned as a tables.Node, tables.Group or a numpy.ndarray depending on its nature, and the value of the as_numpy argument.

Parameters

name (str) – Name, Path, Index name or Alias of the Node in dataset
as_numpy (bool) – if True, returns the Node as a numpy.array. If False, returns the node as a Node or Group object.

Returns

Return the node as a a tables.Node or tables.Group object depending on the nature of the node, or, returns it as a numpy.array if required and if the node is an array node.

get_dic_from_attributes(nodename)¶

Get all attributes from a HDF5 Node in the dataset as a dictionary.

Parameters: nodename (str) – Name, Path, Index name or Alias of the HDF5 group
Returns: Dictionary of the form {'Attribute_name': Attribute_value}

get_attribute(attrname, nodename)¶

Get a specific attribute value from a HDF5 Node in the dataset.

Parameters

attrname (str) – name of the attribute to get
nodename (str) – Name, Path, Index name or Alias of the HDF5 group

Returns

Value of the attribute

get_file_disk_size(print_flag=True, convert=True)¶

Get the disk size of the dataset.

Parameters

print_flag (bool) – print the disk size if True
convert (bool) – convert disk size to a suitable memory unit if True. If False, return result in bytes.

Return float fsize

Disk size of the dataset in unit

Return str unit

Unit of fsize. bytes is the default

get_node_disk_size(nodename, print_flag=True, convert=True)¶

Get the disk size of a HDF5 node.

Parameters

nodename (str) – Name, Path, Index name or Alias of the HDF5 node
print_flag (bool) – print the disk size if True
convert (bool) – convert disk size to a suitable memory unit if True. If False, return result in bytes.

Return float fsize

Disk size of the dataset in unit

Return str unit

Unit of fsize. bytes is the default

get_sample_name()¶: Return the sample name.

set_sample_name(sample_name)¶

Set the sample name.

Parameters: sample_name (str) – a string for the sample name.

get_description(node='/')¶

Get the string describing this node.

By defaut the sample description is returned, from the root HDF5 Group.

Parameters: nodename (str) – the path or name of the node of interest.

set_description(description, node='/')¶

Set the description of a node.

By defaut this method sets the description of the complete sample, in the root HDF5 Group.

Parameters

description (str) – a string for the description of the node or sample.
node (str) – the path or name of the node of interest (‘/’ by default).

set_new_indexname(nodename, new_indexname)¶

Change the indexname of a node in the dataset.

Usefull to solve indexname duplicates issues that can arises when automatically adding elements to the dataset, that have the same name.

Parameters

nodename (str) – Name, Path, Indexname or Alias of the node whose indexname is to be changed
new_indexname (str) – New indexname for the node

set_voxel_size(image_group, voxel_size)¶

Set voxel size for an HDF5/XDMF image data group.

The values are registered in the spacing Attribute of the 3DImage group.

Parameters

image_data_group (str) – Name, Path, Index name or Alias of the 3DImage group
voxel_size (np.array) – (dx, dy, dz) array of the voxel size in each dimension of the 3Dimage

set_origin(image_group, origin)¶

Set origin coordinates for an HDF5/XDMF image data group.

The origin corresponds to the first vertex of the first voxel, that is referenced by the [0,0,0] elements of arrays in the 3DImage group. The values are registered in the origin Attribute of the 3DImage group.

Parameters

image_data_group (str) – Name, Path, Index name or Alias of the 3DImage group
voxel_size (np.array) – (Ox, Oy, Oz) array of the coordinates in each dimension of the origin of the 3Dimage

set_tablecol(tablename, colname, column)¶

Store an array into a structured table column.

If the column is not in the table description, a new field corresponding to the inputed column is added to the table description.

Parameters

tablename (str) – Name, Path, Index name or Alias of the table
colname (str) – Name of the column to set (analogous to name of a field in a Numpy structured array)
column (np.array) – array of values to set as column of the table. It’s shape must match the column shape in table description.

set_nodes_compression_chunkshape(node_list=None, chunkshape=None, compression_options={})¶

Set compression options for a list of nodes in the dataset.

This methods sets the same set of compression options for a list of nodes in the dataset.

Parameters

node_list (list) – list of Name, Path, Index name or Alias of the HDF5 array nodes where to set the compression settings.
chunkshape (tuple) – The shape of the data chunk to be read or written in a single HDF5 I/O operation
compression_options (dict) – Dictionary containing compression options items (keys are options names, values are )

Compression Options

Compression settings can be passed through the compression_options dictionary as follows:

compression_options[option_name] = option_value

These options are the Pytables package Filters class constructor parameters (see PyTables documentation for details) The list of available compression options is provided here:

complevel: Compression level for data. Allowed range is 0-9. A value of 0 (the default) disables compression.

complib: Compression library to use. Possibilities are: zlib’ (the default), ‘lzo’, ‘bzip2’ and ‘blosc’.

shuffle: Whether or not to use the Shuffle filter in the HDF5 library (may improve compression ratio).

bitshuffle: Whether or not to use the BitShuffle filter in the Blosc library (may improve compression ratio).

fletcher32: Whether or not to use the Fletcher32 filter in the HDF5 library. This is used to add a checksum on each data chunk.

least_significant_digit: If specified, data will be truncated using around(scale*data)/scale, where scale = 2**least_significant_digit. In conjunction with enabling compression, this produces ‘lossy’, but significantly more efficient compression.

Important

If the new compression settings reduce the size of the node in the dataset, the file size will not be changed. This is a standard behavior for HDF5 files, that preserves freed space in disk to add additional data in the future. If needed, use the repack_file() method to reduce file disk size after changing compression settings. This method is also called by the class instance destructor.

Note

If compression settings are passed as additional keyword arguments, they are prioritised over the settings in the inputed Filter object.

set_chunkshape_and_compression(nodename, chunkshape=None, compression_options={})¶

Set the chunkshape and compression settings for a HDF5 array node.

Parameters

node (str) – Name, Path, Index name or Alias of the node
chunkshape (tuple) – The shape of the data chunk to be read or written in a single HDF5 I/O operation
compression_options (dict) – Dictionary containing compression options items (keys are options names, values are )

Compression options

Compression settings can be passed through the compression_options dictionary as follows:

compression_options[option_name] = option_value

See set_nodes_compression_chunkshape(), for the list of available compression options.

Important

If the new compression settings reduce the size of the node in the dataset, the file size will not be changed. This is a standard behavior for HDF5 files, that preserves freed space in disk to add additional data in the future. If needed, use the repack_file() method to reduce file disk size after changing compression settings. This method is also called by the class instance destructor.

Note

If compression settings are passed as additional keyword arguments, they are prioritised over the settings in the inputed Filter object.

set_verbosity(verbosity=True)¶: Set the verbosity of the instance methods to inputed boolean.

remove_attribute(attrname, nodename)¶

Remove an attribute from a node in the dataset.

Parameters

attrname (str) – name of the attribute to remove
nodename (str) – Name, Path or Index name of the node to modify

remove_attributes(attr_list, nodename)¶

Remove an attribute from a node in the dataset.

Parameters

attr_list (list) – list of the names of the attribute to remove
nodename (str) – Name, Path or Index name of the node to modify

rename_node(nodename, newname, replace=False, new_indexname=None)¶

Rename a node in the HDF5 tree, XDMF file and content index.

This method do not change the indexname of the node, if one exists.

Parameters

nodename (str) – Name, Path or Index name of the node to modify
newname (str) – New name to give to the HDF5 node
replace (bool, optional) – If True, overwrite a possibily existing node with name newname defaults to False

remove_node(name, recursive=False)¶

Remove a node from the dataset.

Parameters

name (str) – Name, Path, Index name or Alias of the node to remove
recursive (bool) – if True and the node is a Group, removes all childrens of the node as well.

Important

After node removal, the file size will not be changed. This is a standard behavior for HDF5 files, that preserves freed space in disk to add additional data in the future. If needed, use the repack_file() method to reduce file disk size after changing compression settings. This method is also called by the class instance destructor.

repack_h5file()¶

Overwrite hdf5 file with a copy of itself to recover disk space.

Manipulation to recover space leaved empty when removing data from the HDF5 tree or reducing a node space by changing its compression settings. This method is called also by the class destructor if the autorepack flag is True.

static copy_sample(src_sample_file, dst_sample_file, overwrite=False, get_object=False, new_sample_name=None, autodelete=False)¶

Initiate a new SampleData object and files from existing dataset.

Parameters

src_sample_file (src) – name of the dataset file to copy.
dst_sample_file (src) – name of the new dataset files.
overwrite (bool) – set to True to overwrite an existing dataset file with name dst_sample_file when copying.
get_object (bool) – if True returns the SampleData instance
new_sample_name (str) – name of the sample in the new dataset
autodelete (bool) – remove copied dataset files when copied instance is destroyed.

create_elset_ids_field(meshname=None, store=True, fieldname=None, get_sets_IDs=True, tags_prefix='elset', remove_elset_fields=False)¶

Create an element tag Id field on the inputed mesh.

Creates a element wise field from the provided mesh, adding to each element the value of the Elset it belongs to.

Warning

CAUTION : the methods is designed to work with non intersecting element tags/sets. In this case, the produce field will indicate the value of the last elset containing it for each element.

Parameters

mesh (str) – Name, Path or index name of the mesh on which an orientation map element field must be constructed
store (bool) – If True, store the field on the mesh
get_sets_IDs (bool) – If True, get the sets ID numbers from their names by substracting the input prefix. If False, use the set position in the mesh elset list as ID number.
tags_prefix (str) – Remove from element sets/tags names prefix to determine the set/tag ID. This supposes that sets names have the form prefix+ID
remove_elset_fields (bool) – If True, removes the elset indicator fields after construction of the elset id field. (default is False)

core Package¶

samples Module¶

`samples` Module¶