Before you install moltemplate, you must install BASH, python.
Then, download moltemplate using:
git clone https://github.com/jewettaij/moltemplate DESTINATION_DIRECTORY
(If you don't have git installed, you can also visit the web site, click on the green "Code" button on the upper-right, select the "Download ZIP" menu option, and unpack the file.)
There are two ways to install moltemplate:
- using pip
- editing your .bashrc file
Use one method or the other (not both).
If you are familiar with pip, then enter the directory where this README file is located:
cd DESTINATION_DIRECTORY
and install moltemplate using pip3 (which is sometimes also called "pip"):
pip3 install . # (or "pip", if that fails)
If that fails (with both "pip" and "pip3"), then try this instead:
pip3 install . --user # (or "pip", if that fails)
This will install moltemplate for a single user. If you are on a shared computer and you want to install moltemplate system-wide, then use:
sudo pip3 install . # (or "pip", if that fails)
Later, you can uninstall moltemplate using:
pip3 uninstall moltemplate
# (use "pip" and/or prepend "sudo" if you did that earlier)
Again, if you get the error "command not found", try using "pip" instead of "pip3".
When users have difficulty installing moltemplate, it is usually for one of these reasons:
- They have not installed BASH (a.k.a. Xcode, WSL, linux, etc...).
- The computer has an old version of python (before python 3).
- pip and pip3 are missing. (This is very common.)
- There are multiple conflicting versions of python and pip installed.
Once these issues are fixed, installing moltemplate is easy.
Unfortunately, there are several different versions of "python" and "pip", and they go by different names whose meaning is not consistent.
Furthermore, many computers come with python installed but lack "pip" (or "pip3"). In that case, you can use the official package management system on your computer to install "pip3" (or "pip"). Alternatively, you can try installing the anaconda version of python. Anaconda python is recommended because it automatically includes numpy, and it will also automatically update your PATH for you so that pip works correctly. (Note that if you installed anaconda then use "pip", not "pip3" in the commands above.)
Some computers have both "pip" and "pip3" installed. In that case, "pip" and "pip3" may refer to different programs. This usually happens when there are multiple conflicting versions of python installed on your computer, and it is the most frequent reason for moltemplate installation failure. You must choose the version ("pip" or "pip3") which corresponds to the version of python that moltemplate is using. To do that, enter:
which python3
which pip3
If this returns "/usr/bin/python3" and "/usr/bin/pip3" then it is probably safe to use "pip3" in the commands above (because in this example, both "python3" and "pip3" share the same path).
If "which python3" returns something ending in "anaconda3/bin/python3" then try using "pip" (instead of "pip3") in the commands above.
On the other hand, if "which python3" fails to return anything, try entering:
which python
which pip
If this returns "/usr/bin/python" and "/usr/bin/pip" then it is probably safe to use "pip" in the commands above. In that case, try entering:
python --version
If this returns "Python 2.7.13" or something lower, I recommend upgrading to a newer version of python. (Python versions below 3 are no longer supported by "pip" and may cease to work in the future. Anaconda comes with the latest stable version of python and you can install it with or without admin privileges.)
Once you have python and pip (or python3 and pip3) installed, it's never a bad idea to install moltemplate into a temporary python "virtual environment". In a virtual environment, it should not be necessary to use "sudo" or "--user" to get around permissions issues that sometimes occur when using pip. (You can also uninstall moltemplate cleanly simply by deleting the directory that stores the virtual environment where it was installed. That directory is named "venv" in the example below.) Although using a virtual python environment should not be necessary, if you are curious how to do it then try downloading moltemplate to "~/moltemplate", and run these commands:
cd ~/moltemplate
python3 -m venv venv #(or "virtualenv venv" if that fails)
# This will create a local directory named "venv".
# You must "activate" your environment before use:
source venv/bin/activate
# Then install moltemplate into this environment:
pip3 install . #(or "pip" if that fails)
# (Now do something useful with moltemplate...)
Note that if you use a virtual environment, you will have to enter "source ~/moltemplate/venv/bin/activate" into a terminal before you use that terminal to run moltemplate. Virtual environments are explained here
If all this fails, then try installing moltemplate by manually updating your $PATH environment variable. Instructions for doing that are included below. (Either way, you must have a working version of python or python3 installed.)
Alternatively, you can edit your $PATH environment variable manually to include the subdirectory where the "moltemplate.sh" script is located, as well as the subdirectory where most of the python scripts are located. Suppose the directory with this README file is named "moltemplate" and is located in your home directory:
If you use the BASH shell, typically you would edit your
~/.bashrc file and add the following lines to the end of the file:
export PATH="$PATH:$HOME/moltemplate/moltemplate"
export PATH="$PATH:$HOME/moltemplate/moltemplate/scripts"
(Some people prefer to put these lines in their ~/.profile,
or ~/.bash_profile files instead ~/.bashrc. This should work also.)
If you use the TCSH shell, typically you would edit your
~/.cshrc, ~/.tcshrc or ~/.login files to contain the following lines:
setenv PATH "$PATH:$HOME/moltemplate/moltemplate"
setenv PATH "$PATH:$HOME/moltemplate/moltemplate/scripts"
After making these changes, you may need to start a new terminal (shell) for the changes to take effect. If you do not know what a PATH environment variable is and are curious, read:
http://www.linfo.org/path_env_var.html
(I receive this question often.)
(Warning: Do not install moltemplate this way if you are using "vipster", "cellpack2moltemplate", or other software that has a moltemplate python dependency. In order to be able to be able to run "import moltemplate" within python, as those programs do, moltemplate must be installed using pip or pip3.)
Most popular linux distributions include all of the needed prerequisites, except for "pip3" (or "pip"). Enter "pip3" into the terminal. If it returns "command not found" then try again with "pip". If that also fails, then use the package management system for your linux distribution (eg "apt", "yum", ...) to install "pip3" or "pip". (Eg. for ubuntu linux, use "sudo apt install python3-pip".)
Alternatively, you can install the anaconda version of python in linux, windows, and macOS. Anaconda python includes pip and numpy by default.
Although I have never tried this, the BASH shell, python, and pip prerequisites can be installed using Homebrew (or XCODE). However the anaconda version of python and pip is also available for mac OS, and it may be more reliable than the python version included with XCODE or Homebrew. (Note: BASH can be installed using 3rd-party tools like "brew" if it is not included with the operating system by default.)
You can install both moltemplate and LAMMPS in windows, but you will first need to install the BASH shell environment on your computer. I recommend installing either Windows Subsystem for Linux (WSL2), or virtualbox (In the later case, you will also need to install a linux distribution, preferably with a lightweight desktop such as xubuntu.) Alternatively, you can try Hyper-V or (if you have an older version of windows) CYGWIN.
To use LAMMPS and moltemplate, you will also need to install (and learn how to use) a (unix-style) text editor. (Word, Wordpad, and Notepad will not work.) Popular graphical text editors include Atom, Sublime, Notepad++, and VSCode. Older, non-graphical programs include vim, emacs, nano, ne, and jove.
WSL and virtualbox are virtual machines that allow you to run an alternate operating system from within windows. In this case that operating system is linux. The linux operating system includes the BASH shell and python (which moltemplate needs), as well as compilers such as g++ (which can be used for compiling LAMMPS from source), as well as the gdb debugger (which can be useful for understanding why LAMMPS is behaving strangely). It creates an ideal environment for running LAMMPS and moltemplate. WSL and virtualbox also create an alternate filesystem inside windows where the linux operating system is stored. Software (like moltemplate and LAMMPS) that you install there can access the files in that filesystem. If you are using WSL or WSL2, then you should use caution when using windows programs to edit your linux files. Consequently, it might be safer to restrict yourself to using text editors which you have installed and can run from within the WSL or WSL2 environment.