Serveur documentation

The CEFLIB is divided in several parts :

The main library, used to read CEF files, parse metadata and variables content
A IDL interface, in order to call the previous one from IDL
A same interface for MATLAB
A last one for Python language.

In case of problem while building or installing this library,

please consult Known bugs

1. Uncompress and extract sources

Choose a directory to install the software, copy the tar.gz file and extract the sources :

$ cd <install-directory>
$ gzip -d CEFLIB-x.y.z.tar.gz
$ tar xvf CEFLIB-x.y.z.tar

This command will create the CEFLIB directory tree on the current directory.

This delivery contains source code to generate the main CEFLIB library, and additional software interface to call it from different langages.

The delivery contains 5 sub-directories :

LIB

General purpose tools used by all softwares, handling times for example
C

The main C library used to parse CEF files content
IDL

Source code used to write an IDL DLM (Dynamically Loadable Module), which will allow to call this library from IDL
MATLAB

Source code to generate a dynamic library which will allow to call the CEFLIB from Matlab
PYTHON

Source code and scripts to generate a dynamic library that can be use from Python language. Multi-dimensionnal variables need installation on a specific Python package, called numpy

Each library comes with a generic Makefile, which needs some external variables declarations, like compilation options, directories where to find libraries, etc…

These declarations are given in the build script located in the root directory.

2. Update the build script

In the install directory, you will find a shell script called build.

This script contains various definitions, depending on your environment (OS, compiler), used to build the librairy and its different interfaces to IDL, Matlab, Python.

The CEFLIB library has been tested for various operating systems:

Linux (CentOS > 5.6, CentOS 6.x)
Solaris (V9 and V10)
Mac OS (Darwin, Yosemite, El Capitan).

If your are working under other operating systems, try to make it work for your environment, by updating the content of the build script, or contact us in case of problem.

Depending on your environment, you may or not have both ksh and bash installed on your system.

You can use either /bin/ksh or /bin/bash by modifying the first line of the script, selecting one of the two lines below:

#! /bin/ksh
#! /bin/bash

In all cases, you will have to modify the INSTALL_DIR variable defined in the line :

INSTALL_DIR=<directory>

Where INSTALL_DIR must be the path of the directory containing the build script.

e.g.: If you extract the delivery file in your /home/username directory, set the variable as following :

INSTALL_DIR=/home/username/CEFLIB

2.1. IDL specific instructions

To build the IDL interface, you will have to set the IDL_DIR environment variable, which is done generally under Linux by a setup script file provided with IDL.

For example, if IDL is intalled in the /usr/local directory, enter one of the next commands :

$ source /usr/local/rsi/idl/bin/idl_setup               # csh or tcsh shell
$ . /usr/local/rsi/idl/bin/idl_setup.ksh                # ksh or bash shell

Bug with IDL 6.0

There is a problem between this IDL version and the usual zlib library, used to read compressed CEF files (.gz).

You will have to build the CEFLIB IDL version by linking with the IDL MGPEG library which is implementing its own version of zlib.

Please refer to the instructions given in the <install-dir>/IDL/Makefile, to select the expected zlib library, by commenting or not a makefile declaration.

2.2. MATLAB specific instructions

To build the Matlab interface, you will also have to modify the following line :

MATLAB_DIR=<matlab_root_directory>

The Makefile in the MATLAB directory has to know the Matlab root directory, to be able to find some C include files located in the <matlab_root_directory>/extern/include/ directory.

e.g.: in our computer, Matlab is installed on /usr/local/matlab, so we have :

MATLAB_DIR=/usr/local/matlab

2.3. Python specific instructions

To build and use the library from Python, you will have to update the following variable in the build script :

export NUMPY_DIR=/usr/python64/site-packages/numpy

Numpy is a specific Python package, which is not natively installed with Python, that allows handling of multi-dimensionnal arrays.

Informations should be found at :

http://numpy.scipy.org[]

Another useful package should be Matplotlib, that allows to plot data in a similar way than Matlab.

http://matplotlib.sourceforge.net[]

On recent Linux computers, you can use usual package manager to install these packages :

yum on RedHat based systems
aptget on Dedian based systems

For example, on our CentOS 6.2 computer :

$ yum install numpy
$ yum install python-matplotlib

3. Building the libraries

You can build the whole libraries, but you will need to have both IDL and MATLAB installed previously on your system.

In the other case, you can just build the LIB and CEFLIB libraries, and then choose to build either the IDL or MATLAB interface.

3.1. Recursive build of the 4 directories

To generate the whole librairies, enter the following commands :

$ cd <install-directory>
$ ./build clean raz all

This command will recursively generate binaries for LIB C IDL MATLAB and PYTHON subdirectories.

Of course, you will need to have both IDL, Matlab and Python installed on your computer.

