## Diff of /doc/doc.tex[6b82ac] .. [e25bc2] Maximize Restore

### Switch to side-by-side view

--- a/doc/doc.tex
+++ b/doc/doc.tex
@@ -62,7 +62,7 @@
interested reader can see what there is behind'' and expecially anyone interested in it can learn quickly how
it is possible to extend the code and contribute to the project.
\item in chapter \ref{exem} more examples are provided. For a lot of them, we present the octave script
-  alongside with the code for Fenics (in C++ and/or Python) in order to provide the user with a quick reference
+  alongside the code for Fenics (in C++ and/or Python) in order to provide the user with a quick reference
guide.
\end{itemize}

@@ -174,7 +174,7 @@
in the shell shouldn't produce any error.

We can now implement and solve a specific instance of the Poisson problem with Octave.
-The parameters are setted as follow
+The parameters are set as follow
\begin{itemize}
\item $\Omega = [0, 1]\times[0, 1]$
\item $\Gamma_{D} = {(0, y) \cup(1, y)} \ \subset \partial\Omega$
@@ -222,7 +222,7 @@
\end{lstlisting}

To initialize the functional space, we have to specify as argument only the fem-fenics mesh,
-because the finite element type and the polynomial degree have yet been specified in the ufl file:
+because the finite element type and the polynomial degree have already been specified in the ufl file:
\begin{lstlisting}[numbers=none, language = Octave]
V = FunctionSpace('Poisson', mesh);
\end{lstlisting}
@@ -244,7 +244,7 @@
@(x,y) 10*exp(-((x - 0.5)^2 + (y - 0.5)^2) / 0.02));
gg = Expression ('g', @(x,y) sin (5.0 * x));
\end{lstlisting}
-Another possibility for dealing with the coefficients defined in the ufl file would have been to use
+Another possibility for dealing with the coefficients defined in the ufl file would be to use
the function \verb$Constant ()$ or \verb$Function ()$.
The coefficients can thus be used together with the FunctionSpace to set
the Bilinear and the Linear form
@@ -274,7 +274,7 @@
\end{lstlisting}

The complete code for the Poisson problem is reported below, while
-in figure \ref{Poissonfig} the output is presented.
+in figure \ref{Poissonfig} is presented the output.
\begin{figure}
\begin{center}
\includegraphics[height=7 cm,keepaspectratio=true]{./Fem-fenics_poisson.png}
@@ -333,9 +333,9 @@
\end{center}
\end{figure}

-Instead of writing a library from scratch, an interface to one of the finite element library
+Instead of writing a library starting from scratch, an interface to one of the finite element library
which are already available has been created.
-Among the many libraries taken into account, the one whch was best suited for our
+Among the many libraries taken into account, the one which was best suited for our
purposes seemed to be the FEniCS project. It is a collection of free, open source, software
components with the common goal to enable automated solution of pde.''
In particular, Dolfin is the C++/Python interface of FEniCS, providing a consistent Problem
@@ -346,11 +346,11 @@
native oct-file interface or, conversely, to use Octave's Matrix/Array Classes in a C++ application
\cite{whatoctave}.

-The works can be summirized as follows (fig. \ref{Codelayout}):
+The works can be summarized as follows (fig. \ref{Codelayout}):

the elements already available in Octave for the resolution of PDE (Mesh and Linear
Algebra) have been exploited, and wrappers to the other FEniCS functions added.
-To allow exchanges between this programs, the necessary functions
+To allow exchanges between these programs, the necessary functions
for converting an Octave mesh/matrix into a FEniCS one and viceversa have been written.

