\documentclass[a4paper,headings=small]{scrartcl}
\usepackage[english]{babel}
\usepackage[T1]{fontenc}
\usepackage[latin1]{inputenc}
\usepackage{textcomp,lmodern}
\typearea[current]{last}
\usepackage{fixltx2e,mparhack,mathdots}

\usepackage{natbib}
\usepackage{hyperref}
\bibliographystyle{abbrvnat}

\usepackage{microtype}


\newcommand{\Comp}[1]{\texttt{#1}}

\addtolength{\skip\footins}{0.5\baselineskip}

\usepackage{fnpos}


\hypersetup{
	pdftitle = {clpAPI -- Quick Start},
	pdfauthor = {Gabriel Gelius-Dietrich},
	pdfsubject = {R Interface to C API of COIN-OR Clp},
	pdfkeywords = {Optimization, COIN-OR Clp},
    pdfborder = {0 0 0},
    pdfhighlight = {/N}
}


\newcommand{\pkg}[1]{\emph{#1}}
\newcommand{\pkgname}{\pkg{clpAPI}}
\newcommand{\prgname}[1]{\textsc{#1}}


\begin{document}
\title{clpAPI -- Quick Start}
%\VignetteIndexEntry{Package clpAPI -- Quick Start}
\author{Gabriel Gelius-Dietrich}

\maketitle

\section{Introduction}
The package \pkgname{} provides a low level interface to the C~API of
COIN-OR Clp\footnote{COIN-OR linear programming version 1.12.0 or higher
\url{https://projects.coin-or.org/Clp}} (COIN-OR linear programming).
The package \pkgname{} relies on a separate installation of COIN-OR Clp.

\section{Installation}
See \Comp{INSTALL} for installation instructions and platform specific details.

\section{Usage}

In the following, an example lp-problem will be created and solved:

\noindent
\hspace{.5in} maximize
$$z = 5 x_1 + 4 x_2 + 3 x_3$$
\hspace{.5in} subject to
$$
\begin{array}{r@{\:}c@{\:}r@{\:}c@{\:}r@{\:}c@{\:}r}
2 x_1 &+& 3 x_2 &+&   x_3 & \leq  5 \\
4 x_1 &+&   x_2 &+& 2 x_3 & \leq 11 \\
3 x_1 &+& 4 x_2 &+& 2 x_3 & \leq  8 \\
\end{array}
$$
\hspace{.5in} where all variables are non-negative
$$x_1 \geq 0, \ x_2 \geq 0, \ x_3 \geq 0$$

\noindent
Load the library.
<<>>=
library(clpAPI)
@
Create a problem object.
<<>>=
prob <- initProbCLP()
@
Set the direction of optimization ($-1$: maximize, $1$: minimize).
<<>>=
setObjDirCLP(prob, -1)
@
Prepare data structures for the problem object. Number of columns and rows:
<<>>=
nc <- 3
nr <- 3
@
The constraint matrix is passed in column major order format. \textbf{Be
careful here:} all indices start with 0! Row indices.
<<>>=
ia <- c(0, 1, 2, 0, 1, 2, 0, 1, 2)
@
Column indices.
<<>>=
ja <- c(0, 3, 6, 9)
@
Non-zero elements.
<<>>=
ar <- c(2, 4, 3, 3, 1, 4, 1, 2, 2)
@
Lower bounds for the variables (columns).
<<>>=
clb <- rep(0, 3)
@
Right hand side (row upper bounds for the rows).
<<>>=
rub <- c(5, 11, 8)
@
Objective coefficients.
<<>>=
obj <- c(5, 4, 3)
@
Load problem data into the problem object.
<<>>=
loadProblemCLP(prob, nc, nr, ia, ja, ar, clb, NULL, obj, NULL, rub)
@
Solve the problem using the simplex algorithm.
<<>>=
solveInitialCLP(prob)
@
Retrieve the value of the objective function after optimization.
<<>>=
getObjValCLP(prob)
@
Retrieve the primal values of the structural variables (columns) after
optimization.
<<>>=
getColPrimCLP(prob)
@
Retrieve the dual values of the structural variables (columns) after
optimization (reduced costs).
<<>>=
getColDualCLP(prob)
@
Free memory, allacated to the problem object.
<<>>=
delProbCLP(prob)
@


\section{Function names}

\subsection{Searching}

The function names in \pkgname{} are different from the names in
\prgname{COIN-OR Clp},
e.\,g. the function \texttt{addColsCLP} in \pkgname{} is called
\texttt{Clp\_addColumns} in \prgname{COIN-OR Clp}. The directory \texttt{inst/}
containes a file \texttt{c2r.map} which maps a \prgname{COIN-OR Clp} function
name to the corresponding \pkgname{} function name. Additionally, all man-pages
contain an alias to the \prgname{COIN-OR Clp} function name. The call
<<>>=
help("Clp_addColumns")
@
will bring up the man-page of \texttt{addColsCLP}.


\subsection{Mapping}

The file \texttt{c2r.map} in \texttt{inst/} maps the \pkgname{} function names
to the orininal \prgname{COIN-OR Clp} function names of its C-API.
To use the latter, run
<<>>=
c2r <- system.file(package = "clpAPI", "c2r.map")
source(c2r)
@
now either
<<>>=
pr1 <- initProbCLP()
delProbCLP(pr1)
@
or the original functions
<<>>=
pr2 <- Clp_newModel()
Clp_deleteModel(pr2)
@
work both. Keep in mind that the mapping only affects the function names not the
arguments of a function.


\end{document}
