pioc_support.c File Reference

#include "config.h"
#include <pio.h>
#include <pio_internal.h>
#include <execinfo.h>

Include dependency graph for pioc_support.c:

Macros
#define	VERSNO   2001
	This is used with text decomposition files.
#define	ID_SHIFT   16
	Used to shift file index to first two bytes of ncid.
#define	MAX_BACKTRACE   10
	In decomposition files, backtraces are included. More...

Functions
int	pio_start_timer (const char *name)
	Start the PIO timer. More...
int	pio_stop_timer (const char *name)
	Stop the PIO timer. More...
int	PIOc_strerror (int pioerr, char *errmsg)
	Return a string description of an error code. More...
int	PIOc_set_log_level (int level)
	Set the logging level if PIO was built with PIO_ENABLE_LOGGING. More...
int	PIOc_set_global_log_level (int iosysid, int level)
	Set the logging level value from the root compute task on all tasks if PIO was built with PIO_ENABLE_LOGGING. More...
int	pio_init_logging (void)
	Initialize logging. More...
void	pio_finalize_logging (void)
	Finalize logging - close log files, if open.
void	print_trace (FILE *fp)
	Obtain a backtrace and print it to stderr. More...
void	piodie (const char *msg, const char *fname, int line)
	Abort program and call MPI_Abort(). More...
void	pioassert (_Bool expression, const char *msg, const char *fname, int line)
	Perform an assert. More...
int	check_mpi (iosystem_desc_t *ios, file_desc_t *file, int mpierr, const char *filename, int line)
	Handle MPI errors. More...
int	check_netcdf (file_desc_t *file, int status, const char *fname, int line)
	Check the result of a netCDF API call. More...
int	check_netcdf2 (iosystem_desc_t *ios, file_desc_t *file, int status, const char *fname, int line)
	Check the result of a netCDF API call. More...
int	pio_err (iosystem_desc_t *ios, file_desc_t *file, int err_num, const char *fname, int line)
	Handle an error in PIO. More...
int	alloc_region2 (iosystem_desc_t *ios, int ndims, io_region **regionp)
	Allocate a region struct, and initialize it. More...
int	find_mpi_type (int pio_type, MPI_Datatype *mpi_type, int *type_size)
	Given a PIO type, find the MPI type and the type size. More...
int	malloc_iodesc (iosystem_desc_t *ios, int piotype, int ndims, io_desc_t **iodesc)
	Allocate space for an IO description struct, and initialize it. More...
void	free_region_list (io_region *top)
	Free a region list. More...
int	PIOc_freedecomp (int iosysid, int ioid)
	Free a decomposition map. More...
int	PIOc_readmap (const char *file, int *ndims, int **gdims, PIO_Offset *fmaplen, PIO_Offset **map, MPI_Comm comm)
	Read a decomposition map from a file. More...
int	PIOc_readmap_from_f90 (const char *file, int *ndims, int **gdims, PIO_Offset *maplen, PIO_Offset **map, int f90_comm)
	Read a decomposition map from file. More...
int	PIOc_write_nc_decomp (int iosysid, const char *filename, int cmode, int ioid, char *title, char *history, int fortran_order)
	Write the decomposition map to a file using netCDF, everyones favorite data format. More...
int	PIOc_read_nc_decomp (int iosysid, const char *filename, int *ioidp, MPI_Comm comm, int pio_type, char *title, char *history, int *fortran_order)
	Read the decomposition map from a netCDF decomp file produced by PIOc_write_nc_decomp(). More...
int	pioc_write_nc_decomp_int (iosystem_desc_t *ios, const char *filename, int cmode, int ndims, int *global_dimlen, int num_tasks, int *task_maplen, int *map, const char *title, const char *history, int fortran_order)
	Write the decomp information in netCDF. More...
int	pioc_read_nc_decomp_int (int iosysid, const char *filename, int *ndims, int **global_dimlen, int *num_tasks, int **task_maplen, int *max_maplen, int **map, char *title, char *history, char *source, char *version, int *fortran_order)
	Read the decomp information from a netCDF decomp file. More...
int	PIOc_write_decomp (const char *file, int iosysid, int ioid, MPI_Comm comm)
	Write the decomposition map to a file. More...
