Read Me

===========================================
SOFTWARE REQUIREMENTS
===========================================

Before installing VolFEM3D, you should have installed the following 
software:

-------------------------------------------
Requirements for graphical interface
-------------------------------------------

The dependencies for graphical interface are (v means version):
  - Python: Programming language, 2.5 <= v < 3.0.
  - wxPython: wxWidgets bindings for Python, v >= 2.8.
  - Python-VTK: VTK bindings for Python, v >= 5.4.
  - Paramiko: SSH2 protocol for Python.
Note that Paramiko is only necessary for remote connections. If you don't 
use it, you don't need it.
  
To install the previous packages, you can follow these tips:

- Debian-based Linux distributions
-------------------------------------------
Required packages can be downloaded from the official repositories. As an 
example, how to install them using apt-get is shown:
    sudo apt-get install python
    sudo apt-get install python-wxgtk2.8
    sudo apt-get install python-vtk
    sudo apt-get install python-paramiko

- Windows
-------------------------------------------
We recommend a full installation of the scientific-oriented Python 
distribution Python(x,y), containing all the packages required for the 
graphical interface.
Python(x,y) can be downloaded from https://python-xy.github.io/
You can find it in some external mirrors in the Python(x,y) download page. 
In April 2016, the links to the mirrors were:
  - NTUA: http://ftp.ntua.gr/pub/devel/pythonxy/
  - University of Kent: http://www.mirrorservice.org/sites/pythonxy.com/
  - ConnectMV: http://pythonxy.connectmv.com/
For problems with graphics or the installation in Windows XP, see "Known 
issues" below.

If you prefer to install the packages separately, these are the web pages 
to download them:
  - Python: https://www.python.org/downloads/
  - wxPython: http://www.wxpython.org/download.php
  - Python-VTK: http://www.vtk.org/download/
  - Paramiko: http://www.paramiko.org/installing.html

If you prefer to build the packages from source, these are the web pages 
to download the code:
  - Python: https://www.python.org/downloads/source/
  - wxPython: http://wxpython.org/download.php#source
  - Python-VTK: https://gitlab.kitware.com/vtk/vtk
  - Paramiko: https://github.com/paramiko/paramiko

-------------------------------------------
Requirements for solver compilation and/or execution
-------------------------------------------

The next software requirements are necessary to compile and/or run the 
VolFEM3D solvers (v means version):
  - GCC: The GNU C compiler, v > 4.4; recommended, v 4.7.
  - GFortran: The GNU Fortran compiler, v > 4.4; recommended, v 4.7.
  - Make: The GNU Make utility to maintain groups of programs, v >= 3.81.
  - Pthreads: A POSIX threading library.

The installation of these packages depends on your operating system:

- Debian-based Linux distributions
-------------------------------------------
Required packages can be downloaded from the official repositories. As an 
example, how to install them using apt-get is shown:
    sudo apt-get install gcc-4.7
    sudo apt-get install gfortran-4.7
    sudo apt-get install make
    sudo apt-get install libc6
Note that the pthreads library, libpthread, is included in the libc6 
package.
In some Linux distributions, after installing GCC and GFortran you should 
have links named gcc and gfortran pointing to gcc-4.7 and gfortran-4.7 
respectively. If not, compilation using make can fail. You can create them 
manually using the ln command:
    ln -s /usr/bin/gcc-4.7 /usr/bin/gcc
    ln -s /usr/bin/gfortran-4.7 /usr/bin/gfortran

- Windows
-------------------------------------------
This additional software should only be installed if you have to compile 
the VolFEM3D solvers, for example, if you build VolFEM3D from source. If 
you install VolFEM3D from binaries you should not need this.
We recommend to install an official build of MinGW by using the MinGW 
Installation Manager (mingw-get) to install the following packages:
  - mingw32-base (bin): A basic MinGW installation.
  - mingw32-gcc-fortran (bin): The GNU Fortran compiler.
  - mingw32-pthreads-w32 (dev): A POSIX threading library for Win32.
Note that mingw32-base is a meta package that provides a basic GCC 
installation, and includes the C compiler, linker and other binary tools, 
the runtime libraries and Windows API support, mingw32-make and a debugger.
After installing MinGW we recommend to add the folder with the MinGW 
binaries at the beginning of the PATH environment variable in order to 
prevent conflicts with any other installation of MinGW. For example, with 
the MinGW that comes with some versions of Python(x,y).
MinGW can be downloaded from http://sourceforge.net/projects/mingw/
For problems with MinGW and Pthreads-w32, please read "Known issues" below.


===========================================
INSTALLATION
===========================================

Installation of VolFEM3D can be done building it from source.

How to build VolFEM3D from source depends on your operating system:

- Debian-based Linux distributions
-------------------------------------------

In a terminal, go to the folder INSTALLDIR/sources (where INSTALLDIR is 
the VolFEM3D installation folder) and then run:
    make -f Makefile.linux
If you want to clean all temporary files and the result of a compilation, 
run:
    make -f Makefile.linux clean

- Windows
-------------------------------------------

In a command window, go to the folder INSTALLDIR/sources (where INSTALLDIR 
is the VolFEM3D installation folder) and then run:
    mingw32-make -f Makefile.windows
If you want to clean all temporary files and the result of a compilation, 
run:
    mingw32-make -f Makefile.windows clean
Note that you have to use mingw32-make or only make depending on the MinGW 
version or tool used.


===========================================
KNOWN ISSUES
===========================================

* Installation of Python(x,y), version 2.7.5.1, appears to fail in Windows 
XP.
For more information see: 
https://groups.google.com/forum/#!topic/pythonxy/9iyaKStOsqw

* Errors related to "_gfortran_stop_numeric_f08" and "pthreadGC2.dll" can 
arise when a VolFEM3D solver is tried to run without having a suitable 
installation of MinGW. In Windows, we recommended to install an official 
build of MinGW with the following packages:
    mingw32-base (bin): A basic MinGW installation
    mingw32-gcc-fortran (bin): The GNU FORTRAN compiler
    mingw32-pthreads-w32 (dev): A POSIX threading library for Win32
Please, add the folder with the MinGW binaries **at the beginning** of the 
PATH environment variable in order to prevent conflicts with any other 
MinGW installation, for example, with the MinGW that comes with some 
versions of Python(x,y).

* Errors related to the struct "timespec" can arise with some versions of 
MinGW and Pthreads-w32. Some people recommend to comment the definition of 
the struct "timespec" in "pthread.h" to avoid the conflict with the 
definition in "time.h".
For more information see: 
https://github.com/libpd/libpd/issues/87, 
http://mingw-users.1079350.n2.nabble.com/Definition-of-struct-timespec-in-MinGW-runtime-3-21-td7583272.html, 
http://comments.gmane.org/gmane.comp.gnu.mingw.user/44765 and 
http://lists.gnu.org/archive/html/bug-gnulib/2015-01/msg00042.html

* If you have problems with graphics, for example, if you can't visualize 
some graphics or you can't visualize them well, it may be due to the version 
of Python-VTK. Please, make sure that the version of Python-VTK is greater 
than or equal to 5.4.
If you are using a version of VTK greater than or equal to 6.0, please try 
with the version 5. The latest version of Python(x,y) including VTK version 
5 is 2.7.9.0. You can find it in some external mirrors in the Python(x,y) 
download page: https://python-xy.github.io/downloads.html