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

Include dependency graph for example2.c:

Macros
#define	NUM_NETCDF_FLAVORS 4
	The number of possible output netCDF output flavors available to the ParallelIO library.

#define	NDIM 3
	The number of dimensions in the example data. More...

#define	X_DIM_LEN 20
	Length along x dimension.

#define	Y_DIM_LEN 30
	Length along y dimension.

#define	NUM_TIMESTEPS 6
	The number of timesteps of data to write.

#define	VAR_NAME "foo"
	The name of the variable in the netCDF output file.

#define	ERR_BAD 1001
	Return code when netCDF output file does not match expectations.

#define	START_DATA_VAL 42
	The meaning of life, the universe, and everything.

#define	MPIERR(e)
	Handle MPI errors. More...

#define	ERR(e)
	Handle non-MPI errors by finalizing the MPI library and exiting with an exit code. More...

#define	NUM_EVENTS 10
	Number of MPE events. More...

#define	ERR_FILE 1
	File error.

#define	ERR_DUMB 2
	File error.

#define	ERR_ARG 3
	Argument error.

#define	ERR_MPI 4
	MPI error.

#define	ERR_MPITYPE 5
	MPI Type error.

#define	ERR_LOGGING 6
	Logging error.

#define	ERR_UPDATE 7
	Update error.

#define	ERR_CALC 8
	Calculation error.

#define	ERR_COUNT 9
	Count error.

#define	ERR_WRITE 10
	Write error.

#define	ERR_SWAP 11
	Swap error.

#define	ERR_INIT 12
	Init error.

Functions
int	init_logging (int my_rank, int event_num[][NUM_EVENTS])
	This will set up the MPE logging event numbers. More...

int	check_file (int ntasks, char *filename)
	Check the output file. More...

int	calculate_value (int my_rank, int timestep, float *datap)
	Calculate sample data. More...

int	main (int argc, char *argv[])
	Main execution of code. More...

Variables
char	exerr_buffer [MPI_MAX_ERROR_STRING]
	Global err buffer for MPI. More...

int	exresultlen
	This is the length of the most recent MPI error message, stored int the global error string.

char	dim_name [NDIM][PIO_MAX_NAME+1] = {"timestep", "x", "y"}
	The dimension names.

int	dim_len [NDIM] = {NC_UNLIMITED, X_DIM_LEN, Y_DIM_LEN}
	Length of the dimensions in the sample data.

PIO_Offset	chunksize [NDIM] = {2, X_DIM_LEN/2, Y_DIM_LEN/2}
	Length of chunksizes to use in netCDF-4 files.

Detailed Description

A simple C example for the ParallelIO Library.

This example creates a netCDF output file with one 3D variable. One of the dimensions will be unlimited. The example first writes the sample file using the ParallelIO library, then reads it with the plain old netCDF library to check that it is correct.

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

This example uses the MPE performace profiling library, if it is present on the build machine. After the program is run, MPE will produce a file called example2.clog2. In order to see the nice graphs, execute the commands:

clog2ToSlog2 example2.clog2
jumpshot example2.slog2

Macro Definition Documentation

◆ ERR

#define ERR ( e )

Value:

        do {                \
        fprintf(stderr, "Error %d in %s, line %d\n", e, __FILE__, __LINE__); \
        MPI_Finalize();             \
        return e;               \
    } while (0)

Handle non-MPI errors by finalizing the MPI library and exiting with an exit code.

◆ MPIERR

#define MPIERR ( e )

Value:

        do {                                                  \
        MPI_Error_string(e, exerr_buffer, &exresultlen);            \
        fprintf(stderr, "MPI error, line %d, file %s: %s\n", __LINE__, __FILE__, exerr_buffer); \
        MPI_Finalize();                         \
        return 2;                           \
    } while (0)

Handle MPI errors.

This should only be used with MPI library function calls.

◆ NDIM

#define NDIM 3

The number of dimensions in the example data.

In this example, we are using three-dimensional data.

◆ NUM_EVENTS

