ImportHDF5Species

Category

Import and Export

Function

Imports selected particles from an HDF5 file.

Syntax

field = ImportHDF5Species(filename, datasetname, x0min, x0max, x1min, x1max, x2min, x2max, u0min, u0max, u1min, u1max, u2min, u2max, stride, random)

Inputs

Name

Type

Defaults

Description

filename

string

(none)

file name

fieldname

string

(none)

dataset name

x0min

scalar

(none)

minimal value of the 1st coordinate

x0max

scalar

(none)

maximal value of the 1st coordinate

x1min

scalar

(none)

minimal value of the 2nd coordinate

x1max

scalar

(none)

maximal value of the 2nd coordinate

x2min

scalar

(none)

minimal value of the 3rd coordinate

x2max

scalar

(none)

maximal value of the 3rd coordinate

u0min

scalar

(none)

minimal value of the 1st data element

u0max

scalar

(none)

maximal value of the 1st data element

u1min

scalar

(none)

minimal value of the 2nd data element

u1max

scalar

(none)

maximal value of the 2nd data element

u2min

scalar

(none)

minimal value of the 3rd data element

u2max

scalar

(none)

maximal value of the 3rd data element

stride

integer

(none)

the step size between certainly selected particles

random

integer

(none)

the number of particles to select at random

Outputs

Name

Type

Description

field

field

field with selected particles

 

Functional Details

The module imports from an HDF5 file particles which satisfy the user's conditions stated in the section Particle Selection. The HDF5 file must be of a special format described in the section File Structure.

You will encounter the terms "dataset", "dataspace", "scalar dataspace", "attribute", and "root group" in the following text. For their definitions please consult the documentation of the HDF5 library.

The module imports particles of only one dataset. This means that the module needs only one file name and one dataset name.

A particle is described by its position (coordinates) and its data (data elements).

The number of dimensions of the created field is equal to the number of coordinates of the dataset's particles.

The module can import particles that have any number of coordinates and any number of data elements -- those numbers are limited only by the capabilities of the HDF5 library and OpenDX.

The HDF5 data is subject to data conversion when it is loaded into memory. The data can be stored in memory in the float or double types, because OpenDX operates only on those two types. If the size of the dataset's data type is smaller than or equal to the size of a float, then the data is converted to the "float" data type; otherwise the data is stored in memory in the "double" data type.

The module was designed to let the user specify conditions on up to three coordinates and up to three data elements. If you load particles that have more than three coordinates, then the field is going to have that number of dimensions, but you are going to be able to specify conditions for only the first three coordinates. Similarly, if the dataset's particles have more data elements (floats or doubles) than three, then the field's data is going to contain all elements (even though there are more than three), but the conditions can be only given for the first three elements.

You can import particles whose data is a scalar or a vector. Say a particle's data is its mass. In that case you will be able to give conditions only for the u0min and u0max inputs, and the field's data is going to be a scalar.

filename
A required input which gives the name of the file that contains a dataset with particle description. If the name contains an absolute path, the file will be loaded from there, otherwise the module will search for the file in the working directory and in the directories listed in the DXDATA environment variable.
 
datasetname
An optional argument to specify the name of the dataset for the given file. Each set of particles is described by one dataset, and there may be many datasets in a file describing many fields.

The argument may be left blank. In that case the default dataset is chosen, which is the only dataset in the root group of the file. Asking for a default dataset while there are several datasets in the root group is considered an error.

 
x0min
An optional argument to specify the minimum value of the first particle's coordinate. Particles having a lower value of the first coordinate are discarded.

There are no restrictions for this input -- any number can be provided. If the input is left blank, no condition is given.

 
x0max
An optional argument to specify the maximum value of the first particle's coordinate. Particles having a greater value of the first coordinate are discarded.

There are no restrictions for this input -- any number can be provided. If the input is left blank, no condition is given.

 
x1min
An optional argument to specify the minimum value of the second particle's coordinate. Particles having a lower value of the second coordinate are discarded.

