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 HDF5 file containing all data and metadata.

The HDF5 data tree structure is accessible through the h5_dataset class attributes, that is an instance of a class from the package Pytables.

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 base_name of HDF5 file 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 file with the same filename.

Autodelete:

bool, optional (False) set to True to remove HDF5 file 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:

base_name 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

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.

__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(filename=None)

Write xdmf_tree in .xdmf file with suitable XML declaration.

print_dataset_content(as_string=False, max_depth=3, to_file=None, short=False, printTags=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.

  • printTags (bool) – If ‘True’, print information for mesh element and node Tags nodes. Default is ‘False’.

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, printTags=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.

  • printTags (bool) – If ‘True’, print information for mesh element and node Tags nodes. Default is ‘False’.

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.

Parameters:

  • node_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. :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 Index and flush .h5 file.

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 create automatically a XDMF file and launch Paraview to visualize the 2D/3D content in the dataset.

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

  • location (str) – Path, Name, Index Name or Alias of the parent group where the Mesh group is to be created

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

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_index_prefix='', 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

  • field_index_prefix (str) – the prefix to use to field stored in the image object.

  • 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_elem_field=True, compression_options={})

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

Construct an image object from the input 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.

  • location (str) – Path, Name, Index Name or Alias of the parent group where the Image group is to be created

  • 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_elem_field (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.

add_field_time(fieldname, time)

Add a time value to a field array node.

If the grid supporting the field does not have this time value stored, the time value is added to the grid time serie.

Parameters:

  • fieldname (str) – Path, name or indexname of the field Node

  • time (float) – Time value to add to the field

add_grid_time(gridname, time_list)

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

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

  • location (str) – 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.

  • 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

  • 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 field_name 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 input 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=array([0.32973546, 0.07263922, 0.39243168]), 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)

Return 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)

Return 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 for the XDMF format as a tables.Node object or a numpy.array

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

Return mesh elements as a Basictools elements container.

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)

Return 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)

Return 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)

Return 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)

Return 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)

Return 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(field_name, 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:

  • field_name (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:

node (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 image data group.

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

Parameters:

  • image_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 a HDF5 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_group (str) – Name, Path, Index name or Alias of the 3DImage group

  • origin – (Ox, Oy, Oz) array of the coordinates in each dimension of the origin of this image group.

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 input 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 input Filter object.

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

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

Parameters:

  • nodename (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 input Filter object.

set_verbosity(verbosity=True)

Set the verbosity of the instance methods to input 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 and the 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.

resample_image_group(new_voxel_size, location='CellData', new_location=None, in_place=False)

Resample a whole image group with a new spatial resolution.

Note

In the case where the spatial resolution if increased, the new cell data will have a surrounding layer of zeros (for the new cells centers located outside the original cells centers).

Parameters:

  • new_voxel_size (float) – the new spatial resolution.

  • location (str) – the location of the image group to process.

  • new_location (str) – the name of the new location to store the

resampled image group. :param bool in_place: if True, the actual image group will be replaced by the new resampled group.

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(mesh_name=None, store=True, field_name=None, get_sets_ids=True, tags_prefix='elset', remove_elset_fields=False)

Create an element tag id field on the input mesh.

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

Note

  • CAUTION : the method 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_name (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

  • field_name (str) – the name to use for the newly created field, if

not specified, the string ‘_elset_ids’ will be appended to the mesh name. :param bool get_sets_ids: 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.

Parameters:

  • 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)

__annotations__ = {}