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 Cookbook may be especially helpful; it provides a set of examples with an easily searchable table of contents. 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.

If you have any 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.

Getting Started

To use Schrödinger’s modules 1, you need to use the version of Python supplied by Schrödinger, and not a version of Python that may have come with your computer or one you’ve installed yourself at another time. At the command line, this is invoked by typing $SCHRODINGER/run python3 or $SCHRODINGER/run ipython as recommended below.

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.

Unfortunately, we do not support building in a conda environment and do not currently plan to support this.

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 and Jupyter Notebook

An excellent way to explore Schrödinger modules is from a Python interactive prompt. 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).

Jupyter Notebook is also available using the following command-line invocation:

$SCHRODINGER/run jupyter notebook

Note that as of release 2024-4, it is possible to display small structures in both Jupyter Notebooks and in IPython. If the Structure is the last line in the cell, it should display an image of the Structure in 2D. If you include a large Structure (e.g. a protein), you should see a text label.

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 3.11 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.11/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.

Also, as mentioned above, the Schrödinger suite is not compatible with conda environments.

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.ve\Scripts\activate 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 'from schrodinger import structure; print(structure.__file__)' should tell you where the schrodinger.structure module is installed.

Note

On Windows, bat is no longer supported and Powershell should be used instead.

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 (such as VSCode or PyCharm) 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.11/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.