Workstation Setup

This page will help you to set up your computer, access cluster and manage your calculations. The sections are not ordered and you may not need some of them based on your research, but it is a good reference to look at. If you have any IT related problems, you can submit a ticket to this website:
https://www.chem.lsa.umich.edu/workorder/slink/requestform.php

  1. Package Managers for MAC OS (on your local machine=iMac)
    A package manager or package management system is a collection of software tools that automates the process of installing, upgrading, configuring, and removing software packages for a computer‘s operating system in a consistent manner. It typically maintains a database of software dependencies and version information to prevent software mismatches and missing prerequisites.
    A list of package managers can be found online:
    https://en.wikipedia.org/wiki/List_of_software_package_management_systems#Mac_OS_X
    The most commonly used ones are Homebrew and MacPorts. The following link explains how to install Homebrew:
    http://brew.sh/
    After installing Homebrew, packages can be installed by “brew install packageName” command on shell terminal

  2. Set up bashrc and bin (on remote server=athena)
    bshrc is a script file and is executed every time a new bash terminal is started. It is a way to customize your bash terminal. All the commands written in the bashrc file can be typed in a terminal session to customize it, but having a bashrc file is more convenient.
    The following are some useful settings you can copy to your bashrc file. The file can be opened by “vi  ~/.bashrc” command on the terminal. If the file is empty, copy any of the following settings you want and save it. After creating the .bashrc file, make a file named “.bash_profile” (vi ~/.bash_profile) in order to source your .bashrc file every time you log in. Write “source .bashrc” in this file.
    PATH is an environment variable on Unix-like operating systems, specifying a set of directories where executable programs are located. When you run a command or type an executable’s name, the system looks into PATH to find the command/executable. If you want to find the location of an executable, “which executableName” is the command you need. on line 26 in the following code, bin is added to the PATH. Never overwrite the PATH variable, always append to it.
    export PATH=/new/directory:$PATH
    When adding the paths to your bashrc, make sure to use the correct path of executables compiled for Athena and Gollum (guest & parallel queue) processors. The other option is to set the paths in your submission script.

    #To prevent accidental actions
    alias rm="rm -i"
    alias mv="mv -i"
    alias cp="cp -i"
    
    #set prompt, use one of these:
    set prompt='$HOSTNAME: '  #shows local host
    PS1='\w\$'   #shows working directory
    
    #Requesting interactive nodes. You can change #ppn value 
    #to 2, 8, 16,...to request more nodes 
    alias onenode= 'qsub -I -l nodes=1;ppn=1,walltime=24:00:00 -q zimmerman' 
    
    #Some aliasing for laziness reasons
    alias walltime='qstat -tau uniquename' 
    alias ls='ls -BFCh --color'     #-B : ignore backups
    alias ll='ls -BFChl --color'    #-F : classify file type
    alias la='ls -BFCha --color'    #-C : list entries by columns
    alias lla='ls -BFChla --color'  #-h : print sizes in human readable format
                                    #see a complete list in ls manual (man ls)
    alias loadshell='source ~/.bashrc' 
    alias untar='tar -xzf' 
    
    #Export paths 
    export PHOME=/export/zimmerman/paulzim/
    export PATH=~/bin/:$PATH
    #if you need ASE
    export PYTHONPATH=$PHOME/ase:$PYTHONPATH
    
    #if you need VASP 
    export PATH=$PATH:$PHOME/vasp.5.3/exe/mpi/ 
    export VASP_PP_PATH=$PHOME/vasp.5.3/potentials/
    export VASP_SCRIPT=$PHOME/ase/run_vasp_mpi.py 
    export VASP_NCORE=1
    export OMP_NUM_THREADS=1
    

     

    /bin is a subdirectory in root directory (your home directory). bin stands for binary and is a place to keep commands, scripts or executables. If you are a new member in this lab, you have to make a bin directory because it doesn’t exist.
    You can access the bin folder at “cd ~/bin“. If it doesn’t exist, create the folder in your home directory (change directory to /export/zimmerman/yourUniquename and then mkdir bin).
    Copy the molden executable from this directory “/export/applications/molden/src/molden5.4” to your bin, so you can have access to it on the cluster. You can also copy the gmolden executable since it has better visualizations of molecular orbitals than molden. Instead of copying the executables, you can add this directory to your PATH (see the information at the beginning of section 2).
    You also need the freenodes script in your bin to print a list of available nodes on Zimmerman queue (athena). Create a file named “freenodes” and copy the following to that file. You can type “freenodes” in bash terminal to see the list.

    #!/usr/bin/env perl
     use strict;
     use warnings;
     my @jobs = `qstat -tu paulzim |grep " Q " ` ;
     foreach ( 405..428,434 )
     {
     my $node = sprintf("gollum%0.3d",$_);
     my $output = `/usr/local/maui/bin/checknode $node`;
     $output =~ /[.\n]+Configured Resources: PROCS:\s+(\d+)/;
     my $configured = $1;
     $output =~ /[.\n]+Dedicated  Resources: PROCS:\s+(\d+)/;
     my $dedicated = $1;
     my $free = $configured - $dedicated;
     print "$node $free\n";
     }
    

  3. Software you need and how to get them (on your local machine=iMac)

    1. Molden
      It is a visualization package which can display molecules, surfaces, molecular orbitals and electron density.
      You have access to it on the cluster. Read the above section (section 2).
    2. Avogadro
      This is used to build molecules or edit them. For example, input structures for calculations.
      http://avogadro.cc/wiki/Get_Avogadro
    3. VMD
      To create frames from GSM strings for gif files.
      http://www.ks.uiuc.edu/Development/Download/download.cgi?PackageName=VMD
    4. Imagemagick
      Type “brew install imagemagick” in bash terminal. You may need root access for that (“sudo brew install imagemagick”).
    5. chemDraw
      Click on the “Registration Instructions” link on the following page and follow the instructions.
      http://www.itcs.umich.edu/sw-info/authoring/chemoffice.php
    6. Inkscape (optional)
      This software can be used to create posters, figures, schemes, etc. and is also useful for creating figures for your paper. It is a graphic editor like Adobe Photoshop (but it is vector graphics which means you don’t have to worry about resolution of your graphical objects https://en.wikipedia.org/wiki/Vector_graphics) and can be installed using homebrew “brew install inkscape” or from here:
      https://inkscape.org/en/download/mac-os/
      To make a poster, you can also use Adobe Illustrator free of charge through university, but Inkscape is always free.
      https://inkscape.org/en/learn/tutorials/
    7. Molpro
      Add the following to your bashrc file:
      export PATH=/export/applications/Molpro/2012.1.9/molprop_2012_1_Linux_x86_64_i8/bin:$PATHA list of software available through university can be found in Managed Software Center (look for this in finder) in Mac computers.
    8. Mendeley (optional)
      Mendeley is  a software for managing and sharing research papers. It gives you the option to highlight and annotate the papers and saves an online copy of your database, this means you can access the paper you have saved anywhere you log in to your Mendeley account. It also can create .bib files for BibTex. You can find the download link below:
      https://www.mendeley.com/
    9. M+ box
      It is a good idea to keep an online copy of your important files and data. This avoids the loss of files and provides a way of accessing your files. There are multiple options like DropBox and Google Drive, but M+ box gives you unlimited storage space, version control and it is provided through the university. You can download the box sync software to keep your files synced.
      http://www.itcs.umich.edu/storage/box/

  4. UNIX cheat sheet
    Any of the following links could be useful. You can always type “man command” (e.g. man cp) for more information on any command. The stackoverflow website is another very useful resource.

    http://www.digilife.be/quickreferences/QRC/The%20One%20Page%20Linux%20Manual.pdf
    http://files.fosswire.com/2007/08/fwunixref.pdf
    http://cheatsheetworld.com/programming/unix-linux-cheat-sheet/
    http://cb.vu/unixtoolbox.xhtml


  5. Editor and vimrc settings (on remote server and local machine)
    vi (vim) is one of the editors you can use in bash terminal. It is STRONGLY recommended that you read the vim tutorial, so you can learn all the helpful and quick shortcuts. To do so, type “vimtutor” in your terminal and read the tutorial file.
    You can also change the vim settings using vimrc file. The vimrc file is also located in your home directory (vi ~/.vimrc). If it doesn’t exist, you can create one. The following is written in Vim Script language and double quotation is used to add comments.

    ” display line number
    set nu
    ” disable line number display
    set nonu
    ” highlight search
    set hlsearch
    ” disable search highlight
    set nohlsearch
    ” enable mouse scrolling
    set mouse=a
    ” set colorscheme
    colorscheme desert
    ” auto-indent
    set autoindent
    ” tab spacing
    set tabstop=4
    ” unify
    set softtabstop=4
    ” indent/outdent by 4 columns
    set shiftwidth=4
    ” always indent/outdent to the nearest tabstop
    set shiftround
    ” use spaces instead of tabs
    set expandtab
    ” don’t wrap text
    set wrap
    ” set paste mode
    set paste
    set textwidth=80
    “Highlight characters that go over 80 columns
    highlight OverLength ctermbg=red ctermfg=white guibg=#592929
    match OverLength /\%81v.\+/
    “Show a warning color for columns 77-80 and error color for over 80 chars
    au BufWinEnter * let w:m1=matchadd(‘Search’, ‘\%<81v.\%>77v’, -1)
    au BufWinEnter * let w:m2=matchadd(‘ErrorMsg’, ‘\%>80v.\+’, -1)
    ” enable 256-color mode
    set t_Co=256
    ” enable syntax highlighting (previously syntax on)
    syntax enables
    ” filetype detection[ON] plugin[ON] indent[ON] filetype plugin indent on

    Alternatively, you can use Emacs. “tmux” can be used to multiplex several terminals inside one terminal.
    Another useful feature of vim is its macros. It becomes handy especially when you have to repeat a sequence of actions like adding a * at the end of each line in your input file. Here is an introductory tutorial:
    http://www.thegeekstuff.com/2009/01/vi-and-vim-macro-tutorial-how-to-record-and-play/
      As an example, suppose you want to add a space followed with a * at the end of each line in an input file with 50 lines, this is what you can do:
    1. press escape and then “q”
    2. press a key on keyboard where you want the macro to be saved (like “a” or “v”). It displays “recording” at the bottom left of your vim window
    3. press shift+a to go to the end of the line
    4. press space and type *
    5. press escape and down arrow to move to the lower line
    6. press q again to stop recording
    7. to repeat this for 10 lines, simply go to the line you want and type 10@a (a being the key you saved the macro in)


  6. Generating ssh key (on local machine=iMac)
    In order to connect to the cluster and submit your calculations, you need a ssh key. Directions on generating a ssh key and connecting to the cluster are given in the following file:
    Secure Shell
    The file is in the group’s DropBox folder. We couldn’t put it up here for security reasons.
    To enable X11 forwarding, use ssh with -Y option (ssh -Y athena).


  7. Copying from and to the cluster
    This section helps you to copy files from or to the cluster. The secure copy (scp) command is used for copying files. The other option is “sftp”. Here are some examples for “scp”:
    Copying from cluster to your local machine. This command should be typed on the shell terminal connected to your local machine.
    scp your_username@remotehost.edu:foobar.txt /some/local/directory
    e.g. copying file1 in dir1 from athena to current directory:
    scp uniquename@athena.lsa.umich.edu:dir1/file1 .
    Copying from your local machine to the cluster:
    scp foobar.txt your_username@remotehost.edu:/some/remote/directory
    It is more convenient to set up a pair of keys between your local machine and the cluster for copying files.
    Follow the directions (do these on a shell terminal connected to the cluster):
    – type “ssh-keygen”
    – give your file a name like id_desktop (make sure to use a different name than id_rsa to avoid overwriting your cluster keys)
    – no need to type a passphrase
    – copy the public key to the .ssh folder on your local machine and rename it to authorized_keys
    – In the .ssh directory on the cluster, make a config file (the file’s name is config) with the following form

    HOST I
    Hostname ###.###.##.#
    ForwardX11 yes
    User yourUniquename
    IdentityFile /export/zimmerman/uniquename/.ssh/desktop
    serverAliveInterval 60

    -The “Hostname” is the IP address of your computer. You can find it under System preference>Network, Look for IP Address.
    -Also, the remote login should be enabled. To do so, go to System prefences>Sharing and check the box for “remote login”.
    -in your bashrc file, add the following
    export I=’I:Desktop’
    Now, whenever you want to copy a file, just type scp file1 $I on the cluster.
    You can also use the “rsync” command to sync folders on the cluster and your local machine. See rsync manual for more details (type “man rsync” on your terminal).


  8. PBS job scheduling
    To run your calculations, you need to submit them on the cluster. PBS job scheduler manages the queue of jobs on the cluster. The following are some of the useful terminal commands for submitting and managing your jobs. You need to create a PBS job script to submit a job to PBS queue. An example of PBS script in given below (section 9).

    To submit a job:

    qsub your-submission-script

    To check the status of your jobs (Note the header of each column. The first column is Job ID):

    qstat -tau your-uniquename

    To check the status of one job:

    qstat -tua jobID

    To check the directory and node number of a job:

    qstat -f jobID

    To change the wall time of a submitted job:

    qalter jobID -l walltime=hh:mm:ss

    To move a submitted job to a different queue:

    qalter jobID -W queue=<new queue name>

    To check a queue:

    qstat -ta <queueName>

    To delete a job:

    qdel jobID

    To see a summary of all queues:

    qstat -q

  9. Sample PBS submission script
    # set the number of nodes, processes per node, wall time, and queue name
    #PBS -l nodes=1:ppn=8 -l walltime=168:00:00 -q guest
    
    # set name of job
    #PBS -N jobName
    
    # mail alert at (e)nd and (a)bortion of
    # execution
    #PBS -m ea
    # send mail to the following address
    #PBS -M uniqueName@umich.edu
    
    # tells where to put std error and out files
    #PBS -e /directory
    #PBS -o /directory
    # combine std error and out files
    #PBS -j oe
    # start job from the directory it was submitted
    cd $PBS_O_WORKDIR
    # run the executable (a python script in this case)
    python NEB.py
    

  10. Creating a github account:
    https://github.com/join?source=header-home
    Generate a SSH key or add your cluster PUBLIC key to Github:
    https://help.github.com/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent/
    NOTE: make sure not to overwrite your cluster key. Give your ssh key a different name like github_imac when it’s asking you for a name. Also, the keys will be generated in the directory that you run “ssh-keygen” command. So, you may need to copy them to the .ssh folder.Add the public key to your github account as explained here:
    https://help.github.com/articles/adding-a-new-ssh-key-to-your-github-account/
    Then, you need to edit your config file too bc it wouldn’t know which key to use:
    Sample config file:
    ——————————————————————-
    HOST I
    Hostname xxx.xxx.xx.x
    ForwardX11 yes
    User mjafari
    IdentityFile /export/zimmerman/mjafari/.ssh/identity_file
    serverAliveInterval 60HOST github.com
    IdentityFile /export/zimmerman/mjafari/.ssh/identity_file_name
    ——————————————————————-
    Click on your profile icon on the top right corner and go to settings.
    Make your email address public and you can fill out the other fields like your name etc.
    Send Josh/Cody/Mina your email address or username to be added to the group’s github.
    After being added you to the group’s github account, go to this page
    https://github.com/orgs/ZimmermanGroup/people
    and change the 4th column “private” to “public”, so others can see you’re part of the organization.


  11. molden/gmolden Setup Instructions1. Install homebrew by using the command
    /usr/bin/ruby -e &quot;$(curl -fsSL
    https://raw.githubusercontent.com/Homebrew/install/master/install)"
    (https://brew.sh)
    2. Install gcc4.9 with homebrew
    brew install gcc49 –with-fortran (double minus before with-fortran)
    3. Download molden5.7_MacOSX_full.tar.gz to an easily accessible location (the rest of the instructions
    will assume the Desktop) from ftp://ftp.cmbi.ru.nl/pub/molgraph/molden, may also be found by
    further searching further in that path: bin/MacOSX
    4. Double-click to unzip (or tar -xvzf molden5.7_MacOSX_full.tar.gz)
    5. Move the folder to /Users/Shared so everyone can access the executables
    sudo mv ~/Desktop/molden5.7_MacOSX_full.tar.gz /Users/Shared
    6. Symlink molden and gmolden to /usr/local/bin
    sudo ln -s /Users/Shared/molden/molden /usr/local/bin/molden
    sudo ln -s /Users/Shared/molden/gmolden /usr/local/bin/gmolden
    7. Add DYLD_LIBRARY_PATH environment variable to /etc/bashrc (machine-wide .bashrc), verify the gcc
    path before copying the text!
    sudo vim /etc/bashrc
    export
    DYLD_LIBRARY_PATH=/usr/local/Cellar/gcc@4.9/4.9.4/lib/gcc/4.9:$DYLD_LIBRARY_
    PATH
    8. Open a new terminal window and try molden/gmolden