2.2 Compiling (Next)

Simpatico is distributed only as source code, and must be compiled by the user. All source code is written in ANSI standard C++. By default, all code follows the ANSI 1998 C++98 standard, though it is possible to compile a version that uses a few features from C+11. The package has been developed and tested using the gcc and intel compilers in a linux environment, and with the gcc compiler in Mac OS X. It should compile with any modern, standard compliant C++ compiler.

The single-processor programs mcSim and mdSim have no external dependencies. A Message Passing Interface (MPI) library is required to compile the ddSim parallel MD program. An MPI library is also required by the multiprocessor versions of mcSim and mdSim, which implement embarassingly parallel simulations in which each processor simulates a different physical system.

The build system uses unix makefiles, and is thus designed to work only in unix-like environments (i.e., gnu/linux or Mac OS X). It was developed using the gnu version of make (gmake), which is the default on all modern linux distributions and on Mac OS. MacIntosh users will need to install the XCode package and the XCode Command Line Tools to compile simpatico from source.

The source code for simpatico is hosted on github, as project dmorse/simpatico. The source code may be obtained by using the git version control manager program to clone the public git repository. In order to this, a "git" client must be installed on your computer.

Checking for git

Before attempting to use git to clone the source code, check whether a "git" client is installed on your machine, by entering

> which git

from the command line. If git is installed, this should return a valid path, such as "/usr/bin/git". If this command does not return a valid path, you need to install a git client before proceeding.

Instructions for installing git on different platforms are given in the documentation on the git web page, in chapter 1.5 of the Pro Git book by Scott Chacon. If you are using a Mac, the easiest way to install git is simply to install the XCode Command Line Tools, which you will need for other purposes, and which automatically installs a git client. If you are using linux, and git is not already installed, you should use the preferred package manager on your linux distribution to install git.

Cloning the Repository

To obtain a working copy of the simpatico git repository, you should change directory (cd) to the directory you want to contain the simpatico root directory and enter the command

> git clone --recursive https://github.com/dmorse/simpatico.git

This should create a complete working copy of the simpatico source code in a new subdirectory named "simpatico/" of the directory from which you invoked the above command.

The above instructions are for users who simply want to get a copy of simpatico their own use, but who are not (or not yet) interested in sharing modifications of the code with others. Users that want to be able to contribute to the project or share their extensions or improvements of simpatico with others should go through a slightly more complicated procedure. Such users should instead:

Create a user account on github.com, if they do not already have one.
Create a user fork of simpatico on their personal github account
Clone their personal fork of simpatico to a local machine, using the –recursive option and using a communication protocol that is set up to allow them write access.

Herefafter, we assume that the root directory of the simpatico working copy is named simpatico/. References to paths that do not start explicitly with a prefix "simpatico/" should be understood to be relative paths, relative to this directory. The directory structure is explained here.

Comment on Submodules

Some subdirectories of the simpatico/src directory are maintained in separate github repositories and are imported into simpatico as git "submodules". (See chapter 7.11 of the Pro Git online book). Specifically, the src/util and src/tests directories are submodules that contain clones of the dmorse/util and dmorse/test repositories on github, respectively. The use of the "--recursive" option of the git clone command given above should automatically create clones of these submodules in the appropriate locations within the simpatico source directory tree, creating a complete functional copy of the source code. Cloning a copy of simpatico without using the "--recursive" option, however, would create a version of the simpatico directory tree in which the src/util and src/tests directories are empty. If you find yourself with a repository clone in which one or both of these repositories is empty, you can either clone simpatico again with the recursive option, or read chapter 7.11 of the online Pro Git book for instructions on how to manually fetch and update these submodules.

2 User Guide (Up) 2.2 Compiling (Next)