examplePio.c File Reference

A simple C example for the ParallelIO Library. More...

#include "config.h"
#include <getopt.h>
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
#include <mpi.h>
#include <pio.h>

Include dependency graph for examplePio.c:

Macros
#define	TEST_NAME   "examplePio"
	The name of this program.

Typedefs
typedef struct examplePioClass	examplePioClass
	Holds code and data for this example. More...

Functions
struct examplePioClass *	epc_init (struct examplePioClass *this)
	Initialize libraries, create sample data. More...
struct examplePioClass *	epc_createDecomp (struct examplePioClass *this)
	Create the decomposition. More...
struct examplePioClass *	epc_createFile (struct examplePioClass *this)
	Create the netCDF file. More...
struct examplePioClass *	epc_defineVar (struct examplePioClass *this)
	Define netCDF metadata. More...
struct examplePioClass *	epc_writeVar (struct examplePioClass *this)
	Write the sample data to the file. More...
struct examplePioClass *	epc_readVar (struct examplePioClass *this)
	Read the example data from the file. More...
struct examplePioClass *	epc_closeFile (struct examplePioClass *this)
	Closes the netCDF file. More...
struct examplePioClass *	epc_cleanUp (struct examplePioClass *this)
	Clean up allocated resources. More...
struct examplePioClass *	epc_errorHandler (struct examplePioClass *this, const char *errMsg, const int retVal)
	Error handling function. More...
struct examplePioClass *	epc_new (int verbose)
	Create an examplePioClass object. More...
int	main (int argc, char *argv[])
	Main execution of code. More...

Detailed Description

A simple C example for the ParallelIO Library.

This example creates a netCDF output file with one dimension and one variable. It first writes, then reads the sample file using the ParallelIO library.

This example can be run in parallel for 1, 2, 4, 8, or 16 processors.

Typedef Documentation

examplePioClass

typedef struct examplePioClass examplePioClass

Holds code and data for this example.

This struct stores pointers to the functions used in the example, and all the data values needed to run the example code.

Function Documentation

epc_cleanUp()

struct examplePioClass* epc_cleanUp

(

struct examplePioClass *

this

)

Clean up allocated resources.

This function frees the memory used in this example. It calls the ParallelIO library function PIOc_freedecomp() to free decomposition resources. Then calles PIOc_free_iosystem() and MPI_finalize() to free library resources.

Parameters

[in]

this

Pointer to self.

Return values

examplePioClass*

Pointer to self.

epc_closeFile()

struct examplePioClass* epc_closeFile

(

struct examplePioClass *

this

)

Closes the netCDF file.

Uses the PIOc_closefile() function to close the netCDF sample file written by this example.

Parameters

[in]

this

Pointer to self.

Return values

examplePioClass*

Pointer to self.

epc_createDecomp()

struct examplePioClass* epc_createDecomp

(

struct examplePioClass *

this

)

Create the decomposition.

This function is called as part of the creation of a sample data file for this example.

Uses PIOc_InitDecomp() to initalize the decomposition for this example. The arguments are:

