We work on Ubuntu 14.04 with Eclipse. As the project is expected to be under constant development for a while, meaning its set of files will be frequently changed or relocated we chose to rely on Eclipse's automatic makefile generation for now.

To install on an non development machine, provided all dependencies have been installed, you may build the simulation executable on a machine without Eclipse, by copying the mdpar folder there and running make in the project's Release folder.

Below follows the description of a somehow elaborate setup. Nevertheless, you should be able to start development with a minimal installation of Eclipse and openmpi. So you can skip the following sections for starters:

  • Install OpenMpi with VampirTrace
  • Install Profiling Extras
  • Install CUDA
  • Install Doxygen

 

Installing the Simulation Executable

To build and install the simulation executable to your system in order to perform production runs you must:

  • Decompress the package under a folder of you choice, say at /mdpar
  • Go to the release configuration folder.
  • Update the path to include the build scripts folder.
  • If necessary load the openmpi modules at your system.
  • Build the executable.
  • Place the executable where users can find it.

 

mkdir ~/mdpar

cp mdpar.tgz ~/mdpar

cd ~/mdpar

tar -xvfz mdpar.tgz

cd mdpar/Release

export PATH=~/mdpar/mdpar/buildscripts:$PATH

module load openmpi

mdparmake all

sudo cp mdpar /usr/local/bin

 

Install OpenMpi

If you are not interested in profiling the code an openmpi installation through the system's package manager will suffice.

sudo apt-get install openmpi-bin openmpi-doc openmpi-common libopenmpi-dev

 

Install OpenMpi with VampirTrace

If you want to profile the code you must make sure that openmpi comes with VampirTrace support. To check run:

ompi_info | grep -i vampir

If your openmpi does not support VampirTrace you need to make a custom build, which generally goes like:

  • sudo apt-get install libibnetdisc-dev
  • download extract and cd into openmpi-1.10.0
  • sudo ./configure –prefix=/opt/openmpi-1.10.0/
  • sudo make all install

Note that if you have a NVIDIA GPU installed you might need to install the CUDA profiling tools interface for VampirTrace to build properly.

sudo apt-get install cupti

 

Install Profiling Extras

You might want to use TAU instrumentation with VampirTrace or you might want to have the otf2vtf and vtf2profile tools built.

If you want VampirTrace to also enable TAU instrumentation you need to install the program database tools BEFORE building openmpi:

  • Download extract pdtoolkit
  • cd pdtoolkit-3.20
  • sudo ./configure -prefix=/opt/pdtoolkit-3.20
  • sudo make
  • sudo make install
  • vi your .bashrc and add /opt/pdtoolkit-3.20/x86_64/bin to your path

Also extract the VTF lib and copy the header and lib into system folders BEFORE building openmpi.

  • sudo cp ~/soft/vtf3-1.43/include/vtf3.h /usr/include/
  • sudo cp ~/soft/vtf3-1.43/x86_64/lib/libvtf3.a /usr/lib/

If you install TAU and wish it to have access to PDT and VTF you should configure like:

sudo ./configure -bfd=download -unwind=download -pdt=/opt/pdtoolkit-3.20 -prefix=/opt/tau-2.24.1 -vtf=/usr

 

Install CUDA

There is an experimental CUDA kernel implemented for the short pair forces. To build with CUDA, if you have an appropriate GPU you should download and install CUDA.

  • sudo apt-get install nvidia-opencl-dev
  • sudo apt-get install nvidia-cuda-toolkit

 

Install Doxygen

Doxygen is used to make the project's documentation you need to install it, as well as Graphviz to be able to rebuild the documentation.

  • sudo apt-get install doxygen
  • sudo apt-get install Graphviz

 

