Merge branch 'v27' into development

.gitattributes

@@ -1 +1,5 @@
 *ipynb linguist-language=python
+
+*.ipynb	diff=jupyternotebook
+
+*.ipynb	merge=jupyternotebook

.gitignore

@@ -43,9 +43,9 @@ libUnderworld/h5py_ext/
 testResults
 docs/scratch
 docs/test/*Output
-docs/examples/images/*
 *ipynb.out
 *ipynb.err
+myfigure*
 
 # We should probably not cache the output of all the examples -  if we are going to leave the
 # notebook output cells in place, then there is not much need.
@@ -103,8 +103,6 @@ docs/user_guide/deformedMesh.h5
 
 docs/user_guide/surf.gldb
 
-docs/test/image_tests/notebooks/*
-
 docs/test/Pressure_Error.png
 
 docs/test/uplift/buildMount.txt

CHANGES.md

@@ -1,19 +1,47 @@
 CHANGES: Underworld2
 =======================
 
-Release 2.7.0-dev []
+Release 2.7.0b [2019-02-06]
 ------------------
-Enhancements:
-* Timing functionality available
-* glucifer defaults to use onMesh=True
+
+New functionality: 
+* Timing module for high level profiling.
+* Scaling module for numerical value scaling.
+* Index set objects can now directly index numpy arrays.
+* `show_grid()` image rendering.
+
+Changes:
+* glucifer Surface defaults to use onMesh=True.
+* added `data` handle to swarm as shortcut to particle coordinates data.
+* Adding aliases for mesh vertex sets (left,right,etc)
+* Removed `unsupported` subrepo.
+* Docker images switch to MPICH for Shifter compatibility at magnus.
+
+Documentation:
+* Examples reorganised.
+* All examples now include quantitative tests.
+* Moved many examples to models library repo.
+    https://github.com/underworldcode/model_library
+* Added new example, 08_Uplift_TractionBCs.ipynb.
+* Moved benchmarks and tutorials to models library repo.
+* Relocated defunct models:
+    https://github.com/underworldcode/model_graveyard
+* Big overhaul of user guide.
+* User guide rendered to html for Readthedocs page.
+* Updates for docstrings and doctests.
+* Improved error messaging.
+
+Fixes:
+* Fix incorrect particle outside domain issue #335
+* Other stability improvements.
 
 Release 2.6.1b [2018-10-31]
-------------------
+---------------------------
 * Remove `warning` module visibility from top level underworld 
   module.
 
-Release 2.6.0b [2018-10-18]
-------------------
+Release 2.6.0b [2018-09-27]
+---------------------------
 Enhancements:
 * Removed submodules in favour of direct access.
 * Petsc-3.9.x compatible.

COMPILE.md

@@ -1,17 +1,22 @@
 Underworld 2 Compilation
 ========================
 
+Note that for most personal computer usage, we recommend using Underworld
+through a Docker container environment. See README.md for details. 
+
+For HPC usage, you will generally need to compile Underworld, though we 
+support Shifter where available (check with the HPC admins). Basic compilation
+information is below, though please submit a github issue if you have have
+difficulties. 
+
 Dependencies
 -------------
   * MPI
   * PETSc 
   * numpy
-  * libpng
   * swig
-  * libhdf5-mpi
-  * h5py-mpi (optional)
+  * h5py-mpi
 
-Note that h5py (as installed via pip) is usually not parallel enabled. If you have an installation of libhdf5 (parallel), Underworld will attempted to download and build its own h5py during the configuration stage. If you appear to be having difficulties with h5py, it is often useful to try and import it directly from the top underworld level. 
 
 Getting the code
 ----------------
@@ -28,9 +33,7 @@ We periodically post build recipes for particular platforms on the [underworld b
 ```bash
     $ cd libUnderworld
     $ ./configure.py
-    $ ./scons.py
-    $ cd libUnderworldPy ; ./swigall.py ; cd ../
-    $ ./scons.py
+    $ ./compile.py
 ```
 
 Check available configuration options using `./configure.py --help`.  
@@ -45,5 +48,3 @@ You will first need to make the project directory available to import within pyt
 ```
 (note that if you are not using the bash shell, the required command will be different.)
 
-Various example files are provided in the `docs` directory in either ipython notebook format or in python format.
-

Dockerfile

@@ -0,0 +1,4 @@
+FROM underworldcode/underworld2:2.7.0b
+
+# Set the UW_MACHINE env variable for metrics
+ENV UW_MACHINE binder

README.md

@@ -1,53 +1,54 @@
 Underworld 2
 ============
 
-[_Underworld 2_](http://www.underworldcode.org) is a python-friendly version of the Underworld code which provides a programmable and flexible front end to all the functionality of the code running in a parallel HPC environment. This gives signficant advantages to the user, with access to the power of python libraries for setup of complex problems, analysis at runtime, problem steering, and multi physics coupling. While Underworld2 embraces Jupyter Notebooks as the preferred modelling environment, only standard python is required.
+![Underworld Montage](docs/development/docs_generator/images/Montage.png)
 
-The Underworld2 development team is based in Melbourne, Australia at the University of Melbourne and at Monash University led by Louis Moresi. We would like to acknowledge AuScope Simulation, Analysis and Modelling for providing long term funding which has made the project possible. Additional funding for specific improvements and additional functionality has come from the Australian Research Council (http://www.arc.gov.au). The python toolkit was funded by the NeCTAR eresearch_tools program. Underworld was originally developed in collaboration with the Victorian Partnership for Advanced Computing.
-
-Lastest stable release (master branch) [![Build Status](http://130.56.252.251:32779/buildStatus/icon?job=master)](http://130.56.252.251:32779/job/master/)
-
-Development branch - [![Build Status](http://130.56.252.251:32779/buildStatus/icon?job=Underworld2/development)](http://130.56.252.251:32779/job/Underworld2/job/development/)
 
-The Underworld 2 code can be cited via Zenodo [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.1436040.svg)](https://doi.org/10.5281/zenodo.1436040)
+[_Underworld 2_](http://www.underworldcode.org) is a Python friendly version of the Underworld code which provides a programmable and flexible front end to all the functionality of the code running in a parallel HPC environment. This gives significant advantages to the user, with access to the power of Python libraries for setup of complex problems, analysis at runtime, problem steering, and multi physics coupling. While Underworld2 embraces Jupyter Notebooks as the preferred modelling environment, only standard Python is required.
 
-Details of the algorithms are citeable from the references listed below. 
-
-Trying out Underworld2
-----------------------
+The Underworld2 development team is based in Melbourne, Australia at the University of Melbourne and at Monash University led by Louis Moresi. We would like to acknowledge AuScope Simulation, Analysis and Modelling for providing long term funding which has made the project possible. Additional funding for specific improvements and additional functionality has come from the Australian Research Council (http://www.arc.gov.au). The python toolkit was funded by the NeCTAR eresearch_tools program. Underworld was originally developed in collaboration with the Victorian Partnership for Advanced Computing.
 
-You can try out the code at the mybinder.org site. Be aware that it can take a little while for the site to fire up - and that it will time-out after 30 minutes and reset if you log back in. 
+[![Build Status](http://130.56.252.251:32779/buildStatus/icon?job=master)](http://130.56.252.251:32779/job/master/) Lastest stable release (master branch) 
 
-[![Binder](https://mybinder.org/badge.svg)](https://mybinder.org/v2/gh/underworldcode/underworld2-documentation/master)
+[![Build Status](http://130.56.252.251:32779/buildStatus/icon?job=Underworld2/development)](http://130.56.252.251:32779/job/Underworld2/job/development/) Development branch
 
-The mybinder.org installation is running our docker image which you can easily download and run on your own machine. 
+The Underworld2 code can be cited via Zenodo. Details of the algorithms are citeable from the references listed at the bottom of this page.
+
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.1436040.svg)](https://doi.org/10.5281/zenodo.1436040)
 
-### Installation
 
-The Underworld2 docker container is the recommended method of installation for Windows, Mac OSX and Linux. You will need to install [Docker](https://www.docker.com) on your system. The Underworld docker container is available through the docker hub:
+Documentation 
+-------------
 
-https://hub.docker.com/r/underworldcode/underworld2/
+Please visit the Underworld documentation site for an overview of installation, numerical methods, usage and the API reference. 
 
-Please check our blog page for a writeup on using dockers, and also recommendations for native installation on various platforms. 
+https://underworld2.readthedocs.io
 
-http://www.underworldcode.org/pages/Blog/
+In particular, the *Getting Started* section of the User Guide might be useful place to start.
 
-If you need to compile Underworld2 (in particular for HPC usage), please refer to COMPILE.md in this repository.
+Trying out Underworld2
+----------------------
 
-API documentation is available at http://underworld2.readthedocs.io/
+You can try out the code immediately via a Jupyter Binder cloud instance. Be aware that it can take a little while for the site to fire up and that it will time-out after 30 minutes of inactivity and reset if you log back in. 
 
+[![Binder](https://mybinder.org/badge.svg)](https://mybinder.org/v2/gh/underworldcode/underworld2/master)
 
-### Launching from the Underworld Docker Image
+Note that the Binder environment is identical to that obtained through running an Underworld Docker image locally.
 
 
-Most new users may wish to use the Kitematic GUI to download and run Underworld. Simply search for 'underworldcode/underworld2' within Kitematic, and then click 'CREATE' to launch a container. You will eventually wish to modify your container settings (again through Kitematic) to enable local folder volume mapping, which will allow you to access your local drives within your container. 
+Getting Underworld2
+-------------------
+The Underworld2 Docker container is the recommended method of installation on Windows, Mac OSX and Linux. Native compilation is generally not recommended for personal computers, although may be necessary in HPC environments which do not support containerisation. 
 
-For Linux users, and those who prefer the command line, the following minimal command should be sufficient to access the Underworld2 Jupyter Notebook examples: 
+Please refer to the documentation site for further information.
 
-```bash
-   docker run -p 8888:8888 underworldcode/underworld2
-```
 
+Directories
+-----------
+- **underworld**                 - Underworld python modules.
+- **glucifer**                   - gLucifer python modules.
+- **docs**                       - Various documentation.
+- **libUnderworld**              - Backend library
 
 Privacy
 -------

docs/README.md

@@ -0,0 +1,41 @@
+docs
+====
+
+Various user & developer domain documents and models. All models should run
+successfully against corresponding version of Underworld.
+
+
+test
+----
+These are more developer domain scripts, but advanced users might also find them useful.
+
+
+examples
+--------
+Examples generally demonstrate complete underworld model construction and usage.
+
+
+user_guide
+----------
+The user guide takes a more focused look at various aspects of underworld
+model construction. Jupyter notebooks are utilised to allow users to directly
+interact with content. Note that these documents are also rendered at the
+underworld ReadTheDocs page. 
+
+
+cheatsheet
+----------
+One pager outlining the most common Underworld usage patterns 
+and classes.
+
+
+development
+-----------
+Various documents usually more useful for Underworld developers, though
+potentially of wider use. In particular docker related files are housed 
+here. 
+
+
+install_guides
+--------------
+Installation instructions for various HPC facilities.

docs/cheatsheet/cheatsheet.tex

@@ -150,8 +150,9 @@ \section{Mesh and MeshVariables}
 \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) Allow mesh deformation.\\
+\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}
@@ -176,7 +177,7 @@ \section{Mesh and MeshVariables}
 mesh = uw.mesh.FeMesh_Cartesian(elementRes=( 4, 4 ),
                                 minCoord=( 0., 0. ),
                                 maxCoord=( 1., 1. ))
-meshvar = uw.mesh.MeshVariable(mesh, 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)
@@ -193,12 +194,13 @@ \section{Swarms and SwarmVariables}
 \vspace{1mm}
 \textit{Useful methods}:\\
 \begin{addmargin}[1em]{2em}
-\textbf{particleLocalCount}: (Property) Returns the swarm local particle count.\\
-\textbf{particleGlobalCount}: (Property) Returns the swarm global particle count.\\
-\textbf{populate\_using\_layout()}: Populate the swarm globally using provided layout object.\\
 \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{particleCoordinates}: (Property) Handle to the swarm's particle coordinates SwarmVariable.\\
+\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}
@@ -294,7 +296,7 @@ \section{Systems and Conditions}
 \begin{lstlisting}
 import underworld as uw
 mesh = uw.mesh.FeMesh_Cartesian()
-temp_var = uw.mesh.MeshVariable( mesh, 1 )
+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,

docs/development/docker/base/jupyter_notebook_config.json

@@ -1,6 +1,7 @@
 {
     "NotebookApp": {
         "password": "",
-        "token": ""
+        "token": "",
+	"ip":"0.0.0.0"
     }
 }