= Usage of PALM NCL scripts =
[[TracNav(doc/app/ncltoc|nocollapse)]]
== General == 
The standard output format of data in PALM is [[../netcdf|netCDF]]. PALM produces output of 3D volume data, 2D cross sections, profiles, timeseries and spectra. All these kinds of output can be plotted with the ''NCAR Command Language'' [[http://www.ncl.ucar.edu/|NCL]] which is an interpreted language designed specifically for scientific data analysis and visualization.\\\\
For PALM users four NCL scripts and one configuration file exist in the repository [[source:palm/trunk/SCRIPTS/NCL|/trunk/SCRIPTS/NCL]] to receive a quick overview of the output data: 
* [[source:palm/trunk/SCRIPTS/NCL/cross_sections.ncl|cross_sections.ncl]]: contour, isoline or vector plots (of a 2-dimensional vector) from 2D or 3D data; instantaneous or time-averaged xy, xz, yz or 3D data can be used
* [[source:palm/trunk/SCRIPTS/NCL/profiles.ncl|profiles.ncl]]: profile line plots from profile or 3D data
* [[source:palm/trunk/SCRIPTS/NCL/spectra.ncl|spectra.ncl]]: NCL spectra plots from spectra data
* [[source:palm/trunk/SCRIPTS/NCL/timeseries.ncl|timeseries.ncl]]: line plots from timeseries data
* [[source:palm/trunk/SCRIPTS/NCL/.ncl.config.default|.ncl.config.default]]: default configuration file
The shell script [[source:palm/trunk/SCRIPTS/palmplot|palmplot]] is designed for running the NCL scripts interactively and can be found in [[source:palm/trunk/SCRIPTS|/trunk/SCRIPTS]]. The usage is as follows:
{{{
palmplot plot_identifier
}}}
{{{plot_identifier}}} has to be {{{xy}}}, {{{xz}}}, {{{yz}}}, {{{pr}}}, {{{sp}}} or {{{ts}}} in dependence on the data that is to be plotted:
||='''plot_identifier''' =||='''data ''' =||='''used ncl script''' =||
||xy  ||instantaneous or time-averaged xy or 3D data  ||{{{cross_sections.ncl}}}  ||
||xz  ||instantaneous or time-averaged xz or 3D data  ||{{{cross_sections.ncl}}}  ||
||yz  ||instantaneous or time-averaged yz or 3D data  ||{{{cross_sections.ncl}}}  ||
||pr  ||profile or 3D data  ||{{{profiles.ncl}}}  ||
||sp  ||spectra data  ||{{{spectra.ncl}}}  ||
||yz  ||timeseries data  ||{{{timeseries.ncl}}}  ||
Several [[../nclparlist|parameters]] can be steered to change the output of the plots. They can be either written in the prompt, modified within the configuration file {{{.ncl.config.default}}} or both. 
== Using {{{.ncl.config}}} == 
It is recommended to create a personal configuration file by copying the default configuration file {{{.ncl.config.default}}} to the PALM working directory {{{~/palm/current_version}}} and naming it {{{.ncl.config.}}} It is used by NCL directly. So, the [[../nclparlist|parameters]] have to be written in {{{.ncl.config}}} according to the rules of the scripting language NCL (see [[http://www.ncl.ucar.edu/Document/Manuals/Ref_Manual/NclDataTypes.shtml|NCL data types]]). The configuration file contains all steering [[../nclparlist|parameters]] with a short description and can be modified to personal needs.
== Using {{{palmplot}}} == 
For controlling the parameters within the prompt, they need to be written as 
{{{
palmplot plot_identifier parameter=value parameter=string
}}}
It is necessary to set the string parameters which can contain lists ([[../nclparlist/#var|var]], [[../nclparlist/#c_var_pr|c_var]], [[../nclparlist/#vec1_cs|vec1]], [[../nclparlist/#vec2_cs|vec2]], [[../nclparlist/#plotvec_cs|plotvec]]) in single quotes. The list itself has to be separated by blanks.\\
Example: {{{var='pt u w*pt* w”pt”'}}} or {{{c_var='v w'}}} or {{{var='E*'}}}\\\\
Setting of parameters in the configuration file {{{.ncl.config}}} will be ignored if parameters are specified in the prompt.\\\\
A short introduction for using the shell script is given by using 
{{{
palmplot -?  
}}}
== Examples ==
In the following some examples are given for plotting data of the PALM example run [[../examples|example_cbl]].\\
Change to the directory where the data is stored:
{{{
cd ~/palm/current_version/JOBS/example_cbl/OUTPUT
}}}
Enter the following commands:\\
Plotting xy-cross section data:
{{{
palmplot xy file_1=example_cbl_xy.nc var='pt_xy'
}}}
Plotting profile data:
{{{
palmplot pr file_1=example_cbl_pr.nc format_out=eps file_out=pr_data var='pt w”pt” w*2'
}}}
Plotting timeseries data:
{{{
palmplot ts file_1=example_cbl_ts.nc format_out=pdf file_out=ts_data no_rows=6
}}}
Plotting spectra data:
{{{
palmplot sp file_1=example_cbl_sp.nc no_rows=2 no_columns=2 height_level='(/0,1/)'
}}}
== Script crash ==
If one of the scripts aborts and there is no comment, check your personal configuration file {{{.ncl.config}}} - the scripts should not abort with the default values. Be sure to use the right NCL data type (e.g.: integer = 2; float = 2.0; double = 2.0d; string = “name” ).