\documentclass[11pt]{article}
\usepackage{amsmath,amssymb}
\usepackage{times, graphicx,float, multicol}
\usepackage{hyperref}
\usepackage{algorithm,algorithmic}
\usepackage{multirow}

\setlength{\textwidth}{6.5in}
\setlength{\textheight}{9.0in}
\setlength{\topmargin}{-.5in}
\setlength{\oddsidemargin}{-.0600in}
\setlength{\evensidemargin}{.0625in}

\newcommand{\secref}[1]{Section~\ref{#1}}

\newcommand{\doublespace}{\baselineskip0.34truein}
\newcommand{\singlespace}{\baselineskip0.16truein}
\newcommand{\midspace}{\baselineskip0.24truein}
\newcommand{\midplusspace}{\baselineskip0.26truein}



\def\Null{{\operatorname{Null}}}
\def\VEC#1#2#3{#1_{#2},\ldots,#1_{#3}}
\def\VECOP#1#2#3#4{#1_{#2}#4\cdots#4#1_{#3}}
\def\NN{{\mathbb N}}
\def\SE#1#2#3{\sum_{#1=#2}^{#3}}
\def\PE#1#2#3{\prod_{#1=#2}^{#3}}
\def\esub{\subseteq}
\def\st{\colon\,}
\def\nul{\varnothing}
\def\FL#1{\left\lfloor{#1}\right\rfloor}
\def\cF{\mathcal{F}}
\def\cA{{\mathcal A}}
\def\cP{{\mathcal P}}
\def\cC{{\mathcal C}}
\def\cL{{\mathcal L}}
\def\cR{{\mathcal R}}
\def\cS{{\mathcal S}}
\def\R{\mathbb R}
\def\nCk{\binom{[n]}{k}}
\def\cutpos{\cC^+}
\def\cutneg{\cC^-}
\def\cutstar{\cC^*}
\def\genpos{\cA^+}
\def\genneg{\cA^-}
\def\vx{{\mathbf x}}
\def\vy{{\mathbf y}}
\def\vz{{\mathbf z}}

\def\BranchlessSearch{{\textsc{BranchlessSearch}}}
\def\StochasticSearch{{\textsc{StochasticSearch}}}
\def\StochasticPropagation{{\textsc{StochasticPropagation}}}
\def\BranchAndCut{{\textsc{BranchAndCut}}}
\def\TestMMS{\textbf{\color{red}DEPRECATED!}}
\def\PropagatePositive{{\textsc{PropagatePositive}}}
\def\PropagateNegative{{\textsc{PropagateNegative}}}
\def\InitialNegativeSets{\textbf{\color{red}DEPRECATED!}}
\def\SelectBranchSet{{\textsc{SelectBranchSet}}}


\title{\textsl{MMSConjecture} User Guide\\ {\large Version 1.0}}

\author{Derrick Stolee \\ 
	University of Illinois\\ 
	\texttt{stolee@illinois.edu}
   }
       
\begin{document}

\maketitle
\vspace{-.3in}
\begin{abstract}
	The \textsl{MMSConjecture} software is an implementation a branch-and-cut method using linear programs to prove the Manickam-Mikl\'os-Singhi Conjecture for fixed values of $k$. 
	This software is in support of the paper ``A Branch-and-Cut Strategy for the Manickam-Mikl\'os-Singhi Conjecture'' by Hartke and Stolee~\cite{HS}.
\end{abstract}
\def\MMSConjecture{\textsl{MMSConjecture}}

\section{Acquiring \MMSConjecture}

The latest version of {\MMSConjecture} and its documentation
	is available online as part of the \textsl{SearchLib} collection
	at the address
	\begin{center}
	\url{http://www.math.illinois.edu/~stolee/SearchLib/}
	\end{center}

{\MMSConjecture} is made available open-source under the GPL 3.0 license.

Fix a workspace directory which contains the \texttt{MMSConjecture} folder.
Install the \textsl{TreeSearch} and \textsl{Utilities} projects into the \texttt{TreeSearch/} and  \texttt{Utilities/} folders in the workspace.
To compile {\MMSConjecture}, use a terminal to access the \texttt{MMSConjecture/src/} folder.
There are two different types of executables:
\begin{enumerate}
	\item To use GLPK, install GLPK into a directory \texttt{glpk/} in the workspace directory.  Type \texttt{make -f Makefile-GLPK} to compile \texttt{mmsconj-glpk.exe}.
	\item To use CPLEX, install CPLEX into a directory \texttt{cplex/} in the workspace directory. Type \texttt{make -f Makefile-CPLEX} to compile \texttt{mmsconj-cplex.exe}.
\end{enumerate}
The executables will be placed in \texttt{MMSConjecture/bin/}

\subsection{Acquiring Necessary Libraries}

There are two external libraries and two \textsl{SearchLib} projects
	used by {\MMSConjecture}.

\begin{enumerate}
	\item \textsl{GLPK}, the GNU Linear Programming Kit, is an open-source linear programming interface.
		When using GLPK with \textsl{MMSConjecture}, the exact solver is used.
				
			\begin{center}\url{http://www.gnu.org/software/glpk/}\end{center}
			
	\item \textsl{CPLEX}, the IBM ILOG CPLEX Optimizer, is a commercial solver. An academic license is available.
		\begin{center}
			\url{http://www-01.ibm.com/software/integration/optimization/cplex-optimizer/}
		\end{center}	
			
	\item \textsl{TreeSearch} is a project in \textsl{SearchLib}
		that abstracts the structure of a backtrack search in order to allow
		for parallelization.
		\textsl{TreeSearch} is available on the same web site as {\MMSConjecture}.
		Consult the \textsl{TreeSearch} documentation for details about the
			arguments and execution processes.
			
	\item \textsl{Utilities} is a project in \textsl{SearchLib} containing useful objects and functions necessary by other projects in \textsl{SearchLib}.
		\textsl{Utilities} is available on the same web site as {\MMSConjecture}.
\end{enumerate}

\subsection{Full Directory Structure}

For proper compilation, place the different dependencies in the following directory structure:

		\begin{itemize}
			\item \texttt{MMSConjecture/} -- The {\MMSConjecture} project.
				\begin{itemize}
					\item \texttt{src/} -- Contains source code. Compilation occurs here.
					\item \texttt{bin/} -- The final binaries are placed here.
					\item \texttt{scripts/} -- Contains shell scripts with the parameters required to verify the conjectures. See Section~\ref{sec:scripts}.
					\item \texttt{data/} -- Contains data files from previous executions of the programs, including detailed timing information. See Section~\ref{sec:data}.
					\item \texttt{docs/} -- This folder contains documentation, including this guide.
				\end{itemize}
			\item \texttt{TreeSearch/} -- A support project from \textsl{SearchLib}.
			\item \texttt{Utilities/} -- A support project from \textsl{SearchLib}.
				\begin{itemize}
					\item \texttt{src/} -- Type \texttt{make} in this directory to compile the \textsl{Utilities} project.
				\end{itemize}
%			\item \texttt{cliquer/} -- The \textsl{cliquer} library must be placed and compiled here.
%			\item \texttt{nauty/} -- The \textsl{nauty} library must be placed and compiled here.
		\end{itemize}

\section{Execution}

There are three executables in the {\MMSConjecture} project.
\begin{itemize}
	\item \texttt{mmsconj-glpk.exe} 
	
	\item \texttt{mmsconj-cplex.exe}
	
	\item \texttt{mmslight-cplex.exe}
\end{itemize}


\subsection{\texttt{mmsconj-glpk.exe} and \texttt{mmsconj-cplex.exe}}

The first two executables have identical behavior except for the linear program solver implementations.
{\bf Note:} The \texttt{mmsconj-cplex.exe} executable requires \texttt{libcplex123.so} to be present in the current directory, and the shell variable \texttt{ILOG\_LICENSE\_FILE} to be set to the path of the license file.

\begin{center}
	\texttt{mmsconj-*.exe [TreeSearch args] -K \# -N \# [--target \#]  [-gm\#v\#] [--prop none|gac|sgac|bsgac|pos] [--strong] [--rule balanced|middle|opthalf] [--proof] [--stochastic] [--branchless] }
\end{center}

\begin{itemize}
	\item \texttt{-K \#} -- Let \# be the number $k$, for the size of the partial sums.
	\item \texttt{-N \#} -- Let \# be the number $n$ of variables.
	\item \texttt{--target \#} -- Let \# be the target $t$.
	\item \texttt{--strong} -- If present, will enforce that the set $\{1,n-k+2, \dots, n\}$ has negative sum and hence the non-negative sums will not include the star example.
	\item \texttt{-gm\#v\#} -- If present, the first \# is a number $m$ and the second number \# is a value $v$ such that $g(m,k) = v$. When $m = n - k$, this value is used in the initial propagation step (see Algorithm 3 \cite{CHS}) to create more negative $k$-sums.
	
	\item \texttt{--stochastic} -- If present, the propagation step will use \StochasticPropagation, a method for randomly selecting a set and testing feasibility with that set chosen.
	
	\item \texttt{--branchless} -- If present, the propagation step will use \BranchlessSearch, which will test all sets using the LP.
	
	\item \texttt{--prop none|gac|sgac|bsgac|pos} -- Select the propagation method:
		\begin{itemize}
\item \texttt{none} -- Skips the propagation step. 
(Not recommended.)

\item \texttt{gac} -- Global Arc Consistency checks at every step if making a set non-negative would increase the number of sets to at least the target value, and if so adds the constraint that the set must be strictly negative (see Algorithm 4 \cite{CHS}). 
This is the option used for the performance statistics in \cite{CHS}.

\item \texttt{sgac} -- Singleton Global Arc Consistency checks at every step what Global Arc Consistency would do if we changed any single set to non-negative or positive. 
If one change results in a contradiction, then we take the other choice. (Not recommended.)
			
\item \texttt{bsgac} -- Branch Singleton Global Arc Consistency selects the set that would be chosen by the branching rule with the current configuration and tests each branch option. 
If GAC then reports a contradiction, it sets the other option without requiring a branch. 
Useful to reduce the depth of the search tree, but usually slower.
(Not recommended.)
			
\item \texttt{pos} -- Positive Propagation performs the check for Global Arc Consistency (which forces some sets to be negative) and then checks remaining sets if setting them to be strictly negative keeps the linear program feasible.
(This is very similar to performing \BranchlessSearch at every search node.)
If the LP check reports infeasible, the set is set to positive (see Algorithm 5 \cite{HS}).
This check greatly slows the search, but reduces the search tree significantly.
This option is used when printing the proof for the case $k = 4$.
		\end{itemize}
	
	\item \texttt{--rule balanced|middle|opthalf} -- Select the branching rule.
\begin{itemize}
\item \texttt{balanced} -- Select the set $S$ which maximizes $\min\{ |\cL(S) \cap \cutstar|, |\cR(S) \cap \cutstar|\}$.
The goal is to guarantee the most sets change when $S$ is set to be negative or non-negative.
This option is used in the performance statistics.

\item \texttt{middle} -- Select the set which has the median co-lexicographic index among sets in $\cutstar$. 
(Not recommended.)

\item \texttt{opthalf} -- Using the current LP optimal vector $\vx$, find the set $S$ with current sum $\sum_{i\in S} x_i$ closest to $-\frac{1}{2}$, since the branch will either select the sum to be at least $0$ or at most $-1$. 
(Not recommended.)
\end{itemize}

\item \texttt{--proof} -- If present, the steps of a proof will be written to standard out. 
In particular, at the propagation steps, the choices of sets to set as non-negative or negative will be written.
Also, at the branching steps, cases will be created to split the search tree.
Not recommended in general, but used to write the proofs for the cases $k = 3$ and $k = 4$ in the Appendix of \cite{HS}.
\end{itemize}

\subsection{\texttt{mmslight-cplex.exe}}

\begin{center}
	\texttt{mmslight-cplex.exe [TreeSearch args] -K \# -N \# [--target \#]  [-gm\#v\#]  [--strong] [--stochastic] [--steps \#] [--samples \#] [--sampletime \#] }
\end{center}

\begin{itemize}
	\item \texttt{-K \#} -- Let \# be the number $k$, for the size of the partial sums.
	\item \texttt{-N \#} -- Let \# be the number $n$ of variables.
	\item \texttt{--target \#} -- Let \# be the target $t$.
	\item \texttt{--strong} -- If present, will enforce that the set $\{1,n-k+2, \dots, n\}$ has negative sum and hence the non-negative sums will not include the star example.
	\item \texttt{-gm\#v\#} -- If present, the first \# is a number $m$ and the second number \# is a value $v$ such that $g(m,k) = v$. When $m = n - k$, this value is used in the initial propagation step (see Algorithm 3 \cite{CHS}) to create more negative $k$-sums.
	
	\item \texttt{--stochastic} -- If present, the propagation step will use \StochasticPropagation, a method for randomly selecting a set and testing feasibility with that set chosen.
	
	\item \texttt{--branchless} -- If present, the propagation step will use \BranchlessSearch, which will test all sets using the LP.
	
	\item \texttt{--steps \#} -- Specify the number of steps in the probability distribution for selecting a random set in $\cutstar$ (weighted to the left).
	
	\item \texttt{--samples \#} -- Specify the number $M$ such that if $M$ random samples are not decided to be positive or negative in \StochasticPropagation, we should terminate the propagation and return to branching.
	
	\item \texttt{--sampletime \#} -- Specify the maximum number of seconds to spend in \StochasticPropagation.
	
\end{itemize}


\section{\textsl{TreeSearch} Arguments}

\begin{itemize}
	\item \texttt{-k \#} --- The killtime: How many seconds before halting the process and reporting a partial job.
	
	\item \texttt{-m \#} --- The maximum depth: the maximum number of steps to go before halting (or in generation mode, a new job is written at this depth).
	
	\item \texttt{run} --- Run mode: The input jobs are run until finished or the killtime is reached.
	
	\item \texttt{generate} --- Generation mode: The input jobs are run and new jobs are listed when reaching the maximum depth.
	
	\item \texttt{--maxjobs \#} --- The maximum number of jobs to generate before halting with a partial job (default: 1000).
	
	\item \texttt{--maxsols \#} --- The maximum number of solutions to output before halting with a partial job (default: 100).
\end{itemize}

\section{Execution with CPLEX}

Our implementation uses IBM ILOG CPLEX version 12.3.
To compile and execute any file using CPLEX, we require the binary file \texttt{libcplex123.so} in the current directory.
Further, for execution, the environment parameter \texttt{ILOG\_LICENSE\_FILE} must be set to the file containing the license information.
Typically, this is contained in \texttt{cplex/licenses/access.ilm}.

\section{Scripts}
\label{sec:scripts}

In the \texttt{scripts/} folder, there are some files which allow for execution of the 


\section{Data}
\label{sec:data}

The \texttt{data/} folder contains some output from previous executions, as well as tabulated performance data.


\begin{thebibliography}{9}

\bibitem{HS} S. G. Hartke, D. Stolee, A Branch-And-Cut Strategy for the Manickam-Mikl\'os-Singhi Conjecture, preprint (2013).

\bibitem{TreeSearch} D. Stolee,
		TreeSearch user guide,
		available at 
		\href{http://www.math.illinois.edu/~stolee/SearchLib/TreeSearch.pdf}{http://www.math.illinois.edu/~stolee/SearchLib/TreeSearch.pdf}
		(2011).
\end{thebibliography}

\end{document}
