Keywords: import, IPython notebooks
Underworld 2 provides a Python user interface to the Underworld code providing a programmable and flexible front end to the code running in a parallel HPC environment. This gives signficant advantages to the user, allowing them to leverage third party Python libraries for model configuration, analysis at runtime, coupling of multiple physics, etc. The Python interface was partly funded by the NeCTAR eResearch_tools program.
The Python interface allows users to make use of Jupyter notebooks. This allows for an interactive approach to the development and analysis of models.
Underworld documentation is broken down into:
Underworld requires basic knowledge of Python; constructs such as lists, tuples, modules, for-loops, printing and simple functions. This guide covers the basics of how to load modules for Underworld and how to use Jupyter notebooks. A short overview of a typical Underworld model with plots is given at the end of this guide.
The purpose of the user guide is to give users a more detailed understanding of the various aspects of modelling with Underworld. For those interested in getting moving as quickly as possible, the examples are perhaps a better place to start.
Underworld objects utilise Python docstrings to provide documentation inline. You may access this documentation directly by using the native Python help()
function. Quick help information in the form of a pop-up window can be obtained by using a question mark after the object within IPython/Jupyter notebooks; e.g. uw?
.
If you are new to the Jupyter Notebook, you may wish to familiarise yourself with the notebook environment first. There are many useful examples available online. Also, when using the notebook interactively, the Help menu bar option provides handy references.
This guide assumes that you have already installed Underworld. Details on how to install Underworld may be found at the project github page: https://github.com/underworldcode/underworld2
If you encounter issues or suspect a bug, please create a ticket using the issue tracker on github.
Run the following cell (either the run button
on the menu above or press shift+enter
) to load the Underworld module:
import underworld as uw
Let's do a quick run through of setting up some basic Underworld objects.
# First, create a mesh:
mesh = uw.mesh.FeMesh_Cartesian( elementType = ("Q1"),
elementRes = (8, 8),
minCoord = (0., 0.),
maxCoord = (2., 1.))
# Next we create a mesh variable:
temperatureField = mesh.add_variable( nodeDofCount=1 )
# Let's initialise the variable with some data:
for index, coord in enumerate(mesh.data):
temperatureField.data[index] = coord[1] # set the temperature to be the vertical (y) coordinate
# Finally we will plot the temperature field using ``gLucifer`` after importing the gLucifer module.
import glucifer
fig = glucifer.Figure(figsize=(800,400))
fig.append( glucifer.objects.Surface(mesh, temperatureField, colours="blue white red") )
fig.append( glucifer.objects.Mesh(mesh) )
fig.show()
Typically we might then setup boundary conditions, particle swarms, rheology and systems to be solved.
All of these topics are discussed in the following sections of the user guide.