
\section{Output Files}
\label{sec:output_files}


In this section, we describe the formats of the plain-text output files from Bertini\_real.
We document abstractly, and let the user explore concretely by generating data.

By default, the output from Bertini\_real is dumped into a folder named {\tt output\_dim\_D\_comp\_C}, where {\tt D} and {\tt C} are the dimension and component numbers.  This can be overridden by specifying option {\tt -o} at runtime.







\subsection{Regardless of dimension}
\label{sec:output_dim_free}

Some files are produced regardless of object dimension:

\begin{itemize}
	\item {\tt decomp} -- \ref{sec:decomp}
	\item {\tt input\_dim\_D\_comp\_C\_deflated} -- a plain copy from Bertini\_real's input in the containing folder.
	\item {\tt run\_metadata} -- \ref{sec:run_metadata}
	\item {\tt V.vertex} -- \ref{sec:v.vertex}
	\item {\tt vertex\_types} -- \ref{sec:vertex_types}
	\item {\tt witness\_data} -- a plain copy from Bertini's output in the containing folder.
	\item {\tt witness\_set} -- \ref{sec:witness_set}
\end{itemize}

Additional important files written NOT into the output folder:
\begin{itemize}
	\item {\tt Dir\_Name} -- \ref{sec:dir_name}
\end{itemize}



\clearpage
\subsubsection{\tt output/decomp}
\label{sec:decomp}



\begin{center}\begin{minipage}{0.9\linewidth}
\begin{lstlisting}[language=c++, caption={\tt output/decomp}, captionpos=b]
input_filename
number_vars dimension // number_vars includes homvar

FOR // # is dimension
	number_vars_in_projection
	FOR
		proj_coord_real proj_coord_imag 
	END FOR
END FOR

number_patches

FOR // # is number_patches
	number_vars_in_patch
	FOR
		patch_coord_real patch_coord_imag 
	END FOR
END FOR

sphere_radius_real sphere_radius_imag
num_sphere_vars  // # is number natural variables
FOR // # is number natural variables
	sphere_center_coord_real sphere_center_coord_imag
END FOR

number_crit_fibers
FOR // # is number_crit_fibers
	crit_fiber_coord_real crit_fiber_coord_imag
END FOR
\end{lstlisting}
\end{minipage}\end{center}


\subsubsection{\tt output/run\_metadata}
\label{sec:run_metadata}

\begin{center}\begin{minipage}{0.9\linewidth}
\begin{lstlisting}[language=c++, caption={\tt output/decomp}, captionpos=b]
bertini_real_version
/path/to/containing/folder
timing statistics from Boost.Chrono
\end{lstlisting}
\end{minipage}\end{center}






\subsubsection{output/V.vertex}
\label{sec:v.vertex}


\begin{center}\begin{minipage}{0.9\linewidth}
\begin{lstlisting}[language=c++, caption={\tt output/V.vertex}, captionpos=b]
num_vertices num_projections  num_variables  num_filenames // number_vars includes homvar

FOR  // num is num_projections
	FOR // num is num coords incl homvar
		proj_coord_real proj_coord_imag
	END FOR
END FOR


FOR  // each filename
	num_chars_in_filename
	filename
END FOR

FOR // each vertex
	num_coords // may include synthetic variables
	FOR
		coord_real coord_imag
	END FOR

	num_projection_values
	FOR
		proj_val_real proj_val_imag
	END FOR

	input_filename_index
	vertex_type  // see file vertex_types
END FOR
\end{lstlisting}
\end{minipage}\end{center}


\subsubsection{output/vertex\_types}
\label{sec:vertex_types}


\begin{center}\begin{minipage}{0.9\linewidth}
\begin{lstlisting}[language=c++, caption={\tt output/vertex\_types}, captionpos=b]
num_vertex_types

FOR
	VertexType value
END FOR
\end{lstlisting}
\end{minipage}\end{center}


Versions of Bertini\_real prior to 1.4
used sequential type indices rather than binary values, to vertex types.  We converted to binary indices to allow vertices to have multiple types, and represent this compactly.  The Matlab visualization code takes advantage of this, and can plot points in each of the type categories they appear in.  The purpose of this file is to let one write code which self-adapts to any future vertex types.







\subsubsection{output/witness\_set}
\label{sec:witness_set}


\begin{center}\begin{minipage}{0.9\linewidth}
\begin{lstlisting}[language=c++, caption={\tt output/witness\_set}, captionpos=b]
num_points dimension component_number

FOR  // each point
	FOR  // each variable
		coord_real coord_imag
	END FOR
END FOR

