Installing molSimplify

Wednesday, June 10, 2020
Aditya Nandy and Chenru Duan

Install recommendations: For users who do not intend to develop (i.e., change the source code) with molSimplify, we recommend an install via Docker or Conda, where we maintain a static image of molSimplify that includes machine learning models that we have published. For advanced users who would like to develop with molSimplify, we recommend to install from source via Conda.

System requirements: The code should work on any recent OS supporting Python 2.7 or Python 3 (recommended). These include Windows 7 to 10, OS X 10.10 to 10.13 and Ubuntu 14.14. There are no specific memory or processor requirements, but we recommend disabling the force field (-ffoption B) or switching to UFF from the default MMFF94 (-ff uff) if poor performance is observed.

Installation via Docker: Docker is the recommended mode of install for easy use of molSimplify. Following the exact instructions below step by step should allow you to get molSimplify running on your machine.

  1. Make a free account with docker: https://hub.docker.com/.
  2. Install docker for your OS. After you install docker correctly and open the application, there should be a whale icon in your navigation bar.
  3. Open up the docker application and sign in with your free account credentials. It may take some time to start.
  4. You can test that your docker works by typing the following in a terminal: docker run hello-world
    1. Running this will result in something that says: "Hello from Docker! This message shows that your installation appears to be working correctly."
  5. Make the folder where you want your molSimplify to dump the files (a folder to place geometries and input files outputted by molSimplify.). Pick an easy to find location. Find the path of this folder, you will use it in the following step. I am going to dump my files at /Users/molSimplifyUser/Desktop/dockertest --> which I will call MYFILEPATH.
    1. You can open up a terminal and use bash commands like mkdir to make a directory where you want your files dumped. You can then use cd to go to the directory where you want those files dumped (aka MYFILEPATH). Use pwd to get the path (which would replace MYFILEPATH).
  6. Next, run the following command, which should give you the molsimplify container. Replace the section that says MYFILEPATH with your path for where you want to dump your structures and input files. The below command will make a container that is titled "my_container." Keep the part that says hjkgroup/ after the -it flag... that is our dockerhub account.
    1. docker run --name my_container -v MYFILEPATH:/root/Runs/ -it hjkgroup/molsimplify:latest
  7. At this step, make sure you have the -it flag on. If you do not, then it cannot make the interactive docker environment that you want! You should copy the above line directly (starting from docker) and only replace MYFILEPATH.
  8. <---- Will download the docker container --->
  9. After this download is complete, the docker container is going to be running interactively. 
  10. You will notice that you are in an environment with (molSimplify) on the left, followed by root@... This is good! You can use molsimplify now. Any files you make will show up in MYFILEPATH specified earlier. At this point, try building a structure. We can build our favorite Fe(II)(NH3)6 complex:
    1. molsimplify -core fe -lig ammonia -ligocc 6 -ligloc True -oxstate II -spin 5
    2. Check if the files are present in MYFILEPATH!
  11. If you are done with the container and want to leave, simply type exit. This halts all running processes.
    1. You have now left the container, but you can always restart it.
  12. You can type docker ps -a to see your existing containers. If you want to re-start and re-enter the container, type the following:
    1. docker start my_container
    2. docker attach my_container
    3. You're back in the container. That's it!
  13. If you want to remove a container, you can get the names from docker ps -a , and then do docker rm <CONTAINERNAME> where CONTAINERNAME can be identified from the ps -a command.
  14. If you want to stop docker from running completely, go to the whale in your navigation bar and quit docker. Once you open it back up, you can reattach to your old containers. 

 

Installation via Conda: Conda is the recommended mode of installation for our package for more advanced users. (Conda is a package and environment manager application that lets users easily download and install python, R, C, Scala, Java and other programs, without needing to worry about dependencies.) First install Conda from the link above if you don’t already have it. We recommend using the Anaconda version with Python 3 since Python 2 is no longer sustainable. 

1. Once Conda is installed, create a new environment with:

$ conda create -n molSimplify python=3.6

2. Activate this newly created environment with the command:

$ conda activate molSimplify

NOTE: Whenever you want to run molSimplify in a new terminal window, remember first to activate the environment as above!

3. Add package channels that molSimplify depends on.

(molSimplify)$ conda config --add channels hjkgroup

(molSimplify)$ conda config --add channels conda-forge

(molSimplify)$ conda config --add channels defaults

4. Inside this new environment, you can install molSimplify using (NOTE: case sensitive):

(molSimplify)$ conda install -c hjkgroup molSimplify

Here, the “-c” indicates that the package will come from the Anaconda cloud and “hjkgroup” indicates our cloud account. All required dependencies, including OpenBabel and SciPy, will also be automatically installed (NOTE: as of 11/6/2017, Pybel is no longer required).

This approach requires you to activate your molSimplify environment before use (and again each time you close your terminal session or deactivate the environment), but will prevent the installation from conflicting with other Python-based software on your computer. Note that if you would like to use the GUI of molSimplify, PyQt5 needs to be installed separately (see below).

NOTE on debug: If you encounter some tensorflow error, it is verly likely that your hardware is not compatible with the version of tensorflow (1.14.0) pre-installed and shipped with molSimplify. In this case, we suggest you to downgrade your tensorflow to an older version (e.g., 1.12.0).  If you have the "core dumped" error, it is likely that the OpenMP tries to run it with multiple treads and errors out. You can try doing "export OMP_NUM_THREADS=1" to fix it.

Running the GUI (only OS X and Linux supported):

PyQt5 is required for our GUI. If you don't already have it, you can install it using the command:

(molSimplify)$ conda install pyqt=5

Now you can launch the GUI by calling molSimplify without any arguments (the command line version will still work as usual):

(molSimplify)$ molsimplify

OS X 10.12 or older: OpenBabel 2.4.1 may not be compatible with OS X 10.12 or older. If you encounter OpenBabel errors, you can get an older version by running

conda install -c hjkgroup openbabel=2.3.2

Advanced users: molSimplify can also be installed from source using Git. The detailed instruction is on our github page (https://github.com/hjkgrp/molSimplify, section of "installation, via conda") 

If you have any issues with the installation process, please email us!

About Us

The Kulik group focuses on the development and application of new electronic structure methods and atomistic simulations tools in the broad area of catalysis.

Our Interests

We are interested in transition metal chemistry, with applications from biological systems (i.e. enzymes) to nonbiological applications in surface science and molecular catalysis.

Our Focus

A key focus of our group is to understand mechanistic features of complex catalysts and to facilitate and develop tools for computationally driven design.

Contact Us

Questions or comments? Let us know! Contact Dr. Kulik: