Setting Up an Optimization

Outline

1. Define the reaction scheme.
2. Set continuous, categorical, and discrete parameter spaces.
3. Configure objectives and weights.
4. Add impurity or regulatory constraints.
5. Run the first iteration and review the suggested next experiment.

Worked example

Use a simple temperature and concentration optimization so the user can understand the mechanics before adding catalyst, solvent, or time variables.

Field	Example
Reaction	Simple model coupling reaction.
Continuous parameter	Temperature: 40-100 C.
Continuous parameter	Concentration: 0.05-0.50 M.
Objective 1	Maximize yield.
Objective 2	Minimize impurity A.
Constraint	Impurity A must remain below the selected ICH threshold.

First iteration review

After the first iteration, explain why MolTrace recommends the next experiment. The page should show the recommendation card, the predicted objective values, the uncertainty band, and the accept/modify/reject rationale field.

This guide can later be expanded with a Buchwald-Hartwig coupling example after the process chemist has reviewed the chemistry and screenshots.

Enabling the optional Phase C engines

The Phase C heavy-ML engines are optional and off unless an operator turns them on. Two independent conditions must both hold before one activates, and the module tells you which one failed. (v0.63.0, 2026-07-23)

1. A per-capability flag is set for this deployment — MOLTRACE_REACTION_YIELD_GNN, MOLTRACE_REACTION_RETRO, MOLTRACE_REACTION_FORWARD, or MOLTRACE_REACTION_SDL.
2. The dependency is actually installed on the site. The optional packages (torch for the yield GNN, aizynthfinder for retrosynthesis, rxn4chemistry plus transformers for forward prediction) are never declared as backend dependencies; they are site-installed extras, probed at the moment a decision is made.

The yield GNN carries a third condition: it activates only against a supplied benchmark-gate artifact — promotion evidence bound to a gold-set checksum and a model version — so a passing benchmark is proven per call rather than assumed once. A machine-readable producer of that artifact ships with the evaluation CLI.

What happens when the extras are absent

• Yield prediction still works. The surrogate degrades to a named lightweight fit — a Gaussian process where scikit-learn is present, and a zero-dependency k-nearest-neighbour surrogate otherwise. The backend that produced each number is named in the response, so a degraded fit is never mistaken for the heavy model.
• Route scoring and forward checking are unaffected. Scoring a chemist-supplied route and cross-checking a supplied prediction run on the frozen safety and green engines and need no extra at all. What the extras would add is the generative half — proposing a route, or generating a prediction — and that half stays unwired.
• SDL stays manual. Opting a site in only changes what the read-only status endpoint reports; there is no execution surface to enable. Arming and step execution would additionally require a bound site driver, persisted journal anchoring, and the human-approval / safety-gate linkage — none of which is wired.

Before you rely on a prediction

Check the capability readout first. It states, per capability, whether it is enabled, whether the dependency probe succeeded, whether it is active for a real decision, which modules are missing, and why — so a screen that looks quiet is distinguishable from a screen whose engine silently never ran.