There are no restrictions for this input -- any number can be provided. If the input is left blank, no condition is given.

 
x1max
An optional argument to specify the maximum value of the second particle's coordinate. Particles having a greater value of the second coordinate are discarded.

There are no restrictions for this input -- any number can be provided. If the input is left blank, no condition is given.

 
x2min
An optional argument to specify the minimum value of the third particle's coordinate. Particles having a lower value of the third coordinate are discarded.

There are no restrictions for this input -- any number can be provided. If the input is left blank, no condition is given.

 
x2max
An optional argument to specify the maximum value of the third particle's coordinate. Particles having a greater value of the third coordinate are discarded.

There are no restrictions for this input -- any number can be provided. If the input is left blank, no condition is given.

 
u0min
An optional argument to specify the minimum value of the first data element. Particles having a lower value of the first data element are discarded.

There are no restrictions for this input -- any number can be provided. If the input is left blank, no condition is given.

 
u0max
An optional argument to specify the maximum value of the first data element. Particles having a greater value of the first data element are discarded.

There are no restrictions for this input -- any number can be provided. If the input is left blank, no condition is given.

 
u1min
An optional argument to specify the minimum value of the second data element. Particles having a lower value of the second data element are discarded.

There are no restrictions for this input -- any number can be provided. If the input is left blank, no condition is given.

 
u1max
An optional argument to specify the maximum value of the second data element. Particles having a greater value of the second data element are discarded.

There are no restrictions for this input -- any number can be provided. If the input is left blank, no condition is given.

 
u2min
An optional argument to specify the minimum value of the third data element. Particles having a lower value of the third data element are discarded.

There are no restrictions for this input -- any number can be provided. If the input is left blank, no condition is given.

 
u2max
An optional argument to specify the maximum value of the third data element. Particles having a greater value of the third data element are discarded.

There are no restrictions for this input -- any number can be provided. If the input is left blank, no condition is given.

 

 

Particle Selection

Particles from the file's dataset must meet the user's conditions to be selected and be present in the generated OpenDX field. Each particle is examined separately. There are three kinds of conditions: limits, stride and random. A particle is selected when at least one of the conditions is satisfied. If a condition is not given (the values for its inputs are NULL), then this condition does not apply. When no conditions are given, then every particle is selected.

If at least one condition for minimal or maximal values of coordinates (x0min, x0max, ..., x2max) or data elements (u0min, u0max, ..., u2max) is given, then a particle is tested for limits. If a particle satisfies all the given limits, then it is selected.

If the value of the "stride" input is provided, a particle will be selected if: 

	n modulo stride = 0
where:
  1. n is the number of this particle in the dataset (the first particle has the 0 number),
  2. stride is the value of the "stride" input.

If the value of the "random" input is provided, a particle is likely to be selected with the probability p: 

	p = random / N;
where:
  1. random is the value of the "random" input,
  2. N is the number of particles in the file's dataset.

 

File Structure

Both position components and velocity components must be of the same data type. The data type must be of the class H5T_FLOAT.

Data about a set of particles must be stored in one dataset. There might be several datasets in a file, so there might be several particle sets stored there. The module imports particles only from one dataset.

The file must satisfy the following conditions:

  1. there must exist at least one dataset in the file,
  2. the data class of the dataset's data type must be "H5T_FLOAT",
  3. the dataset should have the attribute named "numSpatialDims".

The class of the data type of the dataset must be "H5T_FLOAT" (data types that are of this class are, for example, "NATIVE_FLOAT" or "NATIVE_DOUBLE"). Depending on the data type of the dataset, the created OpenDX field is either of the types "float" or "double". If the size in bytes of the dataset's data type is equal to or smaller than the size in bytes of "float", then the data type of the created OpenDX field is "float", otherwise the data type is "double".

The dataset must be an array of dimensions: 

