/[escript]/trunk/doc/cookbook/escpybas.tex
ViewVC logotype

Diff of /trunk/doc/cookbook/escpybas.tex

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 2774 by ahallam, Thu Sep 24 03:04:04 2009 UTC revision 2775 by ahallam, Wed Nov 25 05:01:43 2009 UTC
# Line 13  Line 13 
13    
14  \section{Escript and Python Basics} \label{sec:escpybas}  \section{Escript and Python Basics} \label{sec:escpybas}
15    
16  The Python scripting language is a powerful and easy to learn environment with a wide variety of applications. \textit{Escript} has been developed as a packaged module for Python specifically to solve complex partial differential equations. As a result, all the conventions and programming syntax associated with Python are coherent with \ESCRIPT. If you are unfamiliar with Python, there are a large number of simple to advanced guides and tutorials availabe online. These texts should provide an introduction that is comprehensive enough for the use of \ESCRIPT. A handful of python tutorials have been listed below.  The \pyt scripting language is a powerful and easy to learn environment with a wide variety of applications. \esc has been developed as a packaged module for \pyt specifically to solve complex partial differential equations. As a result, all the conventions and programming syntax associated with \pyt are coherrent with \esc. If you are unfamiliar with \pyt, there are a large number of simple to advanced guides and tutorials availabe online. These texts should provide an introduction that is comprehensive enough for the use of \esc. A handful of \pyt tutorials have been listed below.
17  \begin{itemize}  \begin{itemize}
18  \item This is a very crisp introduction \url{http://hetland.org/writing/instant-python.html}. It covers everthing you need to get started with \ESCRIPT.  \item This is a very crisp introduction \url{http://hetland.org/writing/instant-python.html}. It covers everthing you need to get started with \esc.
19  \item A nice and easy to follow introduction: \url{http://www.sthurlow.com/python/}  \item A nice and easy to follow introduction: \url{http://www.sthurlow.com/python/}
20  \item Another crisp tutorial \url{http://www.zetcode.com/tutorials/pythontutorial/}.  \item Another crisp tutorial \url{http://www.zetcode.com/tutorials/pythontutorial/}.
21   \item A very comprehensive tutorial from the python authors: \url{http://www.python.org/doc/2.5.2/tut/tut.html}. It covers much more than what you will ever need for \ESCRIPT.   \item A very comprehensive tutorial from the \pyt authors: \url{http://www.python.org/doc/2.5.2/tut/tut.html}. It covers much more than what you will ever need for \esc.
22  \item Another comprehensive tutorial: \url{http://www.tutorialspoint.com/python/index.htm}  \item Another comprehensive tutorial: \url{http://www.tutorialspoint.com/python/index.htm}
23  \end{itemize}  \end{itemize}
24    
25  \subsection{The \modesys Library Tree}  \subsection{The \modesys Library Tree}
26  The \verb esys  library tree has \textbf{3} main modules, \verb escript , \verb finley  and \verb pycad .  The \esys  library tree has three main modules, \verb escript , \verb finley  and \verb pycad . These three modules contain the bulk of the \esc package functions and data structures.
27  \begin{enumerate}  \begin{enumerate}
28  \item \modescript  is the PDE solving module.  \item \modescript  is the PDE solving module.
29  \item \modfinley is the discretisation tool and finite element package.  \item \modfinley is the discretisation tool and finite element package.
30  \item \modpycad  is a special development for creating irregular domains and models. That are easily interpretable by \esc .  \item \modpycad  is a special development for creating irregular domains and models. That are easily interpretable by \esc .
31  \end{enumerate}  \end{enumerate}
32  Further explanations on each of these is available in the \esc user guide or in the API documentation at \url{https://launchpad.net/escript-finley/+download}. \ESCRIPT is also dependent on a few other open-source packages which are not maintained by the \ESCRIPT development team. These are \modnumpy an array and matrix handling package, \modmpl a simple plotting and visualisation tool, \modvtk  the advanced plotting and visualisation package and \verb gmsh  which is required by \modpycad. These packages (\textbf{except} for \verb gmsh ) are included with the binary release but may not be the most recent and up to date.  Further explanations on each of these is available in the \esc user guide or in the API documentation \footnote{Available from \url{https://launchpad.net/escript-finley/+download}}. \esc is also dependent on a few other open-source packages which are not maintained by the \esc development team. These are \modnumpy an array and matrix handling package, \modmpl \footnote{\modnumpy and \modmpl are maintained by SciPy, \url{http://www.scipy.org/}} a simple plotting and visualisation tool, \modvtk \footnote{See \url{http://www.vtk.org/}} an advanced plotting and visualisation package and \verb gmsh \footnote{See \url{http://www.geuz.org/gmsh/}} which is required by \modpycad. These packages (\textbf{except} for \verb gmsh ) are included with the binary release but may not be the most recent and up to date.
33    
34  \subsection{The Domain Constructor in \ESCRIPT}  \subsection{The Domain Constructor in \esc}
35  \label{ss:domcon}  \label{ss:domcon}
36  It is important at this paticular stage to describe how domains and data are organised and related to each other in escript.  It is important at this particular stage, to describe how domains and data are organised and related to each other in \esc.
37  \begin{figure}[t]  \begin{figure}[t]
38   \centering   \centering
39     \includegraphics[width=6in]{figures/functionspace.pdf}     \includegraphics[width=6in]{figures/functionspace.pdf}
40     \label{fig:fs}     \label{fig:fs}
41     \caption{\ESCRIPT domain construction overview}     \caption{\esc domain construction overview}
42  \end{figure}  \end{figure}
43  When the domain variables are submitted to the domain constructor or meshing algorithm, three function spaces are also created. They are;  When the domain variables are submitted to the domain constructor or meshing algorithm, three function spaces are also created (Figure \ref{fig:fs.}) They are;
44  \begin{enumerate}  \begin{enumerate}
45  \item the nodes, called by \verb|ContinuousFunction(domain)| ;  \item the nodes, called by \verb|ContinuousFunction(domain)| ;
46  \item the elements/coefficients, called by \verb|Function(domain)| ; and  \item the elements/coefficients, called by \verb|Function(domain)| ; and
47  \item the boundary, called by \verb|FunctionOnBoundary(domain)| .  \item the boundary, called by \verb|FunctionOnBoundary(domain)| .
48  \end{enumerate}  \end{enumerate}
49  Domains in \ESCRIPT are constructed this way to allow for varying degrees of smoothness in a PDE problem. That is, the continuity of the first derivative of each data input. For example, the coefficients of a PDE need not be continuous, thus this qualifies as a \verb Function()  type, while a temperature distribution must be a \verb ContinuousFunction()  and a flux condition may only exist at a boundary as a \verb FunctionOnBoundary()  .  The domain constructor is able to interpret the data in each of these situations for the solver so that a solution can be produced. It should be noted that a solution has its own function space \verb Solution()  which is located depending on the required output. The domain also allows certain transformations of the function spaces. A \verb ContinuousFunction()  can be transformed into a \verb FunctionOnBoundary()  or \verb Function() . On the other hand there is not enough information in a \verb FunctionOnBoundary()  to transform it to a \verb ContinuousFunction()  .  Domains in \esc are constructed this way to allow for varying degrees of smoothness in a PDE problem. That is, the continuity of the first derivative of each data input. For example, the coefficients of a PDE need not be continuous, thus this qualifies as a \verb Function()  type, while a temperature distribution must be a \verb ContinuousFunction()  and a flux condition may only exist at a boundary as a \verb FunctionOnBoundary()  .  The domain constructor is able to interpret the data in each of these situations for the solver so that a solution can be produced. It should be noted that a solution has its own function space \verb Solution()  which takes a form of one of the aforementioned function spaces depending on the required output. The domain also allows certain transformations of the function spaces. A \verb ContinuousFunction()  can be transformed into a \verb FunctionOnBoundary()  or \verb Function() . On the other hand there is not enough information in a \verb FunctionOnBoundary()  to transform it to a \verb ContinuousFunction()  .
50    
51  The domain also handles an ability of \ESCRIPT known as tagging, which allows areas and lines to be given a name for easier referencing later on.  Domains also make it easier to define specific areas within a model. This is known as tagging and it makes for much easier scripting. Surfaces, blocks and boundaries can be given variable names simplifing PDE coefficient and flux definitions.
52    
53  \subsection{File Commands and Operations in \ESCRIPT}  \subsection{File Commands and Operations in \esc}
54  A number of common file operations and commands are used throughout this cookbook. It is often advantageous to implement these commands when large numbers of output files are generated or dependencies are located in other locations.  A number of common file operations and commands are used throughout this cookbook. It is often advantageous to implement these commands when large numbers of output files are generated or dependencies are located in other locations.
55    
56  To develop an incrementing file name we can use the following convention. For this example we are going to use the \verb|os.path.join| command to join a subdirectory which already exists with the file name which we want to use for our output. The command is;  To develop an incrementing file name we can use the following convention. For this example we are going to use the \verb|os.path.join| command to join a subdirectory which already exists with the file name which we want to use for our output. The command is;
57  \begin{verbatim}  \begin{python}
58  os.path.join(save_path, "data%03d.xml"%i )  os.path.join(save_path, "data%03d.xml"%i )
59  \end{verbatim}  \end{python}
60  There are two arguments to the \verb join  command. The \verb save_path  variable is a predefined string pointing to the directory we want to save our data in, for example a single subfolder called \verb data  would be defined by;  There are two arguments to the \verb join  command. The \verb save_path  variable is a predefined string pointing to the directory we want to save our data in, for example a single subfolder called \verb data  would be defined by;
61  \begin{verbatim}  \begin{verbatim}
62  save_path = "data"  save_path = "data"
# Line 65  while a subfolder of \verb data  called Line 65  while a subfolder of \verb data  called
65  \begin{verbatim}  \begin{verbatim}
66  save_path = "data/ans_one"  save_path = "data/ans_one"
67  \end{verbatim}  \end{verbatim}
68  The second argument of \verb join \xspace contains a string which is the filename. We can use the operator \verb|%| to increment our file names with the value \verb|i| our incrementing counter. The substring \verb %03d  does this by defining the following parameters;  The second argument of \verb join \xspace contains a string which is the filename. We can use the operator \verb|%| to increment our file names with the value \verb|i| denoting a incrementing counter. The substring \verb %03d  does this by defining the following parameters;
69  \begin{itemize}  \begin{itemize}
70   \item \verb 0  becomes the padding number;   \item \verb 0  becomes the padding number;
71   \item \verb 3  tells us the amount of padding numbers that are required; and   \item \verb 3  tells us the amount of padding numbers that are required; and
# Line 80  data003.xml Line 80  data003.xml
80  \end{verbatim}  \end{verbatim}
81  and so on.  and so on.
82    
83  A subfolder check/constructur is available in the cookbook \verb cblib  library called \verb needdirs . The command;  A subfolder check/constructor is available in the cookbook \verb cblib  library called \verb needdirs . The command;
84  \begin{verbatim}  \begin{verbatim}
85  needdirs(save_path)  needdirs(save_path)
86  \end{verbatim}  \end{verbatim}
# Line 88  will check for the existence of \verb sa Line 88  will check for the existence of \verb sa
88    
89    
90  \subsection{Visualisation and Plotting}  \subsection{Visualisation and Plotting}
 \ESCRIPT does not include its own plotting capabilities however it works with a number of free visualisation systems.  
 We will dicsuss two types of systems in this document: \mpl\footnote{\url{http://matplotlib.sourceforge.net/}} and \verb VTK \footnote{\url{http://www.vtk.org/}} visualisation.  
 The \mpl package is a part of SciPy\footnote{\url{http://www.scipy.org}} and is good for basic graphs and plots. The \verb VTK  toolkit allows the \esc data to be exported in a standardised format with powerful visualisation capabilities. This format can be interpreted by many programs. In this cookbook \mayavi \footnote{\url{http://code.enthought.com/projects/mayavi/}} will be used to visualise \verb VTK  files.  
91    \esc does not include its own plotting capabilities. However, it is possible to use a variety of free \pyt packages for visualisation.
92    Two types will be demonstrated in this cookbook; \mpl\footnote{\url{http://matplotlib.sourceforge.net/}} and \verb VTK \footnote{\url{http://www.vtk.org/}} visualisation.
93    The \mpl package is a component of SciPy\footnote{\url{http://www.scipy.org}} and is good for basic graphs and plots. The \verb VTK  toolkit allows the \esc data to be exported in a standardised format with powerful visualisation capabilities. This format can be interpreted by many programs, \mayavi \footnote{\url{http://code.enthought.com/projects/mayavi/}} as an example.

Legend:
Removed from v.2774  
changed lines
  Added in v.2775

  ViewVC Help
Powered by ViewVC 1.1.26