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.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

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 NCL’s 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.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 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 “@” character • T@long_name = “temperature” • T@_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},{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/)

17. 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

18. 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

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,y[*][*]:numeric) 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 < wrapper_input >! 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 fcode::arcln(n,x,y)