Installing NUFEB on Linux and Mac

This section covers instructions on how to compile NUFEB and get started.

1. Pre-compilation instructions

Before compiling NUFEB, please make sure you have installed with the following packages depending upon the operating system used:

1. gcc/g++ (https://gcc.gnu.org/)
2. openmpi (https://www.open-mpi.org/)
3. git (https://git-scm.com/)
4. cmake (https://cmake.org/)

You can run the following commands to install the packages,

On Ubuntu:

sudo apt update
sudo apt-get install cmake git-core g++ openmpi-bin openmpi-common libopenmpi-dev 

Some Ubuntu systems also require OpenGL to be installed manually:

sudo apt-get install libglu1-mesa-dev freeglut3-dev mesa-common-dev

On CentOS:

sudo yum update
sudo yum install cmake git gcc-c++ openmpi openmpi-devel

On MacOS, use Homebrew to install the required libraries:

$ ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/
install/master/install)" < /dev/null 2> /dev/null

then type the following command for the library installation:

brew install gcc open-mpi cmake git

2. Downloading NUFEB

Use GIT checkout and update commands to get the NUFEB files once and then stay current. To do this, use the clone command to create a local copy of NUFEB Github repository:

git clone --recursive https://github.com/nufeb/NUFEB.git

Once the command completes, a new directory named "NUFEB" will be created on your machine which contains the latest NUFEB source code, examples, LAMMPS and thirdparty libraries. After initial cloning, as bug fixes and new features are added to NUFEB, you can stay up-to-date by typing the following GIT commands in the /NUFEB/ directory:

git checkout master
git pull

3. Compiling NUFEB

Use the script file install.sh provided in /NUFEB/ directory to compile the code:

./install.sh [--options]

The [--options] is the additional settings of the compilation. The table below lists all available options:

Option	Description
default	mpi version, no VTK, no HDF5
--serial	serial version
--enable-vtk	compile with VTK library
--enable-hdf5	compile with HDF5 library
--static	compile as a static library
--shared	compile as a shared library

Note that in order to compile NUFEB with VTK or HDF5, you will need to install the corresponding library provided in /NUFEB/thirdparty/ directory. Then compile NUFEB with the corresponding argument. For example, to compile NUFEB with VTK library:

cd thirdparty
./install-vtk.sh
cd ..
./install.sh --enable-vtk

When finished, you should have an executable lmp_mpi or lmp_serial in /NUFEB/lammps/src/ directory and its path will be automatically added to the system (.bashrc).

4. Running NUFEB

By default, NUFEB runs by reading commands from standard input. Thus if you run the NUFEB executable by itself, e.g.

$ mpirun -np 4 lmp_mpi

it will simply wait, expecting commands from the keyboard. Note that for parallel environments you also need to specify the number of processors by using ‘-np X’ command-line switch.

Typically you should put commands in an input script and use I/O redirection, e.g.

$ mpirun -np 4 lmp_mpi -in Inputscript.lammps

If NUFEB is compiled as serial version, use executable “lmp_serial” to run a simulation:

$ lmp_serial < Inputscript.lammps

We provide several examples in the /NUFEB/examples/ directory. To run the examples, go to one of the subdirectories and run NUFEB executable by passing in the input file, for example:

$ cd NUFEB/examples/biofilm-het/
$ mpirun -np 4 lmp_mpi -in Inputscript.lammps

or

$ mpirun -np 4 lmp_mpi -in Inputscript-vtk.lammps

if the VTK library is enabled. Output files will be generated and saved in the same directory during the simulation.