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. You can use it to automate workflows and extend our software’s core functionality.

This document provides an overview of the API 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 full API documentation as a reference. The full API documentation generated from the Python documentation strings can be accessed here. For examples of the Python API in use, see the scripts included with the release at $SCHRODINGER/mmshare-v*/python/common. A further source of examples is $SCHRODINGER/mmshare-v*/python/scripts., which contains code for most of the panels inside of Maestro.

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

Recent years have seen an explosion in high-quality resources for learning Python, including online courses, interactive tutorials, and books, many of which are either free or relatively inexpensive. An introduction to Python is beyond the scope of this document, and any list of resources is likely to be out of date by the time you read this document. We list here only a small subset of these resources to help you get started. The most recent edition of these books is always to be preferred, since the language changes over time. As of the 2018-2 release, Schrodinger’s core libraries are written against Python 3, so you should strongly prefer resources that teach Python 3 over Python 2.

Getting Started

To use Schrödinger’s modules [1], you need to use the version of Python supplied by Schrödinger. At the command line, this is invoked by typing $SCHRODINGER/run python3.

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

Note that any Python that was preinstalled or separately installed on your computer will not be able to access any Schrödinger modules. If a script fails because Schrödinger modules cannot be found, the first thing to check when troubleshooting is that you’re invoking Python correctly.

See below for more about installing additional modules when working with Schrödinger’s Python.

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

IPython

An excellent way to explore Schrödinger modules is from a Python interactive prompt (sometimes known as a REPL, for “Read, Eval, Print Loop”). We recommend the IPython shell for this, which can be started with the command-line invocation:

$SCHRODINGER/run ipython

The IPython shell makes interactive exploration of code easy because it provides tab completion and the ability to introspect code and doc strings immediately in the shell. There are many resources online to learn more about these and other features of IPython.

Note that an IPython shell is also provided from within Maestro (“Python Shell” in the Window menu).

Installing Jupyter Notebook

We do not ship Jupyter Notebook but it can be installed in a virtualenv so that it works seamlessly with our software. To do this, follow the instructions below for creating a virtualenv, activate the virtualenv, and then run:

pip install --upgrade jupyter

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

Upgrading from Python 2 to Python 3

Please see this KB article for help upgrading existing Schrödinger scripts from Python 2 to Python 3.

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.)

Note that installating a module into a virtualenv, as described here, does not make it available within Maestro.

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 3.6 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/python3.6/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 who want to experiment with additional modules that are not shipped with Schrödinger Python. A Python “virtual environment” is an isolated, lightweight, user-local Python installation that can access the Schrödinger modules and to which users can easily install additional Python modules. The venv Python module documentation has more details on this process.

Note that additional libraries installed within a virtualenv will not be available within Maestro’s interactive Python prompt.

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 your virtualenv, type source schrodinger.ve/bin/activate at the terminal for Posix systems or schrodinger.veScriptsactivate on Windows. (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, python3 -c 'import schrodinger.structure; print schrodinger.structure.__file__' should tell you where the schrodinger.structure module is installed.

To leave the virtual environment, just run deactivate.

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 Schrödinger virtualenv is tied to the release used to create it (given by the value of $SCHRODINGER). When you update to a new release, you will need to create a new virtualenv and install your preferred packages into it. See the pip documentation on the pip freeze command for details on how to easily capture and reproduce combinations of pip installed packages.

Setting Up Your Code Editor

Reading or writing code in a plain text editor like Notepad is not recommended, even for modest tasks. Modern code editors offer syntax highlighting, help with refactoring, integrated access to documentation, code completion, and more.

In order to set up a Code Editor so that all its features work properly with Schrödinger software, you will need to set up a Virtual Environment, as described above.

As also noted above, Schrödinger virtualenvs are tied to particular releases. When you update your release, you will need to generate a new virtualenv and point your editor at it.

Footnotes

[1]The modules in the schrodinger namespace are located in a $SCHRODINGER/mmshare-v* subdirectory that can be found by running $SCHRODINGER/run python3 -c 'import os, schrodinger; print(os.path.dirname(schrodinger.__file__))'. (This directory is $SCHRODINGER/internal/lib/python3.6/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:

  1. The current working directory.
  2. The Schrödinger suite-wide executable directories ($SCHRODINGER/internal/bin and $SCHRODINGER/internal/Scripts)
  3. The builtin Schrödinger executable directory ($SCHRODINGER/mmshare-v*/$OS_CPU/bin for a given platform specification $OS_CPU).
  4. The directory specified by the environment variable SCHRODINGER_SCRIPTS.
  5. The directory <SCHRODINGER_DATA>/<RELEASE>/scripts.
  6. The directory $SCHRODINGER/mmshare-vX.Y/python/common.
  7. The directory $SCHRODINGER/mmshare-vX.Y/python/scripts.
  8. Your PATH.