|
|
External Functions (v1.3)
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:
-
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
-
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.
-
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.
-
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) *a
note on DEC OSF compiles.
-
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/
-
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.
oar.pmel.contact_ferret@noaa.gov
