External Functions

How to write Ferret External Functions

This page describes Ferret's External Functions (EF) framework available in Ferret v6.8 and higher; double-precision 6-D Ferret, and PyFerret v7.0 and higher.

Within the External Functions framework, users can write their own Fortran routines to be called by Ferret. External functions are treated by Ferret in a manner nearly identical to Ferret's "internal" functions. The syntax for using external functions is exactly the same as for any other Ferret function.

The external functions are compiled individually to create shared object (.so) files and are dynamically linked to Ferret at run time. Ferret looks for shared object files in the directories specified in the FER_EXTERNAL_FUNCTIONS environment variable.

EF Documentation

Documentation for writing and using external functions is available in the chapter on External Functions in the Ferret Users Guide.

EF Downloads

The install or upgrade procedure for Ferret (Version 5.0 and after), installs all of the External Functions functionality. The environment variable FER_EXTERNAL_FUNCTIONS is defined and set to a directory where the shared object files for external functions reside (.so files). For the Ferret-installed External Functions this directory is set as follows:

setenv FER_EXTERNAL_FUNCTIONS "$FER_DIR/ext_func/libs"

You may wish to write your own external functions. All of the source code you need to get started (Makefiles, common files, simple examples) is located in the EF_double_precision.tar.gz file below.

NOTES:

1. Under Linux, Ferret is compiled with the gfortran Fortran compiler. External functions must be compiled with that same compiler so that the shared object linking will work. Some of our users have contributed documents about using Fortran 90 and Fortran 95 to compile external functions. See the links at the bottom of this page for these notes.

INSTALLATION:

The installation steps for your local External Functions directory are as follows:

setenv MY_LOCAL_EXTFCNS /home/mymachine/mydirectory/external_functions/my_ext_fcns
setenv FER_EXTERNAL_FUNCTIONS "$MY_LOCAL_EXTFCNS $FER_EXTERNAL_FUNCTIONS"

where you add your local external functions directory to the directory containing the Ferret-included functions.

  1. Create a directory for your external functions source code. This will contain subdirectories with the code for different "families" of external functions: examples/, fft_sample/, and others you write. For example, you might create /home/mymachine/mydirectory/external_functions
  2. Create a directory where external functions shared object files will reside (e.g. /home/mymachine/mydirectory/external_functions/my_ext_fcns); then set the environment variable FER_EXTERNAL_FUNCTIONS to this directory. For example in your .login file you could have the lines:
  3. Download EF_double_precision.tar.gz from below. Put it in your external functions source code directory (/home/mymachine/mydirectory/external_functions) and uncompress and untar it. Or go to the PyFerret or Ferret GitHub source repository, as described under "More Examples" below.
  4. Modify the Makefiles in examples/ , contributed/ and fft_sample/ so that "make install" puts the shared object files to your local external functions directory (i.e. copy the .so files to MY_LOCAL_EXTFCNS). When you create your own external functions, have their Makefiles also put the shared object files in your local external functions directory.
  5. In your top level external functions source code directory, make, then make install.* This will compile and install the functions in the examples/ and fft_sample/ directories (There are identical fft functions included with the Ferret installation but this directory is included here to show the use of external functions code in more than one directory, and as examples of more complex functions than the examples).

  6. Now when you run Ferret, yes? show function/external will list all the external functions, including those in your local external functions directory, and they are ready to use. It also lists the large number of functions originally written as external functions, which are linked internally into the Ferret executable.
  7. Use the chapter in the Users Guide on writing external functions to begin to write your own functions. Create external functions directories for your functions, each with a Makefile analygous to the ones in examples/ and fft_sample/

More Examples:

Externally linked: The functions that we distribute as externally linked functions are included in the Ferret Environment tar file from the PyFerret or Ferret gitHub release page (see Downloads). When you untar that file the code is in the ext_func/src directories.

Internally linked: Many functions that were originally written as external functions are now statically linked into the Ferret executable, to make them available to users on platforms where shared object files cannot be used. These also make useful examples. They are also in the Ferret Environment tar fileand will be unpacked into the ext_func/src directories when you install Ferret,. Or browse the code from thegithub.com/NOAA-PMEL/Ferret.git Ferret GitHub source repository, in the directories under the external_functions/ directory. You will need to modify the Makefiles as you did under the examples/ directory above.

Note that functions other than the ones in examples/ and contributed/ directories are statically linked into Ferret, along with the subroutines that they call. As internally-linked functions they take precedence over shared-object file external functions. If you wish to make your own version of any of these functions, you must change its name in order to run your own version. Change the name in all of the subroutines within the function, e.g. if you make a new function based on sampl

We look forward to your contributions to our external functions library. Please pass along your favorite External Functions so that we can run them through some consistency scripts and then post them here for others to use.

EF Contributions

  • sqrt.F returns the square root of one argument
  • chdir.F calls the chdir function to change directories
  • neutral.F Computes neutral density from salinity and temperature. It requires that you download a library of routines from the web.