Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/PRBEM/IRBEM/llms.txt

Use this file to discover all available pages before exploring further.

IDL accesses the IRBEM Fortran library through IDL’s built-in CALL_EXTERNAL function, which loads a shared library (.so on Linux/Unix, .dll on Windows) and invokes a named symbol directly. No intermediate MEX or wrapper compilation step is required — you only need the compiled shared library on disk and the correct CALL_EXTERNAL invocation in your IDL code.

​
Locating the shared library

The IRBEM build system produces the shared library as libirbem.so (Linux/Unix) or libirbem.dll (Windows). The most portable way to construct the full lib_name path inside an IDL script is to branch on the !version.os system variable: 
CASE !version.os OF
  'linux': ext = 'so'
  'sunos': ext = 'so'
  'Win32': ext = 'dll'
ENDCASE
lib_name = 'libirbem.' + ext
If the library does not live in a directory that IDL searches by default, supply the full file system path: 
lib_name = '/opt/irbem/libirbem.' + ext
You can also place libirbem.so (or .dll) in the same directory as your IDL script and construct lib_name relative to ROUTINE_FILEPATH() so that your code remains portable across machines.

​
Critical type requirements

When calling any IRBEM subroutine from IDL using CALL_EXTERNAL, every input and output variable must be declared in the exact type expected by the Fortran subroutine. Passing a variable with the wrong type causes IDL to exit immediately without an error message or stack trace, making the bug extremely difficult to diagnose.
The two rules that prevent nearly all type-mismatch crashes:
Fortran typeRequired IDL typeIDL declaration
INTEGER (32-bit)LONGvar = 0L or LONG(value)
DOUBLE PRECISION (64-bit)DOUBLEvar = 0.0D or DOUBLE(value)
Never use plain IDL INT (16-bit) for Fortran integers, and never use IDL FLOAT (32-bit) for Fortran double-precision arguments. These are the most common sources of silent crashes.

​
String / character arguments

Fortran CHARACTER outputs (e.g. format strings or label fields) must be declared as byte arrays in IDL. Use BYTARR(n) where n matches the declared length of the Fortran character variable: 
; Declare a CHARACTER*80 output buffer
char_out = BYTARR(80)
After the call, convert the byte array back to a string with STRING(char_out).

​
Calling make_lstar via CALL_EXTERNAL

The example below computes magnetic coordinates for a single spacecraft position. All variables are declared explicitly to satisfy the strict type requirements. 
; --- Determine the library name for this platform ---
CASE !version.os OF
  'linux': ext = 'so'
  'sunos': ext = 'so'
  'Win32': ext = 'dll'
ENDCASE
lib_name = 'libirbem.' + ext

; --- Inputs (all LONGs for INTEGER, all DOUBLEs for DOUBLE PRECISION) ---
ntime   = 1L                    ; number of time steps
kext    = 5L                    ; Olson-Pfitzer Quiet external field model
options = [1L, 0L, 0L, 0L, 0L] ; options(1)=1 enables L* computation
sysaxes = 0L                    ; GDZ: altitude, latitude, East longitude

iyear   = [2015L]               ; year
idoy    = [33L]                 ; day of year (33 = 2 February)
ut      = [22363.0D]            ; seconds elapsed since midnight

x1      = [651.0D]              ; altitude, km
x2      = [63.0D]               ; geodetic latitude, deg
x3      = [20.0D]               ; East longitude, deg

; maginput is dimensioned (25, NTIME_MAX) in Fortran (column-major)
; For a single time step, declare a 25-element DOUBLE array.
maginput        = DBLARR(25)
maginput[0]     = 40.0D         ; element 1 (0-based in IDL) = Kp*10

; --- Outputs ---
lm      = DBLARR(1)
lstar   = DBLARR(1)
blocal  = DBLARR(1)
bmin    = DBLARR(1)
xj      = DBLARR(1)
mlt     = DBLARR(1)

; --- Call IRBEM ---
result = CALL_EXTERNAL(lib_name, 'make_lstar1_', $
    ntime, kext, options, sysaxes,               $
    iyear, idoy, ut,                             $
    x1, x2, x3,                                 $
    maginput,                                    $
    lm, lstar, blocal, bmin, xj, mlt,           $
    /UNLOAD, VALUE=REPLICATE(0B, 16))

; --- Print results ---
PRINT, 'Lstar  = ', lstar[0]
PRINT, 'Lm     = ', lm[0]
PRINT, 'MLT    = ', mlt[0]
PRINT, 'Blocal = ', blocal[0]
PRINT, 'Bmin   = ', bmin[0]
PRINT, 'xj     = ', xj[0]
The trailing underscore in 'make_lstar1_' reflects the symbol name that the Fortran compiler emits on Linux. On some platforms the symbol may have a different number of trailing underscores — if CALL_EXTERNAL raises an “unresolved symbol” error, inspect the shared library with nm -D libirbem.so | grep make_lstar to confirm the exact symbol spelling.

​
The VALUE keyword

CALL_EXTERNAL passes all arguments by reference by default. For scalar arguments that Fortran expects to receive by reference (which is the Fortran default for all arguments), this is correct. The VALUE keyword accepts a byte array that selects, per argument position, whether the argument is passed by value (1B) or by reference (0B). For standard IRBEM calls, pass all arguments by reference (0B). 
; Pass all 16 arguments by reference (default Fortran convention)
VALUE = REPLICATE(0B, 16)

​
Array layout

IRBEM uses Fortran (column-major) array ordering. The maginput array is declared DOUBLE PRECISION maginput(25, NTIME_MAX) in Fortran. In IDL, which is also column-major by default, you can declare it as DBLARR(25, ntime). For a single time step, a flat DBLARR(25) is equivalent.

​
Next steps

For the complete list of IRBEM subroutines, their full calling sequences, and descriptions of all input/output parameters, see the API Reference. Each function entry includes the Fortran subroutine signature from which the CALL_EXTERNAL argument list is derived directly.

Build docs developers (and LLMs) love

Get started for freeTalk to us