Commits

Nathan Collier committed 75c90f4

initial commit

Comments (0)

Files changed (15)

+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER         =
+BUILDDIR      = _build
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+	@echo "  dirhtml    to make HTML files named index.html in directories"
+	@echo "  singlehtml to make a single large HTML file"
+	@echo "  pickle     to make pickle files"
+	@echo "  json       to make JSON files"
+	@echo "  htmlhelp   to make HTML files and a HTML help project"
+	@echo "  qthelp     to make HTML files and a qthelp project"
+	@echo "  devhelp    to make HTML files and a Devhelp project"
+	@echo "  epub       to make an epub"
+	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
+	@echo "  text       to make text files"
+	@echo "  man        to make manual pages"
+	@echo "  changes    to make an overview of all changed/added/deprecated items"
+	@echo "  linkcheck  to check all external links for integrity"
+	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
+
+clean:
+	-rm -rf $(BUILDDIR)
+
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml:
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+singlehtml:
+	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	@echo
+	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+pickle:
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files."
+
+json:
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+	@echo
+	@echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+	@echo
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/PetIGA.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/PetIGA.qhc"
+
+devhelp:
+	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+	@echo
+	@echo "Build finished."
+	@echo "To view the help file:"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/PetIGA"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/PetIGA"
+	@echo "# devhelp"
+
+epub:
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+	@echo
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+latex:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+	@echo "Run \`make' in that directory to run these through (pdf)latex" \
+	      "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through pdflatex..."
+	make -C $(BUILDDIR)/latex all-pdf
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text:
+	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+	@echo
+	@echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+	@echo
+	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+changes:
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	@echo
+	@echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/doctest/output.txt."
+.. role:: envvar(literal)
+.. role:: command(literal)
+.. role:: file(literal)
+.. role:: ref(title-reference)
+.. _OVERVIEW:
+
+Overview
+========
+
+PETSc provides a rich environment for modeling scientific applications
+as well as for rapid algorithm design and prototyping. The library
+enable easy customization and extension of both algorithms and
+implementations. This approach promotes code reuse and
+flexibility. PETSc is designed in an object-oriented style (in C also
+with Fortran interface), with components that may be changed via a
+command-line interface at runtime. A few of these objects and their
+types include:
+
+* Matrices (Mat) and Vectors (Vec)
+* Krylov subspace methods (KSP) and preconditioners (PC) 
+* Nonlinear solvers (SNES) and time stepping algorithms (TS)
+
+PetIGA can be thought of as a thin layer on top of PETSc which allows
+for parallel assembly of matrices and vectors coming from discretized
+integral equations. PetIGA is designed in the same style of PETSc,
+adding its own collection of objects. The commonly accessed ones are:
+
+* The context containing all the discretization information (IGA)
+* An axis in one parametric direction of the B-spline space (IGAAxis)
+* A edge/face of the B-spline space (IGABoundary)
+* A quadrature/collocation point (IGAPoint)
+
+
+.. Local Variables:
+.. mode: rst
+.. End:
+.. role:: option(literal)
+.. role:: file(literal)
+.. _TUTORIAL1:
+
+Tutorial 1 - Program Execution and Manipulation
+===============================================
+
+**Objective:** At the end of this tutorial you will understand how to
+run, query, and change different components of the Laplace solver.
+
+**Assumptions:** I assume that you have both PETSc and PetIGA
+configured and compiled. 
+
+Compilation and Execution
+-------------------------
+
+We will use the Laplace code included in the :file:`$PETIGA_DIR/demo/`
+directory to explain and highlight features of using PetIGA to solve
+partial differential equations. First enter this directory and build
+this application by typing::
+
+    make Laplace
+
+This code has been written to solve the Laplace equation on the unit
+domain in 1,2, or 3 spatial dimensions. The boundary conditions are
+Dirichlet on the left and free Neumann on the right, chosen such that
+the exact solution is *u = 1* no matter what spatial dimension
+is selected. To run this code, simply type::
+
+    ./Laplace -print_error
+
+The :file:`-print_error` is particular to this code and will print
+the *L2* norm of the exact error. 
+
+Query Components
+----------------
+
+The natural question is then how does one inquire what the code
+did. What discretization was used? Which solver? All of this can be
+determined without opening the source file. PETSc was built on the
+philosophy that solver components should be changeable from the
+command line, without requiring the code to be recompiled. This means
+that there are many options available. To see some of them type::
+
+    ./Laplace -help
+
+A long list of options will print along with short descriptions of
+what they control. Perusing this list is educational as it gives you
+an idea of just how much can be controlled from the command line. To
+see information about the default discretization, type::
+
+    ./Laplace -iga_view
+
+which will produce::
+
+    IGA: dim=2  dof=1  order=2  geometry=0  rational=0  property=0
+    Axis 0: periodic=0  degree=2  quadrature=3  processors=1  nodes=18  elements=16
+    Axis 1: periodic=0  degree=2  quadrature=3  processors=1  nodes=18  elements=16
+    Partitioning - nodes:    sum=324  min=324  max=324  max/min=1
+    Partitioning - elements: sum=256  min=256  max=256  max/min=1
+
+This view command tells you information about the function space that
+was chosen. We used a 2D quadratic polynomial space with no mapped
+geometries. Although we use general knot vectors, you can see by the
+relationship of the nodes to elements that we used *C1* quadratics. If
+run in parallel, :file:`-iga_view` will also provide information
+about how the problem was divided. For example, on 2 processors::
+
+    IGA: dim=2  dof=1  order=2  geometry=0  rational=0  property=0
+    Axis 0: periodic=0  degree=2  quadrature=3  processors=1  nodes=18  elements=16
+    Axis 1: periodic=0  degree=2  quadrature=3  processors=2  nodes=18  elements=16
+    Partitioning - nodes:    sum=324  min=144  max=180  max/min=1.25
+    Partitioning - elements: sum=256  min=128  max=128  max/min=1
+
+The axis lines reveal that second axis was divided onto 2
+processors. The partitioning information is included to provide
+details of how balanced the partitioning was in terms of nodes and
+elements. We can also learn about which solver was utilized by running
+the code with the following command::
+
+     ./Lapace -ksp_view
+
+which generates::
+
+    KSP Object: 1 MPI processes
+      type: gmres
+        GMRES: restart=30, using Classical (unmodified) Gram-Schmidt Orthogonalization with no iterative refinement
+        GMRES: happy breakdown tolerance 1e-30
+      maximum iterations=10000, initial guess is zero
+      tolerances:  relative=1e-05, absolute=1e-50, divergence=10000
+      left preconditioning
+      using PRECONDITIONED norm type for convergence test
+    PC Object: 1 MPI processes
+      type: ilu
+        ILU: out-of-place factorization
+        0 levels of fill
+        tolerance for zero pivot 2.22045e-14
+        using diagonal shift to prevent zero pivot
+        matrix ordering: natural
+        factor fill ratio given 1, needed 1
+          Factored matrix follows:
+            Matrix Object:         1 MPI processes
+              type: seqaij
+              rows=5832, cols=5832
+              package used to perform factorization: petsc
+              total: nonzeros=592704, allocated nonzeros=592704
+              total number of mallocs used during MatSetValues calls =0
+                not using I-node routines
+      linear system matrix = precond matrix:
+      Matrix Object:   1 MPI processes
+        type: seqaij
+        rows=5832, cols=5832
+        total: nonzeros=592704, allocated nonzeros=592704
+        total number of mallocs used during MatSetValues calls =0
+          not using I-node routines
+
+The acronym KSP represents the PETSc abstraction of Krylov subspace
+methods. In this case, the method used was GMRES with ILU(0) as
+preconditioner. This is PETSc's default for linear systems which are
+not flagged as symmetric. We see that convergence is being determined
+by a relative tolerance reduction of 5 orders of magnitude or 10,000
+iterations.
+
+We can also monitor the progress of the iterative solver by running
+with the :file:`-ksp_monitor` option. This yields::
+
+  0 KSP Residual norm 9.857710770813e+00 
+  1 KSP Residual norm 2.428479391655e+00 
+  2 KSP Residual norm 1.345666842371e+00 
+  3 KSP Residual norm 9.246122694394e-01 
+  4 KSP Residual norm 2.975286675460e-01 
+  5 KSP Residual norm 8.081827277076e-02 
+  6 KSP Residual norm 1.690789970595e-02 
+  7 KSP Residual norm 3.845013201980e-03 
+  8 KSP Residual norm 5.596156980846e-04 
+  9 KSP Residual norm 7.441946439099e-05 
+
+or more concisely we could just use :file:`-ksp_converged_reason`::
+
+    Linear solve converged due to CONVERGED_RTOL iterations 10
+
+These *view* and *monitor* options are usually available for all PETSc
+objects and are useful for debugging and understanding how methods
+work/progress.
+
+Changing Components
+-------------------
+
+Different components of the Laplace solver may be changed from the
+commandline. For example, if you run the Laplace code with
+:file:`-help` again, locate a block of options for the IGA::
+
+  IGA options -------------------------------------------------
+  -iga_dim <-1>: Number of dimensions (IGASetDim)
+  -iga_dof <1>: Number of DOFs per node (IGASetDof)
+  -iga_collocation: <FALSE> Use collocation (IGASetUseCollocation)
+  -iga_processors <-1>: Processor grid (IGASetProcessors)
+  -iga_periodic <0>: Periodicity (IGAAxisSetPeriodic)
+  -iga_basis_type <BSPLINE> (choose one of) BSPLINE BERNSTEIN LAGRANGE HIERARCHICAL (IGABasisSetType)
+  -iga_geometry <>: Specify IGA geometry file (IGARead)
+  -iga_elements <16>: Elements (IGAAxisInitUniform)
+  -iga_degree <2>: Degree (IGAAxisSetDegree)
+  -iga_continuity <-1>: Continuity (IGAAxisInitUniform)
+  -iga_limits <0>: Limits (IGAAxisInitUniform)
+  -iga_order <2>: Order (IGASetOrder)
+  -iga_quadrature <3>: Quadrature points (IGARuleInit)
+
+The numbers in brackets are the default values. Many of the -1 values
+are rather flags for something internal in our code. For example, for
+the :file:`-iga_continuity`, this means that we will use a
+continuity of order *p-1*. So if we run::
+
+./Laplace -iga_dim 3 -iga_elements 10 -iga_degree 3 -iga_continuity 0 -iga_view
+
+we get::
+
+ IGA: dim=3  dof=1  order=3  geometry=0  rational=0  property=0 
+ Axis 0: periodic=0  degree=3  quadrature=4  processors=1  nodes=31  elements=10
+ Axis 1: periodic=0  degree=3  quadrature=4  processors=1  nodes=31  elements=10
+ Axis 2: periodic=0  degree=3  quadrature=4  processors=1  nodes=31  elements=10
+ Partitioning - nodes:    sum=29791  min=29791  max=29791  max/min=1
+ Partitioning - elements: sum=1000  min=1000  max=1000  max/min=1
+
+Similarly the solver components can be changed from the command line. For example,
+we can solve the system using CG and Jacobi by::
+
+    ./Laplace -ksp_type cg -pc_type jacobi -ksp_view
+
+which produces::
+
+    KSP Object: 1 MPI processes
+      type: cg
+      maximum iterations=10000, initial guess is zero
+      tolerances:  relative=1e-05, absolute=1e-50, divergence=10000
+      left preconditioning
+      using PRECONDITIONED norm type for convergence test
+    PC Object: 1 MPI processes
+      type: jacobi
+      linear system matrix = precond matrix:
+      Matrix Object:   1 MPI processes
+        type: seqaij
+        rows=5832, cols=5832
+        total: nonzeros=592704, allocated nonzeros=592704
+        total number of mallocs used during MatSetValues calls =0
+          not using I-node routines
+
+Why Not the Exact Solution?
+---------------------------
+
+It is also possible to write in you own application-specific
+options. These are located in their own block when you run the code
+with the :file:`-help` option::
+
+  Laplace Options -------------------------------------------------
+  -collocation: <FALSE> Enable to use collocation (Laplace.c)
+  -print_error: <FALSE> Prints the L2 error of the solution (Laplace.c)
+  -check_error: <FALSE> Checks the L2 error of the solution (Laplace.c)
+  -save: <FALSE> Save the solution to file (Laplace.c)
+  -draw: <FALSE> If dim <= 2, then draw the solution to the screen (Laplace.c)
+
+You will recall that when you ran the code before with
+:file:`-print_error` the L2 norm of the error was printed. What
+might have been somewhat disconcerting is that the number was not
+closer to zero (you should have seen something on the order of
+:file:`1e-6`). For the problem we have selected, all our spaces
+should return the exact solution. The reason we have an error is that
+the iterative solver is inexact. We can reduce this by tighting the
+conditions for convergence::
+
+ ./Laplace -ksp_rtol 1e-8 -print_error
+
+which returns an L2 error now on the order :file:`1e-10`. We can
+further reduce this by tightening the tolerances further, or by using
+a direct solver::
+
+ ./Laplace -ksp_type preonly -pc_type lu -print_error
+
+The preonly KSP only applies an LU factorization as a preconditioner
+once and therefore is effectively using a direct solver. Now you will
+see that the L2 error has indeed dropped to something on the order
+:file:`1e-15`.
+
+This tutorial highlights a feature of using PetIGA/PETSc to solve
+PDEs--you immediately have access to a wide variety of expert solvers
+and preconditioners. Furthermore, you have query tools to examine and
+study your problems for when they fail.
+
+.. Local Variables:
+.. mode: rst
+.. End:
+.. role:: option(literal)
+.. role:: file(literal)
+.. _TUTORIAL2:
+
+Tutorial 2 - Post-processing Results with igakit
+================================================
+
+**Objective:** At the end of this tutorial you will understand how to output solution vectors from PetIGA and create VTK plots using igakit
+
+**Assumptions:** I assume that in addition to PetIGA and PETSc, you have igakit installed. Also, I assume some familiarity with python.
+
+Poisson Problem
+---------------
+
+To begin this tutorial, compile the demo code
+:file:`$PETIGA_DIR/demo/Poisson.c` and then run with these options::
+
+ ./Poisson -draw -draw_pause 3
+
+This will execute the Poission solver and give you a rough plot of the
+solution for 3 seconds. The problem setup is such that we have unit
+Dirichlet boundary conditions on all boundaries and a unit
+forcing. You should be able to see this in the plot which is
+drawn. Here we are using a built-in viewer of PETSc to plot the
+control points of the solution using::
+
+ VecView(x,PETSC_VIEWER_DRAW_WORLD);
+
+where x was our solution vector. This is fine for visual confirmation
+of correctness in the eyeball norm, but for publications or talks we
+typically desire higher resolution graphics. For this, we need to
+output the discretization information and the solution vector and then
+post-process this. Rerun the example::
+
+ ./Poisson -save
+
+Running with this option will additionally execute two lines in the
+code::
+
+ IGAWrite(iga,"PoissonGeometry.dat");
+ IGAWriteVec(iga,x,"PoissonSolution.dat");
+
+These lines dump the needed information into these datafiles. 
+
+Python Script
+-------------
+
+Now, locate the file :file:`$PETIGA_DIR/demo/PoissonPlot.py` and
+examine its contents. We are using a few features of the python
+package igakit to read in and parse the discretization
+information. First we import the functionality we need::
+
+ from igakit.io import PetIGA,VTK
+ from numpy import linspace
+
+Igakit has a input/ouput module and so we grab the PetIGA and VTK
+functions from this module. We will also grab a Matlab-like linspace
+command from numpy_. Then we need to read in our data files::
+
+ nrb = PetIGA().read("PoissonGeometry.dat")
+ sol = PetIGA().read_vec("PoissonSolution.dat",nrb)
+
+The first of these reads in the discretization information and
+geometry. If no geometry was used, then the control points will be the
+Greville abscissa. This gets stored as an igakit NURBS object into the
+variable :file:`nrb`. There is a lot you can do with this object, but
+for now we will focus only on writing VTK files. The second line reads
+in the solution vector, but requires the NURBS object as well. This is
+so we know how to reshape the linear vector array into something that
+matches the discretization. Then we can write the VTK file ::
+
+ VTK().write("PoissonVTK.vtk",       # output filename
+             nrb,                    # igakit NURBS object
+             fields=sol,             # sol is the numpy array to plot 
+             sampler=uniform,        # specify the function to sample points
+             scalars={'solution':0}) # adds a scalar plot to the VTK file
+
+By specifying :file:`fields=sol` here, we are plotting the solution
+vector on top of the geometry contained in the :file:`nrb`
+variable. Associating the solution vector to the plot is not enough to
+get the solution plotted in the VTK file. Here, we also specify::
+
+ scalars={'solution':0}
+
+where the target of this assignment is a dictionary_. Basically a
+scalar plot will be created per entry in the dictionary. The string
+portion will be what the variable is called in the VTK plot and the
+integer portion indicates which component to use of the :file:`sol`
+vector. In this case, we are solving a scalar problem and so there is
+only one choice.
+
+The sampler line of this VTK call is not needed. By default, a VTK
+will be written by interpolating the solution and geometry at the
+boundaries of non-zero knot spans. We call these *breaks* in
+igakit. However, we can specify a function here to create a finer
+resolution plot as well. We coded a funtion::
+
+ uniform = lambda U: linspace(U[0], U[-1], 100)
+
+where :file:`U` will be the breaks in the B-spline space in each
+dimension. This function simply returns 100 points in between the
+first and the last break. This will create a finely interpolated
+plot. By executing this python script::
+
+ python PoissonPlot.py
+
+you will generate a VTK file called :file:`PoissonVTK.vtk`. This you
+can view with many free viewers such as Paraview_ or VisIt_. Your plot
+should look something like the following figure.
+
+.. image:: ./figs/Poisson.png
+   :align: center
+
+Vector Problems
+---------------
+
+If your problems are vector-valued, then you can output the components
+as vector objects in VTK. Compile and execute the :file:`$PETIGA_DIR/demo/NavierStokesKortweg2D.c` code::
+
+ make NavierStokesKortweg2D
+ ./NavierStokesKortweg2D -nsk_output -ts_max_steps 0
+
+This will run the code with the output option on for zero time
+steps. We will get a vector out of the initial condition. However,
+this problem has three variables: the first is the density and the
+last two are the components of the velocity. We can plot these by
+sightly adjusting our python script::
+
+ from igakit.io import PetIGA,VTK
+ from numpy import linspace
+ nrb = PetIGA().read("iga.dat")
+ sol = PetIGA().read_vec("nsk2d0.dat",nrb)
+ uniform = lambda U: linspace(U[0], U[-1], 100)
+ VTK().write("nsk0.vtk",
+             nrb,       
+             fields=sol,
+             sampler=uniform,
+             scalars={'density':0},
+             vectors={'velocity':[1,2]})
+
+The main difference is that now we have added a :file:`vectors` line
+along with a list of indices. Intuitively, these components align with
+their location in the sol vector as before. Now the resulting VTK file
+will contain multiple components for plotting.
+
+Time Dependent Problems
+-----------------------
+
+If you let the NavierStokesKorteweg code run for more steps (say
+:file:`-ts_max_steps 10`) then you will get more datafiles of the form
+:file:`nsk2d*.dat`. We can slightly edit our script then to convert
+all time steps using the glob_ module::
+
+ from igakit.io import PetIGA,VTK
+ from numpy import linspace
+ import glob
+ nrb = PetIGA().read("iga.dat")
+ uniform = lambda U: linspace(U[0], U[-1], 100)
+ for infile in glob.glob("nsk2d*.dat"):
+     sol = PetIGA().read_vec(infile,nrb)
+     outfile = infile.split(".")[0] + ".vtk"
+     VTK().write(outfile,
+                 nrb,       
+                 fields=sol,
+                 sampler=uniform,
+                 scalars={'density':0},
+                 vectors={'velocity':[1,2]})
+
+The main difference is that we create a list of files to process using
+glob_ and read the solution vector inside of this loop. The output
+filename is then created from the input by removing the extension and
+adding :file:`.vtk`.
+
+.. _numpy: http://www.numpy.org/
+.. _dictionary: http://docs.python.org/2/tutorial/datastructures.html#dictionaries
+.. _Paraview: http://www.paraview.org/
+.. _VisIt: https://wci.llnl.gov/codes/visit/
+.. _glob: http://docs.python.org/2/library/glob.html
+.. role:: option(literal)
+.. role:: file(literal)
+.. _TUTORIAL3:
+
+Tutorial 3 - Creating Geometry with igakit
+==========================================
+
+**Objective:** At the end of this tutorial you will understand how
+  geometries may be generated with igakit and then be read and used in PetIGA.
+
+**Assumptions:** I assume 
+
+
+A Brief Overview of igakit
+--------------------------
+
+Creating a Geometry
+-------------------
+
+Reading Geometry Into PetIGA
+----------------------------
+
+Periodicity
+-----------
+.. role:: option(literal)
+.. role:: file(literal)
+.. _TUTORIAL4:
+
+Tutorial 4 - Disecting the Poission Codes
+=========================================
+
+**Objective:** At the end of this tutorial you will understand 
+
+**Assumptions:** I assume 
+
+Detailed Look at :file:`Poisson1D.c`
+------------------------------------
+
+Higher Dimensions and Dimension Independent
+-------------------------------------------
+
+.. topic:: Abstract
+
+This document is a collection of tutorials intended to exemplify how
+two software packages (PetIGA_ and igakit_) can be used to solve
+partial differential equations. The IGA in the names of both projects,
+refers to `isogeometric analysis`_, a B-spline-based Galerkin finite
+element method. PetIGA is heavily based on PETSc_, a framework geared
+at providing scalable components frequently used in scientific
+software. As such, much of what we cover here is also a tutorial in
+the use of PETSc_.
+
+.. Local Variables:
+.. mode: rst
+.. End:
+# -*- coding: utf-8 -*-
+#
+# PetIGA documentation build configuration file, created by
+# sphinx-quickstart on Fri Sep 23 11:42:32 2011.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#sys.path.insert(0, os.path.abspath('.'))
+
+# -- General configuration -----------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be extensions
+# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+#extensions = ['sphinx.ext.pngmath', 'sphinx.ext.jsmath']
+extensions = ['sphinx.ext.pngmath']
+
+# Add any paths that contain templates here, relative to this directory.
+#templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'PetIGA-igakit'
+copyright = u'2012, L. Dalcin, N. Collier'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = '0.1'
+# The full version, including alpha/beta/rc tags.
+release = '0.1'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+language = 'en'
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = ['_build']
+
+# The reST default role (used for this markup: `text`) to use for all documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+
+# -- Options for HTML output ---------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+html_theme = 'sphinxdoc'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+#html_static_path = ['_static']
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_domain_indices = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'PetIGAdoc'
+
+
+# -- Options for LaTeX output --------------------------------------------------
+
+# The paper size ('letter' or 'a4').
+#latex_paper_size = 'letter'
+latex_paper_size = 'a4'
+
+# The font size ('10pt', '11pt' or '12pt').
+#latex_font_size = '10pt'
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, documentclass [howto/manual]).
+latex_documents = [
+  ('manual', 'PetIGA.tex', u'PetIGA Documentation',
+   u'Lisandro Dalcin, Nathaniel Collier', 'howto'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# If true, show page references after internal links.
+#latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#latex_show_urls = False
+
+# Additional stuff for the LaTeX preamble.
+#latex_preamble = ''
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_domain_indices = True
+
+latex_additional_files = ['sphinxfix.sty']
+latex_elements = {
+    'printmodindex': '',
+    'printindex': '',
+    'preamble' : r'\usepackage{sphinxfix}',
+    }
+
+# -- Options for manual page output --------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    ('index', 'petiga', u'PetIGA Documentation',
+     [u'Lisandro Dalcin, Nathaniel Collier'], 1)
+]

