Squashed 'src/externals/pio1/' changes from 96b76c7..b4e6d54

b4e6d54 limit value of pio_max_var_dims
3645510 Merge pull request ESMCI#1227 from NCAR/pio1_0_cime_merge
6cd47b4 fix whitespace issues pio1

git-subtree-dir: src/externals/pio1
git-subtree-split: b4e6d54044feeaa7be0b400b058735e51c3219c1

DoxygenLayout.xml

@@ -11,15 +11,15 @@
     </tab>
     <tab type="classes" visible="no" title="">
       <tab type="classlist" visible="yes" title="" intro=""/>
-      <tab type="classindex" visible="$ALPHABETICAL_INDEX" title=""/> 
+      <tab type="classindex" visible="$ALPHABETICAL_INDEX" title=""/>
       <tab type="hierarchy" visible="yes" title="" intro=""/>
       <tab type="classmembers" visible="yes" title="" intro=""/>
     </tab>
     <tab type="files" visible="yes" title="">
       <tab type="filelist" visible="yes" title="" intro=""/>
       <tab type="globals" visible="yes" title="" intro=""/>
     </tab>
-    <tab type="examples" visible="no" title="" intro=""/>  
+    <tab type="examples" visible="no" title="" intro=""/>
   </navindex>
 
   <!-- Layout definition for a class page -->

customdoxygen.css

@@ -141,11 +141,11 @@ a.elRef {
 }
 
 a.code, a.code:visited {
-	color: #4665A2; 
+	color: #4665A2;
 }
 
 a.codeRef, a.codeRef:visited {
-	color: #4665A2; 
+	color: #4665A2;
 }
 
 /* @end */
@@ -289,7 +289,7 @@ p.formulaDsp {
 }
 
 img.formulaDsp {
-	
+
 }
 
 img.formulaInl {
@@ -347,20 +347,20 @@ span.charliteral {
 	color: #008080
 }
 
-span.vhdldigit { 
-	color: #ff00ff 
+span.vhdldigit {
+	color: #ff00ff
 }
 
-span.vhdlchar { 
-	color: #000000 
+span.vhdlchar {
+	color: #000000
 }
 
-span.vhdlkeyword { 
-	color: #700070 
+span.vhdlkeyword {
+	color: #700070
 }
 
-span.vhdllogic { 
-	color: #ff0000 
+span.vhdllogic {
+	color: #ff0000
 }
 
 blockquote {
@@ -555,9 +555,9 @@ table.memberdecls {
 }
 
 .memdoc, dl.reflist dd {
-        border-bottom: 1px solid #A8B8D9;      
-        border-left: 1px solid #A8B8D9;      
-        border-right: 1px solid #A8B8D9; 
+        border-bottom: 1px solid #A8B8D9;
+        border-left: 1px solid #A8B8D9;
+        border-right: 1px solid #A8B8D9;
         padding: 6px 10px 2px 10px;
         background-color: #FBFCFD;
         border-top-width: 0;
@@ -609,18 +609,18 @@ dl.reflist dd {
 .params, .retval, .exception, .tparams {
         margin-left: 0px;
         padding-left: 0px;
-}       
+}
 
 .params .paramname, .retval .paramname {
         font-weight: bold;
         vertical-align: top;
 }
-        
+
 .params .paramtype {
         font-style: italic;
         vertical-align: top;
-}       
-        
+}
+
 .params .paramdir {
         font-family: "courier new",courier,monospace;
         vertical-align: top;
@@ -797,8 +797,8 @@ table.fieldtable {
 
 .fieldtable td.fielddoc p:first-child {
         margin-top: 2px;
-}       
-        
+}
+
 .fieldtable td.fielddoc p:last-child {
         margin-bottom: 2px;
 }
@@ -872,7 +872,7 @@ table.fieldtable {
 	color: #283A5D;
 	font-family: 'Lucida Grande',Geneva,Helvetica,Arial,sans-serif;
 	text-shadow: 0px 1px 1px rgba(255, 255, 255, 0.9);
-	text-decoration: none;        
+	text-decoration: none;
 }
 
 .navpath li.navelem a:hover
@@ -901,7 +901,7 @@ div.summary
 	padding-right: 5px;
 	width: 50%;
 	text-align: right;
-}       
+}
 
 div.summary a
 {
@@ -1013,19 +1013,19 @@ dl.section dd {
 	vertical-align: bottom;
 	border-collapse: separate;
 }
- 
+
 #projectlogo img
-{ 
+{
 	border: 0px none;
 }
- 
+
 #projectname
 {
 	font: 300% Tahoma, Arial,sans-serif;
 	margin: 0px;
 	padding: 2px 0px;
 }
-    
+
 #projectbrief
 {
 	font: 120% Tahoma, Arial,sans-serif;
@@ -1120,7 +1120,7 @@ div.toc ul {
         list-style: none outside none;
         border: medium none;
         padding: 0px;
-}       
+}
 
 div.toc li.level1 {
         margin-left: 0px;

doc/CAMexample.txt

@@ -13,7 +13,7 @@
  * Documents produced by Doxygen are derivative works derived from the
  * input used in their production; they are not affected by this license.
  *
- */ 
+ */
 /*! \page CAMexample Community Atmosphere Model (CAM)
 
 \section cam Implementation of PIO in CAM
@@ -37,7 +37,7 @@ initializes PIO in CAM. Init_pio_subsystem calls read_namelist_pio, which calls
 set_pio_parameters. The main parameters set includes the IO mode (netcdf vs pnetcdf),
 number of IO tasks, and IO stride.
 
-Cam_pio_createfile and cam_pio_openfile create and open a PIO file, respectively. 
+Cam_pio_createfile and cam_pio_openfile create and open a PIO file, respectively.
 Cam_pio_createfile is called from cam_write_restart, h_define (called from wshist,
 which is called from write_restart_history), and atm_write_srfrest_mct.
 
@@ -72,7 +72,7 @@ decomposition already exists. The routine performing that search is find_iodesc
 (called from get_phys_decomp and get_dyn_decomp). This capability is supported only
 when the range of history output is the whole domain.
 
-Get_phys_decomp calls get_phys_ldof (or get_column_ldof), and get_dyn_decomp calls 
+Get_phys_decomp calls get_phys_ldof (or get_column_ldof), and get_dyn_decomp calls
 get_dyn_ldof (or get_column_ldof). These routines do the bulk of the work in
 constructing the IO decompositions. Get_column_ldof is called when the history output
 is restricted to a subset of the domain.

doc/Decomp.txt

@@ -1,12 +1,12 @@
 /******************************************************************************
  *
- * 
  *
- * Copyright (C) 2009 
+ *
+ * Copyright (C) 2009
  *
  * Permission to use, copy, modify, and distribute this software and its
- * documentation under the terms of the GNU General Public License is hereby 
- * granted. No representations are made about the suitability of this software 
+ * documentation under the terms of the GNU General Public License is hereby
+ * granted. No representations are made about the suitability of this software
  * for any purpose. It is provided "as is" without express or implied warranty.
  * See the GNU General Public License for more details.
  *
@@ -16,55 +16,55 @@
  */ /*! \page decomp Describing decompositions
 
 
-On of the biggest challenges to working with PIO is setting up 
+On of the biggest challenges to working with PIO is setting up
 the call to \ref PIO_initdecomp.  The user must properly describe
-how the data within each MPI tasks memory should be placed or retrieved from 
-disk. PIO provides several interfaces. We describe the simplest interface 
-first and then progress to the most complex and flexible interface.  
+how the data within each MPI tasks memory should be placed or retrieved from
+disk. PIO provides several interfaces. We describe the simplest interface
+first and then progress to the most complex and flexible interface.
 
 \section decomp_bc Block-cyclic interface
 
-The simplest interface assumes that your arrays are decomposed in a block-cyclic 
-structure and can be described simply using a start-count type approach. 
-A simple block-cyclic decomposition for a 1-dimension (1D)  array is illustrated in Figure 1. 
-Note that contigious layout of the data in memory can be easily mapped to a contigious 
-layout on disk. The \em start arguments correspond to the starting point of the block of contigious 
-memory, while the \em count is the number of words.  Note that \em start and \em count must be arrays of length 
-equal to the dimensionality of the distributed array.  While we use a 1D array for simplicity, PIO 
-currently supports up to the Fortran limit of 7-dimension (7D) arrays. In the case of 7D arrays, the start and count arrays 
+The simplest interface assumes that your arrays are decomposed in a block-cyclic
+structure and can be described simply using a start-count type approach.
+A simple block-cyclic decomposition for a 1-dimension (1D)  array is illustrated in Figure 1.
+Note that contigious layout of the data in memory can be easily mapped to a contigious
+layout on disk. The \em start arguments correspond to the starting point of the block of contigious
+memory, while the \em count is the number of words.  Note that \em start and \em count must be arrays of length
+equal to the dimensionality of the distributed array.  While we use a 1D array for simplicity, PIO
+currently supports up to the Fortran limit of 7-dimension (7D) arrays. In the case of 7D arrays, the start and count arrays
 would be of length 7.
 
 \image html block-cyclic.png "Figure 1: Setting up the \em start and \em count arrays for a single 1D array distributed accross 3 MPI tasks."
 \image latex block-cyclic.eps "Setting up the \em start and \em count arrays for a single 1D array distributed accross 3 MPI tasks." width=10cm
 
-The call to \ref PIO_initdecomp that  would implement the decomposition illustrated in Figure 1 is listed below.   
+The call to \ref PIO_initdecomp that  would implement the decomposition illustrated in Figure 1 is listed below.
 The variable \em iosystem is created by the call to \ref PIO_init.  The second argument \em PIO_double is the PIO kind, and
 indicates that this is a decomposition for a 8-byte real.  (For a list of supported kinds see \ref PIO_kinds.)
-The argument \em dims is the global dimension for the array.  The \em start and \em count arrays are 8-byte integers of 
+The argument \em dims is the global dimension for the array.  The \em start and \em count arrays are 8-byte integers of
 type PIO_OFFSET, while \em iodesc is the IO descriptor generated by the call to PIO_initdecomp.
 
 \verbinclude simple-bc
 
 \section rearr Controlling IO decomposition
 
-The above example represents the simplest way to initialize and use PIO to write out and read distributed arrays.  However, PIO provides some additional features that allows greater control over the IO process.  In particular, it provides the ability to define an IO decomposition. Note that a user defined IO decomposition is optional.  If one is not provided and rearrangement is necessary, PIO will internally compute an IO decomposition.  The reason an IO decomposition may be necessary is described in the section \ref decomp_dof below.  
+The above example represents the simplest way to initialize and use PIO to write out and read distributed arrays.  However, PIO provides some additional features that allows greater control over the IO process.  In particular, it provides the ability to define an IO decomposition. Note that a user defined IO decomposition is optional.  If one is not provided and rearrangement is necessary, PIO will internally compute an IO decomposition.  The reason an IO decomposition may be necessary is described in the section \ref decomp_dof below.
 
 This flexibility provides the ability to define an intermediate decomposition that is unique from the computational decomposition.  This IO decomposition can be constructed to maximize the write or read performance to the disk subsystem.  We extend the
-simple example in Figure 1 to include an IO decomposition in Figure 1b.  
+simple example in Figure 1 to include an IO decomposition in Figure 1b.
 
 \image html block-cyclic-rearr.png "Figure 1b: Block cyclic decomposition with rearrangement"
 \image latex block-cyclic-rearr.eps "Block cyclic decomposition with rearrangement" width=10cm
 
-Figure 1b illustrates the creation of an IO decomposition on two of the MPI tasks. For this decomposition,  the 8 word IO decomposition array and corresponding disk layout are  evenly distributed between PE 0 (yellow) and PE 2 (blue). The arrows in Figure 1b indicates rearrangement that is performed within the PIO library.  In this 
-case, PE 0 sends a word to PE 2, illustrated by the shading of yellow to blue, while PE 1 sends two words to PE 0 as illustrated by the shading of red to yellow.  The rearranged array in the IO decomposition is subsequently written to disk.  
-Note that in this case, only two of three MPI tasks are performing writes to disk. The number of MPI tasks involved in IO to disk is specified in the \ref PIO_init using a combination of the num_aggregator and stride parameters. For figure 1b, the num_aggregator=3 and the stride=2. PIO allows the user to specify the IO decomposition using the 
-optional parameters \em iostart and \em iocount. The following bits of code for PE 0, PE 1, and PE 2 illustrates the necessary calls to \ref PIO_initdecomp.  
+Figure 1b illustrates the creation of an IO decomposition on two of the MPI tasks. For this decomposition,  the 8 word IO decomposition array and corresponding disk layout are  evenly distributed between PE 0 (yellow) and PE 2 (blue). The arrows in Figure 1b indicates rearrangement that is performed within the PIO library.  In this
+case, PE 0 sends a word to PE 2, illustrated by the shading of yellow to blue, while PE 1 sends two words to PE 0 as illustrated by the shading of red to yellow.  The rearranged array in the IO decomposition is subsequently written to disk.
+Note that in this case, only two of three MPI tasks are performing writes to disk. The number of MPI tasks involved in IO to disk is specified in the \ref PIO_init using a combination of the num_aggregator and stride parameters. For figure 1b, the num_aggregator=3 and the stride=2. PIO allows the user to specify the IO decomposition using the
+optional parameters \em iostart and \em iocount. The following bits of code for PE 0, PE 1, and PE 2 illustrates the necessary calls to \ref PIO_initdecomp.
 
-\verbinclude simple-bc-rearr  
+\verbinclude simple-bc-rearr
 
-\verbinclude simple-bc-rearr-pe1  
+\verbinclude simple-bc-rearr-pe1
 
-\verbinclude simple-bc-rearr-pe2  
+\verbinclude simple-bc-rearr-pe2
 
 \section decomp_dof Degree of freedom interface
 
@@ -91,12 +91,12 @@ is illustrated at the bottom of Figure 2.
 
 \image html dof.png "Figure 2: Setting up the comDOF arrays for a single 1D array distributed accross 3 MPI tasks."
 \image latex dof.eps "Setting up the comDOF arrays for a single 1D array distributed accross 3 MPI tasks." width=10cm
- 
-The call to \ref PIO_initdecomp which implements Figure 2 on PE 0 is provided below.  
+
+The call to \ref PIO_initdecomp which implements Figure 2 on PE 0 is provided below.
 
 \verbinclude simple-dof
 
-As with the block-cyclic interface, the degree of freedom interface provides the ability to specify the io decomposition through optional arguments to \ref PIO_initdecomp.  
+As with the block-cyclic interface, the degree of freedom interface provides the ability to specify the io decomposition through optional arguments to \ref PIO_initdecomp.
 
 \image html dof-rearr.png "Figure 3: Setting up the comDOF arrays and setting IO decomposition for a single 1D array distributed accross 3 MPI tasks and written from 2 tasks after rearrangement within the PIO library"
 \image latex dof-rearr.eps "Setting up the comDOF arrays and, io decomposition for a single 1D array distributed accross 3 MPI tasks" width=10cm

doc/DoxygenLayout.xml

@@ -7,7 +7,7 @@
       <tab type="modules" visible="yes" title="Group Index"/>
       <tab type="dirs" visible="yes" title="dirs"/>
       <tab type="classes" visible="yes" title="Data Types"/>
-      <tab type="examples" visible="yes" title="Examples"/>  
+      <tab type="examples" visible="yes" title="Examples"/>
       <tab type="pages" visible="yes" title="Page Index"/>
       <tab type="namespaces" visible="no" title="Namespaces (JMD)">
            <tab type="namespaces" visible="yes" title=""/>

doc/Error.txt

@@ -1,19 +1,19 @@
 /******************************************************************************
  *
- * 
  *
- * Copyright (C) 2009 
+ *
+ * Copyright (C) 2009
  *
  * Permission to use, copy, modify, and distribute this software and its
- * documentation under the terms of the GNU General Public License is hereby 
- * granted. No representations are made about the suitability of this software 
+ * documentation under the terms of the GNU General Public License is hereby
+ * granted. No representations are made about the suitability of this software
  * for any purpose. It is provided "as is" without express or implied warranty.
  * See the GNU General Public License for more details.
  *
  * Documents produced by Doxygen are derivative works derived from the
  * input used in their production; they are not affected by this license.
  *
- */ /*! 
+ */ /*!
 \page error Error Handling
 
 By default, PIO handles errors internally by printing a string

doc/Examples.txt

@@ -1,12 +1,12 @@
 /******************************************************************************
  *
- * 
  *
- * Copyright (C) 2009 
+ *
+ * Copyright (C) 2009
  *
  * Permission to use, copy, modify, and distribute this software and its
- * documentation under the terms of the GNU General Public License is hereby 
- * granted. No representations are made about the suitability of this software 
+ * documentation under the terms of the GNU General Public License is hereby
+ * granted. No representations are made about the suitability of this software
  * for any purpose. It is provided "as is" without express or implied warranty.
  * See the GNU General Public License for more details.
  *
@@ -16,11 +16,11 @@
  */ /*! \page examp Examples
  Examples of the usage of PIO
 
-  PIO has been implemented in several geophysical component models, including the 
-Community Atmosphere Model (CAM), the Community Land Model (CLM), the Parallel Ocean Program 
-(POP), the Community Ice CodE (CICE), and coupler for used by CCSM4.0 (CPL7).  We also provide 
-several simpler example code as well as a test code that is suitable for regression testing and 
-benchmarking.    
+  PIO has been implemented in several geophysical component models, including the
+Community Atmosphere Model (CAM), the Community Land Model (CLM), the Parallel Ocean Program
+(POP), the Community Ice CodE (CICE), and coupler for used by CCSM4.0 (CPL7).  We also provide
+several simpler example code as well as a test code that is suitable for regression testing and
+benchmarking.
 
  - \subpage CAMexample
  - \subpage testpio_example