Initial commit.

Author: mvousden

.gitignore

@@ -0,0 +1,6 @@
+*~
+
+artefacts/
+machines/
+roles/thydel.patch/
+roles/yaegashi.blockinfile/

LICENSE.md

@@ -0,0 +1,27 @@
+Virtualmicromagnetics source code, documentation, and build artefacts are
+licensed by the 3-Clause BSD License as follows:
+
+Copyright (c) 2015, Mark Vousden, University of Southampton
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright
+      notice, this list of conditions and the following disclaimer in the
+      documentation and/or other materials provided with the distribution.
+    * Neither the name of the University of Southampton nor the
+      names of its contributors may be used to endorse or promote products
+      derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYWRITE OWNERS OR SOFTWARE CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
+GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
+OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Makefile

@@ -0,0 +1,12 @@
+# This makefile is the user interface to jobs that the user may wish to carry
+# out using virtual machines.
+
+# 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_virtualmicromagnetics_full.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_virtualmicromagnetics_lite.yml extra_resources_dir=guest_resources/"

README.md

@@ -0,0 +1,203 @@
+Objective
+=========
+
+To use virtual machine software VirtualBox and vagrant, and provisioning
+software Ansible, to produce an environment suitable for micromagnetic
+simulation.
+
+Quick Start
+===========
+
+To get started with this repository and creating virtual machines without
+understanding the underlying concepts, simply adhere to the "Requirements"
+section below and use the Makefile as described in the "How to Use" section
+following it.
+
+Just remember that there is no shortcut to work done true and well.
+
+Introduction to Concepts
+========================
+
+A number of different concepts interplay in this repository, so a brief
+introduction to them is provided here.
+
+Virtual Machines
+----------------
+
+A virtual machine is a software that imitates a certain other software (usually
+an operating system or environment) on a certain hardware. For our purposes
+however, it can be thought of as an operating system running in an operating
+system. Virtual machines are useful because they allow software tasks to be
+undertaken in precisely defined environments with little repercussion on the
+host system they run on. These machines themselves can be described by single
+files representing the equivalent of a hard disk of the machine, as well as a
+description of the hardware that the virtual machine emulates.
+
+VirtualBox (www.virtualbox.org) is a virtualizer software that can create and
+manage virtual machines, and is open source and freely available under the GNU
+GPL (https://www.gnu.org/copyleft/gpl.html) at time of writing. It is a
+"provider" of virtual machines. Other popular provider software includes VMWare
+and KVM.
+
+Vagrant (www.vagrantup.com) is a wrapper around multiple pieces of software. It
+provides a command-line interface to the creation and provision of virtual
+machines, and provides a framework in which virtual machines can be easily
+shared. Most importantly for our purpose, this interfacing can be automated to
+generate virtual machines containing an environment without user
+intervention. This environment can then be used to complete our objectives. To
+specify this environment however, provisioning software is required.
+
+Provisioning
+------------
+
+In the context of virtual machines, provisioning is the action of taking an
+existing virtual machine, and running select commands on it to result in a
+desired end-state. By "state", here we mean how storage is populated with
+packages, environment definitions, and more. The user of a provisioner
+describes the desired state of the system, and the provisioner makes it so. In
+the absence of a provisioner, shell commands can be executed by Vagrant to
+specify the state of the system, but for large projects this becomes unwieldy
+because focus is placed on the instructions needed to obtain the desired state,
+as opposed to the state itself. Since nobody really likes to write large
+projects in shell, a provisioner is recommended.
+
+Ansible (www.ansible.com) is a provisioner supported by Vagrant. It uses YAML
+syntax to describe plays to run on a remote system to define the
+environment. Since the focus is on the end-state of the system, idempotency a
+strong design concern, meaning that tasks only need to be run to achieve a
+change in the state, and are not run if they do not change the state or obtain
+information about it. Plays are described by playbook files, and may contain
+many roles; hence the existence of a "roles" directory in this
+repository. Roles are a way of breaking down a play into sensible sentence-like
+instructions, which in turn contain a number of tasks. Examples of role
+descriptions include "Install magpar." and "Configure passwordless SSH for
+BitBucket access."
+
+In addition to provisioning virtual machines, Ansible is a general framework
+for running instructions to define a state on any machine. This means that
+Ansible can be (and is) used by a host to create virtual machines using
+vagrant. This is convenient due to its inherent idempotency; a virtual machine
+need not be created and defined again from scratch if it already exists.
+
+Tying it together
+-----------------
+
+To conclude, virtual machines are created in this repository to produce build
+artefacts. Ansible is used to define the state of virtual machines, which are
+managed by Vagrant. Vagrant commands VirtualBox to create and internally manage
+virtual machines in an automated way. These virtual machines are in turn
+provisioned by Ansible to define their internal state. Once this provisioning
+has happened, a build artefact is produced according to the desired objective.
+
+Requirements
+============
+
+This repository was developed on and designed for use by Ubuntu GNU/Linux, but
+should be usable by anyone using GNU/Linux and enough modification and
+persistence. The following software are required to use this repository for its
+intended purpose:
+
+  - 2.6 <= Python < 3.0
+    > A note for bleeding-edge distribution users like ArchLinux; Ansible
+      doesn't like Python 3.0. You may need to create a virtualenv
+      (https://pypi.python.org/pypi/virtualenv) to ensure you are working with
+      an older python version.
+  - VirtualBox >= 4.3.28
+  - Vagrant >= 1.7.2
+  - Ansible >= 1.9
+    > available from the python package index (https://pypi.python.org/pypi).
+  - thydel.patch Ansible role
+    > command "ansible-galaxy install thydel.patch" with privileges.
+  - yaegashi.blockinfile Ansible role
+    > command "ansible-galaxy install yaegashi.blockinfile" with privileges.
+  - Vagrant-vbguest plugin >= 0.10.0
+    > command "vagrant plugin install vagrant-vbguest"
+
+The following software is recommended:
+
+  - Cowsay
+
+How to Use
+==========
+
+Now that you have prepared your host machine by following the "Requirements"
+section, you will probably want to build a virtual machine. By way of example,
+if you want the full virtualmicromagnetics experience, command:
+
+  make full
+
+This Makefile uses the master.yml playbook, which runs the "create_vm"
+role. This will create a virtual machine and provision it with the playbook
+passed as a command-line argument in the makefile, which should live in the
+jobs directory (see "Where things are" below). 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 (see 'Where Things Are'
+and 'Artefacts').
+
+Artefacts
+=========
+
+After running a job from the Makefile, certain build artefacts may be
+created. At present only *.vhd (virtual hard disk) files are created, but other
+file types could be produced by future jobs. These files are to be used with
+virtual machine providers, such as VirtualBox. To use these files with the
+VirtualBox GUI, build a "New" machine with an 64 bit Ubuntu OS, and supply as
+much RAM as you are able. All virtual machines in this repository are built off
+such an operating system.
+
+Where Things Are
+================
+
+In order to add jobs, one should edit the Makefile. In order to do that, one
+would need to know where things are, hence the purpose of this section. This
+repository is structured as follows:
+
+  - Makefile: This is the makefile through which all jobs are conducted.
+
+  - ansible.cfg and inventory.txt: These files are used by Ansible when the
+    master.yml playbook is run. They contain configuration information.
+
+  - roles/: This directory contains roles (obviously). Each role is given a
+    subdirectory, and should not overlap. Each role directory contains
+    tasks, and may also contain the subdirectories:
+
+    - vars/ (variable definitions),
+    - templates/ (files to duplicate to the guest virtual machine),
+    - meta/ (metadata, such as role dependencies),
+    - files/ (files used by tasks that aren't covered by the usecases of
+      templates)
+
+    as well as others we haven't thought of yet.
+
+  - jobs/: This directory contains playbooks and directories that can be
+    thought of as jobs in the Makefile. They are either provisioning playbooks,
+    or post-provisioning hookbooks.
+
+  - machines/: This directory is created by the Makefile, and houses the
+    vagrant environment for each individual virtual machine. The provision
+    process is recorded to a log file in the machine's directory (for example,
+    the provision log for the lite build job exists in
+    machines/virtualmicromagnetics-lite/virtualmicromagnetics-lite.log)
+
+  - artefacts/: This directory is created by the Makefile, and houses build
+    artefacts.
+
+Postamble
+=========
+
+See LICENSE.md for licensing details regarding distribution and
+liability. These tools are provided by the University of Southampton (Mark
+Vousden, Max Albert, Hans Fangohr and others). Neither the University of
+Southampton nor the authors assume any responsibility whatsoever for its use by
+other parties, and makes no guarantees, expressed or implied, about its
+quality, reliability, or any other characteristic.
+
+List of Things to do
+====================
+
+  - Learn how YAML linebreaks work, and reduce the lengths of lines to <80
+    characters.
+  - Make syntax more consistent.

ansible.cfg

@@ -0,0 +1,3 @@
+[ssh_connection]
+ssh_args = -o IdentityFile=~/.vagrant.d/insecure_private_key
+

guest_resources/welcome.rst

@@ -0,0 +1,41 @@
+Welcome to the Virtual Micromagnetics Simulation Environment!
+-------------------------------------------------------------
+
+This virtual machine contains a number of distributable software packages that
+are often used by the micromagnetic community to simulate relevant
+problems. These software can be downloaded from this machine; tarballs are
+available in the home directory. Micromagnetic software includes (in no
+particular order):
+
+  | OOMMF 1.2a5 (The Object Oriented MicroMagnetic Framework): http://math.nist.gov/oommf/
+  | Documentation: http://math.nist.gov/oommf/doc/
+
+  | Nmag 0.2: http://nmag.soton.ac.uk/nmag/
+  | Documentation: http://nmag.soton.ac.uk/nmag/current/manual/singlehtml/manual.html
+
+  | magpar 0.9 (Parallel Finite Element Micromagnetics Package): http://www.magpar.net/
+  | Documentation: http://www.magpar.net/static/magpar-0.9/doc/html/
+
+For more information about these packages, see their respective websites and
+`Examples.html <Examples.html>`_, which walks the prospective user through some
+examples and tests where applicable. Users are also encouraged to install their
+own simulation packages for use on this machine. To that end, a number of other
+software packages have been provided:
+
+  | FEniCS 1.5.0: http://fenicsproject.org/
+  | The FEniCS project is a collection of free software tools with many features for solving differential equations in an automated and efficient manner.
+
+  | gmsh 2.8.5: http://geuz.org/gmsh/
+  | Netgen: http://sourceforge.net/projects/netgen-mesher/files/
+  | gmsh and Netgen are 3D mesh generators often used for the finite element method in micromagnetic modelling.
+
+Other lower-level tools are installed for convenience, such as paraview, grace,
+gnuplot, the IPython (Jupyter) Notebook and more. This machine runs on 64-bit
+Ubuntu with Xfce as a desktop environment.
+
+These tools are provided by the University of Southampton (Mark Vousden, Max
+Albert, Hans Fangohr and others). Neither the University of Southampton nor the
+authors assume any responsibility whatsoever for its use by other parties, and
+makes no guarantees, expressed or implied, about its quality, reliability, or
+any other characteristic. Please provide feedback about this machine to Mark
+Vousden at [email protected]

inventory.txt

@@ -0,0 +1,2 @@
+[local]
+127.0.0.1

jobs/hook_virtualmicromagnetics_full.yml

@@ -0,0 +1,67 @@
+---
+# This Ansible playbook outlines actions taken on the host machine on the
+# virtual machine after the virtual machine is provisioned. It is included in
+# the create_VM playbook.
+
+- name: Set the location to look for and place build artefacts, and whether or not to clobber the output virtual hard disk file.
+  set_fact:
+    artefact_dir: "{{ vm_dir }}/../../artefacts/"
+    clobber_vhd: false
+
+- name: Ensure that a directory is created for build artefacts.
+  file:
+    name={{ artefact_dir }}
+    state=directory
+
+- name: Get current repository version.
+  command: git rev-parse HEAD
+  register: current_revision
+
+- name: Define the name used for output files, sans extension.
+  set_fact:
+    output_name: virtualmicromagnetics_full_{{ current_revision.stdout }}
+
+# We can skip the creation of the VHD if it already exists (for
+# idempotency). Hence we check for the VHD here and, if it is found, other
+# creation tasks are not run. User can override this setting by setting
+# clobber_vhd to true.
+- name: Determine whether or not the VHD is already built.
+  stat:
+    path={{ artefact_dir }}/{{ output_name }}.vhd
+  register: vhd_status
+
+- name: Create box file using vagrant.
+  command: vagrant package --output {{ artefact_dir }}/{{ output_name }}.box
+    chdir={{ vm_dir }}
+    creates={{ artefact_dir }}/{{ output_name }}.box
+  when: not vhd_status.stat.exists or (vhd_status.stat.isreg and clobber_vhd)
+
+- name: Extract the virtual machine disk (VMDK) file from the box.
+  command: tar -xvf {{ output_name }}.box -C {{ artefact_dir }} ./box-disk1.vmdk
+    chdir={{ artefact_dir }}
+    creates={{ artefact_dir }}/box-disk1.vmdk
+  when: not vhd_status.stat.exists or (vhd_status.stat.isreg and clobber_vhd)
+
+- name: Convert the virtual machine disk (VMDK) to a virtual hard disk (VHD).
+  command: VBoxManage clonehd --format VHD box-disk1.vmdk {{ output_name }}.vhd
+    chdir={{ artefact_dir }}
+    creates={{ artefact_dir }}/{{ output_name }}.vhd
+  when: not vhd_status.stat.exists or (vhd_status.stat.isreg and clobber_vhd)
+
+- name: Remove the box.
+  file:
+    path={{ artefact_dir }}/{{ output_name }}.box
+    state=absent
+
+- name: Remove the virtual machine disk (VMDK).
+  file:
+    path={{ artefact_dir }}/box-disk1.vmdk
+    state=absent
+
+- name: Destroy the virtual machine.
+  command: vagrant destroy --force
+    chdir={{ vm_dir }}
+
+- name: Inform the user that the virtual hard disk has been created.
+  debug:
+    msg="Virtual machine '{{ vm_name }}' has been successfully created, and a build artefact is in {{ artefact_dir }}."