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.

Information on setting up NCL on your system

How to download and install NCL.
How to set up your NCL environment on your system.
Using NCL in the cheyenne environment.
How to run NCL.

Information on learning NCL

NCL User Guide - this is an excellent beginner's guide to NCL language basics, with a step-by-step tutorial on writing NCL scripts for reading/writing files, doing computational analyses, and generating publication-quality graphics.
Mini-Language Reference Manual - description of the NCL language, file I/O, printing, data processing, command line options, and using external codes.
Hard-copy manuals you can download.
Reference cards you can print.
Information on data analysis.
Hundreds of example NCL scripts you can download and use.
Frequently asked questions

Where to get help and training

Email lists for NCL users.
Watch a series of webinars on a range of NCL topics.
Consider taking an NCL workshop or hosting one at your site.
Workshop PowerPoint slides are available for download.

How to set up your NCL environment

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

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

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.)
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
```
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. Usually this is set for you by your system.
You can test this by running an X application to see if it pops up on your screen. A good test X application is "xclock". At the UNIX command line, type:
```
    xclock
```
If clock pops 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 either your DISPLAY environment variable is not set correctly, or you are logging in remotely from another system using something like "ssh" and haven't turned on X11 fowarding, which you can do with "ssh -X" or "ssh -Y".
If you are still not sure what to do at this point, then subscribe to the "ncl-install" email list and email your question to ncl-install@ucar.edu.
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 may want to change the default color table and the default size of the X11 window.

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.