Getting Started with Win32 GrADS

Version 2.0.a5.oga.3

     

Last Update: 2 March 2009

Contents

Introduction

Win32 GrADS is a port of Brian Doty 's popular Grid Analysis and Display System (GrADS) to the x86 PC running 32-bit MS Windows operating systems. Starting with v1.9 Win32 GrADS is now bundled with the Xming X Windows server, so there is no need to install a separate X server.

This implementation of Win32 GrADS is functionally equivalent to all Unix/Linux versions. Supported features include:

System Requirements

Win32 GrADS is a 32-bit application. You must have the following hardware/software:

This Distribution

In this installation you will find all that you need to run GrADS: programs, font and map datasets, sample test data as well as extension plug-ins. Starting with v2.0.a5 the directory structure has changed substantially to match the OpenGrADS Bundle being adopted for all platforms by the OpenGrADS project.

Batteries included

Because Win32 GrADS is based on the same code as the Unix version, it requires an X server. An X server is the software which processes instructions from "X clients" such as GrADS to do things like draw on the screen. Starting with Version 1.9, the excellent Xming X Server

 

http://www.straightrunning.com/XmingNotes/ 

http://sourceforge.net/projects/xming

 

is bundled and integrated with Win32 GrADS. There is no longer a need to install a separate X server. The Xming X server is developed and maintained by Colin Harrison, being derivative from a number of other open source projects. The binaries included with Win32 GrADS are based on the Xming Sourceforge Public Domain Release. See COPYRIGHT notice under Xming subdirectory and URLs above for additional information.

 

Note: In the past Win32 GrADS has worked with a wide variety of X servers. If for some reason you would like to work with your trusted X server simply remove or rename the Xming directory shipped with Win32 GrADS and set your DISPLAY environment variable as required by your X server (usually DISPLAY=localhost:0.0). By default, when Xming is present, the GrADS binaries automatically set DISPLAY=localhost:7.0, and starts Xming on Display number 7.

Installation

Up to date installation information can be found on the OpenGrADS Wiki.

Using the Automatic Installer

Installing the Windows version of GrADS is very easy. If you downloaded a file called 

         grads-2.0.x-win32_superpack.exe
simply run it, answer a few simple questions, and you are good to go (the installer will also automatically set your PATH so that you can run GrADS from the command line window).

Using the ZIP File

If your distribution came in the form of a zip file, simply unzip the distribution file 

         grads-2.0.x.win32_superpack.zip
to a place of your choice (e.g., under C:\ or C:\OpenGrADS\) and you are ready to go. Then open Windows Explorer and click on any of the wrapper scripts under OpenGrADS (say, opengrads) and start using it.

Setting your PATH

This step is only necessary if your distribution came in the form of a ZIP file. You may find convenient adding the GrADS binary directory,e.g., 
         C:\OpenGraDS\Cygwin\Versions\$version\i686
to your PATH. In this example, $version stands for the particular version of the software being installed, say, 2.0.a5.oga.2. The top directory C:\OpenGrADS has also simple VBScript wrapper scripts that can be used to start the main applications. However, there are a large number of utilities that would not be accessible if you do not add the full path above.

For changing your PATH click on

[Start]/[Control Panel]/[System]

Then select the [Advanced] tab and click on the [Environment Variables] button on the lower left. Select Path under -System Variables- and click on the [Edit] button. Do not delete the current contents of your path; simply append a ";" followed by the name of the directory where your GrADS binaries reside.

Getting more fonts

The Xming server bundled with Win32 GrADS comes with a minimal number of built-in fonts, plus whatever Windows fonts it may find. This is usually fine since GrADS draws its own fonts and does not rely on the X server for writing strings. The only exception is if you are using the Athena Widgets feature, which does make use of X Window fonts. You can install additional Xming fonts from their Sourceforge download page:

http://sourceforge.net/project/showfiles.php?group_id=156984

When installing the fonts make sure you install them with the Xming that came with your Win32 GrADS distribution, not the suggested default C:\Program Files\Xming. For example, if you installed GrADS under C:\OpenGrADS, you will want to install the extra fonts under C:\OpenGrADS\Xming.

Using Win32 GrADS

The following applications are available.
 

Application

Description

Grads

Win32 GrADS with the classic command line interface (ga-> prompt).  This version can read all supported GrADS formats including NetCDF-3, NetCDF-4/HDF-5, HDF-4, GRIB-1/2 and on-line access to data on OPeNDAP servers (both gridded and station datasets.)

