Usage help page

This page is intended to provide helpful hints for using NCL efficiently and effectively. A general working knowledge of the NCL syntax is required for this page.

Supported file format differences

Each supported data format may have its own limitations with respect to operations provided by NCL. The user guide explains the difference (if any) between supported data formats. See the Importing and exporting data section of the user guide.

Use of Blocks

When writing scripts it can be very useful to enclose the script in a block. This forces NCL to scan the entire source of the script in before executing any of the commands nested in the block. This means any syntax errors will be reported before commands are executed. For example, by placing a begin and end around the following, the syntax error after the long loop is detected before the loop is executed.

begin
	tmp = new((/1000000/),float)
	do i = 0,999999
		tmp(i) = i
	end do
	asciiwrite("tmp.ascii",tmp(500000:)
end

Memory usage vs. Disk I/O

Disk I/O is usually much slower than memory accesses therefore it is recommended that searches or access to individual elements of arrays in files be reduced to improve performance. For example, the first script will run much faster than the second because the search variable is not read from disk on every iteration of the loop. The following file "sao.cdf" contains a two dimensional character array called "id" in which the three character station id's are store. The loops look for the index of a specific id.

First loop:

file1 = addfile("sao.cdf","r")
id = file1->id
do i = 0, dimsizes(id(:,0)) - 1
	if( id(i,:) .eq. "DEN")
		break
	end if
end do
print(i)

Second loop:

file1 = addfile("sao.cdf","r")
do i = 0, dimsizes(file1->id(:,0)) - 1
        if( file1->id(i,:) .eq. "DEN")
                break
        end if
end do
print(i)

Defining functions and procedures in scripts

Because functions and procedures can only be defined once and can not be deleted like variables, it is important not to put them in scripts that are intended to be run multiple times from the same invocation of NCL.

Array assignment

NCL's array assigment capability can greatly enhance efficiency in scripts whenever possible. Consider the following script to remove duplicate entries in a sorted array "x".

len = dimsizes(x)
do i = 0 , len - 2
	if((x(i) .eq. x(i+1)))
		do j = i , len - 2
			x(j) = x(j+1)
		end do
		len = len - 1
		i = i - 1      ;Must decriment i in case more than one duplicate
	end if
	if(i .ge. len - 2) 
		break
	end if
end do

The above NCL source can be written as follows

len = dimsizes(x)
do i = 0 , len - 2
        if((x(i) .eq. x(i+1)))
		x(i:len-2) = x(i+1:len-1)
                len = len - 1
                i = i - 1      ;Must decriment i in case more than one duplicate
        end if
        if(i .ge. len - 2)
                break
        end if
end do

If "x" is a very large array a tremendous about of memory allocations and frees can be saved, thus improving performance.

Do loop limitations

In NCL do loops currently have the limitation that once the do loop is initiated. The upper bound (the stopping point) can not be changed. The the following loop demonstrates this property. Since l is set to 10 when the loop starts, i will loop from 0 to 10 regardless of what l ends up being set to.

l = 10
do i = 0,l
	l = l - i
end do