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:– cd /usr/local– gunzip ncl-4.2.0.Solaris2.7_sun4.tar.gz

Untar:– 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– http://ngwww.ucar.edu/ncl-talk/– Email list devoted to NCL discussion– Read by NCL developers and support staff

Examples page– 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 32bits +/- ( 1.175494e-38 ) to (1.701411e+38)long 32bits +/- ( 2.147483e+09 ) (64bit on SGI)integer 32bits +/- ( 2.147483e+09 )short 16bits +/- ( 32767 ) byte 8bits ( 0 ) - ( 255 )

Non-numeric Typesstring

charactergraphicfile 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 left-

hand-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 objectLinux 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 routinesfcode::arcln(n,x,y)