Install Eclipse

  • You should have at least Java Runtime 1.7. You may check with java -version.
  • Download Eclipse PTP, at the time of writing the last version was 9.0.0 working with Eclipse Mars.
  • Extract in /opt/eclipse
  • Create eclipse dash entry for easy startup
    • Create file /usr/share/applications/opt_eclipse.desktop (you might prefer ~/.local/share/applications for a local installation)
    • Edit and paste below:
      [Desktop Entry]
      Name=Eclipse
      Type=Application
      Exec=/opt/eclipse/eclipse
      Terminal=false
      Icon=/opt/eclipse/icon.xpm
      Comment=Eclipse Integrated Development Environment
      NoDisplay=false
      Categories=Development;IDE;Java
  • For Eclipse for be able to locate compilers and libraries you normally need to update your .bashrc properly, setting the PATH, CPATH and LD_LIBRARY_PATH to point to your Mpi installation. Also take care to point you path to your the "buildscripts" folder of your mdpar project. Assuming default folder locations you should add to the path the folder "/home/yourname/workspace/mdpar/buildscripts". Finally, if you care to profile, the code you should also add the VampirTrace include path to your path. You should in any case avoid setting such paths in the project settings as the makefile will no longer be transferable to other machines.
  • Alternatively you may choose to create a separate desktop entry for developing the project, having the path and gcc's include and library paths defined in the environment. To do so either create another desktop entry, or use the existing one, but now changing Exec to something like:

    Exec=env CPATH=/usr/lib/openmpi/include:/usr/lib/openmpi/include/vampirtrace$CPATH LIBRARY_PATH=/usr/lib/openmpi/lib:$LIBRARY_PATH /opt/eclipse/eclipse

    Also change the Name entry to something like “Eclipse for mdpar” to distinguish startups.

    Caveat: You migh run into problems trying to set the PATH with env through Exec. A workaround is to create a bash script that exec calls. So if you have openmpi installed in /opt and need to set the path so that Eclipse can find the compilers you my have to:

    • Create /opt/eclipse/custom_start_for_mdpar
    • Edit it and insert:
      #!/bin/bash
      env PATH=/home/yourhome/workspace/mdpar/buildscripts:/opt/openmpi-1.10.0/bin:$PATH CPATH=/opt/openmpi-1.10.0/include:/opt/openmpi-1.10.0/include/vampirtrace:$CPATH LD_LIBRARY_PATH=/opt/openmpi-1.10.0/lib:$LD_LIBRARY_PATH /opt/eclipse/eclipse
    • Set the exec of the desktop entry to:
      Exec=/opt/eclipse/custom_start_for_mdpar
  • Open Eclipse and create a workspace if needed
  • Prepare Eclipse for handling CUDA files as source files
    • Window -> Preferences
    • File Types
    • New, Pattern: *.cu, File type: C++ source file, OK
    • New, Pattern: *.cuh, File type: C++ header file, OK
    • OK

 

