cheatsheet.tex

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% writeLaTeX Example: A quick guide to LaTeX
%
% Source: Dave Richeson (divisbyzero.com), Dickinson College
% 
% A one-size-fits-all LaTeX cheat sheet. Kept to two pages, so it 
% can be printed (double-sided) on one piece of paper
% 
% Feel free to distribute this example, but please keep the referral
% to divisbyzero.com
% 
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% How to use writeLaTeX: 
%
% You edit the source code here on the left, and the preview on the
% right shows you the result within a few seconds.
%
% Bookmark this page and share the URL with your co-authors. They can
% edit at the same time!
%
% You can upload figures, bibliographies, custom classes and
% styles using the files menu.
%
% If you're new to LaTeX, the wikibook is a great place to start:
% http://en.wikibooks.org/wiki/LaTeX
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\documentclass[10pt,landscape]{article}
\usepackage{amssymb,amsmath,amsthm,amsfonts}
\usepackage{multicol,multirow}
\usepackage{scrextend}
\usepackage{calc}
\usepackage{listings}
\usepackage{ifthen}
\usepackage[landscape]{geometry}
\usepackage[colorlinks=true,citecolor=blue,linkcolor=blue]{hyperref}

\lstset{basicstyle = \ttfamily,columns=fullflexible}

\ifthenelse{\lengthtest { \paperwidth = 11in}}
    { \geometry{top=.5in,left=.5in,right=.5in,bottom=.5in} }
    {\ifthenelse{ \lengthtest{ \paperwidth = 297mm}}
        {\geometry{top=1cm,left=1cm,right=1cm,bottom=1cm} }
        {\geometry{top=1cm,left=1cm,right=1cm,bottom=1cm} }
    }
\pagestyle{empty}
\makeatletter
\renewcommand{\section}{\@startsection{section}{1}{0mm}%
                                {-1ex plus -.5ex minus -.2ex}%
                                {0.5ex plus .2ex}%x
                                {\normalfont\large\bfseries}}
\renewcommand{\subsection}{\@startsection{subsection}{2}{0mm}%
                                {-1explus -.5ex minus -.2ex}%
                                {0.5ex plus .2ex}%
                                {\normalfont\normalsize\bfseries}}
\renewcommand{\subsubsection}{\@startsection{subsubsection}{3}{0mm}%
                                {-1ex plus -.5ex minus -.2ex}%
                                {1ex plus .2ex}%
                                {\normalfont\small\bfseries}}
\makeatother
\setcounter{secnumdepth}{0}
\setlength{\parindent}{0pt}
\setlength{\parskip}{0pt plus 0.5ex}
% -----------------------------------------------------------------------

\begin{document}

\raggedright
\footnotesize

\begin{center}
     \Large{\textbf{Underworld2 Cheat Sheet}} \\
\end{center}
\begin{multicols}{2}
\setlength{\premulticols}{1pt}
\setlength{\postmulticols}{1pt}
\setlength{\multicolsep}{1pt}
\setlength{\columnsep}{2pt}

\section{Where to find us}

\setlength{\parindent}{16pt}

