1. Build SNAC with Pyre on a recent Linux system

1.1 Building Pyre and Exchanger

1.1.1 libxml2 and MPICH
These two libraries are assumed to be available already.
Note that OpenMPI is currently NOT supported.

1.1.2 pythia-0.8
- Available at https://geodynamics.org/cig/software/pythia/
but use the version 0.8 included in this source tree with the following changes:
  - Fixed Makefile.am
    ACLOCAL_AMFLAGS = -I ./m4 ==> ACLOCAL_AMFLAGS = -I m4
  - Reconfigured with 
    autoreconf -i .
  - pympi.h added to packages/mpi/mpimodule

- Run ./configure
./configure --prefix=/Users/eunseo/projects/snac_bmi/pythia

- Make sure that the local sysconfig.pyc doesn't interefere the intallation step
make; make install
  - Ignore the following Python error at the last installation step
    ImportError: cannot import name get_config_var

1.1.3 Exchanger-1.0.1
- Contains classes to be inherited by StGermain and Snac's Exchanger module.
- Original source at https://geodynamics.org/cig/software/exchanger/
  but this source tree contains a modified version that skips pythia installation.
- configure
CXXFLAGS="-fPIC -I${PYTHIA_INCDIR}" ./configure --prefix=/Users/eunseo/projects/bmi-pyre/Exchanger
- make; make install; make install-data (Note: the local sysconfig.pyc can confuse the install process).

1.2 SNAC
- For installation, see the user manual or INSTALL for quick start.
Basically, './configure --options=CHILD; make'.

- Some customization of environment variables might be required 
prior to configuring and building SNAC with Pyre support.
The recommended set of environment variables is given below.
Note that some values need to be changed according to a user's setting.

In bash:
======================================================
export MPI_DIR=/usr
export MPI_BINDIR=${MPI_DIR}/bin
export MPI_INCDIR=${MPI_DIR}/include/mpich
export MPI_LIBDIR=${MPI_DIR}/lib
export PATH=${MPI_BINDIR}:{$PATH}
export LD_LIBRARY_PATH=${MPI_LIBDIR}:{LD_LIBRARY_PATH}

export PYTHIA_DIR=${HOME}/projects/bmi-pyre/pythia
export PYTHIA_INCDIR=${PYTHIA_DIR}/include/pythia-0.8
export PYTHIA_LIBDIR=${PYTHIA_DIR}/lib
export PYTHIA_BINDIR=${PYTHIA_DIR}/bin
export PATH=${PYTHIA_BINDIR}:${PATH}
export PYTHONPATH=${PYTHIA_LIBDIR}/python2.7/site-packages:${PYTHONPATH}

export EXCHANGER_DIR=${HOME}/projects/bmi-pyre/Exchanger
export EXCHANGER_INCDIR=${EXCHANGER_DIR}/include
export EXCHANGER_LIBDIR=${EXCHANGER_DIR}/lib
export EXCHANGER_BINDIR=${EXCHANGER_DIR}/bin
export PATH=${PYTHIA_BINDIR}:${PATH}
export LD_LIBRARY_PATH=${PYTHIA_LIBDIR}:${LD_LIBRARY_PATH}
export PYTHONPATH=${PYTHIA_LIBDIR}/python2.7/site-packages:${PYTHONPATH}

export SNAC_DIR=${HOME}/projects/bmi-pyre/build
export SNAC_BINDIR=${SNAC_DIR}/bin
export SNAC_INCDIR=${SNAC_DIR}/include
export SNAC_LIBDIR=${SNAC_DIR}/lib
export SNAC_MODDIR=${SNAC_DIR}/Python
export PATH=${SNAC_BINDIR}:{$PATH}
export LD_LIBRARY_PATH=${SNAC_LIBDIR}:{LD_LIBRARY_PATH}
export PYTHONPATH=${SNAC_MODDIR}:${PYTHONPATH}
======================================================

1.3 Test
- Go to Snac/tests
- Run: sh ./basic-pyre.sh

1.4 Build SNAC with Pyre on OS X

Building SNAC with Pyre support on OS X is still experimental but 
in principle, the steps described above can be followed.


2. Running Pyre-SNAC through BMI
2.1 Check out CSDMS bmi-python from https://github.com/csdms/bmi-python
2.2 Add bmi-python and bmi-pyre/bmi to PYTHONPATH
======================================================
export BMIPYTHON_DIR=${HOME}/projects/bmi-python
export PYTHONPATH=${BMIPYTHON_DIR}:${PYTHONPATH}

export BMIPYRE_DIR=${HOME}/projects/bmi-pyre/bmi
export PYTHONPATH=${BMIPYRE_DIR}:${PYTHONPATH}
======================================================
2.3 Run bmi-pyre/Snac/tests/basic-bmi-irf.py

3. Using a Docker image
All of the above builidng procedures have been executed on Ubuntu 14.04 
and a public Docker image of the resultant working environment has been created 
on Docker Hub (https://hub.docker.com/r/eunseochoi/bmi-pyre-snac/)

To use the Docker iamge, do the following:
- Install Docker (see http://docs.docker.com/). 
- If on OS X, start a Docker terminal. If on linux, all the docker commands below should be run with sudo.
- pull the latest image
docker pull eunseochoi/bmi-pyre-snac:latest
- start an interactive container using the image
docker run -ti eunseochoi/bmi-pyre-snac:latest
- One can mount a host system's directory with -v.
e.g., docker run -ti -v /Users/eunseo/.ssh:/home/bmiuser/.ssh eunseochoi/bmi-pyre-snac:latest
- become the pre-configured normal user, bmiuser
# su bmiuser
- go to the project directory and do the tests (see Sec. 1.3 and 2.3 above)
> cd ~/bmiprojects