GradsGUI

Win32 GrADS with a Graphical User Interface. This version can read all supported GrADS formats including NetCDF-3, NetCDF-4/HDF-5, HDF-4, GRIB-1/2 and on-line access to data on OPeNDAP servers (both gridded and station datasets.)

GradsDAP 

This the same as Grads above. In the past you needed a separate build of GrADS to access OPeNDAP servers. Starting with v2.0.a5.oga.2 this functionality is available in the main executable Grads.

Gv32 

Windows' based GrADS metafile viewer.

Gxtran

Classic metafile viewer (Gv is nicer).

GxYAT

Converts GrADS metafiles to PNG, SVG, PDF and enscapsulated postscript. Images produced with GxYAT have anti-aliased fonts which are more legible than images created with printim. Notice that GxYAT also comes as a User Defined Command (UDC) and can be used just like printim from the ga-> command line.

Gxeps

Converts GrADS metafiles to enscapsulated postscript (faster). You may want to obtain the Windows version of Ghostview (gsview), freely available from http://www.cs.wisc.edu/~ghost/gsview/. Gsview will allow you to preview and print PostScript documents on win95/NT. Highly recommended.

Gxps

Converts GrADS metafiles to postscript level 1 (slower) 

Gribmap

GRIB file mapping utility 

Gribscan

GRIB file scan utility 

Wgrib, wgrib2

Wes Ebisuzaki's GRIB-1/GRIB-2 utilities (it slices, dices) 

Stnmap

Station mapping utility 

wget

wget is a command line tool for transferring files with URL syntax, supporting FTP, FTPS, HTTP, HTTPS, SCP, SFTP, TFTP, TELNET, DICT, LDAP, LDAPS and FILE.

Sh, tcsh

sh is a win32 port of the GNU Bourne Again Shell (bash). This utility is needed for executing shell commands from grads, e.g., ! ls. For documentation of GNU software consult http://www.gnu.org/doc/doc.html. For source code and additional information, consult http://cygwin.com.

tcsh is a port of the C-shell to Win32.

Rxvt

A nice terminal for replacing Windows COMMAND.COM. You can start Grads under rxvt by entering: 

rxvt -fn fixedsys -fg darkgreen -e Grads 

NOTE: For running rxvt as a standalone program you may need to create the directory c:\cygwin\tmp .

ls, cp, rm, mv, pwd, cat, grep, gzip, etc.

Assorted GNU file utilities to facilitate porting GrADS scripts from Unix to Win32. For documentation of GNU software consult http://www.gnu.org/doc/doc.html For source code and additional information, consult http://cygwin.com

*.dll 

These are Dynamic Link Libraries (DLL) needed by the applications above. If you move them to a different directory, make sure they remain in your PATH. The DLL files above are usually not visible from the Win32 GrADS Program Group. You can change this default behavior from the View/Properties menu of the Windows Explorer. 

You can also start Win32 GrADS or any of the applications above from the DOS command line, e.g.,

c:\> grads

Recall that DOS is case insensitive, so grads is the same as GrADS. See rxvt above for a nice terminal program for Windows.

Documentation

A copy of the GrADS Core Documentation is included in this distribution. The on-line version is available from COLA. OpenGrADS specific documentation is available at the OpenGrADS Wiki.

Another source of documentation isthe OpenGrADS Cookbooks where you can find Recipes on a variety of topics.

OpenGrADS Interfaces and Extensions

This version of GrADS fully supports the Python, Perl, PHP, Java and Matlab interfaces being developed by the OpenGrADS Project. However, the specific Perl/PHP/Python/Java/Malab modules are not included as they need to be installed in the context of specific Perl/PHP/Python/Java/Malab distributions. Please consult the OpenGrADS Wiki for additional information.

This version also includes a preview release of the OpenGrADS Extensions. The same extensions previously released by the OpenGrADS project with GrADS 1.9.0-rc1 are now available with GrADS v2.0, with the addition of some new ones: libmf (from Mike Fiorino) and a new spherical harmonic filter, sh_filt(). Documentation for these user defined functions/commands can be found here

.

IMPORTANT CAVEAT

  ---------------------------------------------------------------
   As COLA has not yet published the official API for User Defined
   functions in GrADS v2.0 we have adopted here an API that is    
   based on our work with v1.9.0-rc1. This is a very low-level    
   API that is *not* endorsed by COLA. As such, it is *not*       
   advisable that users adopt this API to write their own         
   extensions.  Furthermore, the extensions as implemented here   
   are tied to a specific version of GrADS and should always be   
   built in the context a given GrADS source tree.                
   --------------------------------------------------------------