#define NUM_EVENTS 10

Number of MPE events.

The start and stop of each event will be tracked, and graphed. This value is used outside of HAVE_MPE ifdefs.

Function Documentation

◆ calculate_value()

int calculate_value	(	int	my_rank,
		int	timestep,
		float *	datap
	)

Calculate sample data.

This function is deliberately slow in order to take up some time calculating.

Parameters

my_rank	the rank of the processor running the code.
timestep	the timestep.
datap	pointer where we should write datum.

Returns: zero for success, non-zero otherwise.

◆ check_file()

int check_file	(	int	ntasks,
		char *	filename
	)

Check the output file.

Use netCDF to check that the output is as expected.

Parameters

ntasks	The number of processors running the example.
filename	The name of the example file to check.

Returns: 0 if example file is correct, non-zero otherwise.

< File ID from netCDF.

< Number of dimensions.

< Number of variables.

< Number of global attributes.

< ID of unlimited dimension.

< Length of the dimension.

< Number of variable attributes.

< NetCDF data type of this variable.

< Return code for function calls.

< Dimension ids for this variable.

< Name of the dimension.

< Name of the variable.

< Zero-based index to start read.

< Number of elements to read.

< Buffer to read in data.

< Data values we expect to find.

◆ init_logging()

int init_logging	(	int	my_rank,
		int	event_num[][NUM_EVENTS]
	)

This will set up the MPE logging event numbers.

Parameters

my_rank	the rank of the processor running the code.
event_num	array of MPE event numbers.

Returns: 0 for success, non-zero for failure.

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

Set to non-zero to get output to stdout.

Zero-based rank of processor.

Number of processors involved in current execution.

Different output flavors. The example file is written (and then read) four times. The first two flavors, parallel-netcdf, and netCDF serial, both produce a netCDF classic format file (but with different libraries). The last two produce netCDF4/HDF5 format files, written with and without using netCDF-4 parallel I/O.

Names for the output files. Two of them (pnetcdf and classic) will be in classic netCDF format, the others (serial4 and parallel4) will be in netCDF-4/HDF5 format. All four can be read by the netCDF library, and all will contain the same contents.

Number of processors that will do IO. In this example we will do IO from all processors.

Stride in the mpi rank between io tasks. Always 1 in this example.

Number of the aggregator? Always 0 in this example.

Zero based rank of first processor to be used for I/O.

Specifies the flavor of netCDF output format.

The dimension IDs.

Array index per processing unit. This is the number of elements of the data array that will be handled by each processor. In this example there are 16 data elements. If the example is run on 4 processors, then arrIdxPerPe will be 4.

The ID for the parallel I/O system. It is set by PIOc_Init_Intracomm(). It references an internal structure containing the general IO subsystem data and MPI structure. It is passed to PIOc_finalize() to free associated resources, after all I/O, but before MPI_Finalize is called.

The ncid of the netCDF file created in this example.

The ID of the netCDF varable in the example file.

The I/O description ID as passed back by PIOc_InitDecomp() and freed in PIOc_freedecomp().

A buffer for sample data. The size of this array will vary depending on how many processors are involved in the execution of the example code. It's length will be the same as elements_per_pe.

A buffer for reading data back from the file. The size of this array will vary depending on how many processors are involved in the execution of the example code. It's length will be the same as elements_per_pe.

A 1-D array which holds the decomposition mapping for this example. The size of this array will vary depending on how many processors are involved in the execution of the example code. It's length will be the same as elements_per_pe.

Needed for command line processing.

Variable Documentation

◆ exerr_buffer

char exerr_buffer[MPI_MAX_ERROR_STRING]

Global err buffer for MPI.

When there is an MPI error, this buffer is used to store the error message that is associated with the MPI error.

Macros

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ ERR

◆ MPIERR

◆ NDIM

◆ NUM_EVENTS

Function Documentation

◆ calculate_value()

◆ check_file()

◆ init_logging()

◆ main()

Variable Documentation

◆ exerr_buffer