To get stk, you can install it with pip:

$ pip install stk

Developer Setup

  1. Install just.

  2. In a new virtual environment run:

    $ just dev
  3. Setup the MongoDB container (make sure docker is installed):

    $ just mongo
  4. Run code checks:

    $ just check


stk is a Python library which allows construction and manipulation of complex molecules, as well as automatic molecular design, and the creation of molecular, and molecular property, databases.

Molecular Construction

stk provides tools for constructing a variety of molecular structures, including organic and metal-organic cages, covalent organic frameworks, polymers and metal complexes, to name a few. While additional molecular structures are always being added, stk provides tools which allow users to easily specify new kinds of molecular structures, no matter how simple or complex, in case something they want to build is not built-in. stk also makes it easy to specify which isomer of a given structure should be built.

Here is a preview of some of the more complex structures stk can construct

Automatic Molecular Design

stk provides an evolutionary algorithm, which can be used for discovery of new molecules, which have properties desired by the user. This evolutionary algorithm works with any molecule stk can construct, even those defined by users.


stk provides tools for the creation of molecular databases, and storage of molecular property values. stk comes with support for the creation of MongoDB databases, which can be used to store molecules constructed by users, or discovered by the evolutionary algorithm. In addition, property values calculated for those molecules can also be stored and retrieved from the database.

Molecular Database Visualization

stk has a sibling project called stk-vis, which is a cross-platform application, which lets you connect to a database created by stk, and view the molecules deposited into it. stk-vis also shows you any molecular properties you deposited, and lets you browse the building blocks of any constructed molecules. It’s ideal for collaboration between multiple people, because one person can deposit a molecule into the database, and another person can immediately see and examine it. stk-vis is a stand-alone application and does not require coding or stk to use.

Features of stk-vis include

  • 3D interactive molecular rendering.

  • Image of the 2D molecular graph.

  • Tabulation of any molecular properties deposited into the database.

  • Sorting molecules according to property values to quickly find ones with the best and worst properties.

  • You can list the building blocks of any constructed molecules. If those building blocks are also constructed molecules, you can list their building blocks as well, and so on.

  • Writing molecules to files.

You read more about stk-vis here:

Usable Defaults

A goal of stk is to provide simple interfaces and require minimal information from users to achieve basic and common tasks, but also allow extensive customization and extension in order to fulfill complex requirements.

Extensibility and Customization

Every part of stk can be extended and customized in user code, and every user-made extension is indistinguishable from natively implemented features. This means users can use stk to construct new classes of molecules, add new kinds of molecular databases, and add or customize evolutionary algorithm operations, all without looking at stk source code. All such extensions will work with the rest of stk as though they were part of the library itself.

Documentation and Examples

Every use-case and extension or customization of stk has documentation and examples which will guide users. stk is built around abstract base classes, which means all user extensions to stk involve creating a new class and defining, usually, a single method.

Future Releases

stk is under active development. You can get alerted when a new release comes out by going to the GitHub page and click on the watch button in the top right corner. Then select Releases only from the dropdown menu.

Important features in the future will include:

Distributed Evolutionary Algorithms

Evolutionary algorithms are very simple to parallelize. It’s just a matter of calculating each fitness value on a separate CPU core. However, this idea can be taken further. Instead of calculating the fitness function on a separate CPU core, calculate it on a separate computer. stk will support fitness functions, which instead of calculating the fitness value locally, send the molecule over the internet to a server, so that the server is responsible for calculating the fitness value, which it then sends back to the client. You will be able to keep adding servers as your computational requirements increase, and the load will be distributed fairly between them. This will allow continuous horizontal scaling of stk evolutionary algorithms.

More Molecular Structures

stk is always being expanded with new molecular structures. If there is a specific kind of molecule you would like to be able to construct with stk, and you don’t feel like implementing it yourself, simply create an issue on, and describe what you would like to build.

What Next?

Something you might like to do first, is look at the construction overview, which can give you a picture of how stk goes about constructing molecules. It will also introduce you to the basic concepts and types found within stk. Next, the basic examples, will allow you to get a feel for how to use stk. After that, examples of molecular construction can be seen by looking at the documentation of the different topology graphs. In general, you will find examples on how to use a class, in that classes documentation. Once you are comfortable with construction, you can start looking at how to deposit and retrieve the molecules from databases. Finally, stk provides multiple examples on how to use its evolutionary algorithm.