Chapter 9: COMPUTING ENVIRONMENT

Ch9 Sec1. SETTING UP AN ACCOUNT

This discussion assumes that Ferret is already installed on your system. Installation documentation is available separately from the Ferret Downloads web page

STEP 1

Execute interactively or add to your .login file the Unix C-shell command

% source /usr/local/ferret_paths

(Note: If this command doesn't work consult your system manager, who may have placed ferret_paths in a different directory.)

The Ferret program requires access to several files and directories. These Unix paths are stored in environment variables defined by the file "ferret_paths". Your Unix account must  be "made aware" of where the Ferret utilities are located. This is done by adding to the definition of your environment variable PATH the directory "$FER_DIR/bin". Unless your system manager has modified the typical setup, this will occur automatically when you execute the above command.

STEP 2 (personal customization—optional)

Execute the "cp" command below:

% cp $FER_DIR/bin/my_ferret_paths_template \

     $HOME/my_ferret_paths

Then use a text editor to customize my_ferret_paths. Instructions are inside the file.

Some of the Ferret environment variables identify files and directories that are integral to the Ferret program, but others identify files that you may maintain—your data files, GO scripts, and palette files, for example. (The environment variables that you may want to customize are discussed at the end of this section.) To assist in customizing the Ferret environment variables the template file in the "cp" command, above, has been provided. The file is self-explanatory.

STEP 3

Execute the command below interactively or add it to your .login file.

% setenv DISPLAY node:0.0    e.g.,  % setenv DISPLAY anorak:0.0

This command sets the environment variable "DISPLAY" to point to the workstation console or X-terminal where you want Ferret graphical output displayed. In the example above, graphical output is directed to the screen of workstation "anorak."

Ch9 Sec2. FILES AND ENVIRONMENT VARIABLES USED BY FERRET

.ferret—the Ferret initialization file. This optional file holds a list of Ferret commands that will be executed immediately each time Ferret is started, permitting Ferret to be tailored to individual needs and styles. The file must be located in your $HOME (login) directory. A simple way to set up such a file is to enter Ferret, enter the commands that you want executed each time you enter Ferret, exit Ferret and rename the file "ferret.jnl" to ".ferret". Thereafter, all commands in ".ferret" will be executed automatically whenever you enter Ferret.

The following environment variables are defined in the file  ferret_paths:

FER_DATA—a list of directories to be searched to locate data files. Usually this list includes ".", the current directory, and $FER_DSETS/data, a directory of sample data sets provided with Ferret. Your system manager may have set this variable to include other data areas as well. This is the list of directories searched to locate NetCDF files.

FER_DESCR—a list of directories to be searched to locate descriptor files. Descriptors are required by Ferret to access data sets that are in Ferret's "GT" (grids at timesteps) or "TS" (time series) formats. Usually this list includes ".", the current directory, and $FER_DSETS/descr, a directory of sample descriptors provided with Ferret.

FER_GRIDS—a list of directories to be searched to locate grid definition files. Data sets will usually have a grid definition file associated with them so that the grids on which the data are defined may be known.

FER_DIR—top directory of the Ferret distribution on your system.

FER_DSETS—directory of sample data sets provided with the Ferret distribution.

FER_PALETTE—a list of directories to be searched to locate palette files. Usually this list includes "." and $FER_DIR/ppl.

FER_GO—a list of directories to be searched to locate GO scripts. This list usually includes ".", $FER_DIR/go, $FER_DIR/examples (demonstrations and tutorial), and $FER_DIR/contrib (user contributions demonstrating various applications; accuracy not guaranteed).

FER_EXTERNAL_FUNCTIONS—a list of directories to be searched to locate the shared object files (.so files) for external functions. By default this list includes the location of the example functions and the functions included with the Ferret distribution.

Ch9 Sec3. MEMORY USE

Ferret indicates memory problems by issuing the error message "insufficient memory."  If memory is a problem running Ferret the following suggestions may help:

1)    Use the command SET MEMORY/SIZE=nnn to increase the memory cache region available to Ferret.

2)    Use the command SET MODE DESPERATE to determine the threshold size of memory objects at which Ferret will break a large calculation into fragments. A smaller argument value will induce stricter memory management but at a penalty in performance.

3)    Use CANCEL MEMORY whenever you are sure that the data referenced thus far by Ferret will not be referenced again. This is particularly appropriate to batch procedures that use Ferret. This eliminates any memory fragmentation that may be left by previous commands.

4)    Use CANCEL MODE SEGMENTS to minimize the memory usage by graphics  (on a  few X-window systems this may prevent windows from being restored after they are obscured).

5)    When using DEFINE VARIABLE (alias LET) avoid embedding upper and lower axis bounds within the variable definition. Ferret cannot split up large calculations along axes when the limits are fixed in the definition. For example,

yes? LET V2=TEMP/10
yes? PLOT/K=1:10 V2

is preferable to

yes? LET V2=TEMP[K=1:10]/10
yes? PLOT V2

6)    Try to group together calculations that are on smaller dimensioned objects. For example, the expression VAR[i=1:100, j=1:100]*2*PI will make less efficient use of cpu and memory than the expression VAR[i=1:100, j=1:100]*(2*PI). The former multiplies each of the 10000 points of VAR by 2 and then performs a second multiplication of the 10000 result points by PI. The latter computes the scalar 2*PI and uses it only once in multiplying the 10000 points of VAR.

