The NCAR Command Language (NCL)

1
The NCAR Command Language (NCL)

• Ethan Alpert
• Visualization and Enabling Technologies Section,
  SCD, NCAR

2
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

3
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)

4
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!

5
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

6
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)

7
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

8
Reference Documentation

• Main reference documentation
• http//ngwww.ucar.edu/ngdoc/ng/ref/ncl/Overview.ht
  ml
• 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/NclFuncsAnd
  Procs.html

9
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 NCLs object
  oriented Graphics interface
• The Beyond the Basics section covers
  incorporating FORTRAN into NCL

10
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

11
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

12
Data Types

• Numeric Types
• double 64bits /- ( 2.22507e-308 ) to
  (8.98846e307)
• float 32bits /- ( 1.175494e-38 ) to
  (1.701411e38)
• long 32bits /- ( 2.147483e09 ) (64bit on
  SGI)
• integer 32bits /- ( 2.147483e09 )
• short 16bits /- ( 32767 )
• byte 8bits ( 0 ) - ( 255 )
• Non-numeric Types
• string
• character
• graphic
• file
• logical

13
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)

14
Attributes

• Descriptive info about a variable or file
• Any data type but file and list data types
  1D req.
• Assigned and referenced using _at_ character
• T_at_long_name temperature
• T_at__FillValue -999.0

15
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

16
Coordinate Variables

• Allow for more intuitive selection
• T(12,3545,-95-105)
• 1D arrays monotonically increasing or decreasing
• Can only be assigned to a named dimension
• Assigned using character
• Ttime (/0,6,12,18,24/)

17
Reading data from files

• For netCDF, HDF, GRIB
• Use addfiles function
• A addfile(tmp.nc,r)
• K A-gtvariable
• For fortran binary files
• fbindirread, fbinread
• For text
• asciiread

18
Algebraic Operations

• Array based algebra
• Standard operators -, , , /, ,
• Unique operators , , lt, gt
• 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

19
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

20
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

21
Functions and procedures

• Parameters are pass by reference
• Support for definitions of NCL source based
  functions and procedures
• Example
• function myfunc(x,ynumeric)
• begin
• end

22
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 lt wrapper_input gt! wrapper_W.c

23
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

24
Loading and Calling FORTRAN shared objects

• Use external command
• Syntax
• external fcode path to shared object
• Calling FORTRAN routines
• fcodearcln(n,x,y)