Commit ed9ff3bb authored by Andrew Bauer's avatar Andrew Bauer

Adding in Catalyst UG with first draft of update from Word doc.

parent 2df30684
......@@ -2,4 +2,13 @@ cmake_minimum_required(VERSION 2.8)
project(UsersGuides)
set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} ${CMAKE_CURRENT_SOURCE_DIR})
add_subdirectory(ParaView)
option(ParaView_UG "Build ParaView User's Guide" ON)
if(ParaView_UG)
add_subdirectory(ParaView)
endif()
option(ParaViewCatalyst_UG "Build ParaView Catalyst User's Guide" OFF)
if(ParaViewCatalyst_UG)
add_subdirectory(ParaViewCatalyst)
endif()
\ No newline at end of file
\section{Appendix}
\subsection{vtkWeakPointer, vtkSmartPointer and vtkNew}
To simplify reference counting, vtkWeakPointer, vtkSmartPointer and vtkNew can be used.
vtkWeakPointer stores a pointer to an object but doesn’t change the reference count. When the
object gets deleted vtkWeakPointer will get initialized to NULL avoiding any dangling
references. The latter two classes keep track of other vtkObjects by managing the object's
reference count. When these objects are created, they increment the reference count of the
object they are referring to and when they go out of scope, they decrement the reference count
of the object they are referring to. The following example demonstrates this.
\begin{cpplst}
{
vtkNew<vtkDoubleArray> a; // a's ref count = 1
a->Setame(``an array'');
vtkSmartPointer<vtkPointData> pd =
vtkSmartPointer<vtkPointData>::New(); // pd's ref count = 1
pd->AddArray(a.GetPointer()); // a's ref count = 2
vtkSmartPointer<vtkDoubleArray> a2 =
vtkSmartPointer<vtkDoubleArray>::New(); // a2's ref count = 1
pd->AddArray(a2); // a2's ref count = 2
vtkWeakPointer<vtkPointData> pd2;
pd2 = pd; // pd's ref count = 1
vtkPointData* pd3 = vtkPointData::New();
pd2 = pd3;
pd3->Delete(); // pd3 is deleted
pd2->GetClassName(); // bug!
} // don't need to call Delete on any object
\end{cpplst}
Note that when passing a pointer returned from vtkNew as a parameter to a method that the
GetPointer() method must be used. Other than this caveat, vtkSmartPointer and vtkNew objects
can be treated as pointers.
\section{Building ParaView Catalyst}
This section is targeted towards those users or developers responsible for building ParaView
Catalyst. As far as installation is concerned, Catalyst is a subset of the ParaView code base.
Thus, all of the functionality available in Catalyst is also available in ParaView. The difference is
that ParaView will by default have many more dependencies and thus will have a larger
executable size. Catalyst is the flexible and specialized configuration of ParaView that is used to
reduce the executable size by reducing dependencies. For example, if no output images are to
be produced from a Catalyst-instrumented simulation run then all of the ParaView and VTK
code related to rendering and the OpenGL libraries need not be linked in. This can result in
significant memory savings, especially when considering the number of processes utilized when
running a simulation at scale. In one simple example, the executable size was reduced from 75
MB when linking with ParaView to less than 20 MB when linking with Catalyst.
The main steps for configuring Catalyst are:
\begin{enumerate}
\item Setting up an “edition”
\item Extract the desired code from ParaView source tree into a separate Catalyst source tree
\item Build Catalyst
\end{enumerate}
Most of the work is in the first step which is described below. A Catalyst edition is a
customization of ParaView to support a desired subset of functionality from ParaView and VTK.
There can be many editions of Catalyst and these editions can be combined to create several
customized Catalyst builds. Assuming that the desired editions have already been created, the
second step is automated and is done by invoking the following command from the
\textless ParaView\_source\_dir\textgreater /Catalyst directory:
\begin{cpplst}
python catalyze.py -i <edition_dir> -o <Catalyst_source_dir>
\end{cpplst}
Note that more editions can be added with the -i \textless edition\_dir\textgreater and that these are processed in
the order they are given, first to last. For the minimal base edition included with ParaView, this
would be -i Editions/Base. The generated Catalyst source tree will be put in
\textless Catalyst\_source\_dir\textgreater. For configuring Catalyst from the desired build directory, do the
following:
\begin{cpplst}
<Catalyst_source_dir>/cmake.sh <Catalyst_source_dir>
\end{cpplst}
The next step is to build Catalyst (e.g. using make on Linux systems).
\subsection{Creating a ParaView Catalyst Edition}
The main operations for creating an edition of Catalyst are:
\begin{enumerate}
\item Set CMake build parameters (e.g. static or shared library build).
\item Specify files from the ParaView source tree to be copied into the created Catalyst source tree.
\item Specify files from the edition to be copied into the Catalyst source tree.
\end{enumerate}
The information describing which files are in the generated Catalyst source tree is all stored in a
JSON file called manifest.json in the main directory of the edition. The user processes this
information with a Python script called catalyze.py that is located in the
\textless ParaView\_source\_dir\textgreater/Catalyst directory.
\subsection{Setting CMake Build Parameters}
By default, Catalyst will be built with the default ParaView build parameters (e.g. build with
shared libraries) unless one of the Catalyst editions changes that in its manifest.json file. An
example of this is shown below:
\begin{python}
``cmake'':{
``cache'':[
{
``name'':``BUILD\_SHARED\_LIBS'',
``type'':``BOOL'',
``value'':``OF''
}
]
}
\end{python}
Here, ParaView’s CMake option of building shared libraries will be set to OFF. It should be
noted that users can still change the build configuration from these settings but it should be
done after Catalyst is configured with the cmake.sh script.
\subsection{Copying Files from the ParaView Source Tree into the Created Catalyst Source Tree}
By default, very little source code from the ParaView source tree will be copied to the generated
Catalyst source tree. Each edition will likely want to add in several source code files to the
Catalyst source tree. Most of these files will be filters but there may also be several helper
classes that are needed to be copied over as well. In the following JSON snippet we
demonstrate how to copy the vtkPVArrayCalculator class into the generated Catalyst source
tree.
\begin{python}
``modules'':[
{
``name'':``vtkPVVTKExtensionsDefault'',
``path'':``ParaViewCore/VTKExtensions/Default''
``include'':[
{
``path'':``vtkPVArrayCalculator.cxx''
},
{
``path'':``vtkPVArrayCalculator.h''
}
],
``cswrap'':true
}
}
]
\end{python}
A description of the pertinent information follows:
\begin{itemize}
\item "name":"vtkPVVTKExtensionsDefault" – the name of the VTK or ParaView module.
In this case it is vtkPVVTKExtensionsDefault. The name of the module can be found
in the modules.cmake file in the corresponding directory. It is the first argument to the
vtk\_module() function.
\item "path":"ParaViewCore/VTKExtensions/Default" – the subdirectory location of the
module relative to the main ParaView source tree directory (e.g.
\textless ParaView\_source\_dir\textgreater/ParaViewCore/VTKExtensions/Default in this case)
\item ``path'':``vtkPVArrayCalculator.cxx'' – the name of the file to copy from the ParaView
source tree to the generated Catalyst source tree.
\item ``cswrap'':true – if the source code needs to be client-server wrapped such that it is
available through ParaView’s server-manager. For filters that are used through
ParaView’s Python interface or through a server-manager hard-coded \Cplusplus pipeline
this should be tree. For helper classes this should be false.
\end{itemize}
The difficult part here is determining which files need to be included in Catalyst. In the example
above, the actual name of the ParaView proxy for the vtkPVArrayCalculator is Calculator. Thus,
to construct a ParaView client proxy for vtkPVArrayCalculator on the server, the user would
need to call Calculator() in the Python script. The best way to determine this connection
between the name of the ParaView proxy and the actual source code is in the XML files in the
ParaViewCore/ServerManager/SMApplication/Resources. In this case the proxy definition is in
the filters.xml file. The proxy label XML element will be converted into the Python constructor for
the proxy and the class name is stored in the proxy class XML element. The conversion of the
proxy label is done by removing spaces in the XML attribute. This is sufficient for many
situations but for some cases there will be additional classes needed to be included in order to
properly compile Catalyst. This can occur when the included source code derives from a class
not already included in Catalyst or uses helper classes not already included in Catalyst. For the
vtkPVArrayCalculator class we will also need to include the vtkArrayCalculator class that it
derives from.
\subsection{Copying files from the edition into the Catalyst source tree}
Some of the files that need to be in the generated Catalyst source tree cannot be directly copied
over from the ParaView source tree. For example, CMakeLists.txt files need to be modified in
the Catalyst source tree when multiple editions need to added into a specialized CMakeLists.txt
file in the same directory. This is done with the “replace” keyword. An example of this is shown
below for the vtkFiltersCore module. Here, the vtkArrayCalculator source code is added to the
Catalyst source tree and so the CMakeLists.txt file in that directory needs to be modified in
order to include that class to be added to the build.
\begin{python}
``modules'':[
{
``name'':``vtkFiltersCore'',
``path'':``VTK/Filters/Core'',
``include'':[
{
``path'':``vtkArrayCalculator.cxx''
},
{
``path'':``vtkArrayCalculator.h''
}
],
``replace'':[
{
``path'':''VTK/Filters/Core/CMakeLists.txt''
}
],
``cswrap'':true
}
]
\end{python}
In this case, the CMakeLists.txt file that needs to be copied to the Catalyst source tree exists in
the \textless edition\_dir\textgreater/VTK/Filters/Core directory, where edition\_dir is the location of this custom
edition of Catalyst. Since the Base edition already includes some files from this directory, we
want to make sure that the CMakeLists.txt file from this edition also includes those from the
Base edition. This CMakeLists.txt file is shown below:
\begin{python}
set(Module_SRCS
vtkArrayCalculator.cxx
vtkCellDataToPointData.cxx
vtkContourFilter.cxx
vtkContourGrid.cxx
vtkContourHelper.cxx
vtkCutter.cxx
vtkExecutionTimer.cxx
vtkFeatureEdges.cxx
vtkGridSynchronizedTemplates3D.cxx
vtkMarchingCubes.cxx
vtkMarchingSquares.cxx
vtkPointDataToCellData.cxx
vtkPolyDataNormals.cxx
vtkProbeFilter.cxx
vtkQuadricClustering.cxx
vtkRectilinearSynchronizedTemplates.cxx
vtkSynchronizedTemplates2D.cxx
vtkSynchronizedTemplates3D.cxx
vtkSynchronizedTemplatesCutter3D.cxx
vtkThreshold.cxx
vtkAppendCompositeDataLeaves.cxx
vtkAppendFilter.cxx
vtkAppendPolyData.cxx
vtkImageAppend.cxx
)
set_source_files_properties(
vtkContourHelper
WRAP_EXCLUDE
)
vtk_module_library(vtkFiltersCore ${Module_SRCS})
\end{python}
Note that this CMakeLists.txt file does two things. Firstly it specifies which files to be compiled in
the source directory. Next, it specifies properties of the source files. In the above example,
vtkContourHelper is given a property specifying that it should not be wrapped. Another property
which is commonly set indicates that a class is an abstract class (i.e. it has pure virtual
functions). An example of how to do this is shown below.
\begin{python}
set_source_files_properties(
vtkXMLPStructuredDataWriter
vtkXMLStructuredDataWriter
ABSTRACT
)
\end{python}
include(UseLATEX)
add_latex_document(
ParaViewCatalystUsersGuide.tex
INPUTS
Introduction.tex
UserSection.tex
DeveloperSection.tex
BuildSection.tex
Examples.tex
References.tex
Appendix.tex
IMAGE_DIRS Images
DEFAULT_PDF
DEPENDS multicols.sty
USE_INDEX
MANGLE_TARGET_NAMES
)
This diff is collapsed.
\section{Examples}
There are a wide variety of VTK examples at \url{www.vtk.org/Wiki/VTK/Examples}. This site
includes both C, \Cplusplus, Fortran and Python examples but is targeted for general VTK development.
Examples specific to ParaView Catalyst can be found at
\url{www.github.com/Kitware/ParaViewCatalystExampleCode}.
This diff is collapsed.
This diff is collapsed.
\documentclass[letterpaper,10pt,draft]{book}
\usepackage[
paper=letterpaper,
lmargin=1in,
rmargin=1in,
tmargin=1in,
bmargin=1in]{geometry}
% to support adding an image on the title page.
\usepackage{titlepic}
% for adding index. Use \index{key} to put index keywords.
\usepackage{multind}
\makeindex{keyword}
\makeindex{python}
\makeindex{ui}
% Use the extra list environments. This package provides
% compactenum, compactitem etc.
\usepackage{paralist}
% Now to get better table handling
\usepackage{tabularx}
% Use the AMS packages for better mathematical typesetting
\usepackage{amsmath}
\usepackage{amsfonts}
\usepackage{amssymb}
\usepackage[pdftex,final]{graphicx}
\usepackage{caption}
\usepackage{subcaption}
\usepackage[pdftex]{color}
\usepackage{setspace}
% package for subfigures
%\usepackage{subfigure}
% Use the varioref package for fancy references, \vref and friends
\usepackage{varioref}
% to minimize item separation in lists.
\usepackage{enumitem}
% bring in additional macros and stuff
\include{LatexMacros}
% Program listings need to be typeset
\usepackage[final]{listings}
\lstloadlanguages{C++,XML}
\lstset{language=C++, captionpos=b, basicstyle=\footnotesize, commentstyle=\scriptsize, breaklines=true, showstringspaces=false, tabsize=2, xleftmargin=5mm, xrightmargin=5mm}
\lstnewenvironment{cpplst}[1][]
{\lstset{language=C++, captionpos=b, basicstyle=\footnotesize, commentstyle=\scriptsize, breaklines=true,xleftmargin=5mm, xrightmargin=5mm, #1}
\singlespacing}
{\doublespacing}
\definecolor{Code}{rgb}{0,0,0}
\definecolor{Decorators}{rgb}{0.5,0.5,0.5}
\definecolor{Numbers}{rgb}{0.5,0,0}
\definecolor{MatchingBrackets}{rgb}{0.25,0.5,0.5}
\definecolor{Keywords}{rgb}{0,0,1}
\definecolor{self}{rgb}{0,0,0}
\definecolor{Strings}{rgb}{0,0.63,0}
\definecolor{Comments}{rgb}{0,0.63,1}
\definecolor{Backquotes}{rgb}{0,0,0}
\definecolor{Classname}{rgb}{0,0,0}
\definecolor{FunctionName}{rgb}{0,0,0}
\definecolor{Operators}{rgb}{0,0,0}
\definecolor{Background}{rgb}{0.98,0.98,0.98}
\lstnewenvironment{python}[1][]{
\lstset{
numbers=left,
numberstyle=\footnotesize,
numbersep=1em,
xleftmargin=1em,
framextopmargin=2em,
framexbottommargin=2em,
showspaces=false,
showtabs=false,
showstringspaces=false,
frame=l,
tabsize=4,
% Basic
basicstyle=\ttfamily\small\setstretch{1},
backgroundcolor=\color{Background},
language=Python,
% Comments
commentstyle=\color{Comments}\slshape,
% Strings
stringstyle=\color{Strings},
morecomment=[s][\color{Strings}]{"""}{"""},
morecomment=[s][\color{Strings}]{'''}{'''},
% keywords
morekeywords={import,from,class,def,for,while,if,is,in,elif,else,not,and,or,print,break,continue,return,True,False,None,access,as,,del,except,exec,finally,global,import,lambda,pass,print,raise,try,assert},
keywordstyle={\color{Keywords}\bfseries},
% additional keywords
morekeywords={[2]@invariant},
keywordstyle={[2]\color{Decorators}\slshape},
emph={self},
emphstyle={\color{self}\slshape},
%
}}{}
\newcommand{\mytitle}{\textbf{ParaView Catalyst User's Guide}}
% Make fancy headers and everything...
\usepackage{fancyhdr}
\pagestyle{fancy}
% Headers - left, center and right.
\lhead{}
\chead{\mytitle}
\rhead{}
% Footers - as before
%\lfoot{\scriptsize \emph{\svnInfoFile}}
\cfoot{\small \thepage}
%\rfoot{\scriptsize \emph{Rev: \svnInfoRevision , \svnInfoDate}}
\renewcommand{\headrulewidth}{0.5pt}
\renewcommand{\footrulewidth}{0.5pt}
%\addtolength{\headheight}{0.5pt} % make space for the rule
\setlength{\headheight}{14pt}
\fancypagestyle{plain}{%
\fancyhead{} % get rid of headers on plain pages
\renewcommand{\headrulewidth}{0pt} % and the line
}
% Now to define several macros for commonly used abbreviations and such
\usepackage{xspace}
\newcommand{\fixme}[1]{\footnote{{\color{red}#1}}}
\newcommand{\note}[1]{{\small\color{blue}[#1]}}
\newcommand{\todo}[1]{{\large\color{red}[TODO: #1]}}
%\newcommand{\todo}[1]{}
%\newcommand{\note}[1]{}
% formatting for C++
\def\Cplusplus{C\raisebox{0.5ex}{\tiny\textbf{++}} }
% Use the cite package to better organise citations
\usepackage[superscript]{cite}
% Put [] around the superscript citations
\makeatletter
\def\@citess#1{\textsuperscript{[#1]}}
\usepackage{url}
% Use in the form \url{http://mysite.co.uk/~marcus/} or \url!http://mysite.co.uk/~marcus/!
\usepackage{colortbl}
% 21st century - make some real links in the PDF, but keep the colors reasonable...
\usepackage[colorlinks=true,urlcolor=blue,citecolor=black,linkcolor=black,final=true]{hyperref}
\usepackage{wrapfig}
% for multi-columns lists and such
\usepackage{multicols}
% for individual captions for subfigures
\usepackage{caption}
\usepackage{subcaption}
\title{\mytitle{}}
\author{Andrew C. Bauer, Berk Geveci, Will Schroeder}
%\date{}
\titlepic{\includegraphics[width=\textwidth]{Images/catalystlogo.png}}
\begin{document}
\maketitle
\include{ContributorNotes}
\tableofcontents
%------------------------------------------------------------------------------
\chapter{Introduction to ParaView Catalyst}
\label{chapter:Introduction}
\include{Introduction}
\chapter{ParaView Catalyst for Users}
\label{chapter:UserSection}
\include{UserSection}
\chapter{ParaView Catalyst for Developers}
\label{chapter:DeveloperSection}
\include{DeveloperSection}
\chapter{Building ParaView Catalyst}
\label{chapter:BuildSection}
\include{BuildSection}
\chapter{Examples}
\label{chapter:Examples}
\include{Examples}
\chapter{References}
\label{chapter:References}
\include{References}
\chapter{Appendix}
\label{chapter:Appendix}
\include{Appendix}
%------------------------------------------------------------------------------
\end{document}
\section{References}
\begin{itemize}
\item ``Data Co-Processing for Extreme Scale Analysis Level II ASC Milestone''. David Rogers,
Kenneth Moreland, Ron Oldfield, and Nathan Fabian. Tech Report SAND 2013-1122,
Sandia National Laboratories, March 2013.
\item ``The ParaView Coprocessing Library: A Scalable, General Purpose In Situ Visualization
Library''. Nathan Fabian, Kenneth Moreland, David Thompson, Andrew C. Bauer, Pat
Marion, Berk Geveci, Michel Rasquin, and Kenneth E. Jansen. In IEEE Symposium on
Large-Scale Data Analysis and Visualization (LDAV), October 2011, pp. 89–96. DOI
10.1109/LDAV.2011.6092322.
\item ``The Visualization Toolkit: An Object Oriented Approach to 3D Graphics''. Will
Schroeder, Ken Martin, and Bill Lorensen. Kitware Inc., fourth edition, 2004. ISBN 1-
930934-19-X.
\item ``The ParaView Guide: A Parallel Visualization Application''. Utkarsh Ayachit et al.
Kitware Inc., 4th edition, 2012. ISBN 978-1-930934-24-5.
\end{itemize}
This diff is collapsed.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment