How to write Ferret External Functions
This page describes Ferret's External Functions (EF) framework.
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 the Ferret Users Guide.
The install or upgrade procedure for Ferret 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 External Functions included with the Ferret distribution 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.
1. Under Linux, Ferret has been 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.
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.
The installation steps for your local External Functions directory are as follows:
Create a directory for your external functions source code. This will contain
subdirectories with the code for different "families" of external functions:
fft_sample/, and others you write. For example, you might create /home/mymachine/mydirectory/external_functions
- 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:
- Download external_functions_examples from below. Put it in your external functions source code directory (/home/mymachine/mydirectory/external_functions) and uncompress and untar it.
- 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.
- 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).
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.
- 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/
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.
- Source code for example external functions:
- external_functions_examples.tar.gz (tar file contents, for browsing)
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
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/
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.
Also, when they are linked internally, the INCLUDE statements change. To create external functions based on these functions you will need to change all instances of
INCLUDE 'EF_Util.cmn' to INCLUDE 'ferret_cmn/EF_Util.cmn', and
INCLUDE 'EF_mem_subsc.cmn' to INCLUDE 'ferret_cmn/EF_mem_subsc.cmn'
internal_EF_code.tar.gz Note that the directory includes a Makefile and
Using External Functions written in Fortran90 with FerretGlenn 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 95Brent 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 ContributionsWe 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.