1 
ahallam 
2411 

2 
jfenwick 
3989 
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
3 
jfenwick 
3911 
% Copyright (c) 20032012 by University of Queensland 
4 
jfenwick 
3989 
% http://www.uq.edu.au 
5 
ahallam 
2411 
% 
6 


% Primary Business: Queensland, Australia 
7 


% Licensed under the Open Software License version 3.0 
8 


% http://www.opensource.org/licenses/osl3.0.php 
9 


% 
10 
jfenwick 
3989 
% Development until 2012 by Earth Systems Science Computational Center (ESSCC) 
11 


% Development since 2012 by School of Earth Sciences 
12 


% 
13 


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
14 
ahallam 
2411 

15 
gross 
2605 
\section{Why \esc?} 
16 
caltinay 
2982 
\esc is a scripting environment for mathematical modelling based on partial 
17 
ahallam 
2979 
differential equations (PDEs). It provides a highlevel of abstraction from the 
18 


underlying numerical schemes and their implementations. By freeing the user from 
19 


considerations like data constructs, meshing and parallelisation, the user can 
20 


concentrate on the modelling aspects of the problem and still properly utilise 
21 


the powerful mathematical capabilities of PDEs. 
22 
ahallam 
2411 

23 
ahallam 
2979 
\esc is built upon the interpreted programming language \pyt\footnote{see 
24 
caltinay 
2982 
\url{www.python.org}}, a scripting language with many intrinsic functions and 
25 
ahallam 
2979 
capabilities. Additionally, there are also a large number of software packages 
26 


for \pyt which can be used in conjunction with \esc. These packages include 
27 


functions and data constructs for linear algebra, statistics, visualisation, 
28 


image processing and data plotting among others. Furthermore, most \esc scripts 
29 


are scalable and able to run on single core desktop computers right through to 
30 


multicore supercomputers\footnote{\esc supports distributed memory 
31 


architectures with multicore processors through MPI and threading. See the \esc 
32 


user guide at \url{https://launchpad.net/escriptfinley/+download} for details.} 
33 


with no modifications to the scripts. 
34 
ahallam 
2411 

35 
ahallam 
2979 
There are many benefits for using a software platform like \esc for projects 
36 
caltinay 
2982 
that involve mathematical modelling. Building on top of an existing environment 
37 


such as \esc is in many cases much simpler and more cost effective than 
38 


building an original implementation from the ground up. A modelling environment 
39 


needs data structures and solution algorithms which take time to develop and 
40 


test properly, \esc has already covered these aspects and its implementation 
41 


has been widely tested for bugs. Although existing environments may not provide 
42 


the user with the fastest algorithms for their problems, it is generally the 
43 


case, that the overall time needed to identify, implement and test the optimal 
44 


algorithm will exceed the time needed to implement and solve the problem with 
45 


predeveloped and tested software. This is particularly true if a simulation 
46 


does not need to be executed repetitively, or has relatively short lifetime. 
47 


A model for a publication or thesis would be one such instance. 
48 
gross 
2605 

49 
caltinay 
2982 
When it comes to solving partial differential equations, \esc is ideal as it is 
50 
ahallam 
2979 
especially designed for this task. Other implementations are merely an addon to 
51 


a linear algebra focused system (\textit{e.g.} MATLAB). The \esc approach gives 
52 


the user a cleaner environment to work with and provides better efficiency when 
53 


dealing with PDE coefficients. Data structures in \esc allow the user to 
54 
caltinay 
2982 
abstract away details such as data types of these coefficients. For example, if 
55 


a model has been tested with a constant PDE coefficient then the unchanged 
56 
ahallam 
2979 
script can be run with variable coefficients from a database or as a function of 
57 


a dependent variable. This capability of \esc is possible because \esc uses the 
58 


language of PDEs (as opposed to linear algebra) to describe a model. As it turns 
59 


out, the \esc approach can be applied efficiently in very large software 
60 


projects as it leads to a clearer structure for the code, by separating 
61 


modelling issues from lowlevel numerical and computational performance issues. 
62 


At the same time, this arrangement also allows for the implementation of complex 
63 


model coupling on a higherlevel. 
64 
ahallam 
2634 

65 
caltinay 
2982 
The use of \pyt as the platform for \esc makes the development of models simple 
66 


from a user perspective, as \pyt is intuitive and easy to learn. This simplicity 
67 
ahallam 
2979 
does not hamper experienced users either as \pyt also provides access to a very 
68 


large number of tools. This makes it an attractive environment to work in. Best 
69 


of all, \esc is released under an open software license and is freely available 
70 


for download. 
71 
ahallam 
2775 

72 
ahallam 
2634 
\section{How to use this Cookbook} 
73 
ahallam 
2979 
This manual is written with the intention of giving new users a practical 
74 


introduction to \esc. It demonstrates how to solve a variety of problems from 
75 


simple to advanced. We recommend that new users work through the 
76 
caltinay 
2982 
\textit{first few sets of examples} in Chapters \ref{CHAP HEAT DIFF}, 
77 
ahallam 
2979 
\ref{CHAP HEAT 2a} and \ref{CHAP HEAT 2}). 
78 


These chapters contain the necessary basic knowledge, and explain some of the 
79 


common aspects and modules of \esc. The simple examples demonstrate how to 
80 
caltinay 
2982 
create, solve and visualise PDE based models. 
81 
ahallam 
2979 
Future chapters (as they are added to this tutorial) will cover more advanced 
82 


topics with more complex models and methods. Further examples are available in 
83 


the \esc user guide. 
84 
ahallam 
2634 

85 
ahallam 
2979 
All examples covered in this cookbook have been scripted and are ready to run. 
86 


They are available from the \exf folder in the \esc directory. These scripts 
87 


provide a basis for users to develop their own models while at the same time 
88 


demonstrating the steps required to completely solve and visualise the PDE 
89 


problems. 
90 
ahallam 
2634 

91 
ahallam 
2979 
% All of the examples in this cookbook have been developed on a Linux based 
92 
caltinay 
2982 
% operating system. 
93 
ahallam 
2979 
% Unfortunately Windows and Mac support cannot be guaranteed. However, in most 
94 
caltinay 
2982 
% cases minor modifications to the scripts will generally solve any problems. 
95 
ahallam 
2645 

96 
gross 
2605 
\input{quickstart} 
97 
ahallam 
2634 
\input{escpybas} 