\noindent Underworld homepage \& blog: \\
\url{http://www.underworldcode.org/} \\

\noindent Underworld codebase: \\
\url{https://github.com/underworldcode/underworld2} \\

\noindent Issue tracker: \\
\url{https://github.com/underworldcode/underworld2/issues} \\
\noindent Follow us on Facebook! : \\
\url{https://www.facebook.com/underworldcode/}

\setlength{\parindent}{0pt}

\section{Useful Docker Commands}

\noindent Launch a container running Jupyter notebook instance. Port 8888 is
published to make the notebook available from host browser (usually at http://localhost:8888):
\begin{lstlisting}[language=bash]
$ docker run -p 8888:8888 underworldcode/underworld2
\end{lstlisting}

\noindent Run an Jupyter notebook mapping the current directory to a container directory (/workspace/user\_data), and
also publishing port 8888:
\begin{lstlisting}[language=bash]
$ docker run -v $PWD:/workspace/user_data -p 8888:8888 \
                              underworldcode/underworld2
\end{lstlisting}


\noindent Run an Underworld script stored in your current local directory:
\begin{lstlisting}[language=bash]
$ docker run -v $PWD:/workspace underworldcode/underworld2 \
                              python model.py
\end{lstlisting}

\noindent Run a local Underworld script in parallel:
\begin{lstlisting}[language=bash]
$ docker run -v $PWD:/workspace underworldcode/underworld2 \
                              mpirun -np 2 python model.py
\end{lstlisting}

\noindent Update your Underworld2 image:
\begin{lstlisting}[language=bash]
$ docker pull underworldcode/underworld2
\end{lstlisting}

Note: Ctrl-\textbackslash can usually be used to terminate a running docker instance.

\section{Jupyter Notebooks}

\textbf{Enter}: Enter edit mode. \\
\textbf{Esc}: Leave edit mode. \\
\textbf{Cursor Up/Down}: Move to the above/below cell (when not in edit mode). \\
\textbf{Ctrl-Enter}: Execute current cell. \\
\textbf{Shift-Enter}: Execute current cell and move to next. \\
\textbf{Tab}: (After you've commenced typing) Autocomplete. \\
\textbf{Shift-Tab}: (When inside function parenthesis) List function parameters. \\

\section{Mesh and MeshVariables}
Mesh and MeshVariable objects form the basis for numerical PDE solutions.
\newline

\noindent\textbf{uw.mesh.FeMesh\_Cartesian}:
\begin{addmargin}[1em]{2em}
This class generates a regular cartesian mesh.\\
\vspace{1mm}
\textit{Useful methods}:\\
\begin{addmargin}[1em]{2em}
\textbf{add\_variable()}: Add a MeshVariable to the mesh.\\
\textbf{data}: (Property) Access mesh vertex coordinate data.\\
\textbf{deform\_mesh()}: (Context manager) Deform mesh within this manager.\\
\textbf{reset()}: Reset the mesh to its original configuration.\\
\textbf{specialSets}: (Dict) Dictionary of special vertex sets associated with the mesh.\\
\end{addmargin}
\end{addmargin}

\vspace{1mm}

\noindent\textbf{uw.mesh.MeshVariable}:
\begin{addmargin}[1em]{2em}
The MeshVariable class adds data at each vertex of the mesh.\\
\vspace{1mm}
\textit{Useful methods}:\\
\begin{addmargin}[1em]{2em}
\textbf{data}: (Property) Access variable data.\\
\end{addmargin}
\end{addmargin}

\vspace{2mm}
\noindent\textbf{\textit{Example}}:
\begin{lstlisting}
import underworld as uw
mesh = uw.mesh.FeMesh_Cartesian(elementRes=( 4, 4 ),
                                minCoord=( 0., 0. ),
                                maxCoord=( 1., 1. ))
meshvar = mesh.add_variable(1)
meshvar.data[:] = 0.      # initialise data to zero
with mesh.deform_mesh():  # deform mesh
    mesh.data[0] = (-0.1,-0.1)
\end{lstlisting}

\section{Swarms and SwarmVariables}
Swarms define arbitrarily located points which may be used to define complex
geometries for your dynamics.
\newline

\noindent\textbf{uw.swarm.Swarm}:
\begin{addmargin}[1em]{2em}
The Swarm class provides a container for particles.\\
\vspace{1mm}
\textit{Useful methods}:\\
\begin{addmargin}[1em]{2em}
\textbf{add\_particles\_with\_coordinates()}: Populate the swarm using provided coordinates array.\\
\textbf{add\_variable()}: Adds a SwarmVariable to the swarm. Returns the SwarmVariable object.\\
\textbf{data}: (Property) Handle to the swarm's particle coordinates SwarmVariable.\\
\textbf{deform\_swarm()}: (Context manager) Explicitly move swarm particles within this manager.\\
\textbf{particleGlobalCount}: (Property) Returns the swarm global particle count.\\
\textbf{particleLocalCount}: (Property) Returns the swarm local particle count.\\
\textbf{populate\_using\_layout()}: Populate the swarm globally using provided layout object.\\
\end{addmargin}
\end{addmargin}
\vspace{2mm}
\noindent\textbf{uw.swarm.SwarmVariable}:
\begin{addmargin}[1em]{2em}
The SwarmVariable class adds data to each particle. Note that you will usually create swarm
variables via the \textbf{add\_variable()} method on your swarm object.\\
\vspace{1mm}
\textit{Useful methods}:\\
\begin{addmargin}[1em]{2em}
\textbf{data}: (Property) Access the swarm variables underlying data.\\
\end{addmargin}
\end{addmargin}

\vspace{2mm}
\noindent\textbf{\textit{Example}}:
\begin{lstlisting}
import underworld as uw
mesh = uw.mesh.FeMesh_Cartesian()
swarm = uw.swarm.Swarm(mesh)
svar = swarm.add_variable("int",1)
layout = uw.swarm.layouts.PerCellSpaceFillerLayout(swarm,20)
swarm.populate_using_layout(layout)
\end{lstlisting}


\section{Systems and Conditions}
The systems and conditions modules houses PDE related classes.\\
\vspace{1mm}

\noindent\textbf{uw.systems.SteadyStateHeat}:
\begin{addmargin}[1em]{2em}
This class implements FEM to constructs an SLE representation of a steady state heat equation of the form:
 \[\nabla(k \nabla)T = h\]
\end{addmargin}
\vspace{1mm}

\noindent\textbf{uw.systems.Stokes}:
\begin{addmargin}[1em]{2em}
This class implements FEM to constructs an SLE representation of a Stokes type system of the form:
 \[\tau_{ij,j} -  p_{,i} + f_i = 0\]
\end{addmargin}
\vspace{1mm}

\noindent\textbf{uw.systems.Solver}:
\begin{addmargin}[1em]{2em}
This class returns a solver appropriate for the provide SLE object.\\
\vspace{1mm}
\textit{Useful methods}:\\
\begin{addmargin}[1em]{2em}
\textbf{solve()}: Solve the system.\\
\end{addmargin}
\end{addmargin}
\vspace{1mm}

\noindent\textbf{uw.systems.AdvectionDiffusion}:
\begin{addmargin}[1em]{2em}
This class constructs an SUPG implementation of an Advection-Diffusion type system of the form:
 \[\frac{\partial\phi}{\partial t}  + {\bf u } \cdot \nabla \phi= \nabla { ( k  \nabla \phi } )\]
\textit{Useful methods}:\\
\begin{addmargin}[1em]{2em}
\textbf{get\_max\_dt()}: Returns a CFL type timestep size.\\
\textbf{integrate()}: Integrate forward in time for provided time interval.\\
\end{addmargin}
\end{addmargin}
\vspace{1mm}

\noindent\textbf{uw.systems.SwarmAdvector}:
\begin{addmargin}[1em]{2em}
This class implements a time integration scheme to advect swarm particles using a provided velocity.\\
\vspace{1mm}
\textit{Useful methods}:\\
\begin{addmargin}[1em]{2em}
\textbf{get\_max\_dt()}: Returns a CFL type timestep size.\\
\textbf{integrate()}: Integrate forward in time for provided time interval.\\
\end{addmargin}
\end{addmargin}
\vspace{1mm}

\noindent\textbf{uw.conditions.DirichletCondition}:
\begin{addmargin}[1em]{2em}
This class implements a Dirichlet condition at the specified nodes.
\end{addmargin}
\vspace{1mm}

\noindent\textbf{uw.conditions.NeumannCondition}:
\begin{addmargin}[1em]{2em}
This class implements a Neumann condition at the specified nodes.
\end{addmargin}

\vspace{2mm}
\noindent\textbf{\textit{Example}}:
\begin{lstlisting}
import underworld as uw
mesh = uw.mesh.FeMesh_Cartesian()
temp_var = mesh.add_variable( 1 )
bISet = mesh.specialSets["MinJ_VertexSet"]  # grab bottom set
tISet = mesh.specialSets["MaxJ_VertexSet"]  # grab top set
bcs = uw.conditions.DirichletCondition(temp_var,
                indexSetsPerDof=bISet+tISet)
temp_var.data[bISet.data] = 1.  # set bottom BC value
temp_var.data[tISet.data] = 0.  # set top BC value
thermal_system = uw.systems.SteadyStateHeat(temp_var,
                                          fn_diffusivity=1.,
                                          conditions=[bcs,])
solver = uw.systems.Solver(thermal_system)
solver.solve()
\end{lstlisting}

\section{Functions}
Functions provide a high level interface to your modelling data and allow you to define model behaviours.
Functions are overloaded with the +,-,*,-,[] and ** operators.
\vfill
\columnbreak
\noindent\textbf{uw.function.Function}:
\begin{addmargin}[1em]{2em}
This is an abstract class. Any class which inherits from this class is able to behave as a function object.\\
\vspace{1mm}
\textit{Useful methods}:\\
\begin{addmargin}[1em]{2em}
\textbf{evaluate()}: Evaluate the function at the provided coordinate or coordinate array. Returns an array of results.\\
\end{addmargin}
\end{addmargin}
\vspace{1mm}
\noindent\textbf{uw.function.coord}:
\begin{addmargin}[1em]{2em}
This function returns the coordinate at the evaluation position.
\end{addmargin}
\vspace{1mm}
\noindent\textbf{uw.function.analytic}:
\begin{addmargin}[1em]{2em}
This module contains various analytic solutions functions.
\end{addmargin}
\vspace{1mm}
\noindent\textbf{uw.function.branching}:
\begin{addmargin}[1em]{2em}
This module contains various branching functions.
\end{addmargin}
\vspace{1mm}
\noindent\textbf{uw.function.exception}:
\begin{addmargin}[1em]{2em}
This module contains functions which raise exceptions when things go wrong.
\end{addmargin}
\vspace{1mm}
\noindent\textbf{uw.function.math}:
\begin{addmargin}[1em]{2em}
This module contains elementary mathematical functions.
\end{addmargin}
\vspace{1mm}
\noindent\textbf{uw.function.rheology}:
\begin{addmargin}[1em]{2em}
This module contains a function which implements a stress limiting viscosity.
\end{addmargin}
\vspace{1mm}
\noindent\textbf{uw.function.shape}:
\begin{addmargin}[1em]{2em}
This module contains a Polygon shape.
\end{addmargin}
\vspace{1mm}
\noindent\textbf{uw.function.tensor}:
\begin{addmargin}[1em]{2em}
This module contains functions for tensor relations.
\end{addmargin}
\vspace{1mm}

\section{Visualisation}
The Underworld visualisation engine is called \textbf{glucifer}.
\vspace{1mm}

\noindent\textbf{glucifer.Figure}:
\begin{addmargin}[1em]{2em}
The Figure class is the basic container object for visualisation.\\
\vspace{1mm}
\textit{Useful methods}:\\
\begin{addmargin}[1em]{2em}
\textbf{show()}: Show the rendered image.\\
\textbf{save\_image()}: Save a rendered image to disk.\\
\textbf{append()}: Append a drawing object.\\
\textbf{clear()}: Clear the figure of drawing objects.\\
\end{addmargin}
\end{addmargin}

\vspace{1mm}

\noindent\textbf{glucifer.objects.Drawing}:
\begin{addmargin}[1em]{2em}
Subclasses of this class provide the ingredients you will compose your visualisations with.
This is an abstract class so you will never use it directly.
\end{addmargin}

\noindent\textbf{glucifer.objects.Mesh}:
\begin{addmargin}[1em]{2em}
Draw the provided mesh object.
\end{addmargin}

\noindent\textbf{glucifer.objects.Surface}:
\begin{addmargin}[1em]{2em}
Draws the provided function across a mesh surface.
\end{addmargin}

\noindent\textbf{glucifer.objects.Points}:
\begin{addmargin}[1em]{2em}
Draws the provided swarm, using functions to determine point attributes.
\end{addmargin}

\noindent\textbf{glucifer.objects.VectorArrows}:
\begin{addmargin}[1em]{2em}
Draws the vector arrows across a mesh corresponding to a provided vector function.
\end{addmargin}

\noindent\textbf{glucifer.objects.Volume}:
\begin{addmargin}[1em]{2em}
Performs a volume render of the provided function within the provided mesh.
\end{addmargin}


\vspace{2mm}
\noindent\textbf{\textit{Example}}:
\begin{lstlisting}
import underworld as uw
import glucifer
fig = glucifer.Figure()
mesh = uw.mesh.FeMesh_Cartesian() # create something to draw
fig.append( glucifer.objects.Mesh(mesh) )
fig.show()
\end{lstlisting}

\end{multicols}
\end{document}