Diff of /doc/doc.tex [945c19] .. [01b5ec] Maximize Restore

  Switch to side-by-side view

--- a/doc/doc.tex
+++ b/doc/doc.tex
@@ -108,7 +108,7 @@
 If you have done it manually, please be sure that they are available before starting the
 installation of Fem-fenics.
 
-\section{General layout}
+\section{General layout and first example}
 
 A generic problem has to be solved in two steps:
 \begin{enumerate}
@@ -176,110 +176,110 @@
  \item $f = 10 \exp \dfrac{(x-0.5)^{2} + (y-0.5)^{2}}{0.02}$
  \item $g = \sin(5x)$
 \end{itemize}
-\iffalse
+
 As a first thing we need to load into Octave the pkg that we have previously installed
-
-    pkg load fem-fenics
-
-We can thus initialize the environment and import the .ufl file inside Octave. 
-When we call the function \verb$fem_init_env ()$, the new types defined inside fem-fenics 
-are registered to the octave-parser. From the .ufl file, we have to generate the 
+\begin{verbatim}
+    pkg load fem-fenics msh
+\end{verbatim}
+We can thus import the ufl file inside Octave. From the ufl file, we have to generate the 
 corresponding functions for fem-fenics. There is a specific function which seeks 
-every specific element defined inside the .ufl file:
-
-    \verb$fem_create_fs ('name')$ is a function which looks for the finite element 
-    space defined inside the file called name.ufl; if everything is ok, it generates a function
-    \verb$fem_fs_name$
-    \verb$fem_create_rhs ('name')$ is a function which looks for the rhs of the 
-    equation, i.e. for the bilinear form defined inside name.ufl; if successful, 
-    it generates the function \verb$fem_rhs_name$
-    \verb$fem_create_lhs ('name')$ is a function which looks for the linear 
-    form defined inside name.ufl; if successful, it generates the function \verb$fem_lhs_name$
-
+every specific element defined inside the ufl file:
+\begin{itemize}
+    \item \verb$ufl_import_FunctionSpace ('Poisson')$ is a function which looks for the finite element 
+    space defined inside the file called Laplace.ufl; if everything is ok, it generates a function
+    which we will use later
+    \item \verb$ufl_import_BilinearForm ('Poisson')$ is a function which looks for the rhs of the 
+    equation, i.e. for the bilinear form defined inside Laplace.ufl;
+    \item \verb$ufl_import_LinearForm ('Poisson')$ is a function which looks for the linear 
+    form.
+\end{itemize}
 In some cases one could be interested in using these functions separately but if, 
-as in our example, all the three elements are defined in the same .ufl file, 
-we can just call \verb$fem_create_all ('name')$ which generates at once all the three functions described above.
-\begin{verbatim}
-    fem_init_env ();
-    fem_create_all ('Poisson');
-\end{verbatim}
+as in our example, all the three elements are defined in the same ufl file (and only in this case), 
+we can just call \verb$import_ufl_Problem ('Poisson')$ which generates at once all 
+the three functions described above.
+
+\begin{verbatim}
+    ufl_import_Problem ('Poisson');
+\end{verbatim}
+
 To set the concrete elements which define our problem, 
 the first things to do is to create a mesh. 
 It can be managed easily using the msh pkg. In our case, we create a uniform mesh
 \begin{verbatim}
-    x = y = linspace (0, 1, 32);
-    msho = msh2m_structured_mesh (x, y, 1, 1:4); 
+    x = y = linspace (0, 1, 33);
+    msho = msh2m_structured_mesh (x, y, 1, 1:4);
 \end{verbatim}
 Once that the mesh is available, we can thus initialize the 
 fem-fenics mesh using the function \verb$fem_init_mesh()$:
 \begin{verbatim}
-    mshd = fem_init_mesh (msho);
+    mesh = Mesh (msho);
 \end{verbatim}
 If instead of an Octave mesh you have a mesh stored in a different format,
 you can try to convert it to the dolfin xml format using the program dolfin-convert.
-In fact, \verb$fem_init_mesh()$ accepts as arguments also a string with the name of 
+In fact, \verb$Mesh ()$ accepts as arguments also a string with the name of 
 the dolfin xml file which contains your mesh. For example, if you have a mesh saved
 in the gmsh format, you can do as follows:
 \begin{verbatim}
-Shell:
-    dolfin-convert msh.gmsh msh.xml
+    Shell:
+      dolfin-convert msh.gmsh msh.xml
 \end{verbatim}
 and then inside our Octave script:
 \begin{verbatim}
     mshd = fem_init_mesh ('msh.xml');
 \end{verbatim}
 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 been specified in the .ufl file:
-\begin{verbatim}
-    V  = fem_fs_Poisson (mshd);
-\end{verbatim}
-We can now apply essential BC \verb$using fem_bc ()$. This function receives as argument the functional space,
+because the finite element type and the polynomial degree have been specified in the ufl file:
+\begin{verbatim}
+    V = FunctionSpace('Poisson', mesh);
+\end{verbatim}
+We can now apply essential BC using \verb$DirichletBC ()$. This function receives as argument the functional space,
 a function handle which specifies the value that we want to set, and the label of the sides where we want
-to apply the BC.
-\begin{verbatim}
-    bc = fem_bc (V, @(x,y) 0, [2, 4]);
-\end{verbatim}
-The last thing that we have to do before solving the problem, is to set the coefficients. 
+to apply the BC. In our case, we apply homogenous boundary condition on the left and right side of the square
+\begin{verbatim}
+    bc = DirichletBC(V, @(x, y) 0.0, [2;4]);
+\end{verbatim}
+The last thing that we have to do before solving the problem, is to set the coefficients specified
+in the ufl file. It is important that they are called in the same way as in the ufl file.
 In our case they are the source term 'f' and the normal flux 'g'. 
-To set them, we can for example use the function \verb$fem_coeff ()$ to which we have to pass as argument a string,
-which specifies the name of the coefficient as stated in the .ufl file, and a function handle with the value:
-\begin{verbatim}
-  f = fem_coeff ('f', @(x,y) 10*exp(-((x - 0.5)^2 + (y - 0.5)^2) / 0.02));
-  g = fem_coeff ('g', @(x,y) sin (5.0 * x));
-\end{verbatim}
-Another possibility for dealing with the coefficients defined in the .ufl file would be to use 
-the function \verb$fem_func ()$, but I will describe it in a future post.
-
+To set them, we can for example use the function \verb$Expression ()$ to which we have to pass as argument a string,
+which specifies the name of the coefficient, and a function handle with the value required:
+\begin{verbatim}
+    f = Expression ('f', 
+          @(x,y) 10*exp(-((x - 0.5)^2 + (y - 0.5)^2) / 0.02));
+    g = Expression ('g', @(x,y) sin (5.0 * x));
+\end{verbatim}
+Another possibility for dealing with the coefficients defined in the ufl file would be to use 
+the function \verb$Constant ()$ or \verb$Function ()$.
+The coefficient can thus be used together with the FunctionSpace to set 
+the Bilinear and the Linear form
+\begin{verbatim}
+    a = BilinearForm ('Poisson', V, V);
+    L = LinearForm ('Poisson', V, f, g);
+\end{verbatim}
 We can now obtain the discretized representation of our operator using the 
-functions \verb$fem_r(l)hs_Poisson ()$. We have to pass as arguments two things: 
-the BC(s) that we want to apply and the coefficient.
-In our case, 'f' and 'g' are both related to the lhs of the equation and 
-so they have to be passed only to \verb$fem_lhs_Poisson ()$. On the other side, 
-the BC(s) has to be specified both for the rhs and for the lhs because 
-they are imposed setting directly to the right values the corresponding entry:
-\begin{verbatim}
-  A = fem_rhs_Poisson (V, bc);
-  b = fem_lhs_Poisson (V, f, g, bc);
+functions \verb$assemble ()$ or \verb$assemble_system ()$, which also allow us
+to specify the BC(s) that we want to apply.
+Whenever possible, it is better to use the \verb$assemble_system ()$ function
+because it keeps the symmetry of the matrix while setting the entries for the BC:
+\begin{verbatim}
+    [A, b] = assemble_system (a, L, bc);
 \end{verbatim}
 Here A is a sparse matrix and b is a column vector. We can thus use all the 
-functionalities available within Octave: if we are interested in the spectrum 
-of the matrix we can use the eig() function, but for the moment we use the backslash 
-command to solve the linear system:
-\begin{verbatim}
-  u = A \ b;
+functionalities available within Octave to solve the linear system. 
+For the moment we use the easisest possibility, i.e. the backslash command to solve the linear system:
+\begin{verbatim}
+    u = A \ b;
 \end{verbatim}
 Once that the solution has been obtained, we can transform the vector into a 
-fem-fenics function and plot it using \verb$fem_plot ()$, or save it with \verb$fem_save ()$.
-\begin{verbatim}
-  func = fem_func ('u', V, u)
-  fem_plot (func);
-\end{verbatim}
-At the moment \verb$fem_plot ()$ takes as input only arguments of type fem-function, 
-but we will extend it later so that it could also plot variables of type fem-mesh (and maybe even more).
-The result that we obtain should be something like this
-\fi
-
-A possible implementation for the Poisson problem is reported below, while
+fem-fenics function and plot it \verb$plot ()$, or save it \verb$save ()$ in the vtu
+format.
+\begin{verbatim}
+    u = Function ('u', V, sol);
+    save (u, 'poisson')
+    plot (u);
+\end{verbatim}
+
+The complete code for the Poisson problem is reported below, while
 in figure \ref{Poissonfig} is presented the output.
 \begin{figure}
  \begin{center}