num_linears num_vars
FOR // each linear
	FOR // each coordinate
		linear_coeff_real linear_coeff_imag
	END FOR
END FOR

num_patches num_vars
FOR // each patch
	FOR // each coordinate
		patch_coeff_real patch_coeff_imag
	END FOR
END FOR


\end{lstlisting}
\end{minipage}\end{center}




\subsubsection{/Dir\_Name}
\label{sec:dir_name}


\begin{center}\begin{minipage}{0.9\linewidth}
\begin{lstlisting}[language=c++, caption={\tt output/V.vertex}, captionpos=b]
/path/to/output/folder
MPType  // why?  I don't know, it seemed important early on.  
dimension 
\end{lstlisting}
\end{minipage}\end{center}

















\clearpage
\subsection{Curve files}
\label{sec:curve_files}

There are several files written for every curve decomposed, into the containing folder.  For surfaces, each sub-curve is written to its own sub-folder, appropriately named.

\begin{itemize}
	\item {\tt output/curve.cnums} -- \ref{sec:curve.cnums}
	\item {\tt output/E.edge} -- \ref{sec:e.edge}
	\item {\tt output/samp.curvesamp} -- \ref{sec:samp.curvesamp}
\end{itemize}


\subsubsection{\tt output/curve.cnums}
\label{sec:curve.cnums}


This file contains the cycle numbers of the paths, tracked from the generic midpoint to the left and right points.  Degenerate edges get 0's because there is no path.  Otherwise, the numbers are at least 1.

\begin{center}\begin{minipage}{0.9\linewidth}
\begin{lstlisting}[language=c++, caption={\tt output/curve.cnums}, captionpos=b]
number_edges

FOR // each edge
	going_left going_right
END FOR
\end{lstlisting}
\end{minipage}\end{center}



\subsubsection{\tt output/E.edge}
\label{sec:e.edge}

These are 0-based indices into {\tt V.vertex}.

\begin{center}\begin{minipage}{0.9\linewidth}
\begin{lstlisting}[language=c++, caption={\tt output/E.edge}, captionpos=b]
number_edges

FOR // each edge
	left mid right
END FOR
\end{lstlisting}
\end{minipage}\end{center}






\subsubsection{\tt output/samp.curvesamp}
\label{sec:samp.curvesamp}

The curve sampling file contains points in order, on edges.  The points are referred to by 0-based indices into a new V.vertex file created, preserving the initial one from the decomposition.

\begin{center}\begin{minipage}{0.9\linewidth}
\begin{lstlisting}[language=c++, caption={\tt output/samp.curvesamp}, captionpos=b]
num_edges

FOR // each edge
	num_samples_on_edge
	FOR // each sample on edge
		sample_index
	END FOR
END FOR
\end{lstlisting}
\end{minipage}\end{center}






\clearpage
\subsection{Surface files}
\label{sec:surface_files}


\begin{itemize}
	\item {\tt output/F.faces} -- \ref{sec:f.faces}
	\item {\tt output/S.surf} -- \ref{sec:s.surf}
	\item {\tt output/samp.surfsamp} -- \ref{sec:samp.surfsamp}
\end{itemize}

\subsubsection{\tt F.faces}
\label{sec:f.faces}
\begin{center}\begin{minipage}{0.9\linewidth}
\begin{lstlisting}[language=c++, caption={\tt output/F.faces}, captionpos=b]
number_faces

FOR // each face
	midpoint
	critslice_index
	top_edge_index bottom_edge_index
	system_name_top system_name_bottom

	num_left_edges
	FOR // each left edge
		edge_index
	END FOR

	num_right_edges
	FOR // each right edge
		edge_index
	END FOR
END FOR
\end{lstlisting}
\end{minipage}\end{center}

\subsubsection{\tt S.surf}
\label{sec:s.surf}

\begin{center}\begin{minipage}{0.9\linewidth}
\begin{lstlisting}[language=c++, caption={\tt output/S.surf}, captionpos=b]
number_faces 0 num_midslices num_critslices

number_singular_curves
FOR // each singular curve
	singcurve_multiplicity index
END FOR
\end{lstlisting}
\end{minipage}\end{center}



\subsubsection{\tt output/samp.surfsamp}
\label{sec:samp.surfsamp}



\begin{center}\begin{minipage}{0.9\linewidth}
\begin{lstlisting}[language=c++, caption={\tt output/samp.surfsamp}, captionpos=b]
num_faces

FOR // each face
	num_triangles_on_face
	FOR // each triangle
		vert_1 vert_2 vert_3
	END FOR
END FOR
\end{lstlisting}
\end{minipage}\end{center}


