
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)
orexport 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)
orexport 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.nclIf you don't have an NCL script to run, and you would like to run a sample one, then type:
ng4ex gsun01nThis 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.