Installing and running LAMMPS in Windows using cygwin: A very basic tutorial for people who have never used UNIX

Steve Byrnes, June 2010, sjbyrnes.com.

Cygwin is a UNIX system which runs within Windows, and therefore it is an easy way for a Windows user to customize, compile, and run LAMMPS without really learning UNIX and without needing to know C++. This is an alternative to installing LAMMPS through the Windows binary download. The Windows binary download is usually easier, but there are some reasons you may prefer the cygwin method:

By the way, if you are serious about learning UNIX, maybe you should get a real UNIX system separate from windows (dual-boot, virtualization, etc.). Indeed, the key advantage of cygwin is to largely avoid learning UNIX!

Installing and getting familiar with cygwin

First, install cygwin, a version of UNIX that runs within windows. Please refer to these helpful tutorials: Tutorial A, Tutorial B, Tutorial C. As explained in these tutorials, during the cygwin installation, you're presented with many options of what to install or not install. If you have a huge hard drive and fast internet connection, you can just install everything. But a lot of this is stuff you don't need. Personally, I followed the recommendations in Tutorial A, plus everything in "Math" and "libs" and "System", to be safe, and maybe a few others. Read the tutorials for more details, and don't be afraid to run the installation more than once if you decide later on to install extra pieces.

Once you have installed cygwin, run the "cygwin bash shell" program in the Windows Start Menu. (It is possible to run cygwin through a graphical interface, but please don't. It doesn't help for what you'll be doing.) At the same time, open the "cygwin user directory" through Windows Explorer (usually C:\cygwin\home\[your name], unless you had to change it as explained in Tutorial C). The files and folders that you access through the cygwin interface is exactly the files and folders that you see in the "cygwin user directory" in Windows Explorer. [To make the correspondence clearer, you should definitely set up Windows to show file extensions.] You can use this fact to your advantage, using Windows and cygwin simultaneously:

With this approach, you do not need to learn much UNIX. But you do need to know a little bit, especially the commands "cd" and "ls", the most basic commands to navigate the file-system within cygwin. For example, try making a new folder called "TestFolder" in the cygwin user directory, using Windows Explorer (i.e., make a folder C:\cygwin\home\[your name]\TestFolder. Don't forget that file names and folder names cannot have spaces if you want them to be UNIX-compatible.). Then enter "ls" in cygwin, and you should see "TestFolder" appear. Type "cd TestFolder" to enter the folder, and "cd .." to go back up to the user directory. If you have problems so far, read any "introduction to UNIX" tutorial online, or ask a local UNIX user for help.

As another practice, try writing a few lines of text in Notepad++, and save it as "test.txt" in your cygwin user directory. Then, in cygwin, type "ls" and you should see "test.txt". Type "tail test.txt", and you should see the last few lines of the text file.

Finally, some shortcuts for navigating the cygwin file system:

Installing the prerequisites

In this tutorial, we will set up LAMMPS so that it uses the program FFTW for calculating FFTs (fast Fourier transforms), and the program MPICH to have the option of parallel processing (but it will still run fine on a single processor). LAMMPS allows other options for these, but if you do a different option you would need to do more work in editing the makefile and compiling LAMMPS. See LAMMPS getting started page if you want to use some other setup option. More hints on how to install without any MPI.

Now, you need to install "FFTW2". (You can install version 3 directly through the cygwin setup, but since LAMMPS requires version 2, you need to install it yourself.) Download it from its website (file should be called something like "fftw-2.1.5.tar.gz"), and use Windows Explorer to copy-and-paste it in your cygwin user directory. In cygwin, you should see the file with "ls". Type "gunzip fftw-2.1.5.tar.gz". This should turn "fftw-2.1.5.tar.gz" into "fftw-2.1.5.tar". Now type "tar xvf fftw-2.1.5.tar". This should create a new directory, full of files. Enter this directory and enter "./configure", then "make". (These take a very long time.) Then type "make install". If it outputs a message like "Libraries have been installed in...", you should write down that location, you'll need it later.

Next, you need the "MPICH" program, downloadable here. Installing MPICH2 is very similar to FFTW2: Put the file (something like "mpich2-1.2.1p1.tar.gz") in your cygwin user directory, unzip with "gunzip mpich2-[versionnumber].tar.gz" then "tar xvf mpich2-[versionnumber].tar", enter the new folder, run "./configure", then "make", which both take a long time to run.

Installing LAMMPS

Now you're ready to install LAMMPS. Download the C++ "source tarball" from the LAMMPS website and put it into your cygwin user directory as before. Again, type "gunzip lammps.tar.gz" then "tar xvf lammps.tar" to turn it into a folder. Enter this folder, then the subfolder "src". Type "make" to see a list of options for compiling the LAMMPS program. In particular, you should see a heading "make machine", and under it you should see, among other things, "# cygwin = Windows cygwin, mpicxx, MPICH, FFTW". What does this mean? It means that you can type "make cygwin", and your computer will try to compile LAMMPS under the assumption that you're using windows cygwin, and have already installed the MPICH and FFTW libraries, and will compile using "mpicxx", the C++ compiler that came with MPICH. In Windows Explorer, go to the same "src" folder, then the "MAKE" subfolder, and you will see "makefile.cygwin". This document, which you can view and edit in Notepad++, is the list of instructions that cygwin tries to follow in order to compile LAMMPS when you type "make cygwin". (Click here if you want to learn more about what a makefile is and how it works.) You can also open some other makefiles to see how they differ for different setups. All these files are contributed by different people who successfully used that makefile to compile LAMMPS on their own computers. The same makefile is not guaranteed to work on your computer!

In cygwin, try the command "make cygwin". You should see a long list of messages like "angle.d: No such file or directory". These are not errors, they are expected. If there is an actual error it will show up near the end. To fix these errors, you need to edit makefile.cygwin. (Don't forget to make a backup copy first, and please refer to the LAMMPS "Getting Started" page for details.) The most obvious problem you will see is specific paths that need to be corrected for where you actually installed your MPI and FFTW programs. For example, I changed:

Some details will be different for you.

Another potential problem is an error "mpicxx: command not found". "mpicxx" is the C++ compiler included with MPICH. If you installed MPICH as above, you do have this program, but cygwin cannot find it. The easiest fix is to find where this program is, and add that directory to the UNIX PATH variable as described here. For example, in my case, I used Notepad++ to open ".bashrc" in my cygwin user directory, and at the bottom I put a new line with "export PATH=$PATH:/home/Steve/mpich2-1.2.1p1/bin", saved the file, then restarted cygwin.

With luck, "make cygwin" will now run successfully. You know it is successful if it completes without any error messages, and then you will have a new file in the src folder called "lmp_cygwin.exe".

Running LAMMPS

Similar to the descriptions on the LAMMPS "Getting started" page, you can try running LAMMPS with one of the built-in examples. So open a subfolder of the "examples" folder; for example, "melt". Copy lmp_cygwin.exe into this folder, then enter the folder in cygwin, then run LAMMPS with the command "./lmp_cygwin < in.melt". ("in.melt", which you should look at, is the input script which LAMMPS will execute). If it works, congratulations, you are now running LAMMPS!

By the way, the above command runs LAMMPS in serial mode, without parallel processing. To run in parallel mode, you need instead a command like "mpirun -np 2 lmp_cygwin < in.melt". The "-np 2" means "use two processors in parallel". When I first tried this, I got an error message related to "the local mpd". Please refer to the MPICH user's guide or a local expert for help if you need the parallel processing capabilities.