3.2. Separate build of libraries

In an usual case, you will probably generate only the library needed for your favourite software.

In all case, you need to build the core library.

Then you have to choose building the IDL, Matlab of Python interface.

4. Building the core C library

First, you have to start building the LIB and C librairies :

$ cd <install-dir>
$ cd LIB
$ ../build clean raz all        // or ../build -B under linux
$ cd ..
$ cd C
$ ../build clean raz all        // or ../build -B under Linux
$ cd ..

5. Building the IDL interface

The IDL interface build process consists in:

$ cd <install-dir>
$ cd IDL
$ ../build clean raz all        // or ../build -B under Linux

After binaries generation, you must obtain two files:

bin/idl_cef.dlm : Descriptive file of DLM module
bin/idl_cef.so : Shared library

In case of problem, you can have a look on Known bugs.

5.1. Configuration before use

In order to make this library available to IDL, these 2 files must be:

in the current directory before running IDL
in the directory where IDL search for it’s dynamic libraries :
```
/usr/local/rsi/idl/bin/bin.Linux.x86    ; in our computer
```
in a alternate directory, specified using the Unix IDL_DLM_PATH environment variable :
```
$ export IDL_DLM_PATH=<install-dir>/IDL/bin
```

Another possibility is to copy manually the idl_cef.so and idl_cef.dlm, in the IDL dynamic librairies directory, but you will need administrator rights.

You can obtain the IDL’s dynamic librairies directory by entering :

$ idl
IDL> print, !DLM_PATH
/usr/local/rsi/idl_5.4/bin/bin.linux.x86

5.2. Using a profile script

In the IDL directory, you will find a script file:

IDL/profile

##
#       Set the INSTALL_DIR to the directory where you extract the sources
#
INSTALL_DIR=${CIS_ROOT}/SOFT/CEFLIB

##
#       Path to the .pro files
#
export  IDL_PATH=${IDL_PATH}:${INSTALL_DIR}/IDL/pro

##
#       To tell IDL where to find the idl_cef.dlm and idl_cef.so files
#
export  IDL_DLM_PATH=${INSTALL_DIR}/IDL/bin:${IDL_DLM_PATH}

You can use this file, after updating the INSTALL_DIR variable, to configure the IDL interface environment variables.

Running manually:

. IDL/profile

Or incorporating this line in your current profile (generally

5.3. Testing the IDL library

You can test the library with 2 small IDL scripts by entering :

$ cd pro
$ idl fgm.pro           ; plot FGM data
$ idl cis.pro           ; plot CIS density and velocity
$ idl cis_whisper.pro   ; plot CIS H+, O+ and WHISPER density
$ idl
IDL>info, "<cef-file>"  ; print all metadata and attributes

You can also use separate commands like :

IDL> nrec = CEF_READ (<filename>)
IDL> print, CEF_VARNAMES()
IDL> print, CEF_METANAMES()
IDL> print, CEF_META ("file_name")
IDL> print, CEF_GATTRIBUTES()

6. Building the MATLAB interface

To build the CEFLIB Matlab interface enter the following commands:

$ cd <install-dir>
$ cd MATLAB
$ ../build clean raz all        // or ../build -B under Linux

By looking at the <install-dir>/MATLAB directory you will find :

startup.m : Matlab script to describe where to find the CEFLIB binaries and Matlab scripts You can copy this file in your usual Matlab working directory, or insert its commands on your own startup file
lib/libcef.so : dynamic library used to access to the CEFLIB
lib/libcef_mfile.m : Matlab script file describing the CEFLIB interface (new)
lib/cef_init.m : small Matlab script file to load the library and facilitate functions call

In case of problems, consult Known bugs

6.1. Update startup.m

You will have to update the startup.m, and modify the following line :

ceflib_install_dir = <directory>

Set this variable to the path of the directory where you extract the delivery file.

e.g. : if you extract delivery in the /home/username directory, set the variable to :

ceflib_install_dir = /home/username/CEFLIB

7. Building Python interface

To build the CEFLIB Python interface, enter the following commands:

$ cd <install-dir>
$ cd PYTHON
$ ../build clean raz all        // or ../build -B under Linux

In the <install-dir>/PYTHON directory you will find :

libcef.so : Dynamic library user to access to the CEFLIB interface

7.1. Configuration

In order to be accessible, the ceflib.so file has to be :

in the current directory
in a directory declared in the PYTHONPATH environment variable

You can add the following line in your current profile:

export PYTHONPATH=${PYTHONPATH}:<INSTALL_DIR>/PYTHON

7.2. Testing

To use the library, you have to use the import directive, as usual Python modules using :

$ python
>>> import ceflib
>>> ceflib.read ("example_file.cef")

To get some help :

$ pydoc ceflib

cef_lib

CEFLIB Installation manual