int	PIOc_writemap (const char *file, int ndims, const int *gdims, PIO_Offset maplen, PIO_Offset *map, MPI_Comm comm)
	Write the decomposition map to a file. More...
int	PIOc_writemap_from_f90 (const char *file, int ndims, const int *gdims, PIO_Offset maplen, const PIO_Offset *map, int f90_comm)
	Write the decomposition map to a file for F90. More...
int	PIOc_createfile_int (int iosysid, int *ncidp, int *iotype, const char *filename, int mode, int use_ext_ncid)
	Create a new file using pio. More...
int	check_unlim_use (int ncid)
	Check that a file meets PIO requirements for use of unlimited dimensions. More...
int	find_iotype_from_omode (int mode, int *iotype)
	Find the appropriate IOTYPE from mode flags to nc_open(). More...
int	find_iotype_from_cmode (int cmode, int *iotype)
	Find the appropriate IOTYPE from mode flags to nc_create(). More...
int	PIOc_openfile_retry (int iosysid, int *ncidp, int *iotype, const char *filename, int mode, int retry, int use_ext_ncid)
	Open an existing file using PIO library. More...
int	pioc_pnetcdf_inq_type (int ncid, nc_type xtype, char *name, PIO_Offset *sizep)
	Internal function to provide inq_type function for pnetcdf. More...
int	pioc_change_def (int ncid, int is_enddef)
	This is an internal function that handles both PIOc_enddef and PIOc_redef. More...
int	iotype_is_valid (int iotype)
	Check whether an IO type is valid for the build. More...
int	PIOc_set_rearr_opts (int iosysid, int comm_type, int fcd, bool enable_hs_c2i, bool enable_isend_c2i, int max_pend_req_c2i, bool enable_hs_i2c, bool enable_isend_i2c, int max_pend_req_i2c)
	Set the rearranger options associated with an iosystem. More...
int	determine_procs (int num_io_procs, int component_count, int *num_procs_per_comp, int **proc_list, int **my_proc_list)
	This function determines which processes are assigned to the different computation components. More...

Variables
int	pio_next_ncid
	The PIO library maintains its own set of ncids. More...
int	default_error_handler
	The default error handler used when iosystem cannot be located.

Detailed Description

Support functions for the PIO library.

Macro Definition Documentation

MAX_BACKTRACE

#define MAX_BACKTRACE   10

In decomposition files, backtraces are included.

This is the max number of trace levels that will be used.

Function Documentation

alloc_region2()

int alloc_region2	(	iosystem_desc_t *	ios,
		int	ndims,
		io_region **	regionp
	)

Allocate a region struct, and initialize it.

Parameters

ios	pointer to the IO system info, used for error handling. Ignored if NULL.
ndims	the number of dimensions for the data in this region.
regionp	a pointer that gets a pointer to the newly allocated io_region struct.

Returns

0 for success, error code otherwise.

Author

Jim Edwards

check_mpi()

int check_mpi	(	iosystem_desc_t *	ios,
		file_desc_t *	file,
		int	mpierr,
		const char *	filename,
		int	line
	)

Handle MPI errors.

An error message is sent to stderr, then the check_netcdf() function is called with PIO_EIO.

Parameters

ios	pointer to the iosystem_info_t. May be NULL.
file	pointer to the file_desc_t info. Ignored if NULL.
mpierr	the MPI return code to handle
filename	the name of the code file where error occured.
line	the line of code where error occured.

Returns

PIO_NOERR for no error, otherwise PIO_EIO.

Author

Ed Hartnett

check_netcdf()

int check_netcdf	(	file_desc_t *	file,
		int	status,
		const char *	fname,
		int	line
	)

Check the result of a netCDF API call.

Parameters

file	pointer to the PIO structure describing this file. Ignored if NULL.
status	the return value from the netCDF call.
fname	the name of the code file.
line	the line number of the netCDF call in the code.

Returns

the error code

Author

Ed Hartnett

check_netcdf2()

int check_netcdf2	(	iosystem_desc_t *	ios,
		file_desc_t *	file,
		int	status,
		const char *	fname,
		int	line
	)

Check the result of a netCDF API call.

This is the same as check_netcdf() except for the extra iosystem_desc_t pointer, which is used to determine error handling when there is no file_desc_t pointer.

Parameters