figs/Poisson.png

Added
New image
+==========================
+PetIGA and igakit Tutorial
+==========================
+
+:Authors:      Lisandro Dalcin, Nathaniel Collier
+:Contact:      dalcinl@gmail.com, nathaniel.collier@gmail.com
+:Organization: CONICET_, KAUST_
+:Date:         |today|
+
+.. include:: abstract.txt
+
+Contents
+========
+
+.. include:: toctree.txt
+
+.. include:: links.txt
+
+Index
+=====
+
+* :ref:`genindex`
+* :ref:`search`
+
+.. Local Variables:
+.. mode: rst
+.. End:
+.. _CONICET:  http://www.conicet.gov.ar/
+.. _CIMEC:    http://www.cimec.org.ar/
+.. _KAUST:    http://www.kaust.edu.sa/
+
+.. _MPI:      http://www.mpi-forum.org/
+.. _PETSc:    http://www.mcs.anl.gov/petsc/
+.. _PetIGA: https://bitbucket.org/dalcinl/petiga
+.. _igakit:   https://bitbucket.org/dalcinl/igakit
+
+.. _isogeometric analysis:
+    http://en.wikipedia.org/wiki/Isogeometric_analysis
+
+.. Local Variables:
+.. mode: rst
+.. End:
+@ECHO OFF
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set BUILDDIR=_build
+set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
+if NOT "%PAPER%" == "" (
+	set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
+)
+
+if "%1" == "" goto help
+
+if "%1" == "help" (
+	:help
+	echo.Please use `make ^<target^>` where ^<target^> is one of
+	echo.  html       to make standalone HTML files
+	echo.  dirhtml    to make HTML files named index.html in directories
+	echo.  singlehtml to make a single large HTML file
+	echo.  pickle     to make pickle files
+	echo.  json       to make JSON files
+	echo.  htmlhelp   to make HTML files and a HTML help project
+	echo.  qthelp     to make HTML files and a qthelp project
+	echo.  devhelp    to make HTML files and a Devhelp project
+	echo.  epub       to make an epub
+	echo.  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter
+	echo.  text       to make text files
+	echo.  man        to make manual pages
+	echo.  changes    to make an overview over all changed/added/deprecated items
+	echo.  linkcheck  to check all external links for integrity
+	echo.  doctest    to run all doctests embedded in the documentation if enabled
+	goto end
+)
+
+if "%1" == "clean" (
+	for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i
+	del /q /s %BUILDDIR%\*
+	goto end
+)
+
+if "%1" == "html" (
+	%SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The HTML pages are in %BUILDDIR%/html.
+	goto end
+)
+
+if "%1" == "dirhtml" (
+	%SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.
+	goto end
+)
+
+if "%1" == "singlehtml" (
+	%SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml.
+	goto end
+)
+
+if "%1" == "pickle" (
+	%SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can process the pickle files.
+	goto end
+)
+
+if "%1" == "json" (
+	%SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can process the JSON files.
+	goto end
+)
+
+if "%1" == "htmlhelp" (
+	%SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can run HTML Help Workshop with the ^
+.hhp project file in %BUILDDIR%/htmlhelp.
+	goto end
+)
+
+if "%1" == "qthelp" (
+	%SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can run "qcollectiongenerator" with the ^
+.qhcp project file in %BUILDDIR%/qthelp, like this:
+	echo.^> qcollectiongenerator %BUILDDIR%\qthelp\PetIGA.qhcp
+	echo.To view the help file:
+	echo.^> assistant -collectionFile %BUILDDIR%\qthelp\PetIGA.ghc
+	goto end
+)
+
+if "%1" == "devhelp" (
+	%SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished.
+	goto end
+)
+
+if "%1" == "epub" (
+	%SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The epub file is in %BUILDDIR%/epub.
+	goto end
+)
+
+if "%1" == "latex" (
+	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.
+	goto end
+)
+
+if "%1" == "text" (
+	%SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The text files are in %BUILDDIR%/text.
+	goto end
+)
+
+if "%1" == "man" (
+	%SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The manual pages are in %BUILDDIR%/man.
+	goto end
+)
+
+if "%1" == "changes" (
+	%SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.The overview file is in %BUILDDIR%/changes.
+	goto end
+)
+
+if "%1" == "linkcheck" (
+	%SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Link check complete; look for any errors in the above output ^
+or in %BUILDDIR%/linkcheck/output.txt.
+	goto end
+)
+
+if "%1" == "doctest" (
+	%SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Testing of doctests in the sources finished, look at the ^
+results in %BUILDDIR%/doctest/output.txt.
+	goto end
+)
+
+:end
+======
+PetIGA
+======
+
+.. include:: abstract.txt
+
+.. include:: toctree.txt
+
+.. include:: links.txt
+
+.. Local Variables:
+.. mode: rst
+.. End:
+\setcounter{tocdepth}{2}
+
+\pagenumbering{arabic}
+
+\makeatletter
+\renewcommand{\theindex}{
+  \cleardoublepage
+  \phantomsection
+  \py@OldTheindex
+  \addcontentsline{toc}{section}{\indexname}
+}
+\makeatother
+
+\makeatletter
+\renewcommand{\thebibliography}[1]{
+  \cleardoublepage
+  \phantomsection
+  \py@OldThebibliography{1}
+  \addcontentsline{toc}{section}{\bibname}
+}
+\makeatother
+
+\makeatletter
+\renewcommand{\tableofcontents}{
+  \begingroup
+    \parskip = 0mm
+    \py@OldTableofcontents
+  \endgroup
+  \vfill
+  \rule{\textwidth}{1pt}
+  \newpage
+}
+\makeatother
+
+.. toctree::
+   :maxdepth: 2
+
+   OVERVIEW
+   TUTORIAL1
+   TUTORIAL2
+   TUTORIAL3
+   TUTORIAL4
+
+
+.. Local Variables:
+.. mode: rst
+.. End: