Skip to content

Building-block libraries (stock)

What it does: manages the commercial building-block library — which molecules you can buy. Both multi-step planning (deciding whether a route's leaves are purchasable) and SynScore (scoring from that) use it. You can switch the built-in library, add your own, or use only your own — and the same library applies to both planning and scoring.

Two libraries ship built in (downloaded on first use):

  • zinc (the default) — the ZINC in-stock set;
  • molport — MolPort in-stock building blocks.

Python

The built-in libraries are ordinary stock objects; compose them with set operators:

from synomega.stock import zinc, molport, InMemoryStock

mine = InMemoryStock.from_file("my_building_blocks.smi")   # your own library (SMILES file)
# or load a precomputed keys file in seconds: InMemoryStock.from_keys_file("mine.keys")

stock = zinc()               # the built-in zinc only (default)
stock = molport()            # the built-in molport only
stock = zinc() | mine        # supplement: built-in UNION your own
stock = mine                 # standalone: your library only
stock = zinc() | molport()   # both built-ins together
stock = zinc() & molport()   # intersection (listed by both)
stock = zinc() - blacklist   # difference (exclude some)

Pass the composed library to the planner or the scorer, and both use it:

import synomega
planner = synomega.load_default_planner(stock=zinc() | mine)
scorer  = synomega.load_default_scorer(stock=molport())

Omit stock= to use the default zinc. The same stock flows through both multi-step planning and SynScore.

Declarative shortcut

If you'd rather not compose by hand, use resolve_stock:

from synomega.stock import resolve_stock

resolve_stock("molport")                                         # built-in molport only
resolve_stock("zinc", user_stock="mine.smi")                     # supplement (the default)
resolve_stock("zinc", user_stock="mine.smi", mode="standalone")  # your library only
resolve_stock("zinc", user_stock="mine.keys", user_is_keys=True) # your library is a keys file
  • mode="supplement" (default) = built-in UNION your library;
  • mode="standalone" = your library only.

Command line

# switch the built-in library
synomega score --targets targets.smi --library molport --out scores.jsonl

# supplement: built-in zinc UNION your library
synomega plan --target "CCO" --library zinc --stock mine.smi

# standalone: your library only
synomega plan --target "CCO" --stock mine.smi --stock-mode standalone

# your library is a precomputed keys file
synomega score --targets targets.smi --stock mine.keys --stock-is-keys
  • --library {zinc,molport}: the built-in library, default zinc;
  • --stock <file>: your own library (SMILES; add --stock-is-keys for a keys file);
  • --stock-mode {supplement,standalone}: how your library relates to the built-in, default supplement (union).

Custom libraries and precomputed keys

Loading a raw catalogue (SMILES) recomputes an InChIKey for every entry (minutes at tens of millions). Do it once, save a keys file, and future loads take seconds:

synomega build-stock --catalogue my_catalogue.smi.gz --out my.keys.gz

Then use --stock my.keys.gz --stock-is-keys, or in Python InMemoryStock.from_keys_file("my.keys.gz"). Purchasability is tested by InChIKey, so your library and the built-ins are compared on the same footing, and catalogues written by a different toolkit still line up.

Adding a new built-in library

Add one line to the BUILTIN_STOCKS registry in synomega/data.py (name → hosted keys file) and upload the keys file to the asset mirror. Every consumer — multi-step planning, SynScore, and the CLI — resolves the commercial library through that one place, so changing it once takes effect everywhere.