ios	pointer to the iosystem description struct. Ignored if NULL.
file	pointer to the PIO structure describing this file. Ignored if NULL.
status	the return value from the netCDF call.
fname	the name of the code file.
line	the line number of the netCDF call in the code.

Returns

the error code

Author

Ed Hartnett

check_unlim_use()

int check_unlim_use

(

int

ncid

)

Check that a file meets PIO requirements for use of unlimited dimensions.

This function is only called on netCDF-4 files. If the file is found to violate PIO requirements it is closed.

Parameters

ncid	the file->fh for this file (the real netCDF ncid, not the pio_ncid).

Returns

0 if file is OK, error code otherwise.

Author

Ed Hartnett

determine_procs()

int determine_procs	(	int	num_io_procs,
		int	component_count,
		int *	num_procs_per_comp,
		int **	proc_list,
		int **	my_proc_list
	)

This function determines which processes are assigned to the different computation components.

This function is called by PIOc_init_async().

The user may have passed a specification of tasks as array proc_list, or it may be calculated by assigning processors starting at the first one after the IO component, and assigning them in order to each computation component.

Note that memory is allocated for my_proc_list. This must be freed by the caller.

Parameters

num_io_procs	the number of IO processes.
component_count	the number of computational components.
num_procs_per_comp	array (length component_count) which contains the number of processes to assign to each computation component.
proc_list	array (length component count) of arrays (length num_procs_per_comp_array[cmp]) which contain the list of processes for each computation component. May be NULL.
my_proc_list	array (length component count) of arrays (length num_procs_per_comp_array[cmp]) which will get the list of processes for each computation component.

Returns

0 for success, error code otherwise

Author

Ed Hartnett

find_iotype_from_cmode()

int find_iotype_from_cmode	(	int	cmode,
		int *	iotype
	)

Find the appropriate IOTYPE from mode flags to nc_create().

Parameters

cmode	the mode flag from nc_create().
iotype	pointer that gets the IOTYPE.

Returns

0 on success, error code otherwise.

Author

Ed Hartnett

find_iotype_from_omode()

int find_iotype_from_omode	(	int	mode,
		int *	iotype
	)

Find the appropriate IOTYPE from mode flags to nc_open().

The following flags have meaning:

• NC_NETCDF4 - use netCDF-4/HDF5 format
• NC_MPIIO - when used with NC_NETCDF4, use parallel I/O.
• NC_PNETCDF - use classic format with pnetcdf parallel I/O.

Parameters

mode	the mode flag from nc_open().
iotype	pointer that gets the IOTYPE.

Returns

0 on success, error code otherwise.

Author

Ed Hartnett

find_mpi_type()

int find_mpi_type	(	int	pio_type,
		MPI_Datatype *	mpi_type,
		int *	type_size
	)

Given a PIO type, find the MPI type and the type size.

Parameters

pio_type	a PIO type, PIO_INT, PIO_FLOAT, etc.
mpi_type	a pointer to MPI_Datatype that will get the MPI type that coresponds to the PIO type. Ignored if NULL.
type_size	a pointer to int that will get the size of the type, in bytes. (For example, 4 for PIO_INT). Ignored if NULL.

Returns

0 for success, error code otherwise.

Author

Jim Edwards

free_region_list()

void free_region_list

(

io_region *

top

)

Free a region list.

top a pointer to the start of the list to free.

Author

Jim Edwards

iotype_is_valid()

int iotype_is_valid

(

int

iotype

)

Check whether an IO type is valid for the build.

Parameters

iotype

the IO type to check

Returns

0 if valid, non-zero otherwise.

Author

Jim Edwards

malloc_iodesc()

int malloc_iodesc	(	iosystem_desc_t *	ios,
		int	piotype,
		int	ndims,
		io_desc_t **	iodesc
	)

Allocate space for an IO description struct, and initialize it.

Parameters

ios	pointer to the IO system info, used for error handling.
piotype	the PIO data type (ex. PIO_FLOAT, PIO_INT, etc.).
ndims	the number of dimensions.
iodesc	pointer that gets the newly allocated io_desc_t.

Returns

0 for success, error code otherwise.

Author

Jim Edwards

pio_err()

int pio_err	(	iosystem_desc_t *	ios,
		file_desc_t *	file,
		int	err_num,
		const char *	fname,
		int	line
	)

Handle an error in PIO.

This will consult the error handler settings and either call MPI_Abort() or return an error code.

