clancyLab-squid 2.1.1

A set of modules to aid in atomistic and molecular simulations.

Squid is an open-source molecular simulation codebase developed by the Clancy Lab at the Johns Hopkins University. The codebase includes simplified Molecular Dynamics (MD) and Density Functional Theory (DFT) simulation submission, as well as other utilities such as file I/O and post-processing.

Installing

For most, the easiest way to install squid is to use pip install:

[user@local]~% pip install clancylab-squid

If you wish, you may also clone the repository though:

[user@local]~% cd ~; git clone https://github.com/ClancyLab/squid.git

Note, you will need various additional software to fully take advantage of squid. We include some helper scripts to aid you in setting up these files; however, these are not robust and we do encourage you to setup your own development environment. Nevertheless, if you so choose, the following information may be of use:

Setup on Ubuntu

1. Ensure that your system is up-to-date with relevant softare. The following commands will help.

[user@local]~% sudo apt-get update
[user@local]~% sudo apt-get upgrade
[user@local]~% sudo apt-get install build-essential make cmake g++ git swig mpich lmod

2. As the above line installs lmod, we have found that there may be a bug in the default install. If you find that when you open a terminal you are getting a weird error about posix not existing, this is a bug in lua install. Simply put, take the path it wants and make a simlink to point to posix_c.so. An example of how to do this is as follows (note, your lua version and directories may or may not be the same).

[user@local]~% sudo ln -s /usr/lib/x86_64-linux-gnu/lua/5.2/posix_c.so /usr/lib/x86_64-linux-gnu/lua/5.2/posix.so

3. Setup your directories. In this case, we want all programs installed to the ~/programs folder, and all modules installed to ~/.modules.

[user@local]~% mkdir ~/programs; mkdir ~/.modules

4. Setup a default environment file for lmod. In this case, we are making an empty one.

[user@local]~% touch ~/.modules/StdEnv.lua

5. Ensure that lmod is setup. This can be done by ensuring that the ~/.bashrc is updated accordingly. Note, do not blindly copy, but understand what the following lines of code do!

# LMOD Setup
if [ -f /usr/share/lmod/6.6/init/bash ]; then
    . /usr/share/lmod/6.6/init/bash
fi
module use /home/$USER/.modules
if [ -z "$__Init_Default_Modules" ]; then
  export __Init_Default_Modules=1;

  LMOD_SYSTEM_DEFAULT_MODULES=${LMOD_SYSTEM_DEFAULT_MODULES:-"StdEnv"}
  export LMOD_SYSTEM_DEFAULT_MODULES
  module --initial_load --no_redirect restore
else
  module refresh
fi

6. Install as much as possible from squid. This can be done by running the following command:

import os
from squid.installers import *

# Get relevant path information
home_folder = os.path.expanduser("~")
program_folder = "%s/programs" % home_folder
module_folder = "%s/.modules" % home_folder
if not os.path.exists(program_folder):
    os.makedirs(program_folder, exist_ok=True)
if not os.path.exists(module_folder):
    os.makedirs(module_folder, exist_ok=True)

# As we plan to get orca/4.2.0, we need openmpi/3.1.4
openmpi_installer(program_folder, "3.1.4", module_folder)

7. Note, because you may want some programs for others, it is recommended that you first setup openmpi, as above, then return to install the others. This requires that you also load the openmpi module before compiling the next programs.

import os
from squid.installers import *

# Get relevant path information
home_folder = os.path.expanduser("~")
program_folder = "%s/programs" % home_folder
module_folder = "%s/.modules" % home_folder
if not os.path.exists(program_folder):
    os.makedirs(program_folder, exist_ok=True)
if not os.path.exists(module_folder):
    os.makedirs(module_folder, exist_ok=True)

# LAMMPS has many install options.  Here we simplify things.
# Note, we can only choose between mpi or serial.
# Note, "16Mar18_mpi" is the name of the module in the lammps
# submodule folder.  Be unique!
lammps_installer(
    program_folder, "16Mar18", "mpi", "16Mar18_mpi",
    compiler="mpicxx",
    extra_lammps_packages=[
        "RIGID", "PYTHON", "REPLICA", "USER-MISC", "USER-REAXC"],
    smrff_path=None,
    MODULEDIR=module_folder
)

# Install packmol
packmol_installer(program_folder, module_folder)

# Install nlopt
nlopt_installer(program_folder, "2.6.1", module_folder)

8. Download Orca from https://orcaforum.kofo.mpg.de/app.php/dlext/ (note, you’ll have to register), and make your own orca module. An example is listed below (it would be saved in the modules folder as a .lua file.)

help([[
For detailed instructions, go to:
    https://orcaforum.cec.mpg.de/

    ]])
whatis("Version: 4.2.0")
whatis("Keywords: Orca 4")
whatis("URL: https://orcaforum.cec.mpg.de/")
whatis("Description: Orca 4")

load("openmpi/3.1.4")

prepend_path("PATH",               "/home/username/programs/orca/4.2.0")
prepend_path("LD_LIBRARY_PATH",    "/home/username/programs/orca/4.2.0")

Contributing

If you would like to be an active developer within the Clancy Group, please contact the project maintainer to be added as a collaborator on the project. Otherwise, you are welcome to submit pull requests as you see fit, and they will be addressed.

Documentation

Documentation is necessary, and the following steps MUST be followed during contribution of new code:

Setup

1. Download Sphinx. This can be done simply if you have pip installed via pip install -U Sphinx

2. Wherever you have squid installed, you want another folder called squid-docs (NOT as a subfolder of squid).

[user@local]~% cd ~; mkdir squid-docs; cd squid-docs; git clone -b gh-pages [e-mail]:clancylab/squid.git html

3. Forever more just ignore that directory (don’t delete it though)

Adding Documentation

Documentation is done using ReStructuredText format docstrings, the Sphinx python package, and indices with autodoc extensions. To add more documentation, first add the file to be included in docs/source/conf.py under os.path.abspath(‘example/dir/to/script.py’). Secondly, ensure that you have proper docstrings in the python file, and finally run make full to re-generate the documentation and commit it to your local branch, as well as the git gh-pages branch.

For anymore information on documentation, the tutorial follwed can be found here.