Using IRBEM with MATLAB: Setup, Wrappers, and Examples

MATLAB accesses the IRBEM Fortran library through a shared library file (.so on Unix, .dll on Windows) together with a C-style header file (.h) that declares every subroutine in C calling syntax. MATLAB’s built-in loadlibrary / calllib mechanism (often called a “mex file” interface) bridges the two. For historical reasons, every MATLAB wrapper file and function name in IRBEM carries the prefix onera_desp_lib_ rather than irbem_.

Installation

The MATLAB installation instructions below are outdated and are preserved for reference only. The pre-built DLL download links point to the old SourceForge repository. For current builds, compile the shared library from source using the IRBEM Makefile (see the “Everyone else” tab below) and then add the resulting matlab/ folder to your MATLAB path.

Windows 32-bit
Windows 64-bit
Linux / macOS (from source)

Create the top-level folder

Manually create a folder named irbem (for example C:\irbem).

Download and unpack the MATLAB wrappers

Download the matlab folder tarball and untar its contents into irbem\matlab.

Download and unpack the data files

Download the data folder tarball and untar its contents into irbem\data.

Add paths in MATLAB

Open MATLAB, go to File → Set Path, add irbem\matlab and irbem\data, then click Save.

Place the 32-bit DLL

Download the 32-bit Windows DLL and save it as irbem\matlab\onera_desp_lib.dll.

Follow the 32-bit steps first

Complete every step from the 32-bit instructions, but download the 64-bit Windows DLL instead and save it as irbem\matlab\onera_desp_lib.dll.

Install Microsoft Visual Studio redistributables

Install the latest free Microsoft Visual Studio including its “redistributable” DLLs. MATLAB requires a compatible compiler to load any DLL on 64-bit Windows.

Add Cygwin64 runtime DLLs

Copy the following DLLs into the same irbem\matlab folder. Most are part of cygwin64 but can sometimes be found independently:

libgcc_s_seh-1.dll
libgfortran-3.dll
libquadmath-0.dll
libgsl-0.dll (only needed for optional extras)
libgcc_s_sjlj-1.dll (only needed for optional extras)
libgslcblas-0.dll (only needed for optional extras)
IEShims.dll (usually in C:\Program Files\Internet Explorer; copy it)

Build the shared library

The IRBEM Makefile creates a shared library named onera_desp_lib.so (Unix) or onera_desp_lib.dll (Windows) and copies it into the matlab/ subdirectory automatically.

# From the IRBEM root
make all

Add the MATLAB and data folders to the path

After building, add both matlab/ and data/ to the MATLAB search path. The addpath command works for the current session; combine it with savepath to make the change permanent:

addpath C:\irbem\matlab C:\irbem\data
savepath

Alternatively use the GUI path manager: File → Set Path → Add Folder.

Adding the data/ directory to the MATLAB path allows the library to locate the geomagnetic data files it needs at runtime without requiring an explicit path argument.

MATLAB usage patterns

The MATLAB wrappers are designed to feel like native MATLAB functions:

Auto-loading — each .m wrapper checks whether the shared library is already loaded, and if not, loads it from the default location (anywhere on the MATLAB path) automatically.
Vectorised inputs — although the underlying Fortran library limits array sizes, the wrappers split large input arrays into multiple library calls and stitch the results together transparently.
Scalar expansion — when an array of inputs is expected, scalar arguments are automatically expanded with repmat to match the size of the other inputs.
Keyword arguments — integer codes for kext, options, sysaxes, and other enum-style parameters can be replaced with human-readable strings (see below).
Date numbers — all date/time arguments use MATLAB’s datenum format. Use datenum(...) to construct them.
Inline help — every .m file includes a full MATLAB-style help block; run help <function_name> from the MATLAB command window to see parameter descriptions and examples.

Helper functions

The library ships several utility functions that convert human-readable inputs into the integer constants expected by the Fortran library.

% Build the 17-element maginputs array for field model driving parameters.
% Unused parameters should be set to 0; IRBEM interprets 0 as "not provided".
maginput = onera_desp_lib_maginputs( ...
    Kp, Dst, Nsw, Vsw, Psw, ByGSM, BzGSM, ...
    G1, G2, G3, ...
    W1, W2, W3, W4, W5, W6, ...
    AL);

