1 
ahallam 
2411 

2 


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
3 


% 
4 
jfenwick 
2881 
% Copyright (c) 20032010 by University of Queensland 
5 
ahallam 
2411 
% 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/osl3.0.php 
11 


% 
12 


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
13 



14 
gross 
2605 
\chapter{Introduction} 
15 


\label{CHAP INTRO} 
16 


\section{Why \esc?} 
17 
artak 
2957 
\esc is a scripting environment for mathematical modeling based on the partial differential equations (PDEs). It provides a highlevel of abstraction from the underlying numerical schemes and their implementations. By freeing the user from considerations like data constructs, meshing and parallelisation, the user can concentrate on the modeling aspects of his problem and still properly utilise the powerful mathematical capabilities of PDEs. 
18 
ahallam 
2411 

19 
artak 
2957 
\esc is built upon the interpreted programming language \pyt\footnote{see \url{www.python.org}}; a scripting language with many intrinsic functions and capabilities. Additionally, there are also a large number of software packages for \pyt which can be used in conjunction with \esc. These packages include functions and data constructs for linear algebra, statistics, visualisation, image processing and data plotting among others. Furthermore, most \esc scripts are scalable as they are able to run on single core desktop computers right through to multicore supercomputers\footnote{\esc supports distributed memory architectures with multicore processors through MPI and threading. See the \esc user guide at \url{https://launchpad.net/escriptfinley/+download} for details.} with no modifications to the scripts. 
20 
ahallam 
2411 

21 
artak 
2957 
There are many benefits for using a software platform like \esc for projects that involve mathematical modelling. Building on the top of an existing environment such as \esc is in many cases much simpler and more cost effective than building an original implementation from the ground up. A modelling environment needs data structures and solution algorithms which take time to develop and test properly, \esc has already covered these problems and its implementation has been widely tested for bugs. Although existing environments may not provide the user with the fastest algorithms for their problems, it is generally the case, that the overall time needed to identify, implement and test the optimal algorithm will exceed the time needed to implement and solve the problem with predeveloped and tested software. This is particularly true if a simulation does not need to be executed repetitively, or has relatively short lifetime. A model for a publication or thesis would be one such instance. 
22 
gross 
2605 

23 
artak 
2957 
When it comes to solving partial differential equations, \esc is ideal, as it is especially designed for this task. Other implementations are merely an addon to a linear algebra focused system (\textit{e.g.} MATLAB). The \esc approach gives the user a cleaner environment to work with and provides better efficiency when dealing with PDE coefficients. Data structures in \esc allow the user to abstract away details such as data types of these coefficients. For example; if a model has been tested with a constant PDE coefficient, then the unchanged script can be run with variable coefficients from a database or as a function of a dependent variable. This capability of \esc is possible because \esc uses the language of PDEs (as opposed to linear algebra) to describe a model. As it turns out, the \esc approach can be applied efficiently in very large software projects as it leads to a clearer structure for the code, by separating modelling issues from lowlevel numerical and computational performance issues. At the same time, this arrangement also allows for the implementation of complex model coupling on a higherlevel. 
24 
ahallam 
2634 

25 
artak 
2957 
The use of \pyt as the platform for \esc makes the development of models simple from a user prospective, as \pyt is intuitive and easy to learn. This simplicity does not hamper experienced users either as \pyt also provides access to a very large number of tools. This makes it an attractive environment to work in. Best of all, \esc is released under an open software license and is freely available for download. 
26 
ahallam 
2775 

27 
ahallam 
2634 
\section{How to use this Cookbook} 
28 
artak 
2957 
This manual is written with the intention of giving new users a practical introduction to \esc. It demonstrates how to solve a variety of problems from simple to advanced. We recommend that new users work through the 
29 


the \textit{first two sets of examples} in Chapters \ref{CHAP HEAT DIFF} and \ref{CHAP HEAT 2}). 
30 


These present the necessary basic knowledge, and explain some of the common aspects and modules of \esc. These simple examples demonstrate hoe to create, solve and visualise PDE based models. 
31 
gross 
2861 
Future chapters (as they are added to this tutorial) will cover more advanced topics with more complex models and methods. We also refer to the \esc user guide for more examples. 
32 
ahallam 
2634 

33 
artak 
2957 
All examples covered in this cookbook have been scripted and are ready to run. They are available from the \exf folder in the \esc directory. These scripts provide a basis for users to develop their own models while at the same time demonstrating the steps required to completely solve and visualise the PDE problems. 
34 
ahallam 
2634 

35 
gross 
2861 
% All of the examples in this cookbook have been developed on a Linux based operating system. 
36 


% Unfortunately Windows and Mac support cannot be guaranteed. However, in most cases minor modifications to the scripts will generally solve any problems. 
37 
ahallam 
2645 

38 
gross 
2605 
\input{quickstart} 
39 
ahallam 
2634 
\input{escpybas} 