The NCAR Command Language
(NCL)
Ethan Alpert
Visualization and
Enabling Technologies
Section, SCD, NCAR
What is NCL?

NCL is an interpreted programming language
–
–
–
–
Array based algebraic operators
Unique netCDF data model
Traditional programming language constructs
Wide variety of graphics capabilities:



Maps, Contours, XY, Vectors, Streamlines, labelbars, text,
tickmarks as well as line, marker and polygon primatives
Output to X, NCGM, PostScript
Scripts available to convert to image formats
What is NCL?


NCL is available on most UNIX platforms
NCL can run in batch or interactive mode
–


Interactive mode has command history and
command line editing
Many useful functions and procedures
Code integration tool (ability to import
FORTRAN)
Why use NCL?






Capable data processing environment with many
useful functions
Strong and easy to use file I/O capability
Useful for the development and integration of
FORTRAN processing routines
Robust publication quality 2D graphics w/ detailed
maps
Mature product
Free!
Downloading NCL

Go to:
–



http://ngwww.ucar.edu/ncl/download
Read and agree to GPL license
Fill out short registration form
Download binaries
–
Precompiled versions exist for:

IBM RS6000, DEC Alpha, Sun Solaris, Red Hat Linux and
SGI IRIX
Installing NCL

Uncompress tar file in installation directory:
–
–

Untar:
–

cd /usr/local
gunzip ncl-4.2.0.Solaris2.7_sun4.tar.gz
tar –xvf ncl-4.2.0.Solaris2.7_sun4.tar
Set NCARG_ROOT environment variable:
–
–
setenv NCARG_ROOT /usr/local/
set path = ( /usr/local/bin $PATH)
Important resources for using and
learning NCL

Main NCL home page:
–

http://ngwww.ucar.edu/ncl
Contains links to documentation, examples,
FAQ, ncl-talk email list, and update information
Reference Documentation

Main reference documentation
–
–
–
–
–
–
–

http://ngwww.ucar.edu/ngdoc/ng/ref/ncl/Overview.html
All syntax and statements defined
Links to all procedures and functions
Basic overview of graphics
Usage tips
Information on importing FORTRAN
Information on supported data formats
Function and Procedure Reference
–
http://ngwww.ucar.edu/ngdoc/ng/ref/ncl/NclFuncsAndProcs.html
Getting Started Using NCL (GSUN)

Getting Started Using NCL (GSUN)
–
–
–
–
–
–
–
http://ngwww.ucar.edu/ngdoc/ng/ug/ncl/gsun/
Intended for users with little or no NCL experience
Some programming language knowledge is assumed
Learning by example concept
Starts with basics and builds from there
Provides a set of simple functions written in NCL to be used by
new users instead of NCL’s object oriented Graphics interface
The “Beyond the Basics” section covers incorporating
FORTRAN into NCL
Additional resources for using and
learning NCL

NCL users email list
–
–
–

Examples page
–

http://ngwww.ucar.edu/ncl-talk/
Email list devoted to NCL discussion
Read by NCL developers and support staff
http://ngwww.ucar.edu/ncl/examples.html
CCSM NCL page for additional examples
–
http://www.cgd.ucar.edu/csm/support
Graphics Reference Documentation

The High Level Utilities Reference Guide
–
–
–
–
http://ngwww.ucar.edu/ngdoc/ng/ref/hlu/HluClasses.html
Only for users wishing to design their own custom
visualization or for whom the default GSUN or WRF
example are inadequate
NCL reference pages provide brief usage description
GSUN “Beyond the Basics” section covers use as well
Data Types


Numeric Types
double
64bits
+/- ( 2.22507e-308 ) to (8.98846e+307)
float
long
integer
short
byte
32bits
32bits
32bits
16bits
8bits
+/- ( 1.175494e-38 ) to (1.701411e+38)
+/- ( 2.147483e+09 ) (64bit on SGI)
+/- ( 2.147483e+09 )
+/- ( 32767 )
( 0 ) - ( 255 )
Non-numeric Types
string
character
graphic
file
logical
Variables

Based on the netCDF data model
–
–

Values, dimensions
Optionally: attributes, coordinate info (meta-data)
4 types of variables
–
–
–
–
Regular variables (in memory)
File variables (reference files)
Graphic variables (reference plots)
Lists (containers for one or more of the above
variable types)
Attributes

Descriptive info about a variable or file
–

Any data type but “file” and “list” data types; 1D req.
Assigned and referenced using “@” character
–
–
T@long_name = “temperature”
T@_FillValue = -999.0
Dimensions

Dimensions may be “named”
–

Provides an alternative way to reference subscripts
Assigned with “!” character
–
Example
T!0 = “time”
T!1 = “lat”
T!2 = “lon”
–
Allows for dimension reordering
T(lon|:,lat|:,time|:)
–
Used to assign coordinate variables
Coordinate Variables

Allow for more intuitive selection
–
–
–
–
T({12},{35:45},{-95:-105})
1D arrays; monotonically increasing or decreasing
Can only be assigned to a named dimension
Assigned using “&” character
T&time = (/0,6,12,18,24/)
Reading data from files

For netCDF, HDF, GRIB
–
Use addfiles function
A= addfile(“tmp.nc”,”r”)
K = A->variable

For fortran binary files
–

fbindirread, fbinread
For text
–
asciiread
Algebraic Operations



Array based algebra
Standard operators: -, ^, *, /, %, +
Unique operators: %, #, <, >
Logical operators: .eq., .ne., .le., .gt., .ge., .lt.,
.and., .xor., .or., .not.
Dimensionality of operands must either match or be
scalar
Missing values are filtered out by identifying missing
value with _FillValue attribute
Statements

if - Requires a single scalar logical value (i.e. True or
False)
–
multi-dimensional logical values must be reduce to single True
or False value



any - returns True if any of the input values are true
all - returns True if all of the input values are true (excluding
missing values)
do - Do statements very similar to F77
do var = startval, endval [, stride]
...
end do
do while(expression)
...
end do
Statements

assignment (=)
–
–
–
If left-hand-side undefined right-hand-side assigned to lefthand-side symbol
All dimension names, coordinate variables, and attributes
copied or overwritten to left-hand-side
UNLESS right-hand-side enclosed in (/ ... /)
Example:
a=b
; dimensions, attributes, and coordinate
; variables as well as value copied
a = (/b/) ; only value of b is copied
–
If left-hand-side is defined data types must match as well as
dimensionality
Functions and procedures


Parameters are “pass by reference”
Support for definitions of NCL source based
functions and procedures
Example:
function myfunc(x,y[*][*]:numeric)
begin
…
end
Incorporating FORTRAN codes

Create FORTRAN stub text file or add
comments to existing FORTRAN codes
C NCLFORTSTART
FUNCTION ARCLN(NUMPNT, POINTX, POINTY)
DIMENSION POINTX(NUMPNT), POINTY(NUMPNT)
C NCLEND

Call wrapit77
wrapit77 < wrapper_input >! wrapper_W.c
Incorporating FORTRAN codes


Compile FORTRAN and C wrapper to create .o
files
Link object files to create shared object
Linux Example:
nhlcc -c fcode_W.c
nhlf77 -c fcode.f
ld -shared -o fcode.so fcode_W.o fcode.o
Loading and Calling FORTRAN
shared objects

Use external command
Syntax:
external fcode “path to shared object”

Calling FORTRAN routines
fcode::arcln(n,x,y)