Create and Build Project in Eclipse

  • Create a new C++ project
    • File->New->C++ Project
    • Enter “mdpar” as the project name
    • From “Project Type” list select “Executable - Empty Project”
    • From the “Toolchains” list select “Linux GCC”
    • Debug and Release configurations will be automatically created, leave them as they are
  • Add source files to the project
    • Copy the “src” and “buildscripts” folders in the “mdpar” project folder
    • Right click the “mdpar” project in the project explorer and click “refresh” so that the project becomes aware of its contents.
    • Make sure some files in “buildscripts” are executable cd ~/workspace/mdpar/buildscripts chmod +x mdparc++ mdparlink mdparmake
    • You have to have python installed for the build scripts to work
  • Add project root in the include paths
    • Project->Properties->C-C++ Build->Settings
    • Select Configuration [All configurations]
    • At Tool Settings select GCC C++ Compiler->Includes
    • At Include Paths add the project source folder:
      ${workspace_loc:/${ProjName}/src}
  • Enable compiler openmp support
    • Project->Properties->C-C++ Build->Settings
    • Select Configuration [All configurations]
    • At Tool Settings select GCC C++ Compiler->Miscellaneous
    • At other flags append, separating by a space “-fopenmp”
    • At Tool Settings select GCC C++ Linker->Miscellaneous
    • At other flags append, separating by a space “-fopenmp”
  • Disable CUDA for the standard Release and Debug builds.
    • Project->Properties->C-C++ Build->Settings
    • Select Configuration [All configurations]
    • At Tool Settings select GCC C++ Compiler->Preprocessor
    • Add to “Defined Symbols”: "NO_CUDA"
    • Select GCC C++ Linker->Miscellaneous
    • At "Linker Flags" append: "--NO_CUDA"
  • Note: If you want you may also disable bonds with parseable potential input. You may want to do that during development as the parser library slows down builds. To do so also add to “Defined Symbols”: "NEXPRTK".
  • Quick and dirty fix for porting to gcc 4.7 + where the name lookup rules have changed (see also https://gcc.gnu.org/gcc-4.7/porting_to.html)
    • Project->Properties->C-C++ Build->Settings
    • Select Configuration [All configurations]
    • At Tool Settings select GCC C++ Compiler->Miscellaneous
    • At other flags append, separating by a space “-fpermissive”
  • Set custom make, compile and link scripts
    • Project->Properties->C-C++ Build
    • At Builder Settings uncheck "Use default build command"
    • At Build Command set: mdparmake
    • At "Behaviour" tab check "Enable Parallel Build" and select "Use optimal jobs"
    • Goto C-C++ Build->Settings
    • Select Configuration [All configurations]
    • At Tool Settings select GCC C++ Compiler
    • At “Command” set “mdparc++”
    • (remember that eclipse must be able find mdparc++ at your path)
    • At Tool Settings select GCC C++ Linker
    • At “Command” set “mdparlink”
  • In order to make sure the last build executable is available to the test cases add the following post build step to the Eclipse project.
    • In the Eclipse workspace folder create a new folder named “mdconfs”.
    • Project->Properties->C-C++ Build->Settings
    • Select Configuration [All configurations]
    • At Build Steps tab add the following post build step
      • At “Command” enter “cp ${ProjName} ../../mdconfs/${ProjName}”
      • At “Description” enter “Copying executable to confs folder” *

You are now ready to build the simulation. Try Project->Build Configurations-> Set Active->Release. Then Project->Build Project. After a successful build you should find the executable at both the Release and the mdconfs folder.

 

Create and Build CUDA version

  • Create a new build configuration
  • Project->Properties->C-C++ Build
  • Manage Configurations
  • New
  • Name: CUDA, Copy settings from: Existing configuration, Release
  • OK, OK
  • C-C++ Build->Settings->Build Steps tab
  • Set Post build steps Command to:
    cp ${ProjName} ../../mdconfs/${ProjName}_cu
  • At Tool Settings tab, C-C++ Compiler->Preprocessor, remove NO_CUDA from the list of defined symbols.
  • At C-C++ Linker->Miscellaneous, remove –NO_CUDA from the list of Linker Flags.

You are now ready to build the CUDA version. Try Project->Build Configurations->Set Active->CUDA. Then Project->Build Project. After a successful build you should find the executable at both the Release and the mdconfs folder named as mdpar_cu.

 

Installing and Running the Test Cases

The test cases purpose is to check the validity and performance of the simulation.

Primarily there exists an automated test script that runs a sequence of preconfigured simulations with both our simulation and lammps. The deviation of the calculated statistical quantities between the two simulation packages has been stored on disk and the results are checked to conform to it. A report is generated stating the conformance of the results or not, accompanied with plots of the statistical quantities checked.

Running the automated test script is a good way to ensure proper operation of the simulation when changing core parts of it during development and refactoring. It is wise to check whether potential errors have been introduced at every stage of a greater code change, as it can become quite tedious to search for the cause of a numerical error otherwise. Usage of a code versioning system like Mercurial is also crucial to keeping the code error free, as one can always revert to a working copy when some error is detected.

Apart from the automated test script some more test configurations exist that are used either to verify more perplexed parts of the simulation, to measure it's performance or to establish a configuration paradigm.

To place all the test cases in the proper folder

  • In the Eclipse workspace folder create a new folder named “mdconfs”, if you haven't already.
  • Paste the contents of the mdconfs folder there.

You may need to install LAMMPS which is used to cross validate measurements during preconfigured test runs

  • sudo add-apt-repository ppa:gladky-anton/lammps
  • sudo apt-get update
  • sudo apt-get install lammps-daily

If you have installed LAMMPS in another way you may need to alter the test.py script and provide the correct LAMMPS executable name.

  • Edit mdconfs/TestCases/ test.py
  • On top, at the general setting section, set the proper variable value
    lammps_executable = "your-lammps-executable-name"

To run the automated test cases

  • cd ~/workspace/mdconfs/TestCases
  • python test.py
  • Check screen output and report in “reports/report.html”.
  • To run the water electrostatic test case
    • cd ~/workspace/mdconfs/water
    • ./water
    • observe the plot outputs between our code an lammps, they should match