1 

2 
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
3 
% Copyright (c) 20032018 by The University of Queensland 
4 
% http://www.uq.edu.au 
5 
% 
6 
% Primary Business: Queensland, Australia 
7 
% Licensed under the Apache License, version 2.0 
8 
% http://www.apache.org/licenses/LICENSE2.0 
9 
% 
10 
% Development until 2012 by Earth Systems Science Computational Center (ESSCC) 
11 
% Development 20122013 by School of Earth Sciences 
12 
% Development from 2014 by Centre for Geoscience Computing (GeoComp) 
13 
% 
14 
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
15 

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

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

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

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

66 
The use of \pyt as the platform for \esc makes the development of models simple 
67 
from a user perspective, as \pyt is intuitive and easy to learn. This simplicity 
68 
does not hamper experienced users either as \pyt also provides access to a very 
69 
large number of tools. This makes it an attractive environment to work in. Best 
70 
of all, \esc is released under an open software license and is freely available 
71 
for download. 
72 

73 
\section{How to use this Cookbook} 
74 
This manual is written with the intention of giving new users a practical 
75 
introduction to \esc. It demonstrates how to solve a variety of problems from 
76 
simple to advanced. We recommend that new users work through the 
77 
\textit{first few sets of examples} in Chapters \ref{CHAP HEAT DIFF}, 
78 
\ref{CHAP HEAT 2a} and \ref{CHAP HEAT 2}). 
79 
These chapters contain the necessary basic knowledge, and explain some of the 
80 
common aspects and modules of \esc. The simple examples demonstrate how to 
81 
create, solve and visualise PDE based models. 
82 
Future chapters (as they are added to this tutorial) will cover more advanced 
83 
topics with more complex models and methods. Further examples are available in 
84 
the \esc user guide. 
85 

86 
All examples covered in this cookbook have been scripted and are ready to run. 
87 
They are available from the \exf folder in the \esc directory. These scripts 
88 
provide a basis for users to develop their own models while at the same time 
89 
demonstrating the steps required to completely solve and visualise the PDE 
90 
problems. 
91 

92 
\input{quickstart} 
93 
\input{escpybas} 