Getting started

Keywords: import, IPython notebooks

Welcome to using Underworld!

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.

Documentation

Underworld documentation is broken down into:

  1. examples: These notebooks go through the entire workflow for geophysics type problems.
  2. user guide: A more focused look at particular aspects of Underworld (e.g. swarm particles).
  3. publications: Notebooks which replicate models and results from the literature.
  4. docstrings: The Underworld API includes Python docstring type documentation.

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?.

Notebooks

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.

Installation

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

How to get help

If you encounter issues or suspect a bug, please create a ticket using the issue tracker on github.

Importing

Run the following cell (either the run button on the menu above or press shift+enter) to load the Underworld module:

In [1]:
import underworld as uw

A quick demo

Let's do a quick run through of setting up some basic Underworld objects.

In [2]:
# First, create a mesh:
mesh = uw.mesh.FeMesh_Cartesian( elementType = ("Q1"), 
                                 elementRes  = (8, 8), 
                                 minCoord    = (0., 0.), 
                                 maxCoord    = (2., 1.))
In [3]:
# Next we create a mesh variable:
temperatureField = mesh.add_variable( nodeDofCount=1 )
In [4]:
# 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
In [5]:
# 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.