
\section{Install}
\label{sec:installation}


This section of the manual focuses on how to install the necessary dependencies and programs needed to run Bertini\_real on a user's computer. The instructions provided describe the process for Linux, Mac, and Windows operating systems.  If you need help or encounter an problem, please file an issue on Github at 
\href{https://github.com/ofloveandhate/bertini_real/issues}{github.com/ofloveandhate/bertini\_real/issues}.  
This is preferred over email.

When installing Bertini\_real, there are a number of steps required in order to successfully install and run the program. They are:
\begin{enumerate}
\item Installing the \glspl{dependent}
\item Installing Bertini
\item Installing Bertini\_real
\end{enumerate}




\subsection{Dependencies}
\label{sec:deps}

Before installing Bertini and then Bertini\_real, there are a number of packages that need to be installed. The method used to install these \glspl{dependent} changes depending on the operating system, so please be sure to read the section that describes your particular system.  Except for Bertini, you should be able to install all of these using a package manager.  It's there to help.

\paragraph{Bertini dependencies}

\begin{itemize}[noitemsep]
\item \gls{mpfr}
\item \gls{gmp}
\item MPI (whatever implementation you want)
\item flex
\item bison
\end{itemize}


\paragraph{Bertini\_real dependencies}

\begin{itemize}[noitemsep]
\item a C++ compiler capable of the C++11 standard
\item Bertini, {\bf parallel version compiled from source and installed as library}.
\item \gls{mpi} (same one as Bertini was compiled with)
\item Boost $>$= 1.53
\item {\tt autoconf}, {\tt automake}, {\tt make}, {\tt libtool}.  {\em Please use your package manager}.  Also, maybe {\tt pkg-config}.  If you hate the autotools, please set up CMake for Bertini\_real, and do a pull request.
\end{itemize} 



Bertini\_real is parallel-enabled, using MPI.  {\bf You cannot build Bertini\_real without support for MPI at the current time.}  To use multiple processors to decompose a real object, call Bertini\_real as you would any other MPI program: \texttt{mpiexec [options] bertini\_real}.  It also works in serial, without being hosted by the mpi executor.  But you still have to have MPI.  


\subsubsection{Symbolic engine}

One additional piece of software must be installed in order to decompose surfaces -- something to do symbolic work for us.  Two options are available at this time (spring 2017):  Matlab, and Python.  Matlab has much stronger visualization routines for Bertini\_real, and some nice options for improving produced Bertini input files.

	\paragraph*{MATLAB}
One option for symbolic engine for Bertini\_real is Matlab.  Instructions on how to install the program are not provided here. However, if you are associated with a university, or a research facility, they probably have download instructions on their technology support website.   Ensure you have access to the symbolic toolbox.  It's required.

\paragraph*{Python}

Bertini\_real was improved in Fall 2016 to use Python as its symbolic engine, in addition to Matlab.  This allows for fully free software to do the decompositions.  Visualization routines in Python are in progress.  You need the following packages, ideally from {\tt pip}:
\begin{itemize}[noitemsep]
\item {\tt sympy}
\item {\tt scipy}
\item {\tt numpy}
\item {\tt algopy}
\item {\tt mpmath}
  \end{itemize}
and for visualization
\begin{itemize}[noitemsep]
\item {\tt dill}
\item {\tt matplotlib}
  \end{itemize}






\clearpage
\input{install_linux}

\clearpage
\input{install_osx}

\clearpage
\input{install_windows}














\clearpage

\subsection{Testrun -- the Cayley Cubic}

Now that everything has been installed, we can now do a test run, to make sure that everything is working properly. To test this program, we will try to generate a Cayley Cubic using the above programs, following a number of steps. The first step is to create an input file. Open up a text editor in your terminal and create a file called \texttt{input}. 

Below is the text for this input file.. A key feature to notice is the second line, where the \texttt{tracktype} configuration is set to 1. This configuration setting is necessary for Bertini\_real to run. 

\begin{center}\begin{minipage}{0.9\linewidth}
\begin{lstlisting}[language=c++, caption={\tt input} for the Cayley Cubic, captionpos=b]
CONFIG 
tracktype:1;

END;
INPUT
variable_group x, y, z;
function f;
f = 4 * (x^2 + y^2 + z^2) + 16*x*y*z - 1;
END;
\end{lstlisting}
\end{minipage}\end{center}

Once the input file is created, we can now run Bertini. Simply navigate in the command line to the directory of the input file and type \texttt{bertini} or \texttt{bertini input}.  You may need to type in the entire pathway to where Bertini is located, if it's not in the same folder, so the command line read \newline \texttt{/cygdrive/path/to/BertiniSource\_v1.5/bertini-serial.exe input}\- \\ \textbf{Cygwin users:} A user may also use \texttt{bertini-serial.exe} (or \texttt{bertini\_parallel.exe}). This will run Bertini, creating the Numerical Irreducible Decomposition needed for Bertini\_real. The following should print to the terminal or shell:

\begin{center}\begin{minipage}{0.9\linewidth}
\centering
\includegraphics[width=0.6\textwidth]{CayleyCubicBertiniRun.png}
\end{minipage}\end{center}

Once Bertini is finished, the output can be verified as satisfactory (or not). Then, Bertini\_real can be run by calling \texttt{bertini\_real} in the command line. Cygwin users, the same rules that applied to Bertini also apply to Bertini\_real, so be sure to include that `.exe' at the end! However, if the input file used was named `input', no file name is needed at the end of the command line. This program should run for roughly 20-30 seconds, with the final terminal/shell output appearing below:

\begin{center}\begin{minipage}{0.9\linewidth}
\centering
\includegraphics[width=0.6\textwidth]{CayleyCubicBertiniRealRun}
\end{minipage}\end{center}

Finally, MATLAB can be used to visualize the result from the Bertini\_real run. Open MATLAB and enter the `master file', which must be linked to the folder where the Bertini\_real solutions are located. This can be done by first making sure that you are currently in the `master folder', then typing \texttt{addpath(`C:\textbackslash{cygwin64}\textbackslash{path}\textbackslash{to}\textbackslash{solutions\_folder}')} into the command window and pressing enter. Then you can call \texttt{gather\_br\_samples} in the command window, which generates a .mat file. Then, call \texttt{bertini\_real\_plotter\-}. This will create a MATLAB figure, pictured below.

\begin{center}\begin{minipage}{0.9\linewidth}
\centering
\includegraphics[width=0.6\textwidth]{CayleyCubic}
\end{minipage}\end{center}


If you've been able to reproduce the above figure, then you've mastered the basics of Bertini\_real. 





