Skip to content

Workflows

This page introduces the typical workflow for generating reaction networks with nasap-net.

Overview

Network generation consists of three main steps.

Step 1: Assembly enumeration

Define the target assembly as a template, then automatically enumerate all chemically meaningful substructures (subassemblies) from it.

from nasap_net import enumerate_assemblies

assemblies = list(enumerate_assemblies(
    template=target,
    leaving_ligand=X,
    metal_kinds='M',
))

If you want to enumerate substructures from multiple templates, enumerate them separately and then combine. Duplicate assemblies across the results are fine — use extract_unique_assemblies to deduplicate.

from nasap_net import extract_unique_assemblies

assemblies1 = list(enumerate_assemblies(...))
assemblies2 = list(enumerate_assemblies(...))
assemblies = extract_unique_assemblies(assemblies1 + assemblies2)

Step 2: Reaction enumeration

Enumerate all ligand-exchange reactions between the enumerated assemblies. Use MLEKind to specify which ligand (Leaving) is replaced by which ligand (Entering) at which metal (Metal). Forward and reverse directions are enumerated separately.

from nasap_net import enumerate_reactions, MLEKind

reactions = list(enumerate_reactions(
    assemblies=assemblies,
    mle_kinds=[
        MLEKind(metal='M', leaving='X', entering='L'),  # X is replaced by L
        MLEKind(metal='M', leaving='L', entering='X'),  # L is replaced by X
    ],
))

Step 3: Reaction classification

Assign a class label to each elementary reaction using a user-defined function. The ReactionToClassify object obtained via reaction.as_reaction_to_classify() provides the properties and methods needed for classification.

from nasap_net import classify_reactions, IncompleteReactionClassifierError

def classify_reaction(reaction):
    r = reaction.as_reaction_to_classify()
    if r.leaving_kind == 'X' and r.entering_kind == 'L':
        return 'forward'
    elif r.leaving_kind == 'L' and r.entering_kind == 'X':
        return 'backward'
    raise IncompleteReactionClassifierError(r)

reaction_to_class = classify_reactions(reactions, classify_reaction)

Saving and loading

Enumeration and classification results can be saved at any point using save_assemblies / save_reactions / save_classification_result. Saved data can be reloaded with load_assemblies / load_reactions.

from nasap_net import (
    save_assemblies, save_reactions, save_classification_result,
    load_assemblies, load_reactions,
)

save_assemblies(assemblies, 'assemblies.yaml')
save_reactions(reactions, 'reactions.csv')
save_classification_result(reaction_to_class, 'classification_result.csv')

assemblies = load_assemblies('assemblies.yaml')
reactions = load_reactions('reactions.csv', assemblies=assemblies)  # note: assemblies must be passed

Examples

Example Highlights
M4L4 — Enumeration Multiple templates, manual assembly addition, reaction enumeration, saving
M4L4 — Classification Loading saved data, classifier design, counting and saving
M6L4-TT Capping with enumerate_assemblies_capped_with_assembly
M6L4-TT + SP Merging assemblies from multiple templates