Introduction

At the highest level, the Schrödinger Python API provides a base molecular structure class and allows for programmatic interaction with Maestro and Schrödinger computational products. It allows you to create scripts that automate and extend our core functionality.

This document gives you an overview of what is provided, but does not provide the level of detail given in the class and function API documentation. It is aimed at a developer who already knows Python (or can pick it up on their own) and wants to use our API to complete a scientific project.

We recommend that you read this overview first to get your footing, then use the API documentation as a reference. The full API documentation generated from the python documentation strings can be accessed here. For examples of the use of the Python API, see the scripts included with the release at $SCHRODINGER/mmshare-v*/scripts/common.

We have set up a Google Group at http://groups.google.com/group/schrodinger-developer-forum for questions about the API and the documentation. In addition, if you have any proprietary questions please contact help@schrodinger.com.

General Python Information

A general Python introduction is beyond the scope of this document, but there are plenty of resources available for free on the web.

• http://www.python.org contains documentation, examples, and a many useful links. In particular, the Python Tutorial is a reasonable introduction to the language, and the Python Standard Library is an invaluable reference.
• Dive into Python is a useful reference if you have some experience with scripting or programming but not with Python. It is filled with valuable, graduated examples that will help you master Python.
• O’Reilly has published a number of popular Python books that range from the general and introductory to the specific and advanced.
• The Python Package Index contains many useful Python modules.

One final source of Schrödinger-specific examples is our own Script Center.

Getting Started

To use the Schrödinger modules [1], you should use the version of Python supplied by Schrödinger. It should be invoked via $SCHRODINGER/run python.

The Schrödinger modules are also accessible from within Maestro (see Interacting with Maestro).

Running Schrödinger Scripts

Individual Python scripts can be run via:

$SCHRODINGER/run <script.py> [<script options>]

The $SCHRODINGER/run command sets up environment variables needed for executables and libraries shipped by Schrödinger to work properly. It will search a number of standard locations if the named script does not have an explicitly specified path. Along with a number of built in locations in the SCHRODINGER directory [2], these are:

• The current working directory.
• The directory specified by the environment variable SCHRODINGER_SCRIPTS.
• The directory <SCHRODINGER_DATA>/scriptsX.Y, where <SCHRODINGER_DATA> is ~/.schrodinger on Linux and %LOCALAPPDATA%\Schrodinger on Windows.
• Your PATH.

The Schrödinger script installation tools support installation into SCHRODINGER_SCRIPTS (provided that you have write permission) and your <SCHRODINGER_DATA> directory.

Exploring Schrödinger Modules

One good way to explore the Schrödinger modules is from the Python interactive prompt. It can be started with the command-line invocation:

$SCHRODINGER/run python

An alternative to the command-line interactive prompt is the IDLE GUI [3], which can be started with the command $SCHRODINGER/run idle.py. (On Windows, run these commands from the prompt provided by the $SCHRODINGER/SchrodingerShell.)

Readline for the Interactive Prompt

Our Python does not ship with the readline module. On Linux, this module provides tab-completion for keywords and object attributes. To install your own readline module, you will need the gcc compiler. Download the source from the readline package on the Python Package Index and install it with $SCHRODINGER/run setup.py install --home=~/pypackages. To install to the ~/pypackages location with the --home option, you must have an existing ~/pypackages/lib/python directory that is in your PYTHONPATH.

See the Python tutorial on the Python website for documentation about the interactive prompt and setting up readline tab completion. The following example PYTHONSTARTUP file should be enough to get you started:

# This file is sourced before interactive use. To use it yourself, copy
# its contents into a ~/.pythonrc file and set the PYTHONSTARTUP
# environment variable:
#
# PYTHONSTARTUP=~/.pythonrc; export PYTHONSTARTUP
#

try:
    import readline
    import os

    # rlcompleter is "readline completer." Importing it allows tab
    # completion for methods, variables, etc.
    import rlcompleter

    # Bind the tab key to the completion function.
    readline.parse_and_bind('tab: complete')

    # Set up history saving.
    historyPath = os.path.expanduser("~/.pyhistory")

    # Older versions of readline don't seem to have read_history_file.
    #
    try:
        if os.path.exists(historyPath):
            readline.read_history_file(historyPath)
    except AttributeError:
        pass

    del os, readline, rlcompleter

    import atexit

    def save_history(historyPath=historyPath):
        import readline
        readline.write_history_file(historyPath)

    atexit.register(save_history)
    del atexit, save_history, historyPath