(number of particles)x(a particle's length)

A particle's length is the number of elements (floats or doubles) that compose a particle. For instance, there are particles that have two coordinates and three velocity components, and therefore the particle's length is 5.

In the description of each particle, the coordinates go first, and the data go second. Therefore a particle in 3-D with three velocity components is stored in the dataset as (where x's are coordinates and u's are velocities): 

{x0, x1, x2, u1, u2, u3}

The attribute "numSpatialDims" must be of the dataspace H5S_SCALAR and must be of the class H5T_INTEGER. The value of the attribute tells the number of a particle coordinates. If the attribute is not present, then the default value for this attribute is 3.

There may be additionally dataset's attributes defined, but they are of no use for the module and therefore are ignored.

 

Example

In this section presented and commented on are a few ways of importing particles from an HDF5 file, along with figures illustrating the results.

After the module is installed, this example is available as an OpenDX program in the file: 

path_to_OpenDX/samples/moduleTryOut/ImportHDF5SpeciesUsage.net

In the example the file ImportHDF5SpeciesUsage.h5 is used, which was generated by VORPAL (http://www-beams.colorado.edu/~vorpal). The file contains a description of electrons.

The h5dump tool reports the following structure of the file: 

> h5dump -H samples/ImportHDF5SpeciesUsage.h5 
HDF5 "samples/ImportHDF5SpeciesUsage.h5" {
GROUP "/" {
   DATASET "ImportHDF5SpeciesUsage.h5" {
      DATATYPE  H5T_IEEE_F32LE  
      DATASPACE  SIMPLE { ( 5889, 5 ) / ( H5S_UNLIMITED, 5 ) } 
      ATTRIBUTE "numSpatialDims" {
         DATATYPE  H5T_STD_I32LE  
         DATASPACE  SCALAR  
      } 
   } 
} 
}

We can see that the file complies with the requirements stated in the section File Structure: there is a dataset defined with the data type of the "H5T_FLOAT" class, and the attribute "numSpatialDims" of the correct format is present.

The easiest way to use the module is to supply the file name only, and the module will import all the particles (Fig. 1).

If there are too many particles in the dataset, it suffices to import every second or every third particle, thus reducing memory requirements. For example, to import every third particle you have to set the value of the "stride" input to 3. Figure 2 shows the results.

Figure 3 presents particles with u0 > 107. To achieve this result only the "u0min" input must be given the 107 value.

Figure 4 presents particles from Fig. 3 with roughly 750 random particles additionally selected. To achieve this result the "u0min" input must equal to 107 and the "random" input must equal to 750.

Figure 1
Figure 1: All the particles.

Figure 2
Figure 2: Every third particle chosen.

Figure 3
Figure 3: Particles with u0 > 107.

Figure 4
Figure 4: Particles with u0 > 107 and roughly 750 particles randomly selected.

 

Debugging

The module issues warning and error messages if it is provided with incorrect arguments or files. These messages should suffice to diagnose problems. However, you might want to examine the input (an HDF5 file) and output (an OpenDX field) of the module. Use the h5dump utility to examine the structure of an HDF5 file. To get information on the field which the module produced, use the Print module of OpenDX. Please consult the OpenDX documentation to learn about the Print module.

You might want to examine debug messages generated by the module. The module is sensitive to the "d" flag which you can set with the Trace module of OpenDX. Please consult the OpenDX documentation to learn about the Trace module. You need to use the Trace module is the script mode of OpenDX. To start OpenDX in the script mode with the dxhdf5 modules, execute: 

	 dxhdf5 -script -cache off
Then type in this example: 
	 dx> Trace("d", 1);
	 dx> output = ImportHDF5Species("yourFile.h5");

 

See Also

Import, Slab, ImportHDF5Field

 

Example Visual Programs

ImportHDF5SpeciesUsage.net

The example is located in: 

path_to_OpenDX/samples/moduleTryOut/

Please make sure that you run the program with the above directory as the working directory, for there is an HDF5 file used by the example.

Contact Information

Visit http://www-beams.colorado.edu/dxhdf5/index.html#contact for contact information. 


Last modified: 2004/12/13 10:06:05