This page describes Ferret's External Functions (EF) framework available in Ferret v5.0.

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.

(Note: Those who wrote external functions for Ferret v4.91 will need to make small changes to their code, mainly in the utility function calls, and recompile in order to have their external functions work with Ferret v5.0 and later. Also note that starting with Ferret v5.2 there is no need for the utility functions object files, ef_utility/*.o These are now in the Ferret executable and you may safely delete them.)

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_1.3.tar.Z file below.

NOTES:

1. Under Linux, Ferret has been compiled with the g77 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.

2. Under SGI Irix 6.x, Ferret has been compiled with Fortran 90. External functions must be compiled with the same compiler so that shared object linking will work.

INSTALLATION:

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

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:

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.


3. Download EF_1.3.tar.Z from below. Put it in your external functions source code directory (/home/mymachine/mydirectory/external_functions) and uncompress and untar it.


4. Modify the Makefiles in examples/ 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) *a note on DEC OSF compiles.


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

Source code for example external functions: EF_1.3 (tar file contents, for browsing)

EF_1.3.tar.Z More Examples:

Externally linked: The functions that we distribute as externally linked functions are included in the Ferret Environment tar file from the Ferret Downloads page. 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 make useful examples also, and so are included in the following tar file. A Makefile is not included here; the names of any functions and subroutines you wish to compile will need to be added to your external functions Makefile as shown in the previous examples/ and fft_sample/ directories.

Note that the following functions and the subroutines in the subs/ directory are already statically linked into Ferret. 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 samplexy.F, you should rename it to (say) my_xy.F and change subroutines samplexy_init, samplexy_result_limits, samplexy_work_size, and samplexy_compute to myxy_init, myxy_result_limits, smyxy_work_size, and myxy_compute.

internal_EF_code (tar file contents, for browsing. The "subs" directory contains subroutines called by the functions)
internal_EF_code.tar.Z

Using External Functions written in Fortran90 with Ferret

Glenn Carver of the Centre for atmospheric Science, University of Cambridge, UK has generously shared a note on using Fortran90 code in External functions.

Compiling External Functions under Linux with Nag Fortran 95

Brent McDaniel of the Department of Earth and Atmospheric Sciences, Georgia Tech has contributed a note on using Fortran90 code and the Nag f95 compiler to compile External functions under Linux.

EF Contributions

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.

As with all Ferret software, these functions are provided as-is, with no implied warranty. Please read the disclaimer for Ferret software.

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.

writev5d_SuSE_linux.so This is the external function writev5d, compiled for SuSE linux. It corrects the byte-swapping of the Vis5D files that are written. You should put it in your FER_EXTERNAL_FUNCTIONS directory and change its name to writev5d.so.

---

US Department of Commerce NOAA OAR PMEL Contacts Privacy Policy Disclaimer Web Usage Statistics