Two main ideas have guided us throughout the realization of the pkg:
@@ -366,8 +366,8 @@
\item \textbf{coefficient} stores an expression object which is used for the
evaluation of user defined values
\item \textbf{expression} is needed for internal use only as explained below
-  \item \textbf{form} stores a general dolfin::Form and can be used either for
-  a dolfn::BilinearForm as well as for a dolfin::LinearForm
+  \item \textbf{form} stores a general dolfin::Form and can be used both for
+  a dolfn::BilinearForm and for a dolfin::LinearForm
\item \textbf{function} for the dolfin::Function objects
\item \textbf{functionspace} stores the user defined FunctionSpace
\item \textbf{mesh} converts a PDE-tool like mesh structure in a dolfin::Mesh
@@ -381,11 +381,11 @@
The general layout of a class can thus be kept simple and with the main purpose of storing
the associated FEniCS objects, which is done throughout
boost::shared\_ptr< > to the corresponding FEniCS type.
-All the classes also implement at least two constructor:
-a default constructor which is necessary to register a type in the Octave interpreter,
+All the classes also implement at least two constructors:
+a default one which is necessary to register a type in the Octave interpreter,
and a constructor which takes as argument the corresponding dolfin type.

-As an example, the form class implementation follows, while classes which differs from the general
+As an example, the form class implementation follows, while classes which differ from the general
layout are presented below in more details.

\begin{lstlisting}
@@ -448,13 +448,13 @@
In all the classes presented above, the private members are stored using
a boost::shared\_ptr< >  to the corresponding FEniCS type.
This is done because we have to refer in several places to resources which are built dynamically
- and we want that it is destroyed only
-when the last references is destroyed \cite{Formaggia_smart}.
+ and we want that they are destroyed only
+when the last reference is destroyed \cite{Formaggia_smart}.
For example, if we have two different functional spaces in the same problem,
like with Navier-Stokes for the velocity and the pressure, the mesh is shared between
them and no one has its own copy.
Furthermore, they are widely supported inside DOLFIN, and it can thus be avoided to have a copy of the
-same object for FEniCS and another one for DOLFIN: there is just one copy which is shared among DOLFIN
+same object for FEniCS and another one for DOLFIN: there is just one copy which is shared between DOLFIN
and FEniCS.

@@ -471,11 +471,11 @@
: octave_base_value (), pmsh (new dolfin::Mesh(_filename)) {}
\end{lstlisting}

-where the first one accepts as input a mesh in (p, e, t) format and convert it into a xml one, while
-the latter load the mesh stored in the \_filename.xml file.
-
-The constructor are used within the Mesh () function, which therefore accepts as argument
-either a mesh generated with the msh pkg or a string with the name of the file
+where the first one accepts as input a mesh in (p, e, t) format and converts it into a xml one, while
+the latter loads the mesh stored in the \_filename.xml file.
+
+The constructors are used within the Mesh () function, which therefore accepts as argument
+either a mesh generated within the msh pkg or a string with the name of the file
where the dolfin mesh is stored.

Furthermore, if a mesh is stored in another different format,
@@ -543,7 +543,7 @@
The matrix $e$ stores information related to every side edge,
like the number of the vertices of the boundary elements,
and the number of the geometrical border containing the edge,
-which is a convinient way to trate boundary conditions in a problem.
+which is a convenient way to deal with boundary conditions in a problem.
\begin{mdframed}[backgroundcolor=LightBlue, outerlinewidth=0.25pt,linecolor=LightBlue]
\begin{lstlisting}[numbers=none, language=octave]
>> mesh.e
@@ -594,15 +594,15 @@
allow to manipulate a mesh and which don't have a conterpart in the msh pkg,
we have also created wrappers for them (specifically for mesh::refine).

