List routines by category:
Atmospheric Sciences |
Benchmarking |
Color |
Date/Time |
Doc |
File & I/O |
BPCH Format |
Scientific Data Formats |
GAMAP Examples |
GAMAP Internals |
GAMAP Utilities |
GAMAP Data Manipulation |
GAMAP Models &
Grids |
GAMAP Plotting |
General |
Graphics |
Math & Units |
Plotting |
Regridding |
Strings |
Structures |
Time Series
List routines by alphabetical order:
A |
B |
C |
D |
E |
F |
G |
H |
I |
J |
K |
L |
M |
N |
O |
P |
Q |
R |
S |
T |
U |
V |
W |
X |
Y |
Z
NAME:
BPCH2ASCII
PURPOSE:
Translates data from GAMAP-readable binary punch file v. 2.0
format to a simple ASCII file format
CATEGORY:
File & I/O, BPCH Format
CALLING SEQUENCE:
BPCH2ASCII, INFILE, OUTFILE [ , Keywords ]
INPUTS:
INFILE -> Name of the binary punch file to read. If
INFILE is not passed, the user will be prompted
to supply a file name via a dialog box.
OUTFILE -> Name of the ASCII file to be written. It is
recommended to insert the tokens %DATE% and %TIME%
into OUTFILE, since BPCH2ASCII will write a separate
netCDF file for each time index in the *.bpch file.
The tokens %DATE% and %TIME% will be overwritten
with the current values of YYYYMMDD and HHMMSS.
Default is "bpch2nc_output.%DATE%.%TIME%.ascii".
KEYWORD PARAMETERS:
DIAGN -> A diagnostic category name (e.g. "IJ-AVG-$") or
array of names which will restrict the data block
selection. If DIAGN is omitted, then all data blocks
within INFILE will be saved in ASCII format to OUTFILE.
/VERBOSE -> If set, then BPCH2ASCII will also echo the
header lines for each data block to the screen.
FORMAT -> String containing the numeric format for
for the data values. Default is '(7(e13.6,1x))'
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
=============================================
CTM_GET_DATA TAU2YYMMDD (function)
GETMODELANDGRIDINFO REPLACE_TOKEN (function)
UNDEFINE
REQUIREMENTS:
References routines from both GAMAP and TOOLS packages.
NOTES:
(1) BPCH2ASCII assumes that all data blocks in the *.bpch file
file adhere to same grid. This will be true for output
files from the GEOS-CHEM model.
(2) BPCH2ASCII will write a separate ASCII file corresponding
to each time index in the *.bpch file. This prevents
file sizes from getting large, especially if there is
a lot of diagnostic output in the *.bpch file.
(3) BPCH2NC will replace the %DATE% token with the
current YYYYMMDD value, and will replace the %TIME%
token with the current HHMMSS value. Therefore, it
is recommended to insert these tokens into the string
passed via OUTFILE. The tokens %DATE% and %TIME% tokens
may be either in uppercase or lowercase.
(4) The format of the ASCII file is:
Data block #1 header line
Data block #1 values (format specified by FORMAT keyword)
Data block #2 header line
Data block #2 values (format specified by FORMAT keyword)
...
The header line will contain the units and size of
each data block.
(5) The data is written to the ASCII file in column-major
order (i.e. the same way as in FORTRAN), so you can read
the data into FORTRAN w/ the following code:
READ( IUNIT, '(a)' ) HEADER
READ( IUNIT, '(1p,7(e13.6,1x))' )
& ((DATA(I,J), I=1,IMX), J=1,JMX)
where IMX and JMX are the dimensions of the data block.
EXAMPLE:
BPCH2ASCII, 'myfile.bpch', 'myfile.%DATE%.%TIME%.ascii'
; Read data from binary punch file 'myfile.bpch'
; and writes it to ASCII file 'myfile.bpch.ascii'.
MODIFICATION HISTORY:
bmy, 22 May 2002: GAMAP VERSION 1.50
bmy, 28 May 2002: GAMAP VERSION 1.51
- Added FORMAT keyword
bmy, 03 Jun 2004: GAMAP VERSION 2.02
- now pass extra keywords to CTM_GET_DATA
via _EXTRA=e keyword
bmy, 03 Dec 2004: GAMAP VERSION 2.03
- add CATEGORY keyword (passed to CTM_GET_DATA)
in order to refine data block search
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/file_io/bpch2ascii.pro)
NAME:
BPCH2COARDS
PURPOSE:
Reads data from a binary punch file and saves it in a
COARDS-compliant netCDF (network Common Data Format) file.
NOTE: COARDS is a formatting standard for netCDF files which
is widely used in both the atmospheric & climate communities.
COARDS-compliant netCDF files can be read by GAMAP, GrADS and
other plotting packages.
See http://ferret.wrc.noaa.gov/noaa_coop/coop_cdf_profile.html
for more information about the COARDS standard.
CATEGORY:
File & I/O, BPCH Format, Scientific Data Formats
CALLING SEQUENCE:
BPCH2COARDS, INFILE, OUTFILE [, Keywords ]
INPUTS:
INFILE -> Name of the binary punch file to read. If INFILE
is not passed, the user will be prompted to supply a
file name via a dialog box.
OUTFILE -> Name of the netCDF file to be written. It is
recommended to insert the tokens %DATE% (or %date%)
into OUTFILE, since BPCH2COARDS will write a separate
netCDF file for each unique YYYYMMDD value contained
within the *.bpch file. If OUTFILE is not specified,
BPCH2COARDS will use the default file name
"coards.%DATE%.nc".
KEYWORD PARAMETERS:
DIAGN -> Array of diagnostic categories from the bpch file
to save to netCDF format. If omitted, BPCH2COARDS will
save all diagnostic categories.
/VERBOSE -> If set, will print the name of each tracer
as it is being written to the netCDF file. Useful
for debugging purposes.
/NC4 -> Write a netCDF4 file instead of netCDF3. Default is
NetCDF3. NetCDF4 support requires IDL 8.0 or later.
COMPRESS -> Integer 0-9 specifies amount of compression in
netCDF4 files. Default is 2, with very little benefit
for higher compression.
/PCOORD -> Use mean pressure as the vertical coordinate rather
sigma or eta
/ALTCOORD -> Use mean altitude as the vertical coordinate
rather than sigma or eta
/TROPONLY -> Write only tropospheric layers
/ONEFILE -> Write all data to one netCDF output file.
Default is one file per calendar day.
_EXTRA=e -> Picks up additional keywords for NCDF_SET
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
============================================
CTM_GET_DATA TAU2YYMMDD (function)
UNDEFINE REPLACE_TOKEN (function)
STRREPL (function) GETMODELANDGRIDINFO
REQUIREMENTS:
(1) References routines from GAMAP and TOOLS packages.
(2) You must use a version of IDL containing the NCDF routines.
NOTES:
(1) BPCH2COARDS assumes that each data block in the *.bpch
file is either 2-D (lon-lat) or 3-D (lon-lat-alt).
(2) BPCH2COARDS assumes that the number type of each data
block in the *.bpch file is REAL*4 (a.k.a. FLOAT).
(3) BPCH2COARDS assumes that all data blocks in the *.bpch
file adhere to same horizontal grid. This will always
be true for output files from the GEOS-CHEM model.
(4) BPCH2COARDS will write a separate COARDS-compliant netCDF
file corresponding to each unique YYYYMMDD date. This
prevents the files from becoming too large to be read
with IDL.
(5) BPCH2COARDS will replace the %DATE% (or %date%) token with
the current YYYYMMDD value. Therefore, it is recommended
to insert this token into the string passed via OUTFILE.
(6) BPCH2COARDS will write arrays containing the latitudes,
longitudes to the netCDF file. For 3-D data blocks,
the eta or sigma centers will also be written to the
file. Time will be written as TAU values (i.e. hours
since 00:00 GMT on 01-Jan-1985.
(7) The netCDF library has apparently been updated in
IDL 6.0+. The result is that variable names containing
characters such as '$', '=', and ':' may now cause an
error in NCDF_VARDEF. Therefore, we now pre-screen
tracer names with function NCDF_VALID_NAME.
EXAMPLE:
BPCH2COARDS, 'myfile.bpch', 'myfile.%DATE%.nc'
; Will write the contents of "myfile.bpch" to one
; or more COARDS-compliant netCDF files adhering
; to the filename convention "myfile.YYYYMMDD.nc"
MODIFICATION HISTORY:
rjp & bmy, 17 Mar 2005: GAMAP VERSION 2.03
- Based on bpch2nc.pro
bmy, 21 Jul 2005: GAMAP VERSION 2.04
- Bug fix:
bmy, 13 Jul 2006: GAMAP VERSION 2.05
- Remove call to PTR_FREE
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Now count GCAP among the GEOS family
for the purpose of converting the TAU
date to a YYYY/MM/DD date.
phs, 29 Oct 2009: GAMAP VERSION 2.14
- Can process files with 3D data on both
centers and edges of the grid boxes.
bmy, 19 Dec 2011: GAMAP VERSION 2.16
- Now handles multiple vertical dimensions
in the bpch file properly.
- Bug fix: now write vertical levels edges to
the file.
bmy, 27 Sep 2012: - Bug fix: Now handle data blocks that straddle
the date line.
bmy, 05 Nov 2013: GAMAP VERSION 2.17
- Change attributes for better COARDS compliance
bmy, 12 Feb 2014: GAMAP VERSION 2.18
- Add more modifications for 4-D data blocks
from bpch files created w/ GC_COMBINE_ND49
bmy, 03 Mar 2015: - Now define dims in order: time, lev, lon, lat,
which is more COARDS compliant.
cdholmes, 29 Mar 2017 - Add support for NetCDF4 and
compression
- Add support for pressure and altitude
as vertical coordinate
- ONEFILE puts all data into a single
output file
- TROPONLY limits the output to
troposphere layers
- Singleton "altXXX" dimensions are avoided
(See /n/home09/ryantosca/IDL/gamap2/file_io/bpch2coards.pro)
NAME:
BPCH2GMI
PURPOSE:
Reads data from a binary punch file and saves it in
netCDF (network Common Data Format) format. The data
will be shifted so that the first longitude is 0 degrees
(i.e. the prime meridian) in order to conform with the
GMI (Global Model Initiative) model grid definition.
CATEGORY:
File & I/O, BPCH Format, Scientific Data Formats
CALLING SEQUENCE:
BPCH2GMI, INFILE, OUTFILE [, Keywords ]
INPUTS:
INFILE -> Name of the binary punch file to read. If
INFILE is not passed, the user will be prompted
to supply a file name via a dialog box.
OUTFILE -> Name of the netCDF file to be written. It is
recommended to insert the tokens %DATE% and %TIME%
into OUTFILE, since BPCH2NC will write a separate
netCDF file for each time index in the *.bpch file.
The tokens %DATE% and %TIME% will be overwritten
with the current values of YYYYMMDD and HHMMSS.
Default is "bpch2nc_output.%DATE%.%TIME%.nc".
KEYWORD PARAMETERS:
DIAGN -> A diagnostic category name (e.g. "IJ-AVG-$") or
array of names which will restrict the data block
selection. If DIAGN is omitted, then all data blocks
within INFILE will be saved in netCDF format to OUTFILE.
/VERBOSE -> If set, will print the names of each tracer
as it is being written to the netCDF file.
_EXTRA=e -> Picks up additional keywords for netCDF routines
OUTPUTS:
SUBROUTINES:
Internal Subroutines:
============================================
B2G_Valid_VarName (function)
B2G_SetNcDim (function)
B2G_GetNcDim (function)
External Subroutines Required:
============================================
CTM_GET_DATA TAU2YYMMDD (function)
UNDEFINE REPLACE_TOKEN (function)
STRREPL (function) GETMODELANDGRIDINFO
REQUIREMENTS:
(1) References routines from GAMAP and TOOLS packages.
(2) You must use a version of IDL containing the NCDF routines.
NOTES:
(1) BPCH2GMI assumes that each data block in the *.bpch file
is either 2-D (lon-lat) or 3-D (lon-lat-alt).
(2) BPCH2GMI assumes that the number type of each data block
in the *.bpch file is REAL*4 (a.k.a. FLOAT).
(3) BPCH2GMI assumes that all data blocks in the *.bpch file
file adhere to same horizontal grid. This will always
be true for output files from the GEOS-CHEM model.
(4) BPCH2GMI will write a separate NC file corresponding
to each time index in the *.bpch file. This prevents
file sizes from getting large, especially if there is
a lot of diagnostic output in the *.bpch file.
(5) BPCH2GMI will replace the %DATE% token with the
current YYYYMMDD value, and will replace the %TIME%
token with the current HHMMSS value. Therefore, it
is recommended to insert these tokens into the string
passed via OUTFILE. The tokens %DATE% and %TIME% tokens
may also be passed in lowercase (e.g, %date%, %time% ).
(6) BPCH2GMI will write arrays containing the latitudes,
longitudes to the netCDF file. For 3-D data blocks,
the sigma centers will also be written to the file.
Date and time are stored as global attributes.
(7) The netCDF library has apparently been updated in
IDL 6.0+. The result is that variable names containing
characters such as '$', '=', and ':' may now cause an
error in NCDF_VARDEF. Therefore, we now pre-screen
tracer names with function NCDF_VALID_NAME.
EXAMPLE:
BPCH2GMI, 'myfile.bpch', 'myfile.%DATE%.%TIME%.nc'
; Will write the contents of "myfile.bpch" to one
; or more netCDF files "myfile.YYYYMMDD.HHMMSS.nc"
MODIFICATION HISTORY:
bmy & phs, 20 Aug 2007: GAMAP VERSION 2.10
- Based on BPCH2NC
bmy, 19 Dec 2007: GAMAP VERSION 2.12
- Now save sigma edges & centers or
eta edges & centers to the file.
- Extra error trap, if there is only one
level in the file then set IS_3D=0.
bmy, 20 Dec 2011: GAMAP VERSION 2.16
- Changed default filename to "bpch2
(See /n/home09/ryantosca/IDL/gamap2/file_io/bpch2gmi.pro)
NAME:
BPCH2HDF
PURPOSE:
Reads data from a binary punch file and saves it in HDF-SD
(Hierarchical Data Format, Scientific Dataset) format.
CATEGORY:
File & I/O, BPCH Format, Scientific Data Formats
CALLING SEQUENCE:
BPCH2HDF, INFILE, OUTFILE [, Keywords ]
INPUTS:
INFILE -> Name of the binary punch file to read. If
INFILE is not passed, the user will be prompted
to supply a file name via a dialog box.
OUTFILE -> Name of the HDF file to be written. It is
recommended to insert the tokens %DATE% and %TIME%
into OUTFILE, since BPCH2HDF will write a separate
HDF file for each time index in the *.bpch file.
The tokens %DATE% and %TIME% will be overwritten
with the current values of YYYYMMDD and HHMMSS.
Default is "bpch2hdf_output.%DATE%.%TIME%.hdf".
KEYWORD PARAMETERS:
DIAGN -> A diagnostic category name (e.g. "IJ-AVG-$") or
array of names which will restrict the data block
selection. If DIAGN is omitted, then all data blocks
within INFILE will be saved in HDF format to OUTFILE.
_EXTRA=e -> Picks up additional keywords for HDF_SETSD
OUTPUTS:
SUBROUTINES:
External Subroutines Required:
=========================================
CTM_GET_DATA TAU2YYMMDD (function)
UNDEFINE REPLACE_TOKEN (function)
HDF_SETSD GETMODELANDGRIDINFO
REQUIREMENTS:
(1) References routines from GAMAP and TOOLS packages.
(2) You must use a version of IDL containing the HDF-SD routines.
NOTES:
(1) BPCH2HDF assumes that each data block in the *.bpch file
is either 2-D (lon-lat) or 3-D (lon-lat-alt).
(2) BPCH2HDF assumes that all data blocks in the *.bpch file
file adhere to same horizontal grid. This will be true
for output files from the GEOS-CHEM model.
(3) BPCH2HDF will write a separate HDF file corresponding
to each time index in the *.bpch file. This prevents
file sizes from getting large, especially if there is
a lot of diagnostic output in the *.bpch file.
(4) BPCH2HDF will replace the %DATE% token with the
current YYYYMMDD value, and will replace the %TIME%
token with the current HHMMSS value. Therefore, it
is recommended to insert these tokens into the string
passed via OUTFILE. These tokens may be in either
uppercase or lowercase.
(4) BPCH2HDF will also write arrays containing the latitudes,
longitudes, sigma coordinates (for 3-D data blocks only!)
to the HDF file.
(5) BPCH2HDF will write arrays containing the latitudes,
longitudes to the netCDF file. For 3-D data blocks,
the sigma centers and sigma edges will also be written
to the file.
EXAMPLE:
BPCH2HDF, 'myfile.bpch', 'myfile.%DATE%.%TIME%.hdf'
; Will write the contents of "myfile.bpch" to
; one or more HDF files "myfile.YYYYMMDD.HHMMSS.hdf"
MODIFICATION HISTORY:
bmy, 22 May 2002: GAMAP VERSION 1.50
bmy, 22 Oct 2002: GAMAP VERSION 1.52
- bug fix: now do not write vertical layer
dim info to HDF file for 2-D grids
bmy, 22 May 2003: GAMAP VERSION 1.53
- Make sure LONGNAME is not a null string
bmy, 18 Sep 2003: - Call PTR_FREE to free the pointer memory
bmy, 03 Jun 2004: GAMAP VERSION 2.02
- now pass extra keywords to CTM_GET_DATA
via _EXTRA=e keyword
bmy, 03 Sep 2004: GAMAP VERSION 2.03
- now defines ETAC and ETAE variables
for hybrid grids
bmy, 03 Dec 2004: GAMAP VERSION 2.03
- add DIAGN keyword (passed to CTM_GET_DATA)
in order to refine data block search
bmy, 19 May 2006: GAMAP VERSION 2.05
- Now do not free the pointer memory
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Now count GCAP among the GEOS family
for the purpose of converting the TAU
date to a YYYY/MM/DD date.
bmy, 18 Feb 2009: GAMAP VERSION 2.13
- Bug fix: should be N_ELEMENTS( DiagN )
instead of N_ELEMENTS( Category ) in the
IF statement for CTM_GET_DATA.
(See /n/home09/ryantosca/IDL/gamap2/file_io/bpch2hdf.pro)
NAME:
BPCH2NC
PURPOSE:
Reads data from a binary punch file and saves it in
netCDF (network Common Data Format) format.
CATEGORY:
File & I/O, BPCH Format, Scientific Data Formats
CALLING SEQUENCE:
BPCH2NC, INFILE, OUTFILE [, Keywords ]
INPUTS:
INFILE -> Name of the binary punch file to read. If
INFILE is not passed, the user will be prompted
to supply a file name via a dialog box.
OUTFILE -> Name of the netCDF file to be written. It is
recommended to insert the tokens %DATE% and %TIME%
into OUTFILE, since BPCH2NC will write a separate
netCDF file for each time index in the *.bpch file.
The tokens %DATE% and %TIME% will be overwritten
with the current values of YYYYMMDD and HHMMSS.
Default is "bpch2nc_output.%DATE%.%TIME%.nc".
KEYWORD PARAMETERS:
DIAGN -> A diagnostic category name (e.g. "IJ-AVG-$") or
array of names which will restrict the data block
selection. If DIAGN is omitted, then all data blocks
within INFILE will be saved in netCDF format to OUTFILE.
/VERBOSE -> If set, will print the names of each tracer
as it is being written to the netCDF file.
_EXTRA=e -> Picks up additional keywords for NCDF_SET
OUTPUTS:
SUBROUTINES:
Internal Subroutines:
============================================
B2N_Valid_VarName (function)
B2N_SetNcDim (function)
B2N_GetNcDim (function)
External Subroutines Required:
============================================
CTM_GET_DATA TAU2YYMMDD (function)
UNDEFINE REPLACE_TOKEN (function)
STRREPL (function) GETMODELANDGRIDINFO
REQUIREMENTS:
(1) References routines from GAMAP and TOOLS packages.
(2) You must use a version of IDL containing the NCDF routines.
NOTES:
(1) BPCH2NC assumes that each data block in the *.bpch file
is either 2-D (lon-lat) or 3-D (lon-lat-alt).
(2) BPCH2NC assumes that the number type of each data block
in the *.bpch file is REAL*4 (a.k.a. FLOAT).
(3) BPCH2NC assumes that all data blocks in the *.bpch file
file adhere to same horizontal grid. This will always
be true for output files from the GEOS-CHEM model.
(4) BPCH2NC will write a separate NC file corresponding
to each time index in the *.bpch file. This prevents
file sizes from getting large, especially if there is
a lot of diagnostic output in the *.bpch file.
(5) BPCH2NC will replace the %DATE% token with the
current YYYYMMDD value, and will replace the %TIME%
token with the current HHMMSS value. Therefore, it
is recommended to insert these tokens into the string
passed via OUTFILE. The tokens %DATE% and %TIME% tokens
may also be passed in lowercase (e.g, %date%, %time% ).
(6) BPCH2NC will write arrays containing the latitudes,
longitudes to the netCDF file.
(7) For pure-sigma grids (e.g. GEOS-1, GEOS-STRAT, GEOS-3),
BPCH2NC will write the following additional variables to
the netCDF file:
(1) SIGE : Sigma coordinate at level edges
(2) SIGC : Sigma coordinate at level centers
The pressure at the bottom edge of level L is given by:
Pe(L) = Ptop + [ SIGE(L) * ( Psurface - Ptop ) ]
and the pressure at the vertical center of level L is:
Pc(L) = Ptop + [ SIGC(L) * ( Psurface - Ptop ) ]
%%%%% NOTE: This is mostly obsolete, as most met fields
%%%%% that are used to drive CTM's are now placed onto
%%%%% hybrid grids.
(8) For hybrid grids (e.g. GEOS-4, GEOS-5, MERRA), the following
dditional variables will be written to the netCDF file:
(1) ETAE : Eta coordinate on level edges
(2) ETAC : Eta coordinate on level centers
(3) Ap : Hybrid grid "A" parameter
(4) Bp : Hybrid grid "B" parameter
The pressure at the bottom edge of level L is given by:
Pe(L) = Ap(L) + ( Bp(L) * Psurface )
and the pressure at the vertical center of level L is:
Pc(L) = ( Pe(L) + Pe(L+1) ) * 0.5
The hybrid ETA coordinates (similar to sigma) at the
level edges and centers are, correspondingly:
ETAE(L) = ( Pe(L) - Ptop ) / ( Psurface - Ptop )
ETAC(L) = ( Pc(L) - Ptop ) / ( Psurface - Ptop )
%%%%% NOTE: The ETAe and ETAc values are only approximate
%%%%% and are computed with a surface pressure of 1013.25
%%%%% hPa. For your scientific analysis, you should compute
%%%%% the pressures at level edges from Ap, Bp, and a
%%%%% spatially-varying surface pressure field (e.g. saved
%%%%% out from GEOS-Chem or another model).
(7) The date and time of the data are stored in the netCDF
file as global attributes.
(8) The netCDF library has apparently been updated in
IDL 6.0+. The result is that variable names containing
characters such as '$', '=', and ':' may now cause an
error in NCDF_VARDEF. Therefore, we now pre-screen
tracer names with function NCDF_VALID_NAME.
EXAMPLE:
BPCH2NC, 'myfile.bpch', 'myfile.%DATE%.%TIME%.nc'
; Will write the contents of "myfile.bpch" to one
; or more netCDF files "myfile.YYYYMMDD.HHMMSS.nc"
MODIFICATION HISTORY:
bmy, 22 May 2002: GAMAP VERSION 1.50
bmy, 22 Oct 2002: GAMAP VERSION 1.52
- bug fix: now do not write vertical layer
dim info to netCDF file for 2-D grids
bmy, 22 May 2003: GAMAP VERSION 1.53
- Bug fix: LONGNAME cannot be a null string
bmy, 22 Sep 2003: - Now declare all variables first, then save
data into them. This is much more efficient!
- Remove reference to NCDF_SET routine
- Call PTR_FREE to free the pointer memory
- Bug fix: now sort TAU0 values for call to UNIQ
- added /VERBOSE keyword
bmy, 09 Oct 2003: - for IDL 6.0+, use '__' to separate category
name from the tracer name
bmy, 21 Oct 2003: - Now uses function NCDF_Valid_Name to screen
out and replace invalid characters for netCDF
variable names
bmy, 06 Nov 2003: GAMAP VERSION 2.01
- added extra global attributes to facilitate
reading netCDF files created by BPCH2NC
into GAMAP
bmy, 29 Mar 2004: GAMAP VERSION 2.02
- Now saves ETA centers for hybrid grid
instead of sigma centers
bmy, 17 Mar 2005: GAMAP VERSION 2.03
- Bug fix: now prints ETAC properly
when the /VERBOSE keyword is set
bmy, 03 Oct 2006: GAMAP VERSION 2.05
- Bug fix: now do not call PTR_FREE
to free the pointer memory
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Now count GCAP among the GEOS family
for the purpose of converting the TAU
date to a YYYY/MM/DD date.
bmy, 21 Jan 2008: GAMAP VERSION 2.12
- Now save sigma edges & centers or
eta edges & centers to the file.
- Extra error trap, if there is only one
level in the file then set IS_3D=0.
- Now error check for duplicate variable names
bmy, 28 Nov 2008: GAMAP VERSION 2.15
- Now save out hybrid-grid Ap and Bp
parameters so that users can accurately
compute the pressure at level edges and
centers.
- Updated comments
bmy, 07 Mar 2012: GAMAP VERSION 2.16
- Correct typos in /VERBOSE output
(See /n/home09/ryantosca/IDL/gamap2/file_io/bpch2nc.pro)
NAME:
BPCH2PCH
PURPOSE:
Translates data from GAMAP-readable binary punch
file v. 2.0 format to the ancient ASCII-punch
file standard.
CATEGORY:
File & I/O, BPCH Format
CALLING SEQUENCE:
BPCH2PCH, FILENAME [, OUTFILENAME [, Keywords ] ]
INPUTS:
FILENAME -> Name of the binary punch file from which
to read data. FILENAME may be a file mask, and may
contain wild card characters (e.g. ~/ctm.bpch.*). If
FILENAME is omitted or contains a wild card character,
the user will be prompted to pick a file via a dialog box.
OUTFILENAME (optional) -> Name of the output ASCII punch
file. Default is 'ASCIIfile.pch'
KEYWORD PARAMETERS:
DIAGN -> A diagnostic category name (e.g. "IJ-AVG-$") or
array of names which will restrict the data block
selection. If DIAGN is omitted, then all data blocks
within INFILE will be saved in ASCII punch format
to OUTFILE.
/EXTRA_SPACE -> If set, will put an extra space between
the numbers in the ASCII punch file. This might
be necessary when using MATLAB or S-PLUS to read
in the ASCII punch file.
OUTPUTS:
Writes data to ASCII punch file format
SUBROUTINES:
CTM_GET_DATA
REQUIREMENTS:
References routines from both GAMAP and TOOLS packages.
NOTES:
Some limitations:
(1) Works only for global lon-lat diagnostics.
(2) The top header line might be inaccurate (but nobody
really reads that anyway, so forget it for now...)
EXAMPLE:
BPCH2PCH, '~/bmy/ctm.bpch', '~/bmy/ctm.pch'
; Reads data from binary punch file '~/bmy/ctm.bpch'
; and writes it to ASCII punch file '~/bmy/ctm.pch'.
MODIFICATION HISTORY:
bmy, 08 Nov 1999: VERSION 1.00
bmy, 03 Jun 2004: GAMAP VERSION 2.02
- now pass extra keywords to CTM_GET_DATA
via _EXTRA=e keyword;
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/file_io/bpch2pch.pro)
NAME:
BPCH_LINK
PURPOSE:
Copies data from several binary punch files into a single
binary punch file. Also can trim data down to nested-grid
resolution if necessary
CATEGORY:
File & I/O, BPCH Format
CALLING SEQUENCE:
BPCH_LINK, INFILES, OUTFILE [, Keywords ]
INPUTS:
INFILES -> A path name or file mask (with wildcards)
which indicates the names of the individual files
to be linked together in a single bpch file.
OUTFILE -> Name of the bpch file that will contain data
from the individual bpch files specified by INFILES.
KEYWORD PARAMETERS:
/CREATE_NESTED --> If set, then BPCH_LINK will trim data
to the nested grid resolution as specified by the
XRANGE and YRANGE keywords.
XRANGE -> A 2-element vector containing the minimum and
maximum box center longitudes which define the nested
model grid. Default is [-180,180].
YRANGE -> A 2-element vector containing the minimum and
maximum box center latitudes which define the nested
model grid. Default is [-90,90].
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
==============================
OPEN_FILE UNDEFINE
CTM_DIAGINFO
REQUIREMENTS:
Requires routines from the GAMAP and TOOLS packages.
NOTES:
None
EXAMPLE:
BPCH_LINK, 'ctm.bpch.*', 'new.ctm.bpch'
; Consolidates data from the 'ctm.bpch.*' files
; into a single file named 'new.ctm.bpch'
MODIFICATION HISTORY:
bmy, 31 Jan 2003: VERSION 1.00
bmy, 09 Apr 2003: VERSION 1.01
- now can save to nested grid
bmy, 15 May 2003: VERSION 1.02
- now can pass a list of files via INFILES
bmy, 20 Nov 2003: GAMAP VERSION 2.01
- now gets the spacing between diagnostic
offsets from CTM_DIAGINFO
bmy, 28 May 2004: GAMAP VERSION 2.02
- Now use MFINDFILE to get INLIST regardless
of the # of elements of INFILES
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
bmy, 02 Apr 2008: GAMAP VERSION 2.12
- Now read/write bpch as big-endian
(See /n/home09/ryantosca/IDL/gamap2/file_io/bpch_link.pro)
NAME:
BPCH_MONTHLY_MEAN
PURPOSE:
Creates monthly means from GEOS-Chem output saved at less
than monthly intervals. Ideal for working with output of
high-resolution model output, especially if your queuing
system time limits do not permit a 1-month simulation to be
completed in a single run stage.
CATEGORY:
File & I/O, BPCH Format
CALLING SEQUENCE:
BPCH_MONTHLY_MEAN, FILES [, Keywords ]
INPUTS:
FILES -> A vector containing the pathnames of the files from
which you would like to create monthly mean output.
KEYWORD PARAMETERS:
OUTFILENAME -> Name of the file (bpch format) that will
contain the monthly mean output. The default is
"bpch_monthly_mean_output.bpch".
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required
================================
REQUIREMENTS:
Requires other routines from the GAMAP package.
NOTES:
Assumes that each of the files passed via the FILES argument
contains an identical sequence of diagnostic data blocks.
This will normally be the case for GEOS-Chem simulations that
have to be separated into several run stages for the queue
system.
Error checking is minimal, we will fix this later. This
routine in intended for use with files that are created from
individual stages of a long GEOS-Chem simulation. As such,
we can usually assume that all files will have the same
sequence of data blocks, and that all data blocks will be on
the same grid.
EXAMPLE:
FILES = [ 'ctm.bpch.2011010100', 'ctm.bpch.2011011500' ]
BPCH_MONTHLY_MEAN, FILES, OUTFILENAME = 'monthly_mean.bpch'
; Creates monthly-mean output from two GEOS-Chem bpch
; files that contain 15-day averaged data.
MODIFICATION HISTORY:
bmy, 21 Dec 2011: GAMAP VERSION 2.16
- Initial version
(See /n/home09/ryantosca/IDL/gamap2/file_io/bpch_monthly_mean.pro)
NAME:
BPCH_SEP
PURPOSE:
Separates data from one binary punch file into another binary
punch file by time (TAU0), tracer, or location indices. Useful
for making smaller bpch files so that we don't run out of IDL
memory when reading/processing them.
CATEGORY:
File & I/O, BPCH Format
CALLING SEQUENCE:p
BPCH_SEP, INFILE, OUTFILE [, Keywords ]
INPUTS:
INFILE -> A path name or file mask (with wildcards)
which indicates the names of the individual files
to be linked together in a single bpch file.
OUTFILE -> Name of the bpch file that will contain data
from the individual bpch files specified by INFILES.
KEYWORD PARAMETERS:
DIAGN -> Array of diagnostic categories for which to
save out to OUTFILE Default is to save all diagnostic
categories to OUTFILE.
TAU0 -> Time index (hours from 1 Jan 1985) denoting the
data blocks to be saved from INFILE to OUTFILE. You
can use NYMD2TAU to compute this from a YYYYMMDD date.
TRACER -> Tracer number(s) for which to save to OUTFILE.
Default is to save all tracers.
II, JJ, LL -> Longitude, latitude, altitude index arrays used
to cut down the data block to less than global size. Use
IDL notation, meaning first element is 0.
GLOBALCOORDS -> When the data entries in the bpch file
contain only part of the global CTM grid (e.g. ND48,
ND49, ND50, ND51) this indicates
that II, JJ, LL indices should be
interpreted as global CTM indices, rather than relative
to the regional subset grid.
EXCLUDE -> Reverses the selection criteria, so that the
designated DIAGN, TAU0, and TRACER are EXCLUDED from the
output file. Everything else is included. In order to be
excluded, a datablock must match all specified keywords:
DIAGN, TAU0, and TRACER.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
===============================================
CTM_DIAGINFO LITTLE_ENDIAN (function)
OPEN_FILE UNDEFINE
REQUIREMENTS:
None
NOTES:
(1) Assumes that II, JJ, LL contain consecutive indices in
longitude, latitude, and altitude, respectively.
(2) Also assumes that II, JJ, LL are in IDL notation
(i.e. starting from zero). This is so that you can
pass the output from the WHERE command to BPCH_SEP.
EXAMPLES:
(1)
BPCH_SEP, 'ctm.bpch.big', 'ctm.bpch.small', tau0=140256D
; Pulls out data blocks for TAU0=140256 (1/1/2001) from
; "ctm.bpch.big" and saves them in "ctm.bpch.small"
(2)
INTYPE = CTM_TYPE( 'GEOS4', RES=4 )
INGRID = CTM_GRID( INTYPE )
INDX = WHERE( INGRID.XMID ge -60 AND INGRID.XMID le 60 )
INDY = WHERE( INGRID.YMID ge 0 AND INGRID.YMID le 60 )
BPCH_SEP, 'ctm.bpch.big', 'ctm.bpch.small', II=INDX, JJ=INDY
; Pulls out all data blocks for the geographical area
; from 60W - 60E longitude and 0-60N latitude.
MODIFICATION HISTORY:
bmy, 18 Sep 2003: GAMAP VERSION 1.53
bmy, 20 Nov 2003: GAMAP VERSION 2.01
- now gets the spacing between diagnostic
offsets from CTM_DIAGINFO
bmy, 07 Jul 2005: GAMAP VERSION 2.04
- minor bug fix; now can save out data
blocks for more than one matching TAU0
phs, 24 Oct 2006: GAMAP VERSION 2.05
- Added the II, JJ, LL keywords for
selecting a smaller geographical area.
These must be index arrays.
- Added the TRACERN keyword
- Added SWAP_ENDIAN=LITTLE_ENDIAN() in
the call to OPEN_FILE
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
bmy, 02 Apr 2008: GAMAP VERSION 2.12
- Cosmetic changes
bmy, 18 Jul 2016: GAMAP VERSION 2.19
- Now use the spacing obtained from
the diaginfo.dat file
cdh, 04 Apr 2017: -Add GlobalCoord keyword so that II,JJ,LL keywords
work with ND48, ND49, ND50 and ND51 output
-Prevent writing data when no matching
II,JJ,LL coordinates
(See /n/home09/ryantosca/IDL/gamap2/file_io/bpch_sep.pro)
NAME:
BPCH_TEST
PURPOSE:
Reads header and data block information from binary punch
(BPCH for short) files and prints the file pointer locations.
CATEGORY:
File & I/O, BPCH Format
CALLING SEQUENCE:
BPCH_TEST [, FILENAME, [ Keywords ] ]
INPUTS:
FILENAME (optional) -> Name of the binary punch file to read.
If omitted, a dialog box will prompt the user to make
a selection.
KEYWORD PARAMETERS:
/NOPAUSE -> If set, will not pause after displaying information
about each data block. Default is to pause to allow the
user to examine each data blocks header information.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
------------------------------
LITTLE_ENDIAN (function)
REQUIREMENTS:
References routines from the TOOLS package.
NOTES:
BPCH_TEST does not return any data values from the binary
punch file. It is meant to be used for debugging purposes.
EXAMPLES:
BPCH_TEST, 'my.bpch'
BPCH_TEST, FILENAME = 'my.bpch'
; will print info about each data block in 'my.bpch'
MODIFICATION HISTORY:
bmy, 10 Dec 1999: VERSION 1.00
bmy, 25 May 2000: GAMAP VERSION 1.45
- allow user to quit after viewing
each data block header
- add FILENAME keyword, so that the filename
can be passed as a parameter or a keyword
bmy, 21 Jul 2000: GAMAP VERSION 1.46
- now print locations of min, max data values
- changed FILETYPE to reflect new definitions
from CTM_OPEN_FILE
bmy, 24 Aug 2004: GAMAP VERSION 2.03
- Now recognizes bpch file containing
GEOS-CHEM station timeseries data
- Updated comments, cosmetic change
bmy, 05 Feb 2013: GAMAP VERSION 2.17
- Now recognize FTI "CTM bin 4D", which is
output from gc_combine_nd49.pro etc.
(See /n/home09/ryantosca/IDL/gamap2/file_io/bpch_test.pro)
NAME:
CONVERT_O3PL
PURPOSE:
Converts single-tracer Ox rate files from their native
binary format to binary punch format
CATEGORY:
File & I/O, BPCH Format
CALLING SEQUENCE:
CONVERT_O3PL [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
INMODELNAME -> A string containing the name of the model
grid on which the input data resides. Default is GEOS_STRAT.
INRESOLUTION -> Specifies the resolution of the model grid
on which the input data resides. RESOLUTION can be
either a 2 element vector with [ DI, DJ ] or
a scalar (DJxDI: 8=8x10, 4=4x5, 2=2x2.5, 1=1x1,
0.5=0.5x0.5). Default is 2.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
==============================
CTM_TYPE (function)
CTM_GRID (function)
CTM_MAKE_DATAINFO (function)
REQUIREMENTS:
None
NOTES:
Input file names are hardwired for now.
EXAMPLE:
CONVERT_O3PL, INMODELNAME ='GEOS1', $
INRESOLUTION = 4, $
; Regrids P(O3) and L(O3) data from
; GEOS-1 4 x 5 grid to GISS-II-PRIME 4 x 5 grid.
MODIFICATION HISTORY:
bmy, 16 Jul 2002: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
bmy, 02 Apr 2008: GAMAP VERSION 2.12
- Now read input file as big-endian
(See /n/home09/ryantosca/IDL/gamap2/file_io/convert_o3pl.pro)
NAME:
CTM_WRITEBPCH
PURPOSE:
Save GAMAP datainfo records to disk
(in binary punch file format).
CATEGORY:
GAMAP Utilities, BPCH Format
CALLING SEQUENCE:
CTM_WRITEBPCH, DATAINFO, [, Keywords ]
INPUTS:
DATAINFO -> a datainfo record or an array of datainfo records
FILEINFO -> a fileinfo record or an array of fileinfo records
KEYWORD PARAMETERS:
FILENAME -> Filename of output file. Should end in '.bpch'.
SCALE -> An optional scaling factor. This factor will be applied
to _all_ data record upon saving. The globally stored records
are not affected.
NEWUNIT -> With this keyword you can change the unit _name_ for
the saved data. This will _not_ perform a unit conversion!
For a true unit conversion you must also use the SCALE
keyword. NEWUNIT will be applied to _all_ records!
/APPEND -> If set, then will append to an existing binary
punch file rather than writing to a new file.
OUTPUTS:
A binary punch file with the selected data records will be
created.
SUBROUTINES:
External Subroutines Required:
====================================================
CHKSTRU (function) CTM_DIAGINFO
CTM_GET_DATA (function) DATATYPE (function)
OPEN_FILE
REQUIREMENTS:
None
NOTES:
This routine forces reading of all selected data records via
CTM_GET_DATA. This may take a while for huge ASCII punch files.
EXAMPLE:
gamap [,options] ; call gamap to read records from a file
@gamap_cmn ; get global datainfo structure
d = *pglobalDataInfo
ind = where(d.tracer eq 2) ; select all Ox records
ctm_writebpch,d[ind],filename='oxconc.bpch'
MODIFICATION HISTORY:
mgs, 20 May 1999: VERSION 1.00
- stores binary files version 1
mgs, 24 May 1999: VERSION 2.00
- stores binary files version 2
bmy, 26 Jul 1999: VERSION 2.01
- now call function DATATYPE
- make sure only floating point data gets
written to binary punch file v. 2.0
bmy, 19 Jan 2000: - updated commetns
bmy, 07 Jun 2000: GAMAP VERSION 1.45
- Save TRACER mod 100L to the punch file
- updated comments
bmy, 02 Mar 2001: GAMAP VERSION 1.47
- added FILEINFO as an argument; will use
PGLOBALFILEINFO structure if not passed
- removed obsolete comments
bmy, 13 Mar 2001: - now supports Windows, MacOS, and Unix/Linux
bmy, 07 Jun 2001: - removed obsolete code from 7/26/99
mje & bmy, 17 Dec 2001: GAMAP VERSION 1.49
- added /APPEND keyword in order to
append to an existing binary punch file
- updated comments
bmy, 15 Oct 2002: GAMAP VERSION 1.52
- added LEVELSAVE keyword to define certain
levels which to save to disk
- Updated comments, cosmetic changes
bmy, 19 Nov 2003: GAMAP VERSION 2.01
- now get diagnostic spacing from CTM_DIAGINFO
and write TRACER mod SPACING to the BPCH file.
bmy, 27 May 2004: GAMAP VERSION 2.02
- Bug fix: Don't call CTM_GET_DATA to initialize
data pointers if this has been done already
- removed LEVELSAVE keyword
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Now save 4D datablock if the tag
of FILEINFO[0].FILETYPE = 106;
(See /n/home09/ryantosca/IDL/gamap2/gamap_util/ctm_writebpch.pro)
NAME:
FUTURE2BPCH
PURPOSE:
Converts future emission growth factor files from the obsolete
binary format to binary punch format (so that they can be
read by GAMAP).
CATEGORY:
File & I/O, BPCH Format
CALLING SEQUENCE:
FUTURE2BPCH, [ Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
INFILENAME -> Name of the input file containing fossil
fuel scale factors. If omitted, SCALEFOSS2BPCH
will prompt the user for a filename via a dialog box.
OUTFILENAME -> Name of the binary punch file containing
fossil fuel scale factors. Default is to add a
".bpch" extension to INFILENAME.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required
==================================================
CTM_TYPE (function) CTM_GRID (function)
NYMD2TAU (function) CTM_MAKE_DATAINFO (function)
CTM_WRITEBPCH EXTRACT_FILENAME (function)
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
FUTURE2BPCH, INFILENAME='scalefoss.liq.2x25.1998', $
OUTFILENAME='scalefoss.liq.2x25.1998.bpch'
; Converts scalefoss files to BPCH format.
MODIFICATION HISTORY:
bmy, 25 Jan 2006: VERSION 1.00
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
bmy, 02 Apr 2008: GAMAP VERSION 2.12
- Now read bpch as big-endian
(See /n/home09/ryantosca/IDL/gamap2/file_io/future2bpch.pro)
NAME:
MAKE_MULTI_NC
PURPOSE:
Convert bpch files (matching a mask) to netCDF format.
The routine can work recursively : files in subdirectories
are also searched for.
This is a convenient generic wrapper for GAMAP routine
Bpch2coards.pro, to work on several files and directories at
once.
When working recursively, the directory tree in the input
directory is recreated as needed in the output directory.
CATEGORY:
File & I/O, BPCH Format, Scientific Data Formats
CALLING SEQUENCE:
MAKE_MULTI_NC
INPUTS:
none
KEYWORD PARAMETERS:
MASK -> string, default is '*', that is all files
INPUT_PARENT_DIR -> top directory of files to convert, if
not specified, a dialog window pops up
OUTPUT_PARENT_DIR -> top directory destination for netCDF
files, if not specified, a dialog window pops up.
RECURSION -> to search subdirectories. Default is 0
(OFF). Set to 1 to turn it on.
TOKEN -> set if you want to replace 'bpch' with 'nc' in all
part of the full name. Default is to have extension
".nc" added to file name only.
OUTPUTS:
None
REQUIREMENTS:
References routines from the GAMAP package.
NOTES:
To work recursively on the directories, I use FILE_SEARCH
with 2 arguments. This is not possible with MFINDFILE, and
works only with IDL 5.5 and above.
EXAMPLES:
indir = '/as/data/geos/GEOS_1x1/EDGAR_200607/'
outdir = '/home/phs/data/EDGAR_200607/nc/'
mask = '*1x1'
make_multi_nc, input_parent_dir=indir, out=outdir, mask=mask, /r
MODIFICATION HISTORY:
Thu Oct 29 16:40:28 2009, Philippe Le Sager
now pass _extra keyword to BPCH2COARDS (eg /NAMER
needed for nested data)
Thu Feb 19 11:12:16 2009, Philippe Le Sager
renamed MAKE_MULTI_NC. Added recursion keyword
(default is OFF). Now **AUTOMATICALLY** creates missing
subdirectory in output directory tree, when in
recursive mode.
Tue Jan 27 10:40:49 2009, Philippe Le Sager
v1, based on make_c_nc.pro to work on several
directories at once.
bmy, 30 Nov 2010: GAMAP VERSION 2.15
- Updated comments and category in header
bmy, 01 Feb 2012: GAMAP VERSION 2.16
- Skip processing ASCII text files
mps, 04 Mar 2015: - Bug fix: Now assign InFileName before checking
file type
(See /n/home09/ryantosca/IDL/gamap2/file_io/make_multi_nc.pro)
NAME:
MAKE_NC_RECURSIVE
PURPOSE:
Converts files matching a mask to netCDF format.
The routine works recursively. This is a convenience
wrapper for GAMAP routine bpch2coards.pro, to work on
several directories at once.
You just need to (1) create the same directory tree in the
output location, then (2) run the routine once.
CATEGORY:
File & I/O, BPCH Format, Scientific Data Formats
CALLING SEQUENCE:
MAKE_NC_RECURSIVE
INPUTS:
none
KEYWORD PARAMETERS:
MASK -> string, default is '*', that is all files
INPUT_PARENT_DIR -> top directory of files to convert, if
not specified, a dialog window pops up
NEW_PARENT_DIR -> top directory destination for netCDF
files, if not specified, a dialog window pops up
TOKEN -> set if you want to replace 'bpch' with 'nc' in all
part of the full name
OUTPUTS:
None
REQUIREMENTS:
References routines from the GAMAP package.
NOTES:
To work recursively on the directories, I use FILE_SEARCH
with 2 arguments. This is not possible with MFINDFILE, and
works only with IDL 5.5 and above.
EXAMPLE:
; after creating a subdirectories tree in outdir similar to the
; one in indir:
indir = '/as/data/geos/GEOS_1x1/EDGAR_200607/'
outdir = '/home/phs/data/EDGAR_200607/nc/'
mask = '*1x1'
make_nc_recursive, input_parent_dir=indir, new=outdir, mask=mask
MODIFICATION HISTORY:
Tue Jan 27 10:40:49 2009, Philippe Le Sager
v1, based on make_c_nc.pro to work on several
directories at once.
bmy, 30 Nov 2010: GAMAP VERSION 2.15
- Updated comments and categories in header
(See /n/home09/ryantosca/IDL/gamap2/file_io/make_nc_recursive.pro)
NAME:
MAKE_RESTART
PURPOSE:
Creates a restart file for GEOS-Chem.
CATEGORY:
File & I/O, BPCH Format
CALLING SEQUENCE:
MAKE_RESTART [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
OUTMODELNAME -> Name of the model grid onto which the data
will be regridded. Default is "GEOS4_30L".
OUTRESOLUTION -> Specifies the resolution of the model grid
onto which the data will be regridded. OUTRESOLUTION
can be either a 2 element vector with [ DI, DJ ] or
a scalar (DJxDI: 8=8x10, 4=4x5, 2=2x2.5, 1=1x1,
0.5=0.5x0.5). Default for all models is 4x5.
OUTFILENAME -> Name of the restart file that will be created.
Default is "restart.bpch".
TAU0 -> TAU value (hours from 0 GMT on 01 Jan 1985) that
that will be used to timestamp the restart file.
The default TAU0 value 140256.00 (corresponds to
0 GMT on 01 Jan 2001).
TRACERLIST -> A scalar value (or vector) of tracer numbers
to write to the restart file. Default is 1.
DATAVALUE -> Specifies the data value that will be assigned
to all grid boxes in the restart file. Default is 0e0.
DIAGN -> Specifies the diagnostic category name that will
be used to index data fields in the restart file.
Default is "IJ-AVG-$".
UNIT -> Use this keyword to overwrite the default unit
string (as specified in the "tracerinfo.dat" file)
for each data block in the restart file.
/NO_VERTICAL -> Set this switch to create a restart file
with 2-D data blocks (e.g. lon x lat) instead of 3-D
data blocks (e.g. lon x lat x alt).
DIM -> Allows you to manually set the dimensions of the
data blocks (for nested grids). DIM is passed to
CTM_MAKE_DATAINFO.
FIRST -> Allows you to manually set the starting indices
(in Fortran notation, starting from 1) of the data
block. FIRST is passed to CTM_MAKE_DATAINFO.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
===================================================
CTM_GET_DATABLOCK (function) CTM_GRID (function)
CTM_MAKE_DATAINFO (function) CTM_TYPE (function)
CTM_WRITEBPCH NYMD2TAU
REQUIREMENTS:
None
NOTES:
(1) You must make sure that your "diaginfo.dat" and
"tracerinfo.dat" file lists the diagnostic categories
and tracers that you wish to save to the restart file.
EXAMPLE:
MAKE_RESTART, OUTMODELNAME='GEOS4_30L', $
OUTRESOLUTION=2, $
OUTFILENAME='restart.2x25.2005010100', $
TAU0=NYMD2TAU( 20050101L ), $
DATAVALUE=100e0, $
TRACERLIST=[1,2,3,4,5,6], $
UNIT='ppbv', $
DIAGN='IJ-AVG-$'
; Create a GEOS-4 30-level 2x25 restart file for
; CO2 tracers 1-6, setting all tracers equal to
; 100 ppbv.
MODIFICATION HISTORY:
bmy, 19 Jul 2007: VERSION 1.00
bmy, 27 Oct 2010: GAMAP VERSION 2.15
- Added DIM and FIRST for setting the
region properly for nested grids
(See /n/home09/ryantosca/IDL/gamap2/file_io/make_restart.pro)
NAME:
SCALEFOSS2BPCH
PURPOSE:
Converts fossil fuel scale factor files from the obsolete
binary format to binary punch format (so that they can be
read by GAMAP).
CATEGORY:
File & I/O, BPCH Format
CALLING SEQUENCE:
SCALEFOSS2BPCH, [ Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
INFILENAME -> Name of the input file containing fossil
fuel scale factors. If omitted, SCALEFOSS2BPCH
will prompt the user for a filename via a dialog box.
OUTFILENAME -> Name of the binary punch file containing
fossil fuel scale factors. Default is to add a
".bpch" extension to INFILENAME.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required
==================================================
CTM_TYPE (function) CTM_GRID (function)
NYMD2TAU (function) CTM_MAKE_DATAINFO (function)
CTM_WRITEBPCH EXTRACT_FILENAME (function)
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
SCALEFOSS2BPCH, INFILENAME='scalefoss.liq.2x25.1998', $
OUTFILENAME='scalefoss.liq.2x25.1998.bpch'
; Converts scalefoss files to BPCH format.
MODIFICATION HISTORY:
bmy, 15 Jan 2003: VERSION 1.00
bmy, 23 Dec 2003: VERSION 1.01
- rewritten for GAMAP v2-01
bmy, 27 Jun 2006: VERSION 1.02
- Use more robust algorithm for getting
the year out of the file name
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
bmy, 02 Apr 2008: GAMAP VERSION 2.12
- Now read input file as big-endian
(See /n/home09/ryantosca/IDL/gamap2/file_io/scalefoss2bpch.pro)