Keyword arguments for kext and sysaxes

In most wrapper functions you can pass either the integer code or the string keyword shown in the table. The onera_desp_lib_kext and onera_desp_lib_sysaxes converters implement these look-up tables internally.

`kext` integer	String keyword	Model
0	`'None'`	No external field
1	`'MF75'`	Mead–Fairfield 1975
4	`'T89'`	Tsyganenko 1989
5	`'OPQ77'`	Olson–Pfitzer Quiet 1977
7	`'T96'`	Tsyganenko 1996
9	`'T01'`	Tsyganenko 2001

`sysaxes` integer	String keyword	Coordinate system
0	`'GDZ'`	Geodetic: altitude (km), latitude (°), East longitude (°)
1	`'GEO'`	Geographic Cartesian (Re)
2	`'GSM'`	Geocentric Solar Magnetospheric (Re)
3	`'GSE'`	Geocentric Solar Ecliptic (Re)
4	`'SM'`	Solar Magnetic (Re)
5	`'GEI'`	Geocentric Equatorial Inertial (Re)
6	`'MAG'`	Geomagnetic (Re)

Example: calling `make_lstar`

The example below computes magnetic coordinates for a single spacecraft position over Tromsø, Norway.

% Build the date/time as a MATLAB datenum
matlabd = datenum('2015-02-02 06:12:43', 'yyyy-mm-dd HH:MM:SS');

% Choose the external field model and options
kext    = 'OPQ77';         % Olson-Pfitzer Quiet — string keyword
options = [1 0 0 0 0];    % options(1)=1 enables L* computation
sysaxes = 'GDZ';           % input coordinates: altitude, latitude, longitude

% Spacecraft position: 651 km altitude, 63° lat, 20° lon
x1 = 651;   % altitude, km
x2 = 63;    % geodetic latitude, deg
x3 = 20;    % East longitude, deg

% Construct the maginputs array (Kp=4.0 → Kp*10=40; all others zero)
maginput = onera_desp_lib_maginputs(40, 0, 0, 0, 0, 0, 0, ...
                                     0, 0, 0, 0, 0, 0, 0, 0, 0, 0);

% Call the wrapper
[Lm, Lstar, Blocal, Bmin, J, MLT] = onera_desp_lib_make_lstar( ...
    kext, options, sysaxes, matlabd, x1, x2, x3, maginput);

% Display results
fprintf('Lstar  = %.4f\n', Lstar);
fprintf('Lm     = %.4f\n', Lm);
fprintf('MLT    = %.2f h\n', MLT);
fprintf('Blocal = %.2f nT\n', Blocal);
fprintf('Bmin   = %.2f nT\n', Bmin);
fprintf('J      = %.4f\n', J);

The onera_desp_lib_make_lstar wrapper accepts arrays for matlabd, x1, x2, and x3. Pass column vectors of equal length to compute magnetic coordinates for multiple spacecraft positions in a single call.

Note on `fly_in_afrl_crres`

The wrapper function fly_in_afrl_crres requires a set of text data files, most notably crrespro_quiet.txt. If the path to these files is not supplied explicitly, the wrapper searches for crrespro_quiet.txt in the MATLAB search path. Add the IRBEM data/ directory to the path (as described in the installation section) to ensure the file is found automatically.

Getting Started

Language Interfaces

Concepts

Using IRBEM with MATLAB: Setup, Wrappers, and Examples

Installation

MATLAB usage patterns

Helper functions

Keyword arguments for kext and sysaxes

Example: calling `make_lstar`

Note on `fly_in_afrl_crres`

Build docs developers (and LLMs) love

Getting Started

Language Interfaces

Concepts

Documentation Index

​Installation

​MATLAB usage patterns

​Helper functions

​Keyword arguments for kext and sysaxes

​Example: calling make_lstar

​Note on fly_in_afrl_crres

Build docs developers (and LLMs) love

Installation

MATLAB usage patterns

Helper functions

Keyword arguments for kext and sysaxes

Example: calling `make_lstar`

Note on `fly_in_afrl_crres`