-As it has been showed above, the main difference between $(p, e, t)$ and $dolfin xml$
+As it has been shown above, the main difference between $(p, e, t)$ and DOLFIN $xml$
is the way in which the boundaries are distinguished.
The former stores all the information in the $e$ matrix, while the latter uses
-the functions and the methods of the dolfin::mesh class to set/get informations about a mesh.
+the functions and the methods of the dolfin::mesh class to set/get information about a mesh.
The most useful classes available in dolfin are recalled
\begin{itemize}
\item \textbf{MeshIterator}
To know whether an edge belongs or not to the boundary, we can iterate over all the
-edges of our mesh using the classes provided by dolfin:
+edges of our mesh using the classes provided by DOLFIN:
\begin{lstlisting}[numbers=none]
for (dolfin::FacetIterator f (mesh); ! f.end (); ++f)
{
@@ -632,13 +632,13 @@

\item \textbf{MeshValueCollection} "It differs from the MeshFunction class in two ways.
-First, data does not need to be associated with all entities (only a subset).
-Second, data is associated with entities through the corresponding cell index and local entity number
+First, data do not need to be associated with all entities (only a subset).
+Second, data are associated with entities through the corresponding cell index and local entity number
(relative to the cell), not by global entity index, which means that data may be stored robustly to file."\cite{meshvalue}
It is thus obvious that it is better to use the MeshValueCollection whenever saving or writing a mesh.
\end{itemize}

-The containers classes presented above can be used by their own,
+The container classes presented above can be used by their own,
but to set/get data from a mesh it is better to use the methods provided by the classes:
\begin{itemize}
\item \textbf{MeshDomains} "The class MeshDomains stores the division of a Mesh into subdomains.
@@ -652,7 +652,7 @@
Each dataset is identified by a unique user-specified string." \cite{meshdata}
\end{itemize}

-\subparagraph{Geometry from (p, e, t) to xml dolfin}
+\subparagraph{Geometry from (p, e, t) to dolfin xml}
Converting the vertices and cells from (p, e, t) in the xml format can be done using the
dolfin editor, while caution has to be taken for storing information associated with boundaries
and subdomains, as presented in the next paragraph.
@@ -691,8 +691,8 @@
and they are thus treated together referring to the
general dimension D.
The subdomain information is contained in the t matrix,
-and is temporarily copyed to a MeshValueCollection.
-For every column of the t matrix, i.e. for every element of the mesh,
+and it is temporarily copied to a MeshValueCollection.
+For every column of the $t$ matrix, i.e. for every element of the mesh,
we have to look for the corresponding element in the DOLFIN mesh.
We use the class MeshIterator for moving around on the DOLFIN mesh:

@@ -714,7 +714,7 @@

The \verb$all_vertices_in_the_ith_column$ is just like a pseudo code:
we have to be sure that the Cell pointed by f is the one corresponding
-to the $i^{th}$ column of the matrix, checking one-by-one the vertices:
+to the $i^{th}$ column of the matrix, checking the vertices one-by-one:

in $2D$ the cell is a triangle, and we thus have to check $3$ vertices.
As we don't know the order in which vertices are visited, we have to check all the $3! = 6$
@@ -756,7 +756,7 @@
using the MeshDomains class.
Obviously we have to be sure that the information is available within
the file that we are reading, and that it is related to Cell, i.e. to elements of dimension D,
-before it is associated with the last row of the t matrix:
+before it is associated to the last row of the $t$ matrix:

\begin{lstlisting}[numbers=none]
dolfin::MeshFunction<uint> my_cell_marker;
@@ -796,7 +796,7 @@

\subparagraph{Mesh refine}
Now that it is possible to convert meshes between Octave and DOLFIN,
-the functions availables in the dolfin::mesh class can be used to improve the
+the functions available in the dolfin::mesh class can be used to improve the
functionality of the msh package.
For the moment, it has been added the possibility of refining a mesh,
either uniformly or specifying the list of the vertices we want to be refined.
@@ -835,11 +835,11 @@
where the Finite Elements denoted with * are not yet fully supported inside FEniCS.

\section{General layout of a function}
-There are three general kind of functions in the code: functions which create an abstract problem
+There are three general kinds of functions in the code: functions which create an abstract problem
(wrappers to UFL),
functions which create the specific instance of a problem (wrapper to FEniCS) and functions
-which discretize the problem and genertates the matrices.
-\section{Wrappers to UFL}
+which discretize the problem and generate the matrices.
+\subsection{Wrappers to UFL}
As stated in section \ref{genlayout}, a problem is divided in two files:a \textit{.ufl} file
where the abstract problem is described in Unified Form Language (UFL),
and a script file \textit{.m} where a specific problem is implemented and solved.
@@ -848,15 +848,15 @@
they have to be imported inside Octave.
When the UFL file is compiled using the ffc compiler, a header file \textit{Poisson.h} is generated.
In this header file, it is defined the Poisson class, which derives from dolfin::Form,
-and the constructor for the bilinear and linear form are setted.
+and the constructor for the bilinear and linear form are set.
This file is thus available only at compilation time, but it has to be included somehow
in the wrapper function for the Bilinear and the Linear form.
An easy solution would have been to write a set of pre established problems where the user could only
change the values of the coefficient for a specific problem;
-but, as we want to let the user free to write its own
+but, as we want to let the user free to write his own
variational problem, a different approach has been adopted.
-The ufl file is compiled at run time and generates an header file.
-Then, a Poisson.cc file is written from a template which take as input the name
+The ufl file is compiled at run time and generates a header file.
+Then, a Poisson.cc file is written from a template which takes as input the name
of the header file and is compiled including the Poisson.h file;
now the corresponding octave functions for the specific problem is available and will be used from
BilinearForm, LinearForm, FunctionSpace, ... .
@@ -921,8 +921,8 @@
\end{lstlisting}

-\section{Wrappers to DOLFIN}
-The general layout of a function is very simple and is composed of 4 steps which we describe using an example:
+\subsection{Wrappers to DOLFIN}
+The general layout of a function is very simple and it is composed of 4 steps which we describe using an example:
\begin{lstlisting}
DEFUN_DLD (fem_fs, args, , "initialize a fs from a mesh")
{
@@ -939,9 +939,9 @@
\end{lstlisting}
All the functions presented above follow this general structure, and thus here we present
in detail only functions which present some differences.
-\subsection{Sparse Matrices}
-\subsection{Polymorphism}
-\subsection{DirichletBC and Coefficient}
+\subsubsection{Sparse Matrices}
+\subsubsection{Polymorphism}
+\subsubsection{DirichletBC and Coefficient}
These two functions take as input a function handle which cannot be directly evaluated by
a dolfin function to set, respectively, the value on the boundary or the value of the coefficient.
It has thus been derived from dolfin::Expression a class "expression" which has as private member
@@ -978,15 +978,15 @@
\paragraph{DirichletBC}
The BC are imposed directly to the mesh setting to zero all the off diagonal elements
in the corresponding line. This means that we could loose the symmetry of the matrix, if any.
-To avoid this problem, instead of the method apply() it is possible to use the
+To avoid this problem, instead of the method \verb$apply()$ it is possible to use the
function \verb$assemble_system()$ , which preserves the symmetry of the system but which needs to build
together the lhs and the rhs.

\paragraph{Coefficient}
The coefficient of the variational problem can be specified using either a Coefficient
or a Function. They are different objects which behave in different ways: a Coefficient, as exlained above,
-overloads the eval() method of the  dolfin::Expression class and it is evaluated at
-run time using the octave function feval (). A Function instead doesn't need to be evaluated
+overloads the \verb$eval()$ method of the  dolfin::Expression class and it is evaluated at
+run time using the octave function \verb$feval()$. A Function instead doesn't need to be evaluated
because it is assembled copying element-by-element the values contained in the input vector.
\iffalse

@@ -1020,7 +1020,7 @@
This will be illustrated below in the HyperElasticity example.
\fi

-\section{Wrapper to FEniCS}
+\subsection{Wrapper to FEniCS}

\subsection{Code on the fly}