• the ID of the IO system, obtained from PIOc_init_intracomm().
• the NetCDF type of the sample data - in this case a 4-byte integer.
• the number of dimensions (1).
• the lengths of the dimensions.
• the number of data elements assigned to each processor.
• the array which provides the decomposition mapping.
• the IO description pointer.
• the ParallelIO rearranger (we are providing NULL here to get the default arranger).
• optional array of start values for block cyclic decompositions (NULL means don't use block cyclical decompositions).
• optional array of count values for block cyclic decompositions (NULL means don't use block cyclical decompositions).

The decomposition mapping array (called compdof, in this example code), contains a 1 based array of offsets into the array record on file. For this example, the compdof array will have the following sizes and values, depending on number of processors used.

For one processor the decomposition array looks like this (note that the array is 1-based):

rank: 0 length: 16 [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]

For two processors, the decomposition array looks like this on each processor:

rank: 0 length: 8 [1, 2, 3, 4, 5, 6, 7, 8]
rank: 1 length: 8 [9, 10, 11, 12, 13, 14, 15, 16]

For four processors, the decomposition arrays are:

rank: 0 length: 4 [1, 2, 3, 4]
rank: 1 length: 4 [5, 6, 7, 8]
rank: 2 length: 4 [9, 10, 11, 12]
rank: 3 length: 4 [13, 14, 15, 16]

Parameters

[in]

this

Pointer to self.

Return values

examplePioClass*

Pointer to self.

epc_createFile()

struct examplePioClass* epc_createFile

(

struct examplePioClass *

this

)

Create the netCDF file.

This function is called as part of the creation of a sample data file for this example.

Uses the function PIOc_createfile() to create the netCDF output file. The format of the file is created in accordance with the iotype member variable, which specifies one of the following values:

• PIO_IOTYPE_PNETCDF=1 Parallel Netcdf (parallel)
• PIO_IOTYPE_NETCDF=2 Netcdf3 Classic format (serial)
• PIO_IOTYPE_NETCDF4C=3 NetCDF4 (HDF5) compressed format (serial)
• PIO_IOTYPE_NETCDF4P=4 NetCDF4 (HDF5) parallel

The PIOc_createfile() function has the following parameters:

• The IO system ID as set by PIOc_init_intracomm().
• A pointer which will get the ncid of this file when it is created.
• The iotype (one of the values listed above).
• the name of the sample file.
• the NetCDF file creating mode, PIO_CLOBBER means overwrite any existing file with this name.

Parameters

[in]

this

Pointer to self.

Return values

examplePioClass*

Pointer to self.

epc_defineVar()

struct examplePioClass* epc_defineVar

(

struct examplePioClass *

this

)

Define netCDF metadata.

This function is called as part of the creation of a sample data file for this example.

It defines a dimension and a one-dimensional variable in the netCDF file using functions PIOc_def_dim() and PIOc_def_var(). It then calls PIOc_enddef() to end the define mode of the file.

All of the functions take the pioFileDesc returned by PIOc_createfile(). This is the ncid of the netCDF file.

Parameters

[in]

this

Pointer to self.

Return values

examplePioClass*

Pointer to self.

epc_errorHandler()

struct examplePioClass* epc_errorHandler	(	struct examplePioClass *	this,
		const char *	errMsg,
		const int	retVal
	)

Error handling function.

On error, process with rank zero will print error message, the netCDF file will be closed with PIOc_closefile(), and MPI_Abort is called to end the example execution on all processes.

Parameters

[in]	this	Pointer to self.
[in]	errMsg	an error message
[in]	retVal	the non-zero return value that indicated an error

Return values

examplePioClass*

Pointer to self.

epc_init()

struct examplePioClass* epc_init

(

struct examplePioClass *

this

)

Initialize libraries, create sample data.

This function is called as part of the creation of a sample data file for this example.

Ths funtion initializes MPI and the ParallelIO libraries. It sets up the ParallelIO library communicator. It also allocates memory for data used in this example, and assigns sample values to the data array that will be written.

The ParallelIO communicator is set up with a call to PIOc_Init_Intracomm(). This call takes the following parameters:

• The MPI communicator specifying the invovled processors (MPI_COMM_WORLD, in this case, to use all processors).
• The number of I/O tasks. In this example there will be one I/O task for each process.
• The stride (1 in this case).
• The index of the first I/O task.
• The iotype, specifying the flavor of netCDF to use.
• Specify the subset rearranger.
• A pointer that will get the ID of the ParallelIO system created for this call. This ID will be needed when reading or writing to the file using the ParallelIO library.

Parameters

[in]

this

Pointer to self.

Return values

examplePioClass*

Pointer to self.

epc_new()

struct examplePioClass* epc_new

(

int

verbose

)

Create an examplePioClass object.

This function allocates memory for the struct that contains the code and data for this example. Then pointers are to the functions used in the example.

Parameters

[in]

verbose

Non-zero for output to stdout.

Return values

examplePioClass*

Pointer to self.

epc_readVar()

struct examplePioClass* epc_readVar

(

struct examplePioClass *

this

)

Read the example data from the file.

This function is called as part of the creation of a sample data file for this example.

This function reads the data that has been written to the sample data file. The data are read with the PIOc_read_darray() function.

Parameters

[in]

this

Pointer to self.

Return values

examplePioClass*

Pointer to self.

epc_writeVar()

struct examplePioClass* epc_writeVar

(

struct examplePioClass *

this

)

Write the sample data to the file.

This function is called as part of the creation of a sample data file for this example.

The data are written with the PIOc_write_darray() function. After the write is complete, ensure the file is synced for all processes after the write.

Parameters

[in]

this

Pointer to self.

Return values

examplePioClass*

Pointer to self.

main()

int main	(	int	argc,
		char *	argv[]
	)

Main execution of code.

Executes the functions to:

• create a new examplePioClass instance
• initialize MPI and the ParallelIO libraries
• create the decomposition for this example
• create the netCDF output file
• define the variable in the file
• write data to the variable in the file using decomposition
• read the data back from the file using decomposition
• close the file
• clean up resources

The example can be run from the command line (on system that support it) like this:

mpiexec -n 4 ./examplePio

The sample file created by this program is a small netCDF file. It has the following contents (as shown by ncdump) for a 4-processor run:

netcdf examplePio_c {
dimensions:
    x = 16 ;
variables:
    int foo(x) ;
data:

    foo = 42, 42, 42, 42, 43, 43, 43, 43, 44, 44, 44, 44, 45, 45, 45, 45 ;
}

Parameters

[in]	argc	argument count (should be zero)
[in]	argv	argument array (should be NULL)

Return values

examplePioClass*

Pointer to self.