Getting Started With NCL

This list is for people who are new to NCL and are not sure where to start first.

Note that NCL and NCAR Graphics are shipped as one package. The instructions below refer to NCL, but they apply for NCAR Graphics as well.


How to set up your NCL environment

Before you can use NCL, you must do four things:

  1. Set the NCARG_ROOT environment variable.
  2. Add $NCARG_ROOT/bin to your UNIX search path.
  3. Make sure your DISPLAY environment variable is set correctly.
  4. Put a .hluresfile file in your home directory.

  1. Set the NCARG_ROOT environment variable.
    Set the NCARG_ROOT environment variable to the root directory of where the NCL software is installed. For example, if NCL was installed to /usr/local/bin and /usr/local/lib, then NCARG_ROOT should be set to /usr/local.

    To set this environment variable, you must know what kind of UNIX shell environment you're running. Usually, typing:

         echo $SHELL
    
    on the UNIX command line will tell you this information. If it says something like "/bin/tcsh" or "/bin/csh", then you can set the environment variable as follows (using "/usr/local" as an example):
        setenv NCARG_ROOT /usr/local
    
    If it says "/bin/bash" or "/bin/ksh", then use:
        export NCARG_ROOT=/usr/local
    
    If it says "/bin/sh", then use these two lines:
        NCARG_ROOT=/usr/local
        export NCARG_ROOT
    
    To keep from having to type these commands in every time you login, it is best to add these lines (or line) to the appropriate ".*" file in your home directory. (The ~/.cshrc or ~/.bashrc are two examples; be sure to use the one appropriate for the shell environment you are running.)

  2. Add $NCARG_ROOT/bin to your search path.
    This is necessary so that when you run NCL, your system knows where to find the "ncl" executable.

    First, you need to find out where your current UNIX path is being set up. This is usually done in one of the ".*" files in your home directory. You can search for a path setting by typing:

        grep -i path ~/.*
    
    If you see something like one of these lines:
        set path=(~/bin /usr/bin /bin/etc /usr/X11R6/bin /usr/local/bin)
    
    or
        export PATH=~/bin:/usr/bin:/bin/etc:/usr/X11R6/bin:/usr/local/bin
    
    then you can edit this file, and add "$NCARG_ROOT/bin" to the list of paths:
        set path=(~/bin /usr/bin /bin/etc /usr/X11R6/bin /usr/local/bin $NCARG_ROOT/bin)
    
    or
        export PATH=~/bin:/usr/bin:/bin/etc:/usr/X11R6/bin:/usr/local/bin:$NCARG_ROOT/bin
    

  3. Set the DISPLAY environment variable.
    In order to run NCL scripts that display their output directly to an X11 window, you need to have your DISPLAY environment variable set correctly. You can usually test this right away by invoking an X application to see if it comes up correctly. A good test X application is "xeyes":
        xeyes
    
    If a pair of eyes pop up on your screen, then your DISPLAY environment variable is already being set correctly.

    If not, and you get an error message like:

         Error: Can't open display
    
    then you need to set your DISPLAY environment variable. The DISPLAY environment variable needs to be set to the IP address of the machine that you are displaying the X11 window on, and not the IP address of the machine that you are running NCL from. So, for example, if you are logged into a machine called "buffy.ucar.edu" (IP address 111.12.14.16) and running NCL from there, but displaying the graphics to a machine called "xander.ucar.edu" (IP address 111.12.15.17), then on window where you are logged into "buffy", type:
       setenv DISPLAY 111.12.15.17:0
    
    [See the instructions above for setting environment variables for different types of shells.]

    You may, additionally, from a window where you are logged onto "xander" need to type:

      xhost 111.12.14.16
    
    This tells the "xander" machine that it's okay to allow programs being run by "buffy" be displayed on its monitor.

    Again, as with the NCARG_ROOT environment variable above, you may want to add these lines to the appropriate ".*" files in your home directory.

    If the above doesn't work, then please check with your system administrator.

  4. Put a ".hluresfile" file in your home directory.
    In order to better customize the NCL graphical environment, we highly recommend that you copy a .hluresfile to your home directory. You can customize this file to your liking, but at a minimum, you want to change the default font, the default color table, and the text function code.

How to run NCL

Once your NCL environment has been correctly set up, you are ready to run NCL. If you already have an NCL script, say "omega.ncl", you can run it by typing:

    ncl omega.ncl
If you don't have an NCL script to run, and you would like to run a sample one, then type:
    ng4ex gsun01n
This should copy an NCL script called "gsun01n.ncl" to your current working directory and run NCL on it. Running this example requires that you have your DISPLAY environment variable set correctly.