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.
We have set up a Google Group at http://groups.google.com/group/schrodinger-developer-forum for questions about the API and the documentation. Suggestions for improvement are also very welcome. In addition, if you have any proprietary questions please contact firstname.lastname@example.org.
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.
https://www.python.org contains documentation, examples, and many useful links. In particular, the Python Tutorial is a reasonable introduction to the language, and the Python Standard Library is an invaluable reference.
Good introductory Python books include Learn Python The Hard Way and Learning Python.
Effective Python has helpful tips for developing proficiency in Python once the basics are mastered. Python Cookbook has many helpful solutions to frequently encountered problems.
O’Reilly has published a number of popular Python books that range from the general and introductory to the specific and advanced.
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
$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.
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
SCHRODINGER directory 2, these are:
The current working directory.
The directory specified by the environment variable
~/.schrodingeron Linux and
The Schrödinger script installation tools support installation into
SCHRODINGER_SCRIPTS (provided that you have write permission) and
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:
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
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.)
The Schrödinger Python installation uses the
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
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).
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
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
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
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
should work with a bare python command. For example, python3 -c 'from
schrodinger import structure; print(structure.__file__)' should tell you where
schrodinger.structure module is installed.
bat is no longer supported and
Powershell should be
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.
The modules in the
schrodingernamespace 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/schrodingeron Linux and Mac, and
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 (
The builtin Schrödinger executable directory (
$SCHRODINGER/mmshare-v*/$OS_CPU/binfor a given platform specification
The directory specified by the environment variable