These extensions are still being fully tested and should be considered experimental at best. Please report any problem you encounter. Use them at your own risk.

List of User Defined Commands Included

  User
 Defined
 COMMAND           Short Description                Function@Library
 ---------- -----------------------------------  --------------------------
 gsudf      Initialize gs-function package       c_gsudf@^gsudf.gex
 printenv   Expand environment variables         c_xenv@^env.gex
 runenv     Expand env vars and run command      c_env@^env.gex
 @          Expand env vars and run command      c_env@^env.gex
 getenv     Get value of environment variable    c_getenv@^env.gex
 setenv     Set value of environment variable    c_setenv@^env.gex
 gxyat      Save images in PNG/SVG/PDF/PS        c_gxyat@^gxyat.gex
 hello      Hello, World! sample command         c_hello@^libhello.gex
 ipc_verb   IPC verbose toggle                   c_Verb@^libipc.gex
 ipc_open   Open stream for save/load            c_Open@^libipc.gex
 ipc_close  Close stream                         c_Close@^libipc.gex
 ipc_save   Save expression to stream            c_Save@^libipc.gex
 ipc_define Define variable (obsolete)           c_Define@^libipc.gex
 ipc_error  Print IPC error message              c_Error@^libipc.gex
 mfhilo     Find max/min or H/L in 2D field      c_mfhilo@^libmf.gex
 cylprms    Properties relative to lon/lat       c_cylprms@^libmf.gex
 shp_lines  Draw lines    from shapefile         c_lines@^shape.gex
 shp_polyf  Draw polygons from shapefile         c_polyf@^shape.gex
 ---------- -----------------------------------  --------------------------

List of User Defined Functions Included

  User
 Defined
 FUNCTION          Short Description                Function@Library
 ---------- -----------------------------------  --------------------------
 speed      Wind-speed (sample gs-function)      f_gsudf@^gsudf.gex
 lt         Less than operator                   f_bjt@^libbjt.gex
 jd         Julian day                           f_bjt@^libbjt.gex
 cosz       Cosine solar zenith angle            f_bjt@^libbjt.gex
 dayratio   Daylight ratio                       f_bjt@^libbjt.gex
 if         Conditional function                 f_bjt@^libbjt.gex
 maxv       Maximum value                        f_bjt@^libbjt.gex
 minv       Minimum value                        f_bjt@^libbjt.gex
 which      Label gridpoints                     f_bjt@^libbjt.gex
 ftest      F-test                               f_bjt@^libbjt.gex
 ttest      T-test                               f_bjt@^libbjt.gex
 tfit       Point  linear regression             f_bjt@^libbjt.gex
 fit        Global linear regression             f_bjt@^libbjt.gex
 tcorr2     Time correlation                     f_bjt@^libbjt.gex
 tregr2     Point linear regression              f_bjt@^libbjt.gex
 tmave2     Time averaging w/masking             f_bjt@^libbjt.gex
 madvu      Calculates -d(u*EXPR)/dx             f_bjt@^libbjt.gex
 madvv      Calculates -d(V*EXPR)/dy             f_bjt@^libbjt.gex
 madvw      Calculates -d(W*EXPR)/dp             f_bjt@^libbjt.gex
 muadv      Zonal advection                      f_bjt@^libbjt.gex
 mvadv      Meridional advection                 f_bjt@^libbjt.gex
 mwadv      Vertical advection                   f_bjt@^libbjt.gex
 satvap     Saturated vapor pressure             f_bjt@^libbjt.gex
 dew        Dew point temperature                f_bjt@^libbjt.gex
 lw         Thermal infrared fluxes              f_bjt@^libbjt.gex
 lw2        Thermal infrared fluxes v2           f_bjt@^libbjt.gex
 pinterp    Pressure interpolation               f_bjt@^libbjt.gex
 zinterp    Height interpolation                 f_bjt@^libbjt.gex
 line       Draws a line                         f_bjt@^libbjt.gex
 vint2      Mass-weighted vertical integral      f_bjt@^libbjt.gex
 fish       Poisson solver                       f_fish@^fish.gex
 fish_psi   Compute streamfunction               f_psichi@^fish.gex
 fish_chi   Compute velocity potential           f_psichi@^fish.gex
 fish_vor   Compute vorticity                    f_psichi@^fish.gex
 fish_div   Compute divergence                   f_psichi@^fish.gex
 hello      Hello, World! sample function        f_hello@^libhello.gex
 ipc_save   Save expression to stream            f_Save@^libipc.gex
 ipc_load   Load variable from file              f_Load@^libipc.gex
 smth2d     Shuman smoother/de-smoother          f_smth2d@^libmf.gex
 uv2trw     Find radial/tangential velocity      f_uv2trw@^libmf.gex
 re         General interpolator                 ffre@^re.gex
 sh_filt    Spherical harmonic filter            f_shfilt@^shfilt.gex
 sh_power   Spherical harmonic spectra           f_shpowr@^shfilt.gex
 ---------- -----------------------------------  --------------------------

 