7)    If one has SET MODE STUPID:weak_cache, then make sure that the region is fully defined (i.e., check SHOW REGION and check the region qualifiers of your command). When the region along some axis is not specified Ferret defaults to the full span of the data along that axis and is unable to optimize memory usage.

Ch9 Sec4. HARD COPY AND METAFILE TRANSLATION

Ch9 Sec4.1. Hard copy

To obtain hard copy of plots produced by Ferret, follow these steps:

1)    Within Ferret, enter the command

yes? SET MODE METAFILE

This tells Ferret to generate a graphic metafile (ANSI/ISO GKSM format) for each plot created thereafter. To stop making the metafiles type

yes? CANCEL MODE METAFILE

2)    Produce each plot as you would normally. Each new plot on your screen generates an additional file named "metafile.plt.~n~" where "n" will be incremented for each metafile. Overlay commands do not produce additional metafiles. (The metafile name may be set by the SET MODE METAFILE command.)

3)    After exiting from Ferret use the command Fprint.

Note: If it is necessary to use Fprint without exiting Ferret, then issue the command yes? PPL CLSPLT. This will close the current metafile. Note that neither overlays nor additional viewports can be added to the plot after the metafile has been closed.

Fprint is a script which translates metafiles generated by Ferret. It uses the program "gksm2ps" and is intended to simplify sending plots to printers, to an output file only, or to a workstation screen.

For monochrome printers the metafile translator, gskm2ps, uses different line styles (dash-dot patterns) rather than colors for different lines. See Appendix I of the Plotplus manual: Enhancements to Plotplus for a complete list of line styles for monochrome devices.

The Fprint script translates metafiles to Encapsulated PostScript or X-window output. Your system manager should customize the script at your site to permit your specification of the actual printers you have as output devices. Fprint uses standard Unix command line syntax.

Fprint [-h] [-P printer || -o file_name || -X]

        [-p orient] [-# n] [-l line] [-R] metafile(s)

Examples

% Fprint metafile.plt

renders "metafile.plt" on the default printer identified by the environment variable PRINTER.

% Fprint -P myprinter -R metafile.plt*

renders all versions of "metafile.plt" on printer myprinter. Does not date stamp them.

% Fprint -o my_plot.ps metafile.plt.~1~

writes plot "metafile.plt.~1~" to a postscript file named "my_plot.ps".

Ch9 Sec4.2. Metafile translation

The command "gksm2ps" allows you to control the translation of the device-independent metafiles made by Ferret into device-specific output files. "gksm2ps" was written by Larry Oolman at the University of Wyoming and modified at NOAA/PMEL for use with Ferret. The "gksm2ps" command uses standard Unix command line syntax. See usage hints provided by the -h option.

gksm2ps [-h] [-p landscape||portrait] [-l ps||cps] [-d cps||phaser] \

         [-X || -o <ps_output_file>] [-R] [-a] [-g WxH+X+Y] file(s)

If the user does not specify an output option (-o or -X) gksm2ps translates the metafile and produces a PostScript file called gksm2ps_output.ps. After translation by gksm2ps, metafiles  are renamed with a date stamp unless -R was specified. To get hard copy printed, the output PostScript file needs to be sent to the appropriate printer.

Ch9 Sec5. OUTPUT FILE NAMING

Ferret uses a file naming scheme to differentiate successive graphic metafiles and  journal files. The scheme is styled after the gnu (Free Software Foundation) emacs editor. The scheme appends numbers to the end of the file name as in the following examples:

Metafile.plt.~2~
metafile.plt.~12~
metafile.plt

The third example, "metafile.plt" with no suffix appended, is the most recent file. When the next successive file is created, this file will have the suffix ".~nnn~" appended to its name. "nnn" is the current highest file suffix number plus one.

Two Unix tools are provided to assist with managing multiple file suffix numbers:

See the introductory chapter, section "Unix tools," p. 24, for further information.

Ch9 Sec6. INPUT FILE NAMING

There are several Ferret commands that use filenames. These include:

GO filename
SET DATA filename
LIST/FILE=filename  (do not use relative versions (below) with LIST)
USER/FILE=filename
SET MODE META filename
SET MODE JOURNAL filename
SET MODE PPLLIST filename

The filename specified can be just the filename itself, or it can include the path to the file. For example:

    GO ferret.jnl         or         GO "/home/disk1/jnl_files/far_side.jnl"

Note that if the path is specified as part of the filename, the entire name must be enclosed in quotation marks.

Ch9 Sec6.1. Relative version numbers

Under some circumstances (see the GO command, p. 268) a special syntax called "relative version numbers" will apply. If a filename has a version value of zero or less its value is interpreted  relative to the current highest version number.

For example, if the current directory contains the files

ferret.jnl   ferret.jnl.~1~   ferret.jnl.~2~   ...  ferret.jnl.~99~   

then the filename ferret.jnl.~0~ refers to ferret.jnl and the filename ferret.jnl.~-1~ refers to ferret.jnl.~99~.

The syntax for relative version numbers is quite flexible. For example, if the desired file is ferret.jnl.~99~, both of the following are valid:

    yes? GO ferret.jnl.~-1~       or         yes? GO ferret.jnl~-1