README for Heart Demo Project  ver. 1.0
             ========================================

Description
==========================
This is the "heart_demo" project that implements minimal functionality
for a real-time 3D cardiac electrophysiology simulation.
It can be launched on "host" and Intel(R) Many Integrated Core Architecture processors.


Prerequisites
==========================
This demo utilizes MPI, OpenMP* and the Qt* library. To use the demo, you need to have an MPI library
and the Qt library installed on your system. The latest version of Qt is available at http://www.qt.io/product/.
To build the sources, you need a C++ compiler (https://software.intel.com/en-us/c-compilers).


Build and Running Instructions
==========================
To build the binary demo for Intel(R) Xeon(R) Processor, set up the appropriate Intel(R) C++ Compiler, 
set up the environment for Intel(R) MPI Library, and launch build_qt.sh. As a result, 
a folder "build" will appear with the binary.
To build the demo with GCC* compiler and a newer Qt library, adjust the build_qt.sh script accordingly.
For the binary demo for Intel(R) Xeon Phi(TM) processor, set up Intel(R) Manycore Platform Software Stack, 
set up the environment for Intel(R) MPI Library, and launch build_mic.sh.
As a result, the folder "build_mic" with the binary will appear.

Usage:  ./heart_demo -m <mesh_file> -s <setup_file> [options]
where options could be:
        -m, --mesh_file    -  defines a VTK file containing tetrahedral mesh
        -s, --setups_file  -  defines a file containing basic model parameters
        -v, --visualize    -  enable real time visualization
        -i, --improve-locality  -  do the cuthill-mkcee reordering on the VTK mesh before calculations
        -b, --block-gather -  wait for completion on each gatherv operation (meaningful only with -v)
        -w, --write-images -  save visualization frames as images
        -t                 - simulation time

There are three types of mesh and setup files: small, medium, and large. The "bigger" mesh and setup defines the thoroughness of calculation. Note that when you specify the –v option to visualize the process, one of the MPI processes will be responsible for that. 
The -i option allows you to reorder the data in the way when each of the MPI processes (process k) communicates only with the k-1 and k+1 processes. Without the –i option each process communicates with the rest ones. 

A typical launch command for visualization is the following: 
mpirun -n 2 ./heart_demo -m ../mesh_small -s ../setup_small.txt -t 100 -i -v



Licensing
==========================
This demo is distributed under the BSD license (see the LICENSE.TXT file), with the exception
of the RCM component (distributed under LPGL v3):
- rcm.hpp and rcm.cpp
  This is a set of functions implementing the "Reversed Cuthill Mckee" reordering algorithm.
  Downloaded from http://people.sc.fsu.edu/~jburkardt/cpp_src/rcm/rcm.html.
  Distributed under GNU LGPL v3. These two files are compiled to produce a shared librcm.so.
  The "heart_demo" executable is then dynamically linked with it.

Other components used in the "heart_demo" project:
- luo_rudy_1991.cpp(hpp) - the code of the LR cell elctrophysiology.
  The files are autogenerated with COR software (http://cor.physiol.ox.ac.uk/)
  based on luo_rudy_1991.cellml model.
  The COR software is released "as is" with no warranty of any kind, explicit
  or implicit.
  The input model file is taken from https://models.physiomeproject.org/workspace/luo_rudy_1991
  and is licensed under a Creative Commons Attribution 3.0 Unported License
  (http://creativecommons.org/licenses/by/3.0/).

- oxford_mesh.tgz contains input mesh data that can be used for simulations. It is taken from
  http://www.cs.ox.ac.uk/chaste/cardiac_index.html and is freely available.

Notices
=======

*Other names and brands may be claimed as the property of others.