Quick Start

Download

Kameleon-plus is hosted on google code: https://code.google.com/p/ccmc-software/

You may download an archived version of the code here: Kameleon-plus-6.0.1

Once downloaded, create a directory to store the source and unpack into it:

mkdir ~/Kameleon-plus-source
tar -xzf Kameleon-plus-6.0_source.tar.bz2 --directory ~/Kameleon-plus-source

Requirements

  • cmake - minimum 2.8
  • cdf - 3.5
  • boost - 1.54.0
  • hdf5 (optional)
  • SWIG minimum version 3.0.0 (optional - for python and java wrapper support)

Example files * <links to example files>

Build

To minimize clutter, Kameleon-plus now uses an out-of-source system-independent build structure. To build the library and example executables, make a fresh build directory:

mkdir ~/Kameleon-plus-build
cd ~/Kameleon-plus-build
cmake /path/to/Kameleon-plus-source
make -j8

This populates the build directory with Makefiles for Linux and Mac (or Visual Studio Files for Windows). The last line compiles the ccmc libraries and executables that make use of them.

Executables

The table below shows all executables created by the build process and a brief description of their function.

Note: The executable paths will be /path/to/Kameleon-plus-source/bin/examples/<language>.

language executable Description
c++/ kameleon_prog opens and samples kameleon supported Model
time_interp tests interpolation between time steps *
tracer_prog tests the field line tracer on supported models
integrator_prog tests field line integrator on supported models
coordinate_transformation_test tests cxform’s coordinate transformations *
lfm_test tests the reader and interpolator for LFM
enlil_test tests the reader/interpolator for Enlil
adapt3d_test tests the reader/interpolator for Adapt3d
open_ggcm_test tests the reader/interpolator for open-GGCM
mas_test tests the reader/interpolator for MAS
swmf_iono_test tests the reader/interpolator for SWMF ionosphere model
CDFReader tests the reader CDF file reader
c/ filereader_compat_test tests c wrapper for filereader
kameleon_compat_test tests c wrapper for kameleon
time_interp_c tests c wrapper for time interpolator
tracer_c tests c wrapper for tracer
fortran/ generalfilereader_compat_f tests FORTRAN wrapper for general file reader
kameleon_compat_f tests FORTRAN access to models through Kameleon
timeinterp_compat_f tests FORTRAN compatibility for time interpolator
tracer_compat_f tests FORTRAN compatibility for field line tracer
time_series_test saves time series of multiple variables to an output file
python/ kameleon_test.py tests python access to kameleon objects
tracer.py tests python access to field line tracer
* - indicates the example needs work!

Libraries

The build will also generate the following platform-dependent libraries (names corresponding to a Mac build shown here). The example programs automatically link to these. The library paths will begin with /path/to/Kameleon-plus-source/lib

library path library name Description
ccmc/ libccmc.a main ccmc library containing model readers, interpolators, and tools
ccmc/c/ libccmc_wrapper_c.a c wrapper for ccmc library
ccmc/fortran/ libccmc_wrapper_fortran.a fortran wrapper for ccmc library
ccmc/java/ libkameleon_plus-wrapper-java-6.0.0.jnilib java wrapper for ccmc library (lib<name>.so for linux,<name>.dll for windows)
kameleon_plus-native-Darwin-6.0.0.jar platform-specific java library (Darwin on mac)
ccmc/python/CCMC CCMC.py, _CCMC.so python module - “make install” will install to system’s python libraries

Build Flags

To control the build process, the following flags may be invoked when running cmake from your build directory:

cmake -D<flag_1>=ON -D<flag_2>=OFF -D<flag_3> /path/to/Kameleon-plus-source
<flag> default Description
BUILD_SHARED_LIBS ON build shared ccmc library (libccmc.dylib, libccmc.so, or ccmc.dll)
BUILD_STATIC_LIBS ON build static ccmc library (libccmc_static.a)
USE_STATIC_LIBS OFF link against the static version of any required libraries when building
BUILD_HDF5 ON Build with HDF5 library - (will ignore if HDF5 is not found)

These flags will be saved in your build directory in the file CMakeCache.txt. If you edit this file, the new values will be used next time you run cmake. See Trouble-shooting for potential conflicts between these flags.

Install

Libraries

To install the compiled libraries on your platform (/usr/local/lib/ccmc on Mac):

