Personal tools
You are here: Home Documentation External Functions
Document Actions

External Functions

by ansley — last modified 2010-05-21 17:22

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.

EF Downloads

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.

NOTES:

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.

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:
  3. 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.

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

  5. 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.
  6.  
  7. 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).

  8.  
  9. 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.

  10.  
  11. 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:
external_functions_examples.tar.gz (tar file contents, for browsing)

external_functions_examples.tar.gz

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.

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

oar.pmel.contact_ferret@noaa.gov

Powered by Plone CMS, the Open Source Content Management System

This site conforms to the following standards: