Rowan Docs

Python API

Introduction

Rowan's Python API makes it simple to script and automate complex computational chemistry workflows.

Traditional computational chemistry workflows are very difficult to automate:

  • Input files are typically created or edited by hand.
  • Jobs are run one at a time on a local workstation, or transferred to an external high-performance-computing cluster.
  • And outputs are poorly formatted and difficult to analyze in an automated way.

While lots of software packages have attempted to address parts of this problem (like BigChem, cctk, AaronTools, or Auto-QChem), it's still difficult for the average computational chemist to automate a non-trivial workflow and run it hundreds or thousands of times at scale.

Rowan's API aims to solve this problem. Our computational chemistry platform provides a single unified interface to dozens of computational methods, making it possible to run semiempirical calculations, density-functional theory, and neural network potentials without having to learn an entirely new package.

We automatically allocate computational resources to meet demand, so calculations submitted to Rowan don't have to wait in the queue for hours, days, or weeks. Any job run through Rowan's API can also be viewed through our web interface, making it easy to visually inspect important results or systematically query past calculations.

Getting Started

Installation

To get started, install rowan-python from the Python Package Index:

pip install rowan-python

We recommend using a tool like micromamba or pixi to manage your Python environments.

Authentication

Usage of the Python API requires generation of an API key at labs.rowansci.com. This guide walks through the process of generating a new API key.

Use your API key by assigning it to rowan.api_key:

import rowan
rowan.api_key = "my_secret_api_key"

Equivalently, you can set the environment variable ROWAN_API_KEY, in keeping with 12-factor app design:

export ROWAN_API_KEY=my_secret_api_key

Running Your First Calculation

This simple Python script will run a pKa workflow on phenol (specified by SMILES string) and return the result.

import rowan
rowan.api_key = "my_secret_api_key"

result = rowan.compute(
    name="phenol pka",
    molecule="c1ccccc1O",
    workflow_type="pka",
)

print(result["object_data"]["strongest_acid"])  # 10.17

Copy the above code into a Python file (e.g. phenol_pka.py), replace the API key with your own secet API key, and then run the script. After a few seconds, you should see a response like this:

$ python phenol_pka.py
10.168116455063156

Building With Rowan's API

RDKit API

from rowan.rowan_rdkit import run_tautomers 

mol = Chem.MolFromSmiles("C1=CC(=O)NC=C1")

pyridone_tautomers = run_tautomers(mol)
print(pyridone_tautomers)

For users who mainly work with RDKit objects, Rowan has a streamlined RDKit-native API. Users can directly calculate microscopic pKa values, rank different tautomers, or generate, optimize, and sort conformers using advanced neural network potentials. Rowan's RDKit API can also automatically run calculations in parallel across different machines, making it possible to scale high-accuracy computational chemistry to entire libraries of molecules with just a few lines of code. Read the full RDKit API reference.

Full API

import rowan

folder = rowan.Folder.create(
    name="test Rowan API folder"
)

try:
    result = rowan.compute(
        workflow_type="basic_calculation",
        molecule="CC(=O)OC",
        name="test",
        settings={"method": "gfn2_xtb", "tasks": ["energy"]},
        engine="xtb"
    )

    print(result)

finally:
    rowan.Folder.delete(folder["uuid"])

Rowan's low-level API gives developers full access to calculations, folders, and workflows, allowing your program create, fetch, update, and delete any number of computational jobs. Read the full low-level Python API reference.