cd path/to/Kameleon-plus-build
make install

Python Module

You can load the CCMC python library by placing the following at the top of your script:

import sys
sys.path.append('path/to/Kameleon-plus-source/lib/ccmc/python/CCMC')
import CCMC as ccmc

Alternatively, you can install the CCMC module into your system’s python extensions:

cd path/to/Kameleon-plus-source/lib/ccmc/python
sudo python setup.py install

Test that install worked:

python -c "from CCMC import _CCMC as ccmc"

If this command segfaults, try this Python Error: ccmc module segFaults on load.

Tests

Kameleon has been tested successfully on the following platforms:

platform OS Compilers Notes
mac OSX Darwin-12.5.0 Clang 5.1.0 (C,C++), gfortran  
linux scientific linux gnu  
windows cygwin gnu apt-cyg for requirements. export PATH=/usr/local/bin/:/usr/bin/:/bin/

Automated testing will be available soon. In the meantime, try running one of the basic c++ examples:

The following commands read from a cdf file, interpolate and print the z-component of the magnetic field at the coordinates -30 0 0 in the model’s coordinate system:

cd path/to/kameleon-plus-source/bin/examples/c++
./kameleon_prog /path/to/ccmc-converted/file.cdf bz -30 0 0

Example python program:

import CCMC
kameleon = CCMC.Kameleon()
kameleon.open("/path/to/ccmc-converted/file.cdf")
kameleon.loadVariable("bz")
interpolator = kameleon.createNewInterpolator()
bz = interpolator.interpolate("bz",25,0,0)
print "bz:", bz
kameleon.close()

Much of Kameleon’s functionality is illustrated in several examples accross multiple languages. See Full Examples to get started.

Trouble-shooting

Depending on the platform, you may run into issues during the configuration or build process. In almost all cases, you will need to rebuild from a fresh build directory (or at least delete the CMakeCache.txt in your current one).

CMake Error: Libraries not found

Cmake may be unable to find the required libraries if they are installed in unusual places. If so, you can set the paths to required libraries manually:

cmake -DBOOST_ROOT=/path/to/boost -DCDF_PATH=/path/to/CDF -DHDF5_ROOT=/path/to/HDF5 /path/to/Kameleon-plus-source

Build Error: -fPIC errors

This error can occur when linking. This is due to the static libraries not being compiled with the -fPIC flag. You can either rebuild using:

cmake -DBUILD_STATIC_LIBS=OFF /path/to/Kameleon-plus-source

or manually set the -fPIC flags:

cmake -DCMAKE_C_FLAGS=-fPIC -DCMAKE_CXX_FLAGS=-fPIC /path/to/kameleon/source

Python Error: ccmc module segFaults on load

After installing the Python Module and testing:

python -c "from CCMC import _CCMC as ccmc"

If this command segfaults, it means the ccmc module is linked against a different python library from the command line python. To fix this, follow these steps:

  1. Run the following command to determine which library your system’s python is linked to:

    otool -L /path/to/system/python (mac)
    ldd /path/to/system/python (linux)
    

This will print /path/to/system/python/library/Python

  1. Rebuild Kameleon-plus:

    cd path/to/Kameleon-plus-build
    cmake -DPYTHON_LIBRARY=/path/to/system/python/library/Python path/to/Kameleon-plus-source
    make -j8
    
  2. Reinstall

Building Programs with Kameleon-Plus

You can use CMake to build on top of the Kameleon libraries.

  1. Write your program using the Full Examples as a guide.

  2. Copy your program’s source code to the appropriate example language directory:

    cp my_program.cpp /path/to/Kameleon-plus-source/src/example/c++
    
  1. Edit the corresponding CMakeLists file (i.e. src/example/c++/CMakeLists.txt) and add the lines:

    add_executable(my_program my_program.cpp)
    include_directories(/path/to/custom/includes)
    target_link_libraries(my_program ccmc)
    

For a custom fortran program, the process is the same except for the link line:

target_link_libraries(my_program ccmc_wrapper_fortran)
  1. Make a fresh build directory, then rebuild Kameleon-plus:

    cd path/to/Kameleon-plus-build
    cmake path/to/Kameleon-plus-source
    make -j8
    

Your custom programs should now appear in Kameleon-plus-source/bin/examples/<language>