Purpose:
This guide covers the full process of installing LAMMPS on a university managed machine using Windows Subsystem for Linux (WSL) running Ubuntu-20.04.
If you are unfamilliar with Linux command line consider checking out this guide for some basic tips.
Method:
The whole process involved the following steps:
- Enable WSL
- Install a Linux distro (Ubuntu 20.04 in this case)
- Check/Configure networking on the Linux machine
- Download the source files
- Build pre-requisites for LAMMPS
- Build packages for LAMMPS
- Build LAMMPS
It is probably wise to have a Powershell window running as admin with your install account throughout this process. If any command fails in Powershell, an admin CMD prompt should always work.
Installing/Enabling WSL
In your admin Powershell window run the following commands:
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
This will enable the WSL feature and the VM Platform feature. We set the /norestart flag so we will only need to restart once for both features instead of after each install.
Restart the PC and open your admin powershell.
WSL comes in two versions, 1 and 2. We need to be running version 2. This is because version 1 does not implement a virtualised Linux kernel, it instead translates Linux kernel calls into Windows kernel calls. This will not work with LAMMPS. WSL 2 does implement a virtual Linux kernel.
Run the following command to set the default version to 2
wsl --set-default-version 2
You may be prompted to update the kernel, follow the link and install the downloaded MSI with simple elevated permissions.
Run the command again and it should just link you to an article that explains key differences between WSL 1 and 2.
Check network adapter properties in Windows and ensure that Hyper-V Virtual Switch is enabled.
Installing a Distro of Linux (Ubuntu-20.04)
Open the Microsoft Store and search Ubuntu, you should see multiple options, but I chose Ubuntu-20.04 LTS. LTS means long term support.
Once installed DO NOT RUN THE DISTRO.
Switch to Powershell and run:
wsl -l -v
This will list installed distros and their versions. This needs to be version 2 as stated above, there is a segment in the Possible Errors segment that walks through changing the version of an installed distro.
Once confirmed that this is WSL version 2 we can run the distro and continue with user setup.
The user should choose this credential and make it different from their university password. This will be the sudo/admin password, so you will either need to be given the password by them, or have them enter it each time it is requested.
There is a segment in the quality of life section of this guide about changing sudo password. You can set up a pass for yourself to make the install process faster, then have the user set it to their choice at the end.
Setting up the network under Linux
Once we have the user set up and we see the terminal, we may need to set up the network to look at our DNS servers. Run a ping test to www.google.com
ping www.google.com
If this doesn't return success try pinging 8.8.8.8. You should see success here, if both work you can skip to "Preparing for the Install"
Otherwise, if the ping fails, enter the following to Powershell:
wsl -l -v
wsl --terminate <distro>
ipconfig /all
We need to find the DNS servers from the ipconfig output and keep them on screen. Boot Linux again and enter the following into the linux machine
cd /etc
cat resolv.conf
We should see the contents of the resolv.conf file. We need to add lines to the resolv.conf file containing our DNS details
Replace x.x.x.x with name servers of your choice. UOD uses the following:
10.21.0.1
10.32.0.1
10.32.0.2
Make sure the commands contain the "-a". This appends the text instead of replacing it
echo "nameserver 10.21.0.1" | sudo tee -a resolv.conf
echo "nameserver 10.32.0.1" | sudo tee -a resolv.conf
echo "nameserver 10.32.0.2" | sudo tee -a resolv.conf
ping www.google.com
You should now see success when pinging google. Now that we have internet connectivity we can download the packages needed.
Preparing for the install
First we should update any existing packages by running the following, and entering y when prompted.
sudo apt-get update
sudo apt-get upgrade
Now that we are up to date we can grab the packages necessary. We are downloading and building this software, and we will need a suite of compilers to do. Run the following commans and enter y when prompted.
sudo apt-get install gcc
sudo apt-get intsall g++
sudo apt-get install gfortran
sudo apt-get install make
sudo apt-get wget
This should be all the compilers we need plus a tool to download the source. We will now create a folder to contain the files and download everything we need.
cd ~/
mkdir lammps
cd lammps
wget http://www.fftw.org/fftw-3.3.8.tar.gz
wget http://www.mpich.org/static/downloads/3.3.1/mpich-3.3.1.tar.gz
wget https://lammps.sandia.gov/tars/lammps-stable.tar.gz
A tar.gz file is basically an archive much like .zip or .rar we will extract them and we should keep these on hand.
Be aware that these are versioned releases that were the most recent as of May 2021.
To extract run the following:
tar -xvf fftw-3.3.8.tar.gz
tar -xvf mpich-3.3.1.tar.gz
tar -xvf lammps-stable.tar.gz
This should create a folder and fill it with the contents of the tar.gz.
We are now in a state where we can begin building and installing the files we just downloaded.
Installing prerequisites
We need to build the software in the order specified, at least LAMMPS needs to be last, as it depends on the other two being present.
Enter the following to build FFTW.
cd fftw-3.3.8/
./configure
If this does not work try the below instead. It should print out a lot of text, it will be obvious if it fails.
./configure --prefix=/share/home/lammps/fftw-3.3.8/ --enable-shared=yes
Then continue with the build
sudo make
sudo make install
cd ..
We then need to repeat these steps for MPICH.
cd mpich-3.3.1/
./configure
Again if this doesn't work try:
./configure --prefix=/share/home/lammps/fftw-3.3.8/
Then continue with the build and install. This one takes some time to complete.
make
sudo make install
cd ..
Building and installing LAMMPS. Again be aware that your folder names may differ from the current version as of May 2021
We need to build any packages the researcher's models depend on, in this case the four below. There is a command that will build all packages, but I found the make mpi failed if I ran that. See the possible issues section for more detail and how to resolve if it fails for you.
cd /lammps-29Oct20/src
make yes-manybody
make yes-molecule
make yes-granular
make yes-user-meamc
make mpi
This part takes a fairly long time to complete. Once finished you can see a blue file called lmp_mpi in the current directory (/lammps-29Oct20/src).
We need to create a symbolic link to allow lmp_mpi file to be used in commands, use the below to do so:
I found when deploying for Nutanix images the path was different, but this needs to be the entire path to the lmp_mpi file in the first argument.
ln -s /share/home/lammps/lammps-29Oct20/src/lmp_mpi /usr/bin/lmp_mpi
Testing
We should now be able to test LAMMPS. There are some example files included, and they run quickly.
The -np flag sets how many processor cores we should be using. I set this to two for safety, but on purpose built PCs the max would be however many cores appear in task manager.
cd lammps-29Oct20/examples/shear
mpirun -np 2 lmp_mpi -in in.shear
When this is complete, you can verify the number of processors by scrolling up the output to the top, it should say something like "using 2x1x1 processor grid" this will naturally scale with more cores being added. There will also be a table at the bottom of the output, just above that it that states how many tasks it was running.
If this is successful you should see a file called log.lammps in the directory.
This should now be complete, ask the user to test a few of their simpler models.
Additional Quality of Life
Mapping the linux drive for access from Windows
You can map the hard disk of any WSL distro installed.
To access the mapped drive the Linux machine does need to be running, if you try to access it when the machine is disabled it will take a very long time to fail and potentially crash explorer.
Using the normal process for mapping a drive, when prompted to select a letter and find a drive enter the below
\\wsl$\
This should have an auto complete list of all distros. Only map the root of the drive as I found it very slow and unstable when mapping deeper folders. You can create shortcuts to deeper folders and place them on the user's desktop. Again, the Linux distro they are accessing needs to be running for these to work.
Changing the sudo Password
When you first install a distro, you create a user and set a password. This will become the sudo or admin pass, and you may need to change this once the install is complete. In order to do this run the following
sudo passwd root
You will first be prompted for the current pass, then asked to enter the new pass.
Potential Errors
The make yes-all command causes build failure
This could be tested on a new install, it should include all packages and prevent future tickets. However I had an issue where it would not build lmp_mpi.
You would use this command instead of the individual make commands.
If the final build fails after trying this, you can do the following to remove all LAMMPS files and re-extract the archive.
cd ~/lammps/
rm -rf lammps-(version date)
tar -xvf lammps-stable.tar.gz
Then run the original instructions from the guide above to build individual modules and build lmp_mpi.
Missing packages when running LAMMPS
This occurs when a needed package was not built with the make yes-package command, and the model requires that package.
For example our shear example requires manybody, if I neglected to include this I would need to add it.
We can go back into the source folder and make the package, however I have not experimented with if lammps needs to be rebuilt once this happens or if the package is then included into the currently installed version of LAMMPS.
If it still fails, follow the steps above for a failed build. Once the files are remoed follow the steps in the guide to rebuild lammps, but add the additional package before running make lmp_mpi
cd ~/lammps/lammps-29Oct20/src
make yes-manybody
Distro is on WSL 1 not WSL 2
This one is quite an easy fix but can take a few minutes to do. I will assume that you have run the below and seen the output shows your distro is on version 1.
wsl -l -v
To convert it is handy to run the above anyway, so we can see the exact distro name, we will need it in the following command to change our version.
wsl --set-version <distro> 2
The last thing we need to do is make sure we set the default version to version 2, so that any future installs will not nee to be converted.
wsl --set-default-version 2