Installation

Overview

This source code distribution uses the GNU autoconf/make mechanism and Doxygen for extracting the documentation.

HQP can be compiled and tested by invoking:
$ ./configure
$ make
Basically two libraries are built: hqp and omu. Furthermore an example is created in ./hqp_docp, tesing HQP alone, and a demo collection in ./odc, testing HQP together with the front-end Omuses.

An up-to-date reference documentation can be created from the sources with
$ make doc

The results of make (object codes, lib, executables) can be removed with
$ make clean
The results of make and configure (makefiles) can removed with
$ make distclean

Installation details

Required software

The compilation of HQP relies on the following software:

Moreover, HQP uses the Tool Command Language

The required software is normally there under Linux.

Hints for Windows

The freely available Cygwin is an easy way to get the required software under Windows all at once (see http://sources.redhat.com/cygwin/). When using the Net installation wizard setup.exe, make sure to select the following packages for installation:

Libs/tcltk
Devel/gcc
Devel/gcc-g++
Devel/gcc-g77
(only to use additional integrators, e.g. DASPK)
Devel/gcc-mingw
(only to compile a non-cygwin version)
Devel/gcc-mingw-g++
(only to compile a non-cygwin version)
Devel/gcc-mingw-g77
(only to compile a non-cygwin version)
Devel/doxygen
(only to re-generate reference documentation)

Note: Tcl is not installed properly under Cygwin (<=1.5.5), causing Hqp not to find the Tcl library (init.tcl). See section "Known Problems" below.

Detailed installation steps

  1. Unpack the distribution file by invoking
    tar -xzf hqp<version>.tar.gz
    This creates the new directory hqp containing everything.

  2. cd to the created directory and invoke
    ./configure
    This creates the files ./makedirs, ./makedefs ./odc/Makefile, ./hqp_docp/Makefile, lib/pkgIndex.tcl, and ./doc/Doxyfile. Following options can be specified:

    Feature options:

    --enable-fortran
    Include the numerical integration routines RKsuite and optionally DASPK with libomu (see also daspk/README). This requires an f77 compiler on your machine. Note: The automatic settings done by ./configure are only guesses. Please check the variables FORTRAN_* in ./makedefs.
    --enable-mex
    Include MEX S-function interface with Omuses. This requires MATLAB(R) and Simulink(R) on your machine for include files declaring data structures and for runtime libs implementing mxArray.
    Additionally you may specify:
    --with-matlab
    Root directory of MATLAB(R) installation, e.g. --with-matlab=/usr/local/matlab
    --with-matlab-libs
    Directory containing MATLAB(R) runtime libraries, e.g. --with-matlab-libs=/usr/local/matlab/extern/lib/glnx86
    Note: see "Problems with MEX" below, if this feature does not work
    --enable-cute
    Include CUTE interface with HQP.
    --enable-ascend
    Include current preliminary version of an interface to Ascend4. This requires that this distribution is unpacked in the directory of the Ascend distribution, e.g. in /home/myname/ascendiv-0.9 (for Ascend see http://www.cs.cmu.edu/~ascend/Home.html)

    Installation options:

    --prefix=PATH
    Path where you'd like to install the libraries and include files (default is /usr/local).

    Build options:

    --disable-shared (--enable-shared)
    Build shared (static) libraries. Shared is default, except for Windows, where building a DLL is somewhat tricky. Shared libraries are required if Hqp/Omuses shall be used as package extending a Tcl application.
    --enable-symbols
    build debug version, including symbolic information
    --enable-gmalloc
    Use GNU malloc instead of the system routines. Gmalloc will be enabled automatically if your system malloc doesn't work properly (e.g. under DEC OSF). According to the authors experience gmalloc doesn't work on all machines, but fortunately it does where it's needed :-)

    Use a specific Tcl installation, which is not found automatically:

    --with-tcl
    Directory containing Tcl configuration file tclConfig.sh, e.g. --with-tcl=/usr/local/lib
    --with-tclinclude
    Directory containing include file tcl.h.

  3. Compile the distribution by invoking
    make
    (or
    make -f Makefile.hqp
    to skip building Omuses and Odc)

  4. Directly after compilation, a test run of an example in ./odc is performed automatically that should produce the result "optimal". Some more examples are given in ./odc (please see also the documentation in ./doc).

  5. Optionally install the libraries and includes by invoking
    make install
    The following directories and files are created: 
         $prefix / lib     / Hqp<version> / pkgIndex.tcl
                       / libhqp-<version>.so
                       / libomu-<version>.so
                       / libhqp.so -> libhqp-<version>.so
                       / libomu.so -> libomu-<version>.so
             / include / hqp-<version> / *.h
                       / hqp -> hqp-<version>

  6. See ./hqp_docp/README if you want to apply HQP directly to multistage problems, without using ADOL-C or differential equations.

  7. See ./hqp_cute/README if you want to use HQP in the testing environment CUTE.

  8. Send correspondence to the developers listed at http://hqp.sf.net

Using alternative compilers

Gernerally for using an other compiler, say cl, invoke
CC=cl ./configure

Hints for using cl, i.e. the "native" compiler under Windows

Alternative for Windows

Yet another alternative for Windows

Cygwin can also be used to compile libraries and programs that run natively under Windows not relying on the Posix emulation layer provided by cygwin1.dll.

Known Installation Problems

Problems with Tcl

application-specific initialization failed: Can't find a usable init.tcl in the following directories: C:/cygwin/share/tcl8.4 ...

This error is caused by an unproper installation of Tcl. Two work-arounds are possible:

Fail to link Omuses with Matlab(R) runtime library (--enable-mex)

Message: Cannot export libmx_NULL_THUNK_DATA: symbol not found

This problem can be solved by generating a gcc compatible library stub from libmx.lib coming with Matlab(R). Generate liblibmx.a with the following commands in the directory MATLAB_LIBDIR:
$ echo EXPORTS > libmx.def
$ nm libmx.lib | grep ' T _' | sed 's/.* T _//' >> libmx.def
$ dlltool --def libmx.def --dllname libmx.dll --output-lib liblibmx.a

Fail to load MEX S-function (mdlInitializeSizes fails)

The lcc compiler coming with Matlab(R) does not appropriately export the mexFunction of the DLL. That is why the dynamic load fails. Use an other compiler to generate the S-function with mex. For instance gcc (see http://gnumex.sf.net) or Microsoft Visual C++ (directly supported by Matlab(R)) work.

Problems with specific gcc versions:

Problems with Cygwin

Problems with MinGW/MSYS

HQP is hosted at SourceForge. Documentation generated on Sat Nov 8 14:21:32 2008 using doxygen.