We provide a set of Matlab wrappers for the IRBEM FORTRAN library through the use of a shared library file (.dll on windows, .so on Unix). Matlab refers to this type of interface as a "mex file". In addition to the shared library file, Matlab requires a C-style header file that includes the C-style calling syntax for each FORTRAN function. This .h file is provided with the IRBEM Matlab library. For historical reasons, the Matlab routines and files are prefixed with "onera_desp_lib" rather than "irbem".
Easy way for 32-bit windows users:
Sort of easy way for 64-bit windows users:
Hard way for everyone else:
The IRBEM make file (call make help from irbem/trunk) will create
the shared library file for use with IDL or Matlab. A copy of the shared library is
created in the "matlab" subdirectory, and is given a name "onera_desp_lib.dll" or
"onera_desp_lib.so" depending on the platform. Thus, in order to access the library
and the wrappers, the user needs only add the "matlab" subdirectory (e.g. "c:\irbem\matlab")
to the Matlab path. In order for the library to easily locate the data files that
it needs, it is also advisable to add the "data" subdirectory to the Matlab path.
Matlab provides a GUI interface to add folders to the search path from "Set Path"
entry on the "File" menu. It is also possible to add these two folders to the path
using the Matlab "addpath" command; however, this command does not make the change
to the path permanent, so that "addpath" will have to be issued once in each new Matlab
session. The "savepath" function can make the path change permanent, as can the GUI
path manager interface. Thus, one could use the following commands, if the IRBEM library
is located in "c:\irbem":
addpath c:\irbem\matlab c:\irbem\data
savepath
The Matlab wrappers are built to provide
Matlab-like function calls into the library. These wrappers handle loading the library
into Matlab's function space, formatting inputs and outputs for proper calls to the
library, and providing "vectorized" functionality wherever reasonable. Each wrapper
function will determine whether the FORTRAN library has been loaded, and, if not,
attempt to load it from the default location (anywhere in the Matlab path).
Each .m file provided includes a robust set of helps obtainable via help <funtion_name>
in the usual Matlab way. This help call will provide details of how to call the function.
Although the FORTRAN library often limits the size of arrays, the Matlab wrappers
typically handle arbitrarily large array inputs by splicing together multiple calls
to the library. Also, in many cases, when a set of arrays is expected as input, the
Matlab wrappers will accept scalars for some, which will be repeated (via Matlab's
repmat function) to be the same size as the other array arguments.
In many cases, the library requires integer inputs that represent different options,
e.g., kext=5 for the Olson-Pfitzer Quiet external field model. In most cases, the
Matlab wrapper supports string (keyword) inputs in place of the integer values. This
keyword approach is implemented for kext, options, sysaxes, and whichm, among others.
Whenever date/time arguments are required by the FORTRAN library, the Matlab library
expects Matlab Date Numbers (construct argument "matlabd" with Matlab's datenum function).
The FORTRAN library function fly_in_afrl_crres requires a set of text files. If the
path to these files is not specified, the wrapper will attempt to guess it by locating
one of these, 'crrespro_quiet.txt' in the Matlab search path.
When available from MATLAB a calling sequence is provided for each function (see detailled
description of each functions).
Helper functions that support the wrappers:
The following function creates the proper maginputs array for use with the field models.
maginputs = onera_desp_lib_maginputs(Kp,Dst,Nsw,Vsw,Psw,ByGSM,BzGSM,G1,G2,G3,W1,W2,W3,W4,W5,W6,AL);
The following funnction will load the shared library file from the non-default location.
onera_desp_lib_load(libfile,headerfile);
The following functions are used by the library to convert the Matlab wrapper inputs
into the inputs needed by the FORTRAN library. These include "as appropriate" the
look-up tables that convert keyword inputs into the integer constants used by the
FORTAN library.
kext = onera_desp_lib_kext(kext);
options = onera_desp_lib_options(inoptions);
sysaxes = onera_desp_lib_sysaxes(sysaxes) ;
[iyear,idoy,UT] = onera_desp_lib_matlabd2yds(matlabd);