The error hanlder has three settings:

Errors cause abort: PIO_INTERNAL_ERROR.

Error codes are broadcast to all tasks: PIO_BCAST_ERROR.

Errors are returned to caller with no internal action: PIO_RETURN_ERROR.

Parameters

ios	pointer to the IO system info. Ignored if NULL.
file	pointer to the file description data. Ignored if NULL. If provided file->iosystem is used as ios pointer.
err_num	the error code
fname	name of code file where error occured.
line	the line of code where the error occurred.

Returns

err_num if abort is not called.

Author

Jim Edwards

pio_init_logging()

int pio_init_logging

(

void

)

Initialize logging.

Open log file, if not opened yet, or increment ref count if already open.

Author

Jayesh Krishna, Ed Hartnett

pio_start_timer()

int pio_start_timer

(

const char *

name

)

Start the PIO timer.

Parameters

name	name of the timer.

Returns

0 for success, error code otherwise.

Author

Ed Hartnett

pio_stop_timer()

int pio_stop_timer

(

const char *

name

)

Stop the PIO timer.

Parameters

name	name of the timer.

Returns

0 for success, error code otherwise.

Author

Ed Hartnett

pioassert()

void pioassert	(	_Bool	expression,
		const char *	msg,
		const char *	fname,
		int	line
	)

Perform an assert.

Note that this function does nothing if NDEBUG is defined.

Parameters

expression	the expression to be evaluated
msg	an error message
fname	name of code file where error occured
line	the line of code where the error occurred.

Author

Jim Edwards

pioc_change_def()

int pioc_change_def	(	int	ncid,
		int	is_enddef
	)

This is an internal function that handles both PIOc_enddef and PIOc_redef.

Parameters

ncid	the ncid of the file to enddef or redef
is_enddef	set to non-zero for enddef, 0 for redef.

Returns

PIO_NOERR on success, error code on failure.

Author

Ed Hartnett

PIOc_createfile_int()

int PIOc_createfile_int	(	int	iosysid,
		int *	ncidp,
		int *	iotype,
		const char *	filename,
		int	mode,
		int	use_ext_ncid
	)

Create a new file using pio.

This is an internal function that is called by both PIOc_create() and PIOc_createfile(). Input parameters are read on comp task 0 and ignored elsewhere.

Parameters

iosysid	A defined pio system ID, obtained from PIOc_Init_Intracomm() or PIOc_InitAsync().
ncidp	A pointer that gets the ncid of the newly created file. This is the PIO ncid. Within PIO, the file will have a different ID, the file->fh. When netCDF integration is used, the PIO ncid is also stored in the netcdf-c internal file list, and the PIO code is called by the netcdf-c dispatch code. In this case, there are two ncids for the file, the PIO ncid, and the file->fh ncid.
iotype	A pointer to a pio output format. Must be one of PIO_IOTYPE_PNETCDF, PIO_IOTYPE_NETCDF, PIO_IOTYPE_NETCDF4C, or PIO_IOTYPE_NETCDF4P.
filename	The filename to create.
mode	The netcdf mode for the create operation.
use_ext_ncid	non-zero to use an externally assigned ncid (used in the netcdf integration layer).

Returns

0 for success, error code otherwise.

Author

Ed Hartnett

PIOc_openfile_retry()

int PIOc_openfile_retry	(	int	iosysid,
		int *	ncidp,
		int *	iotype,
		const char *	filename,
		int	mode,
		int	retry,
		int	use_ext_ncid
	)

Open an existing file using PIO library.

This is an internal function. Depending on the value of the retry parameter, a failed open operation will be handled differently. If retry is non-zero, then a failed attempt to open a file with netCDF-4 (serial or parallel), or parallel-netcdf will be followed by an attempt to open the file as a serial classic netCDF file. This is an important feature to some NCAR users. The functionality is exposed to the user as PIOc_openfile() (which does the retry), and PIOc_open() (which does not do the retry).

Input parameters are read on comp task 0 and ignored elsewhere.

Parameters

iosysid	a defined pio system descriptor.
ncidp	a pio file descriptor.
iotype	a pio output format.
filename	the filename to open
mode	the netcdf mode for the open operation
retry	non-zero to automatically retry with netCDF serial classic.
use_ext_ncid	non-zero to use an externally assigned ncid (used in the netcdf integration layer).

Returns

0 for success, error code otherwise.

Author

Jim Edwards, Ed Hartnett

Return code from MPI function codes.

pioc_pnetcdf_inq_type()

int pioc_pnetcdf_inq_type	(	int	ncid,
		nc_type	xtype,
		char *	name,
		PIO_Offset *	sizep
	)

Internal function to provide inq_type function for pnetcdf.

Parameters

ncid	ignored because pnetcdf does not have user-defined types.
xtype	type to learn about.
name	pointer that gets name of type. Ignored if NULL.
sizep	pointer that gets size of type. Ignored if NULL.

Returns

0 on success, error code otherwise.

Author

Ed Hartnett

PIOc_read_nc_decomp()

int PIOc_read_nc_decomp	(	int	iosysid,
		const char *	filename,
		int *	ioidp,
		MPI_Comm	comm,
		int	pio_type,
		char *	title,
		char *	history,
		int *	fortran_order
	)

Read the decomposition map from a netCDF decomp file produced by PIOc_write_nc_decomp().

Parameters

iosysid	the IO system ID.
filename	the name of the decomp file.
ioidp	pointer that will get the newly-assigned ID of the IO description. The ioid is needed to later free the decomposition.
comm	an MPI communicator.
pio_type	the PIO type to be used as the type for the data.
title	pointer that will get optial title attribute for the file. Will be less than PIO_MAX_NAME + 1 if provided. Ignored if NULL.
history	pointer that will get optial history attribute for the file. Will be less than PIO_MAX_NAME + 1 if provided. Ignored if NULL.
fortran_order	pointer that gets set to 1 if fortran array ordering is used, or to zero if C array ordering is used.

Returns

0 for success, error code otherwise.

Author

Ed Hartnett

pioc_read_nc_decomp_int()

int pioc_read_nc_decomp_int	(	int	iosysid,
		const char *	filename,
		int *	ndims,
		int **	global_dimlen,
		int *	num_tasks,
		int **	task_maplen,
		int *	max_maplen,
		int **	map,
		char *	title,
		char *	history,
		char *	source,
		char *	version,
		int *	fortran_order
	)

Read the decomp information from a netCDF decomp file.

This is an internal function.

Parameters

iosysid	the IO system ID.
filename	the name the decomp file will have.
ndims	pointer to int that will get number of dims in the data being described. Ignored if NULL.
global_dimlen	a pointer that gets an array, of size ndims, that will have the size of the global array in each dimension. Ignored if NULL, otherwise must be freed by caller.
num_tasks	pointer to int that gets the number of tasks the data are decomposed over. Ignored if NULL.
task_maplen	pointer that gets array of size num_tasks that gets the length of the map for each task. Ignored if NULL, otherwise must be freed by caller.
max_maplen	pointer to int that gets the maximum maplen for any task. Ignored if NULL.
map	pointer that gets a 2D array of size [num_tasks][max_maplen] that will have the 0-based mapping from local to global array elements. Ignored if NULL, otherwise must be freed by caller.
title	pointer that will get the contents of title attribute, if present. If present, title will be < PIO_MAX_NAME + 1 in length. Ignored if NULL.
history	pointer that will get the contents of history attribute, if present. If present, history will be < PIO_MAX_NAME + 1 in length. Ignored if NULL.
source	pointer that will get the contents of source attribute. Source will be < PIO_MAX_NAME + 1 in length. Ignored if NULL.
version	pointer that will get the contents of version attribute. It will be < PIO_MAX_NAME + 1 in length. Ignored if NULL.
fortran_order	int pointer that will get a 0 if this decomposition file uses C array ordering, 1 if it uses Fortran array ordering.

Returns

0 for success, error code otherwise.

Author

Ed Hartnett

PIOc_readmap()

int PIOc_readmap	(	const char *	file,
		int *	ndims,
		int **	gdims,
		PIO_Offset *	fmaplen,
		PIO_Offset **	map,
		MPI_Comm	comm
	)

Read a decomposition map from a file.

The decomp file is only read by task 0 in the communicator.

Parameters

file	the filename
ndims	pointer to an int with the number of dims.
gdims	pointer to an array of dimension ids.
fmaplen
map
comm

Returns

0 for success, error code otherwise.

Author

Jim Edwards

