Skip to content

Software Development Kit (SDK)

When subscribing to the Cebule Tier, you can access the API via the Python SDK which can be regarded as a simple and user-friendly overlay to make use of well-defined functions to interact with the Cebule engine.

First we present how the API has been structured and then move on to present the collection of functions and argument possibilities of the SDK,

Application Programming Interface (API)

The API can be utiilized to search for molecules and includes the following internal features of the search method through the database holding more than 200.000.000 molecules:

  • Molecules ranking based on the identifiers (e.g. SMILES, formula).
  • Definition of how many molecules should be returned with an exact number. This improvement refers to the GET /search endpoint.
  • The query parameters for the GET /search endpoint are:
q

- the keyword to search for (required)

start

- offset of the first result to return (default: 0)

limit

- number of results to return (default: 50)

cursor

- value of nextCursorMark from the previous response

You can find the current documentation of the MQS API also under the respective tab within the Dashboard:

Figure 1: Documentation page of the API within the Dashboard.

Software Development Kit (SDK)

The SDK allows you to work in a more simplified way to integrate the MQS tool stack with your own coding projects or software in comparison to the bare bone MQS REST-API interface.

The Python SDK provides currently an additional layer for working with the API by improving the ease of use of the API with tailored functions.

As an example of what the SDK provides here the authentication and search functions in use from the SDK after importing mqsdk and setting up a session:

import mqsdk
session = mqsdk.Session("<email address>", "<password>")
results = session.data.search("aspirin", start=0, limit=10)
print(results)

Atom Order

Various Cebule tasks in the SDK (GEOMETRY_OPT, GROUP_CONTRIBUTION, FORCE_FIELD_MD) rely on a set atom order, and to interpret the outputs of those tasks one can use the ATOM_ORDER task in Cebule.

Cebule SDK TaskType: ATOM_ORDER

  • Determine the Cebule atom order for a given molecule specified as a SMILES string or a list of atomic symbols
  • Inputs:
  • smiles: str - SMILES representation of the molecule, OR
  • symbols: list[str] - List of atomic symbols (e.g., ["C", "H", "O"])
  • Cebule max_processors: N/A (lightweight operation)
  • Output: List of element symbols in the order they appear across Cebule task outputs (which is sorting atoms by atomic number in ascending order)

Example with SMILES: 

session.cebule.create_task("order", TaskType.ATOM_ORDER, smiles="CCO")

# Result:
["H", "H", "H", "H", "H", "H", "C", "C", "O"]

Example with symbols: 

session.cebule.create_task("order", TaskType.ATOM_ORDER, symbols=["C", "O", "H", "N", "H"])

# Result:
["H", "H", "C", "N", "O"]
This result lets us know the atomic indices used in other tasks. For instance in GEOMETRY_OPT output list we know that the first XYZ coordinate corresponds to a hydrogen atom and the last coordinate corresponds to an oxygen. In the GROUP_CONTRIBUTION output indices we know that if a group contains the atom at index 6, this is a carbon atom.

The Python SDK can be found under the following link: https://gitlab.com/mqsdk/python-sdk and check out the Molecule Search Jupyter Notebook.

You need to have subscribed to the Quantum & Machine Learning Tier for getting access to the API which the Python SDK depends on.

All example notebooks for the Python SDK can be found in the notebooks folder and example scripts in the scripts folder of the repository.