\documentclass[preprint]{acmart}
\usepackage{listings}
\usepackage{url}

\lstset{frame=tb,
  aboveskip=3mm,
  belowskip=3mm,
  showstringspaces=false,
  columns=flexible,
  basicstyle={\small\ttfamily},
  numbers=none,
  numberstyle=\tiny\color{gray},
  keywordstyle=\color{blue},
  commentstyle=\color{dkgreen},
  stringstyle=\color{mauve},
  breaklines=true,
  breakatwhitespace=true,
  tabsize=3,
  backgroundcolor = \color{lightgray!10}
}

% inline lstinline style
\makeatletter
\lstdefinestyle{mystyle}{
  basicstyle=%
    \ttfamily
    \color{blue}%
    \lst@ifdisplaystyle\scriptsize\fi
}

% Metadata Information
\acmJournal{TOMS}

% Copyright
%\setcopyright{acmcopyright}
\setcopyright{none}
\settopmatter{printacmref=false} % Removes citation information below abstract
\renewcommand\footnotetextcopyrightpermission[1]{} % removes footnote with conference info
\pagestyle{plain} % remove running headers
% remove first page left-footer
\usepackage{xpatch}
\makeatletter
\xpatchcmd{\ps@firstpagestyle}{Manuscript submitted to ACM}{}{}
\makeatother