PIOc_readmap_from_f90()

int PIOc_readmap_from_f90	(	const char *	file,
		int *	ndims,
		int **	gdims,
		PIO_Offset *	maplen,
		PIO_Offset **	map,
		int	f90_comm
	)

Read a decomposition map from file.

Parameters

file	the filename
ndims	pointer to the number of dimensions
gdims	pointer to an array of dimension ids
maplen	pointer to the length of the map
map	pointer to the map array
f90_comm

Returns

0 for success, error code otherwise.

Author

Jim Edwards

PIOc_set_global_log_level()

int PIOc_set_global_log_level	(	int	iosysid,
		int	level
	)

Set the logging level value from the root compute task on all tasks if PIO was built with PIO_ENABLE_LOGGING.

Set to -1 for nothing, 0 for errors only, 1 for important logging, and so on. Log levels below 1 are only printed on the io/component root.

A log file is also produced for each task. The file is called pio_log_X.txt, where X is the (0-based) task number.

If the library is not built with logging, this function does nothing.

Parameters

iosysid	the IO system ID
level	the logging level, 0 for errors only, 5 for max verbosity.

Returns

0 on success, error code otherwise.

Author

Jim Edwards

PIOc_set_log_level()

int PIOc_set_log_level

(

int

level

)

Set the logging level if PIO was built with PIO_ENABLE_LOGGING.

Set to -1 for nothing, 0 for errors only, 1 for important logging, and so on. Log levels below 1 are only printed on the io/component root.

A log file is also produced for each task. The file is called pio_log_X.txt, where X is the (0-based) task number.

If the library is not built with logging, this function does nothing.

Parameters

level

the logging level, 0 for errors only, 5 for max verbosity.

Returns

0 on success, error code otherwise.

Author

Ed Hartnett

PIOc_set_rearr_opts()

int PIOc_set_rearr_opts	(	int	iosysid,
		int	comm_type,
		int	fcd,
		bool	enable_hs_c2i,
		bool	enable_isend_c2i,
		int	max_pend_req_c2i,
		bool	enable_hs_i2c,
		bool	enable_isend_i2c,
		int	max_pend_req_i2c
	)

Set the rearranger options associated with an iosystem.

Parameters

iosysid	a defined pio system descriptor.
comm_type	Type of communication (pt2pt/coll) used by the rearranger. See PIO_REARR_COMM_TYPE for more detail. Possible values are : PIO_REARR_COMM_P2P (Point to point communication) PIO_REARR_COMM_COLL (Collective communication)
fcd	Flow control direction for the rearranger. See PIO_REARR_COMM_FC_DIR for more detail. Possible values are : PIO_REARR_COMM_FC_2D_ENABLE : Enable flow control from compute processes to io processes and vice versa PIO_REARR_COMM_FC_1D_COMP2IO : Enable flow control from compute processes to io processes (only) PIO_REARR_COMM_FC_1D_IO2COMP : Enable flow control from io processes to compute processes (only) PIO_REARR_COMM_FC_2D_DISABLE : Disable flow control from compute processes to io processes and vice versa.
enable_hs_c2i	Enable handshake while rearranging data, from compute to io processes
enable_isend_c2i	Enable isends while rearranging data, from compute to io processes
max_pend_req_c2i	Maximum pending requests during data rearragment from compute processes to io processes
enable_hs_i2c	Enable handshake while rearranging data, from io to compute processes
enable_isend_i2c	Enable isends while rearranging data, from io to compute processes
max_pend_req_i2c	Maximum pending requests during data rearragment from io processes to compute processes

Returns

0 on success, otherwise a PIO error code.

Author

Jayesh Krishna

PIOc_strerror()

int PIOc_strerror	(	int	pioerr,
		char *	errmsg
	)

Return a string description of an error code.

If zero is passed, the errmsg will be "No error".

Parameters

pioerr	the error code returned by a PIO function call.
errmsg	Pointer that will get the error message. The message will be PIO_MAX_NAME chars or less.

Returns

0 on success.

Author

Jim Edwards

PIOc_write_decomp()

int PIOc_write_decomp	(	const char *	file,
		int	iosysid,
		int	ioid,
		MPI_Comm	comm
	)

Write the decomposition map to a file.

Parameters

file	the filename to be used.
iosysid	the IO system ID.
ioid	the ID of the IO description.
comm	an MPI communicator.

