add README.md

2 files changed, 70 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..9227fe2
--- /dev/null
+++ b/README.md
@@ -0,0 +1,70 @@
+pyfrUtils
+=========
+
+<p align="center">
+   <img src=./images/partitionsTrimmed.png width="720" height="361" alt="partitions"/>
+</p>
+
+<p align="center">
+   A two-dimensional grid with two partitions.  Each partition has both triangular and quadrilateral cells
+</p>
+
+
+Description
+-----------
+
+*pyfrUtils* comprises two utility programs for the pre- and post-processing of mesh and data files created by [PyFR](http://www.pyfr.org/), the framework for solving advection-diffusion problems using the Flux Reconstruction method.  
+
+The first program, *pyfrm2xdmf*, reads the partitioning information from the mesh file and writes to a file format, *xdmf*, that can be directly imported by visualisation sofware such as *ParaView*.  This enables the partition scheme to be inspected ahead of a solution run.
+
+The second program, *pyfrs2vtu*, provides a convenient interface for converting the format of multiple solution files in one pass.  A sequence of time steps from a transient run, for example, can be provided as a single command line argument.
+
+Installation
+------------
+
+There are a number of options for the installation of *pyfrUtils*.  If a Python 3 *virtualenv* is being used to run PyFR then a sensible place is .../*virtualenv*/bin/.  
+
+Other options, on Linux systems, are:
+
+
+* $HOME/bin
+* /usr/local/bin
+
+
+The programs use Python 3 syntax.  If a virtual environment is not being used then attention may be required to ensure that the operating system executes the scripts using a Python 3 interpreter, not a Python 2 interpreter.
+
+Requirements
+------------
+
+
+1. *pyfrs2vtu* requires a PyFR installation.
+2. pyfrm2xdmf requires the *h5ls* command to be available.  This is one of the [HDF5](https://www.hdfgroup.org/HDF5/) utilities.  On Debian/Ubuntu systems the utility is provided by the *hdf5-tools* package.
+
+
+Usage
+-----
+
+### pyfrm2xdmf
+
+*pyfrm2xdmf* takes a single mesh file as a command line argument.  The program generates a single xdmf file and one or more connectivity files as output.  The connectivity files, one per cell shape per partition, are written in xml format.  
+
+For example, from within a directory containing a mesh file mesh.pyfrm, the command is:
+
+$ pyfrm2xdmf mesh.pyfrm
+
+This command generates the file mesh.xdmf and, according to the grid and partition scheme, connectivity files with names of the form con_*cell*_*partition*.xml.  For example, the filename con_tri_p0.xml contains the connectivity information for triangles in partition 0.
+
+*ParaView *reads the connectivity files and the original mesh file when importing the xdmf file.  Initially the complete grid is shown.  The individual partitions and the cell shapes within partitions may subsequently be viewed by using the *Extract Block* filter.
+
+### pyfrs2vtu
+
+Within a directory containing a mesh file and a set of solution files, the following command will convert all of the solution files to *vtu* format:
+
+$ pyfrs2vtu mesh.pyfrm *.pyfrs -d4
+
+For the full command line syntax, see:
+
+$ pyfrs2vtu --help
+
+
+
diff --git a/images/partitionsTrimmed.png b/images/partitionsTrimmed.png
new file mode 100644
index 0000000..365f9b1
--- /dev/null
+++ b/images/partitionsTrimmed.png