INSTALL.html

/* Note: the HTML code is embedded in C comments for Doxygen */

/** @page installation Installation

<h2>Overview</h2>

<p>This source code distribution uses the GNU autoconf/make mechanism.</p>

HQP can be compiled and tested by invoking:
<br><code>
$ ./configure
<br>
$ make
</code><br>

<p>Basically two libraries are built: hqp and omu.
Furthermore an example is created in <tt>./hqp_docp</tt>, testing HQP alone,
and a demo collection in <tt>./odc</tt>, testing HQP together with the front-end Omuses.</p>

An up-to-date reference documentation can be created from the sources using Doxygen with
<br><code>
$ make doc
</code><br>

<p></p>
The results of make (object codes, lib, executables) can be removed with
<br><code>
$ make clean
</code><br>

<p></p>
The results of make and configure (makefiles) can removed with
<br><code>
$ make distclean
</code><br>

<h2>Installation details</h2>

<h3>Required software</h3>

The compilation of HQP relies on the following software:
<ul>
<li>an sh-compatible command interpreter (see IEEE POSIX Shell and Tools spec)</li>
<li>GNU make</li>
<li>a compiler for C, C++ and optionally Fortran 77</li>
</ul>

Moreover, HQP uses the Tool Command Language
<ul>
<li>Tcl version 8.1 or higher (typically packages <tt>tcl</tt> for the runtime and <tt>tcl-dev</tt> for include files)</li>
</ul>

<h3>Detailed installation steps</h3>

<ol>
<li>
Unpack the distribution file by invoking
<br><code>
 tar -xzf hqp&lt;version&gt;.tar.gz
</code><br>
This creates the new directory hqp containing everything.
</li>
<p></p>
<li>
cd to the created directory and invoke
<br><code>
 ./configure
</code><br>
This creates the files ./makedirs, ./makedefs 
   ./odc/Makefile, ./hqp_docp/Makefile, lib/pkgIndex.tcl, and ./doc/Doxyfile.
Following options can be specified:

<p><b>Feature options:</b></p>
<dl>
 <dt><pre>--enable-adolc</pre></dt>
     <dd>Include code that uses ADOL-C for automatic differentiation 
     as part of Omuses. This simplifies the manual implementation of 
     optimization programs. See the Odc demo collection, 
     e.g. ./odc/Prg_BatchReactor.[hC] using ADOL-C vs. 
     ./odc/Prg_BatchReactor_bare.[hC] accessing lower level interfaces.<br>
     Additionally you may specify:</dd>
     <dl>
     <dt><pre>--with-adolc</pre></dt>
       <dd>Directory prefix of ADOL-C installation, e.g.
       <pre>--with-adolc=/usr</pre></dd>
     </dl>
 <dt><pre>--enable-fortran</pre></dt>
     <dd>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 for gfortran. 
     Please check the variables FORTRAN_* in ./makedefs.</dd>
 <dt><pre>--enable-mex</pre></dt>
     <dd>Include MEX S-function interface with Omuses. This requires MATLAB&reg;
     and Simulink&reg; on your machine for include files declaring data
     structures and for runtime libs implementing mxArray.<br>
     Additionally you may specify:
     <dl>
     <dt><pre>--with-matlab</pre></dt>
       <dd>Root directory of MATLAB&reg; installation, e.g.
       <pre>--with-matlab=/usr/local/matlab</pre></dd>
     <dt><pre>--with-matlab-libs</pre></dt>
       <dd>Directory containing MATLAB&reg; runtime libraries, e.g.
       <pre>--with-matlab-libs=/usr/local/matlab/extern/lib/glnx86</pre></dd>
     </dl>
    </dd>
 <dt><pre>--enable-cute</pre></dt>
     <dd>Include CUTE interface with HQP.</dd>
 <dt><pre>--enable-ascend</pre></dt>
     <dd>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)</dd>
</dl>

<p><b>Installation options:</b></p>
<dl>
 <dt><pre>--prefix=PATH</dt>
     <dd>Path where you'd like to install the libraries and include files
     (default is /usr/local).</dd>
</dl>

<p>Build options:</p>
<dl>
 <dt><pre>--disable-shared</pre> (<pre>--enable-shared</pre>)</dt>
     <dd>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.</dd>
 <dt><pre>--enable-symbols</pre></dt>
     <dd>build debug version, including symbolic information</dd>
 <dt><pre>--enable-gmalloc</pre></dt>
     <dd>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 :-)</dd>
</dl>

<p><b>Use a specific Tcl installation, which is not found automatically:</b></p>
<dl>
 <dt><pre>--with-tcl</pre></dt>
     <dd>Directory containing Tcl configuration file tclConfig.sh, e.g.
     <pre>--with-tcl=/usr/local/lib</pre></dd>
 <dt><pre>--with-tclinclude</pre></dt>
     <dd>Directory containing include file tcl.h.</dd>
</dl>
</li>

<p></p>
<li>
Compile the distribution by invoking
<br><code>
  make
</code><br>
(or
<br><code>
  make -f Makefile.hqp
</code><br>
 to skip building Omuses and Odc)
</li>

<p></p>
<li>
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).
</li>

<p></p>
<li>
Optionally install the libraries and includes by invoking
<br><code>
  make install
</code><br>
The following directories and files are created:
<br><pre>
     $prefix / lib     / Hqp&lt;version&gt; / pkgIndex.tcl
                       / libhqp-&lt;version&gt;.so
                       / libomu-&lt;version&gt;.so
                       / libhqp.so -> libhqp-&lt;version&gt;.so
                       / libomu.so -> libomu-&lt;version&gt;.so
             / include / hqp-&lt;version&gt; / *.h
                       / hqp -> hqp-&lt;version&gt;
</pre><br>

<p></p>
<li>
See <tt>./hqp_docp/README</tt> if you want to use HQP directly for
multistage optimization, bypassing Omuses
(no support for differential equations or automatic differentiation).
</li>

<p></p>
<li>
See ./hqp_cute/README if you want to use HQP in the testing environment
CUTE.
</li>

<p></p>
<li>
Get in contact with the developers through 
<a href="https://github.com/omuses/hqp">GitHub</a>.
</li>

</ol>

<h3>Using alternative compilers</h3>

Gernerally for using an other compiler, say cl, invoke
<br><code>
  CC=cl ./configure
</code><br>

<h3>Hints for compiling under Windows</h3>

<p>The POSIX/GNU build tools are still needed (tar, gzip, sh, make, patch).
They are provided for Windows by <a href="http://www.mingw.org">MinGW</a> or
<a href="http://www.cygwin.com">Cygwin</a>.
These environments also include gcc and tcl, besides more.</p>

<p>Alternatively the native Windows compiler cl can be configured for the
actual compilation (CC=cl ./configure), provided it finds in the PATH
environment -- the Visual Studio Command Prompt that comes with
Visual Studio Tools sets the path; the POSIX shell for building HQP might be
started from there. Tcl should be installed from a binary distribution
available for Windows in this case and configured via <code>--with-tcl</code> (see above).</p>

*/

