%% if you are submitting an initial manuscript then you should have submission as an option here
%% if you are submitting a revised manuscript then you should have revision as an option here
%% otherwise options taken by the article class will be accepted
\documentclass[finalversion]{FPSAC2018}
\articlenumber{97}
%% but DO NOT pass any options (or change anything else anywhere) which alters page size / layout / font size etc

%% note that the class file already loads {amsmath, amsthm, amssymb}

\usepackage{verbatim}
\usepackage{tikz}



%----------------------------
% New Commands
%----------------------------

\newcommand{\packageFont}[1]{\textit{#1}}

\newcommand{\Vis}{\packageFont{Visualize}\ }
\newcommand{\Visp}{\packageFont{Visualize}}
\newcommand{\M}{\packageFont{Macaulay2}\ }
\newcommand{\Mp}{\packageFont{Macaulay2}}
\newcommand{\G}{\packageFont{Graphs}\ }
\newcommand{\Gp}{\packageFont{Graphs}}
\newcommand{\Po}{\packageFont{Posets}\ }
\newcommand{\Pop}{\packageFont{Posets}}
\newcommand{\SC}{\packageFont{SimplicialComplexes}\ }
\newcommand{\SCp}{\packageFont{SimplicialComplexes}}

\newcommand{\js}{JavaScript\ }
\newcommand{\jsp}{JavaScript}

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

\newtheorem{thm}{Theorem}[section]
\newtheorem{lem}[thm]{Lemma}


%% define your title in the usual way
\title{Visualizing combinatorial objects in Macaulay2}

%% define your authors in the usual way
%% use \addressmark{1}, \addressmark{2} etc for the institutions, and use \thanks{} for contact details
\author{Brett
Barwick\thanks{\href{mailto:bbarwick@uscupstate.edu}{bbarwick@uscupstate.edu}.
B.B. was partially supported by NSA Grant No.
H98230-10-1-0361.}\addressmark{1}, 
Thomas
Enkosky\thanks{\href{mailto:tomenk@bu.edu}{tomenk@bu.edu}}\addressmark{2}, 
Branden
Stone\thanks{\href{mailto:bstone@hamilton.edu}{bstone@hamilton.edu}}\addressmark{3}, 
\and Jim
Vallandingham\thanks{\href{mailto:vlandham@gmail.com}{vlandham@gmail.com}}\addressmark{4}}

%% then use \addressmark to match authors to institutions here
\address{
\addressmark{1}Division of Mathematics and Computer Science, University of South Carolina Upstate, 800 University Way, Spartanburg, SC 29303 \\
%
\addressmark{2}Mathematics and Statistics, Boston University, 111 Cummington Mall, Boston, MA 02215 \\
%
\addressmark{3}Mathematics Department, Hamilton College, 198 College Hill Road, Clinton, NY 13323 \\
%
\addressmark{4}Data Visualization Engineer, \url{http://vallandingham.me/}
}


%% put the date of submission here
\received{\today}

%% leave this blank until submitting a revised version
%\revised{}

%% put your English abstract here, or comment this out if you don't have one yet
%% please don't use custom commands in your abstract / resume, as these will be displayed online
%% likewise for citations -- please don't use \cite, and instead write out your citation as something like (author year)
\abstract{Using JavaScript, this package creates interactive visualizations of a variety of objects in a modern browser. The user has the ability to manipulate the object, run various tests, and compute invariants. Once finished, the user can export the result back to the Macaulay2 session.}

%% put your French abstract here, or comment this out if you don't have one
% \resume{\lipsum[2]}

%% put your keywords here, or comment this out if you don't have them yet
\keywords{Macaulay2, Graph, Poset, Simplicial Complex, Newton Polytope}

%% you can include your bibliography however you want, but using an external .bib file is STRONGLY RECOMMENDED and will make the editor's life much easier
%% regardless of how you do it, please use numerical citations, ie. [xx, yy] in the text

%% this sample uses biblatex, which (among other things) takes care of URLs in a more flexible way than bibtex
%% but you can use bibtex if you want
\usepackage[backend=bibtex]{biblatex}
\addbibresource{97-Barwick-Enkosky-Stone-Vallandingham.bib}
%% note the \printbibliography command at the end of the file which goes with these biblatex commands

\begin{document}

\maketitle
%% note that you DO NOT have to put your abstract here -- it is generated by \maketitle and the \abstract and \resume commands above


% A description of the context and state of the art
% will not work on http://web.macaulay2.com beacuse you cannot open a browser from there
\section{Introduction and Current State}\label{intro}

The computer algebra system (CAS) \M \cite{M2} has been funded by the National Science Foundation since 1992 and focuses mainly on algebraic geometry and commutative algebra. However, the \M community has also created many great packages to aid in the study of algebraic combinatorics. For example, the \SC package allows users to compute the $f$-vector, homology, and Alexander dual of a given simplicial complex, among other important invariants. The \Po package provides functionality for analyzing poset structures such as the intersection lattice of a hyperplane arrangement or an LCM lattice. In this note we discuss a new package, \Visp, which allows users to visually interact with combinatorial objects created by previously established packages such as these. This interaction has the potential to aid in both teaching and research. 

The \Vis package for \M  utilizes the \js library D3 \cite{D3} to bind mathematical objects to a document object model (DOM). Once bound, these objects can be displayed and interacted with in a modern browser. The browser then becomes a portal to \Mp, allowing the user to visually edit, test, and manipulate the object before sending it back to \M for analysis with more sophisticated tools. For example, if the user wants to delete an edge from a graph, they can simply select the edge with the cursor and press the delete key.  Adding an edge to a graph is as simple as dragging and dropping the edge from one existing vertex to another. Once the desired graph is constructed, the object can be sent back to \M for further study. 

Currently \Vis supports interaction with the \Gp, \Pop, and \SC packages and a stable version is integrated in \Mp, version 1.10. The package also has the ability to create a Newton polytope associated to a monomial ideal in a polynomial ring in 2 or 3 variables and allows the user to export each visualization as TikZ code, suitable for inclusion in a manuscript. Unfortunately \Vis will not work on the \M server \cite{M2web} or with CoCalc \cite{CoCalc} as there is no display environment. As such, \M must be installed on the user's machine in order to use \Visp; this process will be discussed in Section~\ref{access}. 

In Section~\ref{application} we give examples of the functionality of \Vis and a basic workflow. Further, we provide comparisons to other programs with similar functionality in Section~\ref{compare}.


% A description of the software itself: main functionalities and algorithms, ...
% A description of typical applications and use cases
\section{Main Functionalities and Applications}\label{application}

The primary function of the \Vis package is to create an interactive user interface with \M via a modern browser. The user experience is centered around 3 methods: \meth{openPort}, \meth{visualize}, and \meth{closePort}. The basic workflow for this package begins by requiring the user to open a port for communication between \M and the web browser. Once the port is open, the \meth{visualize} method can be used freely. The general workflow is as follows:

\begin{enumerate}
	\item Load or install the \Vis package.

	\item Open a port with the \meth{openPort} method for communication with the browser. It is up to the user to choose a port and also to close the port when finished.

	\item\label{three} Define an object to visualize. For example, a graph, poset, digraph, etc.

	\item Run the \meth{visualize} method, passing the previously created object as an input. This will open the browser with an interactive interface. This session is in communication with \M through the open port above. At this point, the user can edit and manipulate the created object.

	\item\label{five} End the session, which automatically exports any edits made to the object back to \Mp.

	\item Continue manipulating and studying the object in \Mp,
	repeating steps \ref{three}--\ref{five} as necessary.

	\item When finished, either close the port with \meth{closePort} or restart \Mp.
\end{enumerate}     


\subsection{Visualizing Data}

%The main method used to visualize objects is \meth{visualize}. Given an open port, this method will create an interactive visualization of a variety of objects in a modern browser. While viewing the object, the user has the ability to manipulate it and run various tests. Once finished, the user can export the finished result back to the \M session. 
In the following we give an application of the \meth{visualize} method in conjunction with the \G package. As mentioned above, the \Po and \SC packages are also supported. %; many of the features are similar. 
     
In order to use the \meth{visualize} method, the user must first open a port on their machine. This could potentially be dangerous as someone could be listening on that port. However, the open port is only accessible to the localhost and is most vulnerable if the package is being run on a server. The user may choose any port number they wish. Common ports are 8080 and 8081. For example, 
\begin{verbatim}
    i1 : needsPackage "Visualize"
    o1 = Visualize
    o1 : Package

    i2 : openPort "8080"
    --Port $localhost:8080 is now open.
\end{verbatim}
%
With an open port, constructing an object in the browser is not much different than constructing the object normally. For example, to create a graph in \M we would use the following commands. 
%
\begin{verbatim}	
    i3 : needsPackage"Graphs"
    o3 = Graphs
    o3 : Package

    i4 : G = graph({{1,2},{1,3},{2,3},{3,4}},Singletons=>{5});
\end{verbatim}
%
To visualize this in the browser, we use the \meth{visualize} method.
%
\begin{verbatim}
    i5 : visualize G
    -- Visualizing. Your browser should open automatically.
    -- Click 'End Session' in the browser when finished.	
\end{verbatim}
%
At this point the user's default browser will open with an interactive session similar to what is shown in Figure \ref{figure1}. 
%
\begin{figure}
	\begin{center}
		\fbox{\includegraphics[width = .75\textwidth]{graphpic2.pdf}}
	\end{center}
	\caption{An interactive visualization of the graph in the browser.}
	\label{figure1}
\end{figure}
%
With the graph displayed in the browser, the user has many options available. While the specific options vary depending on the object being visualized, the general concepts are all the same. Using the mouse, the vertices of the graph can be moved around and pinned to the canvas. Further, creation (and deletion) of edges and vertices is possible by simply clicking and dragging. 

The menu on the right side of the session provides options to enable/disable editing, show/hide labels, highlight neighbors of vertices, reset the positions of the nodes, and turn off the D3 force environment (which causes the vertices to move and naturally settle into an attractive layout). The browser interface also allows for exporting TikZ code of the graph as seen on the screen (currently only in grayscale) as well as the ability to run boolean tests or calculate numerical invariants that the \G package supports. 

Once the graph has been modified and/or tested, clicking 'End session' will export the graph in the browser back to \M for more sophisticated calculations and constructions. When finished, the \meth{closePort} command will close the port that was opened. 
%
\begin{verbatim}
    i6 : closePort()
    --Port $localhost:8080 is now closing. This could take a few seconds.	
\end{verbatim}
%
Restarting or quitting \M will also close the port. 

% A comparison with existing software or algorithms
\section{Comparison with Existing Software}\label{compare}

Graphing and interacting with objects is not a new feature for computer algebra software. In fact, almost all major platforms (Maple, Mathematica, MATLAB, SageMath, etc.) have interactive plotting capabilities. However, these interactions are usually centered around a sliding bar which may be used to adjust a parameter, causing a static image to refresh. Using \jsp, the combinatorial objects pictured by \Vis are not static and move across the screen when created. The user is then able to tweak the particular layout of the image, directly manipulating the object without a frame of reference to center the image. Also, the object can be edited and tested directly from the browser interface, creating a new object that can be sent back to \M for further investigation. To the best of the authors' knowledge, there is no other current program with this functionality that supports all of the structures supported by the \Vis package. The closest comparable open source software package we could find is GraphViz \cite{Gansner00}.  This program has been in development for almost two decades, and as such provides more robust visualization options than our package for graphs and digraphs, especially with a large number of vertices and edges.  However this software cannot interface directly with \M and also does not natively handle posets or simplicial complexes.  While some applets and software packages have been developed for visualizing posets and/or simplicial complexes (for example \cite{Jipsen}, \cite{Freese}, and \cite{visualsc}), these software packages also do not interface natively with any computer algebra system and most do not allow the user to interact with and manipulate the objects in real-time.

Before \Visp, \M did not have any interactive visualizations for the supported packages. While some packages did support the generation of static images of graphs, posets, and Newton polytopes, the user did not have any control over the design of the image or any way to interact visually with the object.

% As \Vis is strictly an interface between \M and the browser, the functionality of the package is inherently limited to the packages that \M supports. 


% Brief evidence for the ease of use and reuse: documentation, examples of usage, availability, license, software requirements, installation instructions, (plans for) integration in existing platforms (e.g. GAP, Magma, Maple, Mathematica, or SageMath).
% Brief evidence for software quality and sustainability: tests, development model, use of collaborative tools, etc.
\section{Ease of Use and Sustainability}\label{access}

The \Vis package has been available with \M starting with version 1.10. The user only needs to run \meth{needsPackage "Visualize"} as detailed above to have access to the package. Funded by the NSF since 1992, \M is open source and available for download at \href{http://macaulay2.com}{http://macaulay2.com} for Linux and MacOS platforms. Full documentation for \Vis is available on the \M website as well as locally by running the following in \Mp.
%
\begin{verbatim}
    i7 : installPackage "Visualize"

    i8 : viewHelp Visualize
\end{verbatim}
%
The documentation contains detailed examples for each of the supported packages. Currently \Vis only supports three packages: \Gp, \Pop, and \SCp. The authors plan to continue development and extend support to other packages in the future. 

As of version 0.8, \Vis does not have any tests implemented. Most of the code is written in \js and relies on connection to the \M server for the visualizations to be created. As far as we know, the unit testing framework available in \M is not able to handle this situation. As such, we currently rely on users to post issues to the development repository on GitHub \cite{visualizeGH}.


\acknowledgements{
	We are grateful to the following people who have generously contributed code or worked on our code at various \M workshops: Ata Firat Pir, Elliot Korte, Will Smith, and Julio Urenda. We are also extremely thankful to Dan Grayson and Mike Stillman for their help in facilitating communication between \M and the browser.

	Finally, we are thankful to the authors of the open source \js libraries \cite{D3,noUiSlider,BootSideMenu,Bootstrap,clipboard}. These libraries greatly enhanced the aesthetics and functionality of our package.
    }

%% if you use biblatex then this generates the bibliography
%% if you use some other method then remove this and do it your own way
\printbibliography

\end{document}