except ImportError:
    pass

Accessing Your Own Modules

This subsection can be skipped until you want to use modules that aren’t included in our distribution. (In addition to Schrödinger packages our distribution contains a number of useful third-party modules including Numpy, SciPy, matplotlib, PyOpenGL, and BioPython.)

The Schrödinger Python installation uses the PYTHONPATH environment variable in the same way as any other Python installation, so the easiest way to access your own modules is by adding their directories to the PYTHONPATH. Note that these modules must be compatible with Python 2.7 and compiled modules must be compatible with the Schrödinger installation (e.g. for Linux-x86 installations they must be 32-bit).

If a SCHRODINGER_PYTHONPATH environment variable is present, our Python distribution uses it in preference to the standard PYTHONPATH. This allows an incompatible local Python installation to coexist with our distribution. Because Maestro and other Schrödinger executables use Python, it is important to set SCHRODINGER_PYTHONPATH if your PYTHONPATH contains incompatible modules. Set it to an empty string to override the PYTHONPATH without specifying an alternate search path.

Installing Additional Modules

To install additional modules to a local directory for use with Schrödinger’s Python distribution, you can run $SCHRODINGER/run setup.py install --prefix=$LOCAL_PY_PACKAGES on the setup.py file provided with the package. (For this to work, your $LOCAL_PY_PACKAGES/lib/python2.7/site-packages directory must exist and be in your PYTHONPATH.) See Installing Python Modules for general information on installing python packages.

Per-user Virtual Environments for Installing Additional Modules

We recommend virtual environments for users that want to experiment with additional modules that are not shipped with Schrödinger Python. A Python “virtual environment” is a lightweight user-local Python installation that can access the Schrödinger modules and easily install additional Python modules. The `venv Python module documentation <https://docs.python.org/3/library/venv.html`_ has more details on this process.

If you want to share third-party modules with multiple users or want a more permanent set of modules, a virtual environment probably isn’t necessary. Instead, just install them to some standard directory and set your PYTHONPATH to pick them up.

To try a virtual environment yourself, run $SCHRODINGER/run schrodinger_virtualenv.py schrodinger.ve. This creates a new subdirectory in the working directory called schrodinger.ve that contains a new virtual environment. To activate it, source schrodinger.ve/bin/activate. (Source activate.csh if you are in a csh-compatible shell.) After activating the virtual environment, importing schrodinger modules should work with a bare python command. For example, python -c 'import schrodinger.structure; print schrodinger.structure.__file__' should tell you where the schrodinger.structure module is installed.

In the virtual environment, the pip utility is also provided, and can be used to install packages to the virtual environment. If you have a compatible C compiler, pip install readline will install the readline module to the virtual environment. A useful alternative to the standard python interactive prompt that can be installed via pip is IPython (pip install IPython).

To leave the virtual environment, just run deactivate.

Footnotes

[1]

The modules in the schrodinger namespace are located in a $SCHRODINGER/mmshare-v* subdirectory that can be found by running $SCHRODINGER/run python -c 'import os, schrodinger; print os.path.dirname(schrodinger.__file__)'. (This directory is $SCHRODINGER/internal/lib/python2.7/site-packages/schrodinger on Linux and Mac, and $SCHRODINGER/internal/lib/site-packages/schrodinger on Windows.)

[2]

For completeness, if the script argument to $SCHRODINGER/run does not have an explicitly specified path, the following locations are searched in order: The current working directory. The Schrödinger suite-wide executable directories ($SCHRODINGER/internal/bin and $SCHRODINGER/internal/Scripts) The builtin Schrödinger executable directory ($SCHRODINGER/mmshare-v*/$OS_CPU/bin for a given platform specification $OS_CPU). The directory specified by the environment variable SCHRODINGER_SCRIPTS. The directory <SCHRODINGER_DATA>/suite2013-1/scripts. The directory $SCHRODINGER/mmshare-vX.Y/python/common. The directory $SCHRODINGER/mmshare-vX.Y/python/scripts. Your PATH.

[3]	IDLE is not currently supported on Mac OS X.