########################################################

              README for SMOG 2 (v2.6-beta)

SMOG 2 is a downloadable software package for 
generating structure-based models, as provided by the 
smog-server.org webserver (i.e. SMOG v1). These models 
may be used to perform simulations using Gromacs, NAMD,
or OpenMM.

SMOG 2 is free software, distributed under the GNU 
General Public License. See COPYING.

This distribution of SMOG 2 includes two versions of 
SMOG models, the C-alpha model (Clementi et al. JMB 2000)
and the all-atom model (Whitford et al. Proteins 2009),
as well as two definitions of contacts (LJ, Gaussians).
The software is written such that you may also design
your own form of structure-based models without having
to modify the source code. For even greater flexibility,
we recommend checking the -OpenSMOG option, which 
provides a platform for performing SMOG models in OpenMM.

This README provides the absolute basics for using
SMOG 2.  For more advanced usage information, consult
the manual, available at smog-server.org

We encourage everyone to provide feedback/suggestions
on usage, extensions and bugs to [email protected],
or post questions to the users forum.  You can sign up
for the users forum at
https://mailman.rice.edu/mailman/listinfo/smog-users


      Jeffrey Noel, Jose' Onuchic and Paul Whitford

########################################################


########################################################

              CONFIGURE/INSTALL SMOG 2

There are several ways to install/configure SMOG 2 on
your machine. Depending on your needs and accessible
machine, you will need to choose from one of the options
below.


OPTION 1 - USE A CONTAINER
The easiest method to use SMOG 2 is to access the Docker 
or Singularity container. Go to the SMOG 2 page for 
information on how to use use the SMOG 2 images for 
Docker and Singularity.

Note: Instructions for building your own container can be
found in the containers/docker and containers/singualarity
directories in this repo. This can be helpful if you are
trying to add your own features to SMOG 2.


OPTION 2 - Using apt-get (Ubuntu)
Getting Perl configured for SMOG 2 on Ubuntu can be quite simple. 

You can generally run these two commands with sudo, or as root, 
and you will be ready to run SMOG 2 (See "FINAL STEPS...." below)
 
>apt-get install -y --no-install-recommends cpanminus pdl default-jre libxml-simple-perl 

>cpanm String::Util Exporter XML::Validator::Schema


OPTION 3 - USING CONDA OR MINICONDA (Only tested with Linux)
This is a bit more involved than using a container, but
it should be rather straightforward.

If you don't have Conda/Miniconda, you will need to first
install one of them.

Once conda is installed, create an environment for use 
with SMOG 2. In this example, we  will call the environment 
"smogenv"

>conda create --name smogenv perl

activate the environment

>conda activate smogenv

Next, it is necessary to install a few Perl modules.

>conda install -c bioconda perl-xml-simple perl-xml-libxml java-jdk
>conda install -c eumetsat perl-pdl
>perl -MCPAN -e 'install XML::Validator::Schema'

If these five commands are successful, then go to
"FINAL STEPS WHEN NOT USING A CONTAINER".


OPTION 4 - MANUAL INSTALLATION OF SUPPORTING LIBRARIES
This is the most difficult configuration process.  In
most cases, the above options are sufficient. But, in 
case you need to perform a manual installation, here
are the instructions.

The following modules need to be installed. (CPAN
can be used to make this installation process a bit
simpler.)
XML::Simple
XML::SAX::ParserFactory
XML::Validator::Schema
XML::LibXML 
Exporter
PDL
Getopt::Long
Scalar::Util

Note: If installing a module fails, it may be necessary 
to use CPAN to install additional modules, or perhaps use
yum to install missing tools. Just check the error messages 
to identify which dependencies are missing.

If you do not have java installed (uncommon), then you will
also have to install it.


FINAL STEPS WHEN NOT USING A CONTAINER

Note: This description assumes you are using bash or zsh

Once the modules and java are installed, you need to 
run the configure script. 

>source configure.smog2

When this is run, it will try to determine which version of
Perl to use.  Specifically, it will use "which perl" to find
the version, and  smog2 will be configured with this version.
However, it is not uncommon that users have multiple  version
of Perl available, where the version found is smog-incompatible.
If you know which version of Perl you want to run, you can
export an environment variable, or set a variable  when sourcing.
For example, if the version of Perl you want to use is 
/opt/local/bin/perl, then you could do

>export perl4smog="/opt/local/bin/perl"
>source configure.smog2

or 

>perl4smog="/opt/local/bin/perl" source configure.smog2

If you want to install smog2 (i.e. configure in a specific
directory and write-protect), then use the smog_install_dir
variable. For example, if one wanted to install it in
/usr/bin/smog2, one could do

>smog_install_dir="/usr/bin/smog2" perl4smog="/opt/local/bin/perl" source configure.smog2

If configuration is complete, you will have a directory
$smog2dir/bin, which will contain wrappers for SMOG 2,
as well as for tools described in the manual. If you
call the configure script multiple times, new files
will not be created, but the environment will still
be initialized.


VERIFY YOUR CONFIGURATION

It is highly recommended that once SMOG is configured,
you run the full set of SMOG-CHECK routines. This will
verify your configurations are correct and that SMOG
is producing accurate force field files. For information,
see README file in the SMOG-CHECK directory.

########################################################


########################################################

			USAGE

If your configuration/installation step completes
successfully, running SMOG 2 can be quite simple.  

Note: It is assumed that $SMOG_PATH is the main
SMOG 2 directory.

To use the default C-alpha model (proteins only) 

smog2 -i <PDBFILE> -CA  

For the default C-alpha model with gaussian contacts (proteins only) 

smog2 -i <PDBFILE> -CAgaussian  

For the default All-atom model: 

smog2 -i <PDBFILE> -AA

For the default All-atom model with gaussian contacts: 

smog2 -i <PDBFILE> -AAgaussian

If you would like to use other models:

Coarse-grained models
smog2 -i <PDBFILE> -t <CG_TEMPLATES> \
 	-CG -t_contacts $SMOG_PATH/SBM_AA

In this example, <CG_TEMPLATES> is the directory containing 
the CG templates and <PDBFILE> is the the system for which 
you would like to generate a SMOG model.

To run an All-atom model: 
smog2 -i <PDBFILE> -t $SMOG_PATH/SBM_AA  

For a list of all supported flags and options, type:
smog2 --help

For more advanced usage of SMOG 2, please consult the
user manual.

########################################################