ViewVC logotype

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

Parent Directory Parent Directory | Revision Log Revision Log

Revision 2861 - (hide annotations)
Wed Jan 20 02:47:42 2010 UTC (11 years, 10 months ago) by gross
File MIME type: application/x-tex
File size: 7791 byte(s)
some modification to the cookbook
1 ahallam 2411
2     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3     %
4     % Copyright (c) 2003-2009 by University of Queensland
5     % Earth Systems Science Computational Center (ESSCC)
6     % http://www.uq.edu.au/esscc
7     %
8     % Primary Business: Queensland, Australia
9     % Licensed under the Open Software License version 3.0
10     % http://www.opensource.org/licenses/osl-3.0.php
11     %
12     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
14 ahallam 2494 \section{Escript and Python Basics} \label{sec:escpybas}
15 ahallam 2411
16 ahallam 2775 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 ahallam 2494 \begin{itemize}
18 ahallam 2775 \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 ahallam 2494 \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/}.
21 ahallam 2775 \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 ahallam 2494 \item Another comprehensive tutorial: \url{http://www.tutorialspoint.com/python/index.htm}
23     \end{itemize}
25 gross 2861 \subsection{The \modesys Modules}
26     \esc is part of the \esys package.
27     Besides the particle simualation code
28     \verb|ESyS-Particle|\footnote{see \url{https://launchpad.net/esys-particle}} which is not covered
29     in this tutorial \esys includes the following modules
30 ahallam 2494 \begin{enumerate}
31 gross 2861 \item \modescript is the PDE solving module.
32 ahallam 2645 \item \modfinley is the discretisation tool and finite element package.
33 gross 2861 \item \modpycad is a special development for creating irregular shaped domains.
34 ahallam 2494 \end{enumerate}
35 gross 2861 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}}.
36     \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 part of the SciPy package, see \url{http://www.scipy.org/}} a simple plotting tool, \modvtk \footnote{See \url{http://www.vtk.org/}} an advanced 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 support bundles.
37 ahallam 2494
38 gross 2861
42 ahallam 2658 \begin{figure}[t]
43     \centering
44 ahallam 2681 \includegraphics[width=6in]{figures/functionspace.pdf}
45 ahallam 2658 \label{fig:fs}
46 ahallam 2775 \caption{\esc domain construction overview}
47 ahallam 2658 \end{figure}
48 gross 2861
49     \subsection{The Domain Constructor in \esc}
50     \label{ss:domcon}
51     It is important at this particular stage, to describe how domains and data are organised and related to each other in \esc.
53     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;
54 ahallam 2658 \begin{enumerate}
55     \item the nodes, called by \verb|ContinuousFunction(domain)| ;
56     \item the elements/coefficients, called by \verb|Function(domain)| ; and
57     \item the boundary, called by \verb|FunctionOnBoundary(domain)| .
58     \end{enumerate}
59 ahallam 2775 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() .
60 ahallam 2658
61 ahallam 2775 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.
62 ahallam 2658
63 ahallam 2775 \subsection{File Commands and Operations in \esc}
64 jfenwick 2657 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.
65 ahallam 2494
66     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;
67 ahallam 2775 \begin{python}
68 jfenwick 2657 os.path.join(save_path, "data%03d.xml"%i )
69 ahallam 2775 \end{python}
70 ahallam 2494 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;
71     \begin{verbatim}
72     save_path = "data"
73     \end{verbatim}
74     while a subfolder of \verb data called \verb ans_one would be defined by;
75     \begin{verbatim}
76     save_path = "data/ans_one"
77     \end{verbatim}
78 ahallam 2775 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;
79 ahallam 2494 \begin{itemize}
80     \item \verb 0 becomes the padding number;
81     \item \verb 3 tells us the amount of padding numbers that are required; and
82     \item \verb d indicates the end of the \verb % operator.
83     \end{itemize}
84 jfenwick 2657 To increment the file name a \verb %i is required directly after the operation the string is involved in. When correctly implemented the output files from this command would be place in the directory defined by \verb save_path as;
85 ahallam 2494 \begin{verbatim}
86     data001.xml
87     data002.xml
88     data003.xml
89     ...
90     \end{verbatim}
91     and so on.
93 ahallam 2775 A subfolder check/constructor is available in the cookbook \verb cblib library called \verb needdirs . The command;
94 ahallam 2658 \begin{verbatim}
95     needdirs(save_path)
96     \end{verbatim}
97 ahallam 2681 will check for the existence of \verb save_path and if missing, make the required directories.
98 ahallam 2658
100 ahallam 2634 \subsection{Visualisation and Plotting}
101 ahallam 2775 \esc does not include its own plotting capabilities. However, it is possible to use a variety of free \pyt packages for visualisation.
102     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.
103     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.

  ViewVC Help
Powered by ViewVC 1.1.26