/** @page structure Directory structure of the distribution

<p>The HQP distribution contains the following sub-directories:</p>

<h2>Main modules</h2>
<dl>
<dt>hqp</dt>
<dd>
The actual solver for sparse nonlinear optimization

</dd>
<dt>omu</dt>
<dd>
 Front-end Omuses for treating dynamic optimization problems
</dd>
</dl>

<h2>Examples</h2>
<dl>
<dt>odc</dt>
<dd>
 Omuses Demo Collection (examples using the front-end Omuses)
</dd>

<dt>hqp_docp</dt>
<dd>
 Example for directly using the DOCP interface of HQP
</dd>
</dl>

<h2>External model interfaces</h2>
<dl>
<dt>hxi</dt>
<dd>
  Hqp eXternal Interfaces (currently S-function)
</dd>

<dt>hqp_cute</dt>
<dd>
Files required to run HQP with CUTE
</dd>
</dl>

<h2>Additional differential equation solvers</h2>
<dl>
<dt>daspk</dt>
<dd>
  Place holder for DASPK differential-algebraic equation solver
</dd>

<dt>rksuite</dt>
<dd>
  RKsuite differential equation solvers (by R.W. Brankin et al)
</dd>
</dl>

<h2>Base modules</h2>
<dl>
<dt>meschach</dt>
<dd>
  Matrix library (by D.E. Steward and Z. Leyk)
</dd>

<dt>iftcl</dt>
<dd>
Interface wrapping Tcl (Tool Command Language; used for configuring solver options and for controlling the execution)
</dd>

<dt>malloc</dt>
<dd>
  GNU malloc library (HQP may be configured to use GNU malloc instead of the system malloc)
</dd>
</dl>

<h2>Documentation</h2>
<dl>
<dt>doc</dt>
<dd>
Doxygen input file for generating source code documentation.
</dd>
</dl>

*/