Getting Started With NCLThis 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.
- Basic overview of the capabilities of NCL.
- How to download and install NCL.
- How to set up your NCL environment on your system.
- Setting up your environment to run NCL or NCAR Graphics on the NCAR supercomputers.
- How to run NCL.
- Mini-Language Reference Manual - description of the NCL language, file I/O, printing, data processing, command line options, and using external codes.
- Line-by-line description of NCL code for newbies.
- Frequently asked questions
- Hard-copy manuals you can download.
- Information on data analysis.
- Hundreds of example NCL scripts you can download and use.
- Email lists for NCL users.
- Consider taking an NCL workshop or hosting one at your site.
- Workshop PowerPoint slides are available for download.
- There's a series of simple-to-complex graphical exercises that are part of the workshop.
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 $SHELLon 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/localIf it says "/bin/bash" or "/bin/ksh", then use:
export NCARG_ROOT=/usr/localIf it says "/bin/sh", then use these two lines:
NCARG_ROOT=/usr/local export NCARG_ROOTTo 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/binthen 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
- 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":
xeyesIf 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 displaythen 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 184.108.40.206) and running NCL from there, but displaying the graphics to a machine called "xander.ucar.edu" (IP address 220.127.116.11), then on window where you are logged into "buffy", type:
setenv DISPLAY 18.104.22.168: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 22.214.171.124This 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.
- 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.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.