Returns

0 for success, error code otherwise.

Author

Jim Edwards

PIOc_write_nc_decomp()

int PIOc_write_nc_decomp	(	int	iosysid,
		const char *	filename,
		int	cmode,
		int	ioid,
		char *	title,
		char *	history,
		int	fortran_order
	)

Write the decomposition map to a file using netCDF, everyones favorite data format.

Parameters

iosysid	the IO system ID.
filename	the filename to be used.
cmode	for PIOc_create(). Will be bitwise or'd with NC_WRITE.
ioid	the ID of the IO description.
title	optial title attribute for the file. Must be less than PIO_MAX_NAME + 1 if provided. Ignored if NULL.
history	optial history attribute for the file. Must be less than PIO_MAX_NAME + 1 if provided. Ignored if NULL.
fortran_order	set to non-zero if fortran array ordering is used, or to zero if C array ordering is used.

Returns

0 for success, error code otherwise.

Author

Ed Hartnett

pioc_write_nc_decomp_int()

int pioc_write_nc_decomp_int	(	iosystem_desc_t *	ios,
		const char *	filename,
		int	cmode,
		int	ndims,
		int *	global_dimlen,
		int	num_tasks,
		int *	task_maplen,
		int *	map,
		const char *	title,
		const char *	history,
		int	fortran_order
	)

Write the decomp information in netCDF.

This is an internal function.

Parameters

ios	pointer to io system info.
filename	the name the decomp file will have.
cmode	for PIOc_create(). Will be bitwise or'd with NC_WRITE.
ndims	number of dims in the data being described.
global_dimlen	an array, of size ndims, with the size of the global array in each dimension.
num_tasks	the number of tasks the data are decomposed over.
task_maplen	array of size num_tasks with the length of the map for each task.
map	pointer to a 2D array of size [num_tasks][max_maplen] with the 0-based mapping from local to global array elements.
title	null-terminated string that will be written as an attribute. If provided, length must be < PIO_MAX_NAME + 1. Ignored if NULL.
history	null-terminated string that will be written as an attribute. If provided, length must be < PIO_MAX_NAME + 1. Ignored if NULL.
fortran_order	set to non-zero if using fortran array ordering, 0 for C array ordering.

Returns

0 for success, error code otherwise.

Author

Ed Hartnett

PIOc_writemap()

int PIOc_writemap	(	const char *	file,
		int	ndims,
		const int *	gdims,
		PIO_Offset	maplen,
		PIO_Offset *	map,
		MPI_Comm	comm
	)

Write the decomposition map to a file.

Parameters

file	the filename
ndims	the number of dimensions
gdims	an array of dimension ids
maplen	the length of the map
map	the map array
comm	an MPI communicator.

Returns

0 for success, error code otherwise.

Author

Jim Edwards

PIOc_writemap_from_f90()

int PIOc_writemap_from_f90	(	const char *	file,
		int	ndims,
		const int *	gdims,
		PIO_Offset	maplen,
		const PIO_Offset *	map,
		int	f90_comm
	)

Write the decomposition map to a file for F90.

Parameters

file	the filename
ndims	the number of dimensions
gdims	an array of dimension ids
maplen	the length of the map
map	the map array
f90_comm	an MPI communicator.

Returns

0 for success, error code otherwise.

Author

Jim Edwards

piodie()

void piodie	(	const char *	msg,
		const char *	fname,
		int	line
	)

Abort program and call MPI_Abort().

Parameters

msg	an error message
fname	name of code file where error occured
line	the line of code where the error occurred.

Author

Jim Edwards

print_trace()

void print_trace

(

FILE *

fp

)

Obtain a backtrace and print it to stderr.

This is appended to the text decomposition file.

Note from Jim:

The stack trace can be used to identify the usage in the model code of the particular decomposition in question and so if using the pio performance tool leads to tuning that could be applied in the model you know more or less where to do it.

It's also useful if you have a model bug - then you have 20 or so decomp files and you need to identify the one that was problematic. So it's used as an add to the developer and not used at all by any automated process or tools.

Parameters

fp	file pointer to send output to

Author

Jim Edwards

Variable Documentation

pio_next_ncid

int pio_next_ncid

The PIO library maintains its own set of ncids.

This is the next ncid number that will be assigned.