Merge branch 'development' into release

Author: mvousden

.gitignore

@@ -4,4 +4,9 @@ machines/
 roles/thydel.patch/
 roles/yaegashi.blockinfile/
 docs/_build/
-docs/graphs/*.pdf
+docs/images/graphs/*.pdf
+docs/images/graphs/*.png
+
+*.aux
+*.log
+*.synctex.gz

Makefile

@@ -1,32 +1,59 @@
 # This makefile is the user interface to jobs that the user may wish to carry
 # out using virtual machines.
 
+## Container targets
+full-container:
+	ansible-playbook master.yml -c local -i localhost, -v -k --extra-vars="type=container container_name=full playbook=provision_virtualmicromagnetics_full.yml hookbook=hook_container.yml extra_resources_dir=guest_resources/"
+
+lite-container:
+	ansible-playbook master.yml -c local -i localhost, -v -k --extra-vars="type=container container_name=lite playbook=provision_virtualmicromagnetics_lite.yml hookbook=hook_container.yml extra_resources_dir=guest_resources/"
+
+oommf-container:
+	ansible-playbook master.yml -c local -i localhost, -v -k --extra-vars="type=container container_name=oommf playbook=provision_virtualmicromagnetics_oommf.yml hookbook=hook_container.yml extra_resources_dir=guest_resources/"
+
+magpar-container:
+	ansible-playbook master.yml -c local -i localhost, -v -k --extra-vars="type=container container_name=magpar playbook=provision_virtualmicromagnetics_magpar.yml hookbook=hook_container.yml extra_resources_dir=guest_resources/"
+
+nmag-container:
+	ansible-playbook master.yml -c local -i localhost, -v -k --extra-vars="type=container container_name=nmag playbook=provision_virtualmicromagnetics_nmag.yml hookbook=hook_container.yml extra_resources_dir=guest_resources/"
+
+fidimag-container:
+	ansible-playbook master.yml -c local -i localhost, -v -k --extra-vars="type=container container_name=fidimag playbook=provision_virtualmicromagnetics_fidimag.yml hookbook=hook_container.yml extra_resources_dir=guest_resources/"
+
+## VM targets
+full-vm: full
+lite-vm: lite
+oommf-vm: oommf
+magpar-vm: magpar
+nmag-vm: nmag
+fidimag-vm: fidimag
+
 # This target builds a virtual hard disk file containing various open
 # micromagnetics simulation technologies and other convenient packages.
 full:
-	ansible-playbook master.yml -c local -i localhost, -v -k --extra-vars="vm_name=virtualmicromagnetics-full playbook=provision_virtualmicromagnetics_full.yml hookbook=hook.yml extra_resources_dir=guest_resources/"
+	ansible-playbook master.yml -c local -i localhost, -v -k --extra-vars="type=vm vm_name=virtualmicromagnetics-full playbook=provision_virtualmicromagnetics_full.yml hookbook=hook_vm.yml extra_resources_dir=guest_resources/"
 
 # This target builds a virtual hard disk file containing various open
 # micromagnetics simulation technologies.
 lite:
-	ansible-playbook master.yml -c local -i localhost, -v -k --extra-vars="vm_name=virtualmicromagnetics-lite playbook=provision_virtualmicromagnetics_lite.yml hookbook=hook.yml extra_resources_dir=guest_resources/"
+	ansible-playbook master.yml -c local -i localhost, -v -k --extra-vars="type=vm vm_name=virtualmicromagnetics-lite playbook=provision_virtualmicromagnetics_lite.yml hookbook=hook_vm.yml extra_resources_dir=guest_resources/"
 
 # This target builds a virtual hard disk file containing an OOMMF
 # installation.
 oommf:
-	ansible-playbook master.yml -c local -i localhost, -v -k --extra-vars="vm_name=virtualmicromagnetics-oommf playbook=provision_virtualmicromagnetics_oommf.yml hookbook=hook.yml extra_resources_dir=guest_resources/"
+	ansible-playbook master.yml -c local -i localhost, -v -k --extra-vars="type=vm vm_name=virtualmicromagnetics-oommf playbook=provision_virtualmicromagnetics_oommf.yml hookbook=hook_vm.yml extra_resources_dir=guest_resources/"
 
 # This target builds a virtual hard disk file containing a Magpar
 # installation.
 magpar:
-	ansible-playbook master.yml -c local -i localhost, -v -k --extra-vars="vm_name=virtualmicromagnetics-magpar playbook=provision_virtualmicromagnetics_magpar.yml hookbook=hook.yml extra_resources_dir=guest_resources/"
+	ansible-playbook master.yml -c local -i localhost, -v -k --extra-vars="type=vm vm_name=virtualmicromagnetics-magpar playbook=provision_virtualmicromagnetics_magpar.yml hookbook=hook_vm.yml extra_resources_dir=guest_resources/"
 
 # This target builds a virtual hard disk file containing a Nmag
 # installation.
 nmag:
-	ansible-playbook master.yml -c local -i localhost, -v -k --extra-vars="vm_name=virtualmicromagnetics-nmag playbook=provision_virtualmicromagnetics_nmag.yml hookbook=hook.yml extra_resources_dir=guest_resources/"
+	ansible-playbook master.yml -c local -i localhost, -v -k --extra-vars="type=vm vm_name=virtualmicromagnetics-nmag playbook=provision_virtualmicromagnetics_nmag.yml hookbook=hook_vm.yml extra_resources_dir=guest_resources/"
 
 # This target builds a virtual hard disk file containing a fidimag
 # installation.
 fidimag:
-	ansible-playbook master.yml -c local -i localhost, -v -k --extra-vars="vm_name=virtualmicromagnetics-fidimag playbook=provision_virtualmicromagnetics_fidimag.yml hookbook=hook.yml extra_resources_dir=guest_resources/"
+	ansible-playbook master.yml -c local -i localhost, -v -k --extra-vars="type=vm vm_name=virtualmicromagnetics-fidimag playbook=provision_virtualmicromagnetics_fidimag.yml hookbook=hook_vm.yml extra_resources_dir=guest_resources/"

README.md

@@ -1,4 +1,4 @@
-Welcome to the Virtual Micromagnetics project repository!
+Welcome to the Virtual Micromagnetics project repository! [![DOI](https://zenodo.org/badge/19288/computationalmodelling/virtualmicromagnetics.svg)](https://zenodo.org/badge/latestdoi/19288/computationalmodelling/virtualmicromagnetics)
 
 Provided by Mark Vousden, Hans Fangohr, and others at the University of Southampton. Funded by EPSRC's DTC grant EP/G03690X/1.
 

docs/conf.py

@@ -60,9 +60,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = u'1.0.2'
+version = u'1.0.4'
 # The full version, including alpha/beta/rc tags.
-release = u'1.0.2'
+release = u'1.0.4'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/container-software.rst

@@ -0,0 +1,62 @@
+.. _container-software:
+
+Containers and Related Software
+===============================
+
+In :ref:`getting-started-user`, we created a :term:`container` in addition to a
+:term:`virtual machine` based on the Full :term:`Virtual Micromagnetics`
+environment. This page talks about containers and how the
+:term:`provider`\-:term:`manager`\-:term:`provisioner` model applies to
+container creation. We recommend reading :ref:`vm-software`, if you have not
+already.
+
+Containers and Images
+---------------------
+
+A :term:`container` is a virtualisation mechanism similar to a :term:`virtual
+machine`\, in that it allows users to run software in a controlled environment
+with a cap on available computing resources (like memory). Where a virtual
+machine contains the entire software stack above and including the operating
+system, a container uses the operating system and kernel of the host machine to
+produce its environment. Containers are created from :term:`image`\s (container
+templates, analogous to :term:`box file`\s) to run a single process, and are
+usually destroyed once that process has been completed.
+
+Images can be distributed to other users so that they can run :term:`Virtual
+Micromagnetics` environments from a container.
+
+Software Related to Containers
+------------------------------
+
+As with :term:`virtual machine`\s, :term:`container`\s require supporting
+software to function. The
+:term:`provider`\-:term:`manager`\-:term:`provisioner` model outlined for
+virtual machines in :ref:`vm-software` also applies to containers as follows:
+
+ - Provisioner: Ansible is also used to provision containers. In :term:`Virtual
+   Micromagnetics`, scripts to provision containers and virtual machines with
+   software are very similar, encouraging code reuse.
+
+ - Manager: Vagrant is used to manage containers in this project in a similar
+   way to how virtual machines are managed. An exception is that Vagrant can
+   only be used to host :term:`box file`\s, meaning another hosting method is
+   needed for :term:`images`.
+
+ - Provider: Docker is used in Virtual Micromagnetics to create containers for
+   simulation (as the user) and for provisioning (as the poweruser). Docker
+   also supports online hosting of images; this is used in Virtual
+   Micromagnetics as a distribution method.
+
+Summary
+-------
+
+:term:`Container`\s are another virtualisation mechanism, like :term:`virtual
+machines`. Containers virtualise fewer elements of the software stack so they
+are smaller, but consequently impose more requirements on the :term:`host
+machine`. Like virtual machines, containers can be provisioned, managed, and
+distributed.
+
+You are now ready to :ref:`get started as a
+poweruser<getting-started-poweruser>`, which explains how to create custom
+environments containing software you choose, as well as instructions for adding
+new software or configuring your own virtual environment.

docs/developer-notes.rst

@@ -1,6 +1,6 @@
 .. _dev-notes:
 
-Developer Notes (valid for version 1.0.2)
+Developer Notes (valid for version 1.0.4)
 =========================================
 
 In :ref:`getting-started-poweruser`, we created a virtual environment from
@@ -9,66 +9,77 @@ completely specify your own environment. Knowledge of Ansible is needed, which
 can be gleaned from their excellent documentation at
 http://docs.ansible.com/ansible/.
 
-Overview: The Build and Run Processes
--------------------------------------
+.. _dev-build-process:
+
+Build and Run
+-------------
+
+The Build and Run Processes for Virtual Machines
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-This graph shows the operations involved in the build and run processes.
+This graph shows the operations involved in the build and run processes for
+:term:`virtual machine`\s.
 
-.. image:: images/graph.png
+.. image:: images/vm_graph.png
 
-Lets break this down:
+The run process is simple: the user follows the instructions in
+:ref:`getting-started-user` to create a virtual machine for themselves. Lets
+break down the build process:
 
-- Input Environment -> Developer's Virtual Machine: The input environment is a
-  :term:`virtual environment` containing only the operating system and few
+- Input Environment Box File -> Initial Virtual Machine: The input environment
+  is a :term:`virtual environment` containing only the operating system and few
   convenience tools. In development, Vagrant and VirtualBox create a
   :term:`virtual machine` from this environment in the ``create_vm`` role (see
   :ref:`dev-build-process`).
 
-- Ansible Provisions: Vagrant commands Ansible to provision this machine using
-  an Ansible playbook.
+- Initial Virtual Machine -> Virtual Machine with Simulation Packages: Vagrant
+  commands Ansible to provision this machine using an Ansible playbook.
 
-- Developer's Virtual Machine -> Output Environment: Vagrant then packages the
-  virtual machine into a new virtual environment, which can be distributed to
-  others. Tagged releases are uploaded by administrators to
-  atlas.hashicorp.com, where they become available to all Vagrant users.
+- Virtual Machine with Simulation Packages -> Output Environment Box File:
+  Vagrant then packages the virtual machine into a new virtual environment,
+  which can be distributed to others. Tagged releases are uploaded by
+  administrators to atlas.hashicorp.com, where they become available to all
+  Vagrant users.
 
-- Output Environment -> User's Virtual Machine: The previous steps are run in
-  the build phase by a developer as the build process. This step represents the
-  user following the instructions in :ref:`getting-started-user` to create a
-  virtual machine for themselves, which is referred to as the run process.
+The Build and Run Processes for Containers
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The run process performed by the user has been documented in
-:ref:`getting-started-user`. Here we introduce the build process, which
-represents the other section of this diagram.
+In the same way, this graph shows the operations involved in the build and run
+processes for :term:`container`\s.
 
-.. _dev-build-process:
+.. image:: images/container_graph.png
+
+Again the process of creating and running a container as a user is as simple as
+following the instructions in :ref:`getting-started-user`. The build process is
+also similar; a container template (:term:`image`) is downloaded, a container
+is created and provisioned, and the container is packaged as an image for
+download by all Docker users. The key difference is that Docker pushes the
+image to https://hub.docker.com/ as opposed to Vagrant.
 
-The Build Process
-~~~~~~~~~~~~~~~~~
+Details
+~~~~~~~
 
 The build (make) process in step 3 in :ref:`getting-started-poweruser` allowed
 us to create a virtual environment. The Makefile in the software repository can
 build multiple targets. Each target runs Ansible on the ``master.yml``
-playbook, which in turn runs the ``create_vm`` role in the roles
-directory. This creates a virtual machine and provisions it with the playbook
-passed as a command-line argument in ``Makefile``, which lives in the jobs
-directory. It will also do some post-provisioning tasks using the hookbook,
-again passed as a command-line argument. The fundamental difference between the
-playbook and the hookbook is that the playbook is run on the guest virtual
-machine by vagrant, and the hookbook is run on the host machine. Different
-Makefile targets may place different build artefacts in the artefacts
-directory.
+playbook, which in turn runs the ``create_vm`` or ``create_container`` role in
+the roles directory. This creates a virtual machine or container and provisions
+it with the playbook passed as a command-line argument in ``Makefile``, which
+lives in the jobs directory. It will also do some post-provisioning tasks using
+the hookbook, again passed as a command-line argument. The fundamental
+difference between the playbook and the hookbook is that the playbook is run on
+the guest virtual machine by :term:`Vagrant`, and the hookbook is run on the
+host machine. Different Makefile targets may place different build artefacts in
+the artefacts directory.
 
 Roles add or configure software, playbooks describe the roles that must be
 enacted to provision the machine, hookbooks describe what to do with that
 machine (like creating a :term:`box file`), and jobs are Makefile targets that
-produce certain machines.
-
-To add a new environment, one needs to add a job that follows the pattern of
-existing jobs.
+produce certain machines. To add a new environment, one needs to add a job that
+follows the pattern of existing jobs.
 
 Where Things Are
-----------------
+~~~~~~~~~~~~~~~~
 
 In order to add jobs, one should edit ``Makefile``. In order to do that, one
 would need to know where things are, hence the purpose of this section. The
@@ -115,8 +126,8 @@ server. Firstly, we add a target to ``Makefile`` (append the following to the ``
 
   # This target builds a virtual hard disk file containing an OOMMF and Fidimag
   # installation.
-  doc-example:
-      ansible-playbook master.yml -c local -i localhost, -v -k --extra-vars="vm_name=virtualmicromagnetics-doc-example playbook=provision_virtualmicromagnetics_doc-example.yml hookbook=hook.yml extra_resources_dir=guest_resources/"
+  doc-example-vm:
+      ansible-playbook master.yml -c local -i localhost, -v -k --extra-vars="type=vm vm_name=virtualmicromagnetics-doc-example playbook=provision_virtualmicromagnetics_doc-example.yml hookbook=hook_vm.yml extra_resources_dir=guest_resources/"
 
 Now we need to describe what the state of the machine should be, by writing the
 playbook `jobs/provision_virtualmicromagnetics_doc-examples.yml`::
@@ -199,8 +210,25 @@ now looks like::
       - { role: set_hostname, HOSTNAME: {{ vm_name }} }
       - emacs
 
-Further Tinkering
-~~~~~~~~~~~~~~~~~
+Can I have a Container Too?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You certainly can, with minimal changes too. Add this target to your Makefile::
+
+  # This target builds a container image containing an OOMMF and Fidimag
+  # installation.
+  doc-example-container:
+      ansible-playbook master.yml -c local -i localhost, -v -k --extra-vars="type=container container_name=doc-example playbook=provision_virtualmicromagnetics_doc-example.yml hookbook=hook_container.yml extra_resources_dir=guest_resources/"
+
+The only differences between this target and the one added previously are:
+
+ - The value of "type" is now "container", not "vm".
+ - The value of "hookbook" is now "hook_container.yml", not "hook_vm.yml".
+ - "vm_name=virtualmicromagnetics-doc-example" is now
+   "container_name=doc-example".
+
+Further Tinkering with the Virtual Machine
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 We have explored how a new :term:`virtual environment` can be created, and how
 new software can be added. In this section, we describe how the virtual machine
@@ -240,9 +268,10 @@ Summary and Final Words
 To summarise, :term:`virtual environment`\s are created from an empty Ubuntu
 virtual machine after being provisioned and packaged. This build process allows
 the user to create a Virtual Micromagnetics :term:`virtual machine` using
-Vagrant and VirtualBox. We have also presented how a new environment can be
-created, how the software of that environment can be controlled, and how the
-virtual machines can be parameterised.
+Vagrant and VirtualBox. A similar approach is used to create :term:`image`\s
+for :term:`Docker` :term:`containers`\. We have also presented how a new
+environment can be created, how the software of that environment can be
+controlled, and how the virtual machines can be parameterised.
 
 Thank you for using Virtual Micromagnetics! If you create roles for your
 favourite software, consider sharing them with the community. You can create a

docs/environments-software.rst

@@ -91,7 +91,7 @@ they contain:
 +-----------------+--------+----+----+-----+------+----+-------+
 
 See :ref:`getting-started-poweruser` if more fine-grained control over your
-software interests you. However, we firstly recommend reading :ref:`software`
-to understand more about :term:`virtual machine`\s, :term:`virtual
-environment`\s, and the software used to create them in the Virtual
-Micromagnetics project.
+software interests you. However, we firstly recommend reading
+:ref:`vm-software` to understand more about :term:`virtual machine`\s,
+:term:`virtual environment`\s, and the software used to create them in the
+Virtual Micromagnetics project.

docs/getting-started-poweruser.rst

@@ -7,7 +7,7 @@ In :ref:`environments`, we learned about the different :term:`Virtual
 Micromagnetics` environments available to users, which bundle sets of
 configured software. Here we outline how you can create virtual environments
 yourself, which you can distribute to others. We recommend reading
-:ref:`software`, if you have not already.
+:ref:`vm-software`, if you have not already.
 
 To create a new, custom :term:`virtual environment`, you will need the
 following software in addition to the software list in