v0.3: Add species pool support

[janitha-mahanthe]

Update the workflow so reaction handling no longer assumes the pool contains only monomers. Generated products should also be stored and reused as valid reacting species. This change mainly affects prepare_reactions.py and reaction_detector.py.

[janitha-mahanthe]

The main hurdle with this method is that the pool will contain both monomers and products (dimers, trimers, etc.). Since monomer-monomer reactions have already been generated, failing to filter reactions correctly in the second loop will cause the detector to re-process monomer-monomer and monomer-product combinations redundantly.

As the loop iterates through products, the number of reaction instances could scale from 100 to 10,000 or more. Even if original reactions are separated later, this combinatorial explosion risks causing infinite loops, memory leaks, or program crashes.

[janitha-mahanthe]

During development, we decided to include a new JSON file (eb79fcb) and a new Python library (7892067) to handle the reaction rules.

The Issue (Sequential Reactions):
There is a logic gap for multi stage reactions.

For example, in an epoxy reaction between a primary amine and an epoxy ring (diepoxy), the first reaction must occur between the primary amine and the epoxy. The secondary reaction then has to occur between the newly formed secondary amine and the epoxy ring. AutoREACTER is currently undergoing development to handle these sequential cases, but version 0.2 cannot process them yet.

If we blindly add a generic "secondary amine + epoxy" rule to reaction_library.py to account for this second step, it creates a loophole. If someone includes a standard secondary amine in their input, the system will simply react it with the epoxy, resulting in a basic, non-polymerization reaction.

@jrgissing, as we are designing this new rule system, how should we proceed?

• Should we allow the AutoREACTER to proceed with these types of non-polymerization reactions?
• Or should we strictly restrict the logic to polymerizations only (v0.2 currently only supports polymerizations)?

(Fortunately, RDKit can natively detect primary and secondary amines, so we don't need a separate secondary functional group library to parse this).

[jrgissing]

I would not worry about restricting reactions to those that result in polymerization. Having too many sets of templates is better than too few, and users can ignore reactions they do not want. Long-term, I imagine people will want AutoREACTER to support non-polymerization reactions as well, even if we continue to focus on populating the library with reactions that are useful for polymerization.

[janitha-mahanthe]

@jrgissing Thanks, that makes sense. I will continue without strictly restricting it to polymerization-only reactions.

[janitha-mahanthe]

Design update: species pool and reaction-rule handling

During recent development, the main design architecture for the species-pool workflow has shifted slightly.

The original idea was to allow the reaction pool to contain both monomers and generated products. However, this creates a larger reaction space than expected, especially because AutoREACTER will have a much larger reaction library in v0.3. To keep this manageable, the reaction library should be organized into reaction categories, such as amidation, esterification, epoxy-amine chemistry, vinyl reactions, etc.

A key issue is tracking which reactions are actually active in the system. From the second loop onward, AutoREACTER should not blindly scan the full reaction library. Instead, it should track which reactions have already occurred in the system and only enable the relevant follow-up reactions.

This is especially important for sequential reactions. For example, in epoxy-amine curing, the first reaction occurs between a primary amine and an epoxy ring. After that, the generated secondary amine can react again with another epoxy ring. If we simply add a generic secondary amine + epoxy reaction to the main reaction library, it creates a loophole where an input molecule that already contains a secondary amine could react directly with epoxy, even if that is not part of the intended sequential curing pathway.

To address this, we plan to introduce a rule-based system. The rule system will define which follow-up reactions should become active after a previous reaction occurs.

Example dummy structure:

[
    {
        "description": "EPOXY CURING",
        "if": "Di-Epoxide and Primary Amine Polyamination",
        "then": "Di-Epoxide and Secondary Amine Polyamination"
    }
]

This is only a dummy concept, but the final implementation will likely follow this type of structure.

Based on the discussion, we will not strictly restrict AutoREACTER to polymerization-only reactions. Having more available templates is better than having too few, and users can ignore reactions they do not need. Long term, AutoREACTER may support non-polymerization reactions as well, even though the current focus remains polymerization-related reaction-template generation.

[jrgissing]

OK, makes sense to me. I will note that I am a little worried about the sustainability of this complication, because it seems to imply that you will need to describe the relationship between any newly added reactions and any/all existing reactions in the database. There may end up being complex relationships between different reactions/pathways. As a pathological example, what if the second stage of one polymerization pathway is the same as the first stage of another pathway? Also, will folks not interested in restricting to polymerization be able to turn off the rules? I think your solution is good for now, just suggesting things to keep in mind.

[janitha-mahanthe]

1. No Professor, My Idea is too add existing + rule based reactions for the upcoming loops. Otherwise rule list would be too long too.
2. I haven't thought about it yet. I will keep this in mind.