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.
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.
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:
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>/<RELEASE>/scripts
.The directory
$SCHRODINGER/mmshare-vX.Y/python/common
.The directory
$SCHRODINGER/mmshare-vX.Y/python/scripts
.Your
PATH
.