Warning, /doc/old_doc/OutputFiles is written in an unsupported language. File is not indexed.
view on githubraw file Latest commit ad38444b on 2018-01-31 20:35:48 UTC
e6e4237de7 Chri*0001 Format for raw output files from MITgcmUV
0002 =========================================
0003
0004 Introduction
0005 ------------
0006 When running in parallel mode with multiple processes the MITgcmUV
0007 model operates as N separate programs, each responsible for its "local"
0008 region of the "total" model domain. Synchronisation and sharing of data between
0009 these processes is done explicitly by calls to data exchange and
0010 barrier routines. Consequently there is no single program that has
0011 a view of the whole model domain as the code is running. Any simple
0012 I/O can only operate on the local region of the model domain - I/O
0013 operations to and from datasets that represent the total domain need
0014 to address the multiple process behavior explicitly.
0015 Under MITgcmUV there are a set of I/O support routines that mask the
0016 details of this process and enable end-users to read and write datasets
0017 in a straight-forward manner. The routines use the following design
0018 strategy:
0019 o Input datasets are for the total domain
0020 o Output datasets are for the local domain
0021 o A separate program "joinds" is provided which joins a set of
0022 local domain datasets together to form total model domain dataset.
0023
0024 MITgcmUV IO support routines
0025 ----------------------------
3114ed666c Chri*0026 o SUBROUTINE READ_FLD_XY_RS( pref, suff, fld, time, thid )
0027 _RS fld(1-OLx:sNx+OLx,1-OLy,sNy+OLy,nSx,nSy)
0028
0029 o SUBROUTINE READ_FLD_XY_RL( pref, suff, fld, time, thid )
0030 _RL fld(1-OLx:sNx+OLx,1-OLy,sNy+OLy,nSx,nSy)
0031
0032 o SUBROUTINE READ_FLD_XYZ_RS( pref, suff, fld, time, thid )
0033 _RS fld(1-OLx:sNx+OLx,1-OLy,sNy+OLy,nZ,nSx,nSy)
0034
0035 o SUBROUTINE READ_FLD_XYZ_RL( pref, suff, fld, time, thid )
0036 _RL fld(1-OLx:sNx+OLx,1-OLy,sNy+OLy,nZ,nSx,nSy)
0037
0038 o SUBROUTINE WRITE_FLD_XY_RS( pref, suff, fld, time, thid )
0039 _RS fld(1-OLx:sNx+OLx,1-OLy,sNy+OLy,nSx,nSy)
0040
0041 o SUBROUTINE WRITE_FLD_XY_RL( pref, suff, fld, time, thid )
0042 _RL fld(1-OLx:sNx+OLx,1-OLy,sNy+OLy,nSx,nSy)
0043
0044 o SUBROUTINE WRITE_FLD_XYZ_RS( pref, suff, fld, time, thid )
0045 _RS fld(1-OLx:sNx+OLx,1-OLy,sNy+OLy,nZ,nSx,nSy)
0046
0047 o SUBROUTINE WRITE_FLD_XYZ_RL( pref, suff, fld, time, thid )
0048 _RL fld(1-OLx:sNx+OLx,1-OLy,sNy+OLy,nZ,nSx,nSy)
0049
0050 all routines
0051 CHARACTER*(*) pref
0052 CHARACTER*(*) suff
0053 INTEGER time
0054 INTEGER thid
0055
0056 macros
0057 _RS -> REAL*4 or REAL*8
0058 _RL -> REAL*8
0059
0060 pref - String used in prefix part of file name.
0061 Examples 'theta.' = temperature
0062 from 'uVel.' = zonal velocity
0063 MITgcmUV 'vVel.' = meridional velocity
0064 'salt.' = salinity
0065 suff - String used in suffix part of file name.
0066 Examples '0000000100' = iteration number
0067 from 'ckptA' = checkpoint file
0068 MITgcmUV
0069 fld - Two or three dimensional REAL*4 or REAL*8 srray.
0070 Examples theta = temperature field
0071 from cg2d_x = surface elevation field
0072 MITgcmUV
0073 time - Time level in the calling subroutine
0074 this - Thread id of the calling subroutine
e6e4237de7 Chri*0075
0076 Dataset format
0077 --------------
0078 Datasets are written using the standard Fortran 77 sequential binary
0079 file format. The Fortran IO statements in he model code do not specify any
0080 particular format, however, compile and run-time flags are used on some platforms.
0081 On DEC platforms by default the IO form is set to big-endian with a compile time
0082 flag. On CRAY platforms a runtime flag is normally used to select IEEE
0083 representation. The Fortran 77 sequential binary file format is
0084 4 byte header
0085 data
0086 4 byte terminator
0087 The header and terminator are unsigned integers which give the length
0088 of the data section in bytes. This is format is standard over all UNIX
0089 platforms. In Fortran this style of file is generated by code of the
0090 form
0091
0092 REAL A(dim1, dim2, ..... )
0093 OPEN(unitnumber,filename,FORM='FORMATTED')
0094 WRITE(unitnumber) A
0095 END
0096
0097 The data is sequenced in the standard Fortran convention of the left-most
0098 index varying fastest. This convention holds for any dimension of datsets
0099 one-dimensional, two-dimensional, three-dimensional and four-dimensional or
0100 more datasets are all written this way.
0101
0102 Multiprocess support
0103 --------------------
0104 The format described above is used for multi-process simulations. In this
0105 case the data written to separate files with each process writing data that
0106 is local to it. To support this approach a file naming convention is used and a second
0107 file of "meta" information accompanines the data. The naming convention
0108 is used to avoid duplicate names and to make it easy to identify sets of
0109 files that together represent the total domain data. The meta file contains
0110 information about the extent of the sub-domain within each file.
0111 The naming convention used is
0112 PREF.SUFF.pPNUMBER.tTNUMBER.data
0113 PREF.SUFF.pPNUMBER.tTNUMBER.meta
0114
0115 where
0116 PREF - Is a field identifying the data within the file. For
0117 temperature PREF is T, for zonal velocity PREF is U etc...
0118 SUFF - Is a field identifying the "instance" of the data within the
0119 file. The instance is typically the time level. In general
0120 the instance will be a model timestep number.
0121 PNUMBER - Is a process number used to identitfy which process of
0122 a multi-process run generated this data. The number ranges
0123 from 0 to (number of processors)-1.
0124 TNUMBER - Is a thread number used to identify which thread of a
0125 multi-threaded run generated this data. The number ranges
0126 from 0 to (number of threads)-1.
0127
0128 the .data suffix identifies the file containing the actual data.
0129 the .meta suffix identifies the file containing textual information
0130 indicating the extent of the domain written to the .data file.
0131
0132 .meta file Format
0133 -----------------
0134 This file contains a set of parameters that are specified using the
0135 generic parameter specification format used in GCMPACK software. This
0136 format consists of a sequence of assignments and comments
0137 Assignments have the form
0138 keyword =[ val-list ];
0139
0140 where
0141 keyword is a text string
0142 val-list is a sequence of one or more fields separated by commas
0143
0144 Comments are preceeded by // or # characters or contained in
0145 /* */ pairs.
0146 The keywords contained in a .meta file are
0147 id - This is a numeric identifier. It can be used to
0148 verify consistency over a set of .meta files.
0149 nDims - This is a single integer indicating the dimensionality
0150 of the data in the .data file.
0151 dimList - This is a sequence of triplets. There is one triplet for
0152 each dimension and the triplets are ordered in the same
0153 way as the dimensions. Each triplet is made of three integers.
0154 The first integer gives the domain extent globally for
0155 the associated dimension.
0156 The second integer gives the low coordinate for the values
0157 within .data file for the associated dimension.
0158 The third integer gives the high coordinate for the values
0159 within .data file for the associated dimension.
0160 Thus for a .data file containing the north-west quadrant of
0161 a global domain of size 90 x 40 the .meta might read
0162 nDims = [ 2 ];
0163 dimList = [ 90, 46, 90, 40, 1, 20];
0164 For a global domain of size 90 x 40 x 33 the .meta file
0165 would read
0166 nDims = [ 3 ];
0167 dimList = [ 90, 46, 90, 40, 1, 20, 33, 1, 33];
0168
0169
0170
0171 Example matlab program to join files
0172 ------------------------------------
0173 The following matlab script joins together a collection of files that
0174 were written in split form. The files to join are indicated by a user
0175 defined PREF.SUFF pair. e.g. T.0000002800. The script uses the UNIX
0176 ls command to find all files starting with T.0000002800 and then
0177 scans the .meta files to extract the dimensions. It then merges all
0178 the sections together to form a complete representation of the global
0179 dataset.
0180 >> function [AA] = rdmeta(fname,varargin)
0181 >> %
0182 >> % Read MITgcmUV Meta/Data files
0183 >> %
0184 >> % A = RDMETA(FNAME) reads data described by meta/data file format.
0185 >> % FNAME is a string containing the "head" of the file names.
0186 >> %
0187 >> % eg. To load the meta-data files
0188 >> % T.0000002880.p0000.t0000.meta, T.0000002880.p0000.t0000.data
0189 >> % T.0000002880.p0001.t0000.meta, T.0000002880.p0001.t0000.data
0190 >> % T.0000002880.p0002.t0000.meta, T.0000002880.p0002.t0000.data
0191 >> % T.0000002880.p0003.t0000.meta, T.0000002880.p0003.t0000.data
0192 >> % use
0193 >> % >> A=rdmeta('T.0000002880');
0194 >> %
0195 >> % A = RDMETA(FNAME,MACHINEFORMAT) allows the machine format to be specified
0196 >> % which MACHINEFORMAT is on of the following strings:
0197 >> %
0198 >> % 'native' or 'n' - local machine format - the default
0199 >> % 'ieee-le' or 'l' - IEEE floating point with little-endian
0200 >> % byte ordering
0201 >> % 'ieee-be' or 'b' - IEEE floating point with big-endian
0202 >> % byte ordering
0203 >> % 'vaxd' or 'd' - VAX D floating point and VAX ordering
0204 >> % 'vaxg' or 'g' - VAX G floating point and VAX ordering
0205 >> % 'cray' or 'c' - Cray floating point with big-endian
0206 >> % byte ordering
0207 >> % 'ieee-le.l64' or 'a' - IEEE floating point with little-endian
0208 >> % byte ordering and 64 bit long data type
0209 >> % 'ieee-be.l64' or 's' - IEEE floating point with big-endian byte
0210 >> % ordering and 64 bit long data type.
0211 >> %
0212 >>
0213 >> % Default options
0214 >> ieee='n';
0215 >>
0216 >> % Check optional arguments
0217 >> args=char(varargin);
0218 >> while (size(args,1) > 0)
0219 >> if deblank(args(1,:)) == 'n' | deblank(args(1,:)) == 'native'
0220 >> ieee='n';
0221 >> elseif deblank(args(1,:)) == 'l' | deblank(args(1,:)) == 'ieee-le'
0222 >> ieee='l';
0223 >> elseif deblank(args(1,:)) == 'b' | deblank(args(1,:)) == 'ieee-be'
0224 >> ieee='b';
0225 >> elseif deblank(args(1,:)) == 'c' | deblank(args(1,:)) == 'cray'
0226 >> ieee='c';
0227 >> elseif deblank(args(1,:)) == 'a' | deblank(args(1,:)) == 'ieee-le.l64'
0228 >> ieee='a';
0229 >> elseif deblank(args(1,:)) == 's' | deblank(args(1,:)) == 'ieee-be.l64'
0230 >> ieee='s';
0231 >> else
0232 >> sprintf(['Optional argument ' args(1,:) ' is unknown'])
0233 >> return
0234 >> end
0235 >> args=args(2:end,:);
0236 >> end
0237 >>
0238 >> % Match name of all meta-files
0239 >> eval(['ls ' fname '*.meta;']);
0240 >> allfiles=ans;
0241 >>
0242 >> % Beginning and end of strings
0243 >> Iend=findstr(allfiles,'.meta')+4;
0244 >> Ibeg=[1 Iend(1:end-1)+2];
0245 >>
0246 >> % Loop through allfiles
0247 >> for j=1:prod(size(Ibeg)),
0248 >>
0249 >> % Read meta- and data-file
0250 >> [A,N] = localrdmeta(allfiles(Ibeg(j):Iend(j)),ieee);
0251 >>
0252 >> bdims=N(1,:);
0253 >> r0=N(2,:);
0254 >> rN=N(3,:);
0255 >> ndims=prod(size(bdims));
0256 >> if (ndims == 1)
0257 >> AA(r0(1):rN(1))=A;
0258 >> elseif (ndims == 2)
0259 >> AA(r0(1):rN(1),r0(2):rN(2))=A;
0260 >> elseif (ndims == 3)
0261 >> AA(r0(1):rN(1),r0(2):rN(2),r0(3):rN(3))=A;
0262 >> elseif (ndims == 4)
0263 >> AA(r0(1):rN(1),r0(2):rN(2),r0(3):rN(3),r0(4):rN(4))=A;
0264 >> else
0265 >> sprintf('Dimension of data set is larger than currently coded. Sorry!')
0266 >> return
0267 >> end
0268 >>
0269 >> end
0270 >>
0271 >> %-------------------------------------------------------------------------------
0272 >>
0273 >> function [A,N] = localrdmeta(fname,ieee)
0274 >>
0275 >> mname=fname;
0276 >> dname=strrep(mname,'.meta','.data');
0277 >>
0278 >> % Read and interpret Meta file
0279 >> fid = fopen(mname,'r');
0280 >> if (fid == -1)
0281 >> sprintf(['Fila e' mname ' could not be opened'])
0282 >> return
0283 >> end
0284 >>
0285 >> % Scan each line of the Meta file
0286 >> allstr=' ';
0287 >> keepgoing = 1;
0288 >> while keepgoing > 0,
0289 >> line = fgetl(fid);
0290 >> if (line == -1)
0291 >> keepgoing=-1;
0292 >> else
0293 >> % Strip out "(PID.TID *.*)" by finding first ")"
0294 >> ind=findstr([line ')'],')'); line=line(ind(1)+1:end);
0295 >> % Remove comments of form //
0296 >> line=[line ' //']; ind=findstr(line,'//'); line=line(1:ind(1)-1);
0297 >> % Add to total string
0298 >> allstr=[allstr line];
0299 >> end
0300 >> end
0301 >>
0302 >> % Close meta file
0303 >> fclose(fid);
0304 >>
0305 >> % Strip out comments of form /* ... */
0306 >> ind1=findstr(allstr,'/*'); ind2=findstr(allstr,'*/');
0307 >> if size(ind1) ~= size(ind2)
0308 >> sprintf('The /* ... */ comments are not properly paired')
0309 >> return
0310 >> end
0311 >> while size(ind1,2) > 0
0312 >> allstr=[allstr(1:ind1(1)-1) allstr(ind2(1)+3:end)];
0313 >> ind1=findstr(allstr,'/*'); ind2=findstr(allstr,'*/');
0314 >> end
0315 >>
0316 >> eval(lower(allstr));
0317 >>
0318 >> N=reshape( dimlist , 3 , prod(size(dimlist))/3 );
0319 >>
0320 >> A=allstr;
0321 >> % Open data file
0322 >> fid=fopen(dname,'r',ieee);
0323 >>
0324 >> % Read record size in bytes
0325 >> recsz=fread(fid,1,'uint32');
0326 >> ldims=N(3,:)-N(2,:)+1;
0327 >> numels=prod(ldims);
0328 >>
0329 >> rat=recsz/numels;
0330 >> if rat == 4
0331 >> A=fread(fid,numels,'real*4');
0332 >> elseif rat == 8
0333 >> A=fread(fid,numels,'real*8');
0334 >> else
0335 >> sprintf('Ratio between record size and size in meta-file inconsistent')
0336 >> sprintf(' Implied size in meta-file = %d', numels )
0337 >> sprintf(' Record size in data-file = %d', recsz )
0338 >> return
0339 >> end
0340 >>
0341 >> erecsz=fread(fid,1,'uint32');
0342 >> if erecsz ~= recsz
0343 >> sprintf('WARNING: Record sizes at beginning and end of file are inconsistent')
0344 >> end
0345 >>
0346 >> fclose(fid);
0347 >>
0348 >> A=reshape(A,ldims);
0349 >>