Troubleshooting

  1. It says that Xming is starting up but the graphics window never comes up. Both GrADS and the Xming server uses the local network to talk to each other. If your Windows Firewall or anti-virus software is preventing programs from accessing the network you will not be able to see any graphics on the screen (although GrADS may function OK in batch mode). The solution is to reconfigure your firewall/antivirus software to allow Xming/GrADS to access the local network.
  2. I have a previous installation of X/Win32 GrADS and there is some kind of conflict involving the cygwin1.dll.   This a common problem and of simple solution. The easiest thing to do is to uninstall the previous version of GrADS. Or else, make sure that the directory where the previous version binaries reside is not on your path. There is a good chance (test it first) that the previous version of GrADS will work with the newer cygwin1.dll. In this case, remove or rename the older cygwin1.dll and see what happens.
  3. I am a regular cygwin user and the included cygwin.dllis conflicting with my cygwin installation. See the discussion above. If you have an older cygwin installation, you may want to update that first. If your cygwin installation is newer than the version shipped with GrADS, you may want to remove the cyg*.ddl files included in the OpenGrADS/win32/ directory and stick with the ones in your newer cygwin distribution. If all else fails, download the cygwin version of the supplibs and the GrADS sources and rebuild. See instructions in the OpenGrADS Wiki.

Getting Help

A list server is available for GrADS users to exchange information on problem solving, script refinements, user defined functions, etc. Messages typically contain requests for help and ideas for solutions from users who have faced similar problems. Reference is frequently made to upgrades to GrADS and how to obtain them. All posts to the listserver are automatically dispatched to all subscribed users. In order to keep out spammers and internet marketers, subscription is no longer automatic. Send an email to the address below giving your affiliation, electronic and postal addresses, phone, etc. and you will be added by the system administrator.

To join, send email to: gradsusr-request@list.cineca.it

Once subscribed, carefully read and archive the important information regarding the use of the listserver and how to send messages. When reporting bugs or problems, please include the following information in your post: 

  1. The version of GrADS you are running (it is a good idea to include all the output from 'q config') 
  2. The platform you are running GrADS on (e.g. SunOS, DEC Alpha, Windows95...) 
  3. A brief description of the problem 
  4. The simplest possible script that illustrates the problem 
  5. The error messages from GrADS 
  6. The output from running "ncdump -c" on your NetCDF file if you're having trouble getting GrADS to read the file. 

If nobody responds to your post, it may be because you didn't provide enough information. In order to get the answers you want from the GrADS community, you have to ask the questions in the right way. Of course, it may also be the simple case that nobody has an answer.If a week has gone by and there is still no reply, try reposting again, making sure that you've included all the items from the list above, and noting that it is your 2nd request.

 

To unsubscribe, send an email containing the message "SIGNOFF GRADSUSR" to listserv@list.cineca.it 

Credits

This Win32 port was contributed by Arlindo da Silva (dasilva@opengrads.org). Win32 GrADS is built with the Cygwin tools and the X Client Libraries provided by Cygwin/X Project. The Xming server is developed and maintained by Collin Harrison.

 

Mike Fiorino provided invaluable help during the initial phase of this port. Don Hooper helped porting the SDF interface; Steve Emmerson provided guidance with UDUNITS. Brian Doty tested some of the grads widget features. Many thanks to all.  

 

GrADS License Terms

The Grid Analysis and Display System (GrADS) Version 2.0

Copyright (C) 1988-2009 by Brian Doty and the Institute of Global Environment and Society (IGES). 

 

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; using version 2 of the License.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA. See file COPYRIGHT for additional information.