\newcommand{\hlctexttt}[1]{\texttt{\colorbox{cyan!10}{#1}}}
\newcommand{\hlgtexttt}[1]{\texttt{\colorbox{lightgray!15}{#1}}}
\newcommand{\code}[1]{\hlgtexttt{#1}}
\newcommand{\hlight}[1]{\hlctexttt{#1}}

% DOI
\acmDOI{0000001.0000001}


% Document starts
\begin{document}

\title{User Manual for CP-CALS}

\author{Christos Psarras}
\affiliation{%
 \institution{Rheinisch-Westfälische Technische Hochschule Aachen}
 \city{Aachen}
 \country{Germany}}
\email{christos.psarras@rwth-aachen.de}
\author{Lars Karlsson}
\affiliation{%
  \institution{Ume{\aa} Universitet}
  \city{Ume{\aa}}
 \country{Sweden}
}
\email{larsk@cs.umu.se}
\author{Rasmus Bro}
\affiliation{%
    \institution{University of Copenhagen}
    \city{Copenhagen}
    \country{Denmark}}
\email{rb@food.ku.dk}
\author{Paolo Bientinesi}
\orcid{0000-0002-4972-7097}
\affiliation{%
    \institution{Ume{\aa} Universitet}
    \city{Ume{\aa}}
    \country{Sweden}}
\email{pauldj@cs.umu.se}
\thanks{*~ Corresponding authors}

\maketitle

\section{Requirements}

\subsection{Mandatory}
\begin{itemize}
    \item \hlight{CMake 3.17.5} or higher.
    A bash script is provided, to help install CMake 3.17.5 (for Linux) in the \code{extern} folder and updates the \code{PATH} environment variable to point to it. Try using it by navigating to the directory where you cloned CALS and running: \code{source scripts/environment\_setup.sh}. Then, using the same terminal session, running \code{cmake --version} should return version 3.17.5.
    \item \hlight{OpenMP}
    \item \hlight{BLAS/LAPACK} (not required for MATLAB MEX generation). Either of the following libraries has been tested:
    \begin{itemize}
        \item Intel MKL
        \item OpenBLAS
    \end{itemize}
\end{itemize}

\subsection{Optional}
\begin{itemize}
    \item CUDA 11
    \item MATLAB 2019b
\end{itemize}

\subsection{Compilers}
CALS should compile with any compiler supporting C++17 features. It has been tested to compile with \code{g++-8}, \code{g++-10} and \code{clang-10}.

\section{Compilation}

\subsection{Cloning}
Clone the CP-CALS repository using:

\begin{lstlisting}
git clone https://github.com/HPAC/CP-CALS.git
\end{lstlisting}

\noindent and navigate in the directory of the CP-CALS repository using:

\begin{lstlisting}
cd CP-CALS
\end{lstlisting}

\subsection{MKL backend}
\noindent Use the following commands to compile the MKL version of CP-CALS.

\begin{lstlisting}
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DWITH_MKL=ON
cmake --build build -j 8
\end{lstlisting}

\subsection{OpenBLAS backend}
\noindent Use the following commands to compile the OpenBLAS version of CP-CALS.

\begin{lstlisting}
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DWITH_OPENBLAS=ON
cmake --build build -j 8
\end{lstlisting}

\section{CUDA Support}
\noindent Use the following commands to enable CUDA support for CP-CALS. (works for either MKL or OpenBLAS backends; MKL used in the example)

\begin{lstlisting}
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DWITH_MKL=ON -DWITH_CUBLAS=ON
cmake --build build -j 8
\end{lstlisting}

\section{MATLAB Interface}
\noindent Use the following commands to compile the MATLAB MEX files (no prior compilation of CP-CALS needed).

\begin{lstlisting}
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DWITH_MATLAB=ON -DMATLAB_PATH=</path/to/Matlab>
cmake --build build -j 8
\end{lstlisting}

\noindent \code{</path/to/Matlab>} is the absolute path to the MATLAB install directory.

\section{Doxygen}
To produce the DOXYGEN documentation files for CP-CALS, use the following command:
\begin{lstlisting}
doxygen DOXYGEN
\end{lstlisting}

\section{Functions}

\subsection{C++}
The function \code{cp\_cals}, located in the \code{include/cals.h} header file, is the function that computes multiple Concurrent Alternating Least Squares algorithms, for the Canonical Polyadic Decomposition.

\noindent The function definition follows:
\begin{lstlisting}
CalsReport cp_cals(const Tensor &X, KtensorQueue &kt_queue, CalsParams &params);
\end{lstlisting}

\paragraph{Input}
\begin{itemize}
    \item \code{X}: Target tensor to be decomposed.
    \item \code{kt\_queue}: A queue of references to the input Ktensors, which need to be fitted to the target tensor using ALS.
    \item \code{params}: Parameters for the algorithm, of type \code{CalsParams}.
\end{itemize}

\code{CalsParams} is a struct containing all the parameters that can be given to \code{cp\_cals}. Those include:

\begin{itemize}

\item \code{update\_method}: Method for updating factor matrices. Possible values \{UNCONSTRAINED, NNLS\}
\item \code{dim\_t max\_iterations}: Maximum number of iterations before evicting a model.
\item \code{double tol}: Tolerance of fit difference between consecutive iterations.
\item \code{bool line\_search}: Whether to use line search.
\item \code{int line\_search\_interval}: Number of iterations when line search is invoked.
\item \code{double line\_search\_step}: Factor for line search.
\item \code{bool cuda}: Use CUDA (to use this verify taht code is compiled with CUDA support).
\item \code{dim\_t buffer\_size}: Maximum size of the multi-factor columns (sum of ranks of concurrent models)

\end{itemize}


\subsection{MATLAB}
The function \code{cp\_cals} in file \code{matlab/matlab\_src/cp\_cals.m} is the function that computes CP-CALS for MATLAB. Please, refer to that file for detailed documentation on how to invoke this function within MATLAB.

\section{Examples}

\code{build/src/examples/driver} contains a demonstration of how to use CALS (The -h flag is supported for a look at possible input arguments).

\subsection{MATLAB examples}

After compiling the MATLAB MEX, one can execute file \code{matlab/matlab\_src/TTB\_vs\_CALS.m} in MATLAB. This executable performs a comparison of TensorToolbox and CALS. The user first needs to point MATLAB to the CALS MEX and the Tensor Toolbox source code by editing the first two lines of the file.


\end{document}
