edu-chem-reaction

Chemical Reaction Microscopic Demo → Interactive Webpage

What this skill produces

A single-page HTML that can be opened directly in a browser: on one side is the 3D molecular animationcorresponding to the reaction (Three.js, rotatable and zoomable, drag the "reaction progress" slider to see frame by frame chemical bond breaking/forming and atomic recombination, with step-by-step highlighting + floating molecule labels), on the other side is the KaTeX reaction equation + step-by-step explanation + atom conservation counter, and optionally an energy-reaction progress curve, plus overlay layers such as flames, catalyst protons, and electron transfer. The form is consistent with template/reaction.html .

Dependencies (important)

The computation core lib/reaction_kernel.py depends on sympy(used for balancing). Before running the script, first confirm there is a python3that can import sympy: run python3 -c "import sympy"(on this machine:/opt/homebrew/bin/python3.11）。

Handling when libraries are missing (important): if import raises an error (the same applies to sympy or any library used later),first ask the user whether to install, and only install after consent (python3 -m pip install <库名>) or switch interpreters;do not install directly without asking。 RDKit is optional: if installed, the hybrid geometry will use it to generate real conformations from SMILES; if not installed, use the built-in VSEPR library— both work,this skill will never automatically install RDKit。

Workflow

Step 1: Obtain the reaction spec (unify the three entry points)

Organize the reaction into a structured spec (format see references/problem-schema.md): reactants/products, atom mapping or explicit atoms, conditions (ignition/electrolysis/catalysis/reversible), category, step-by-step explanation,language。

• Text reaction/equation: directly extract reactants and products, call the kernel to balance automatically.
• Image: use vision to read the image and extract the equation, andecho the recognized reaction back to the user for confirmation(equation/conditions/category/language) before continuing.
• Random question generation: pick a reaction from the registry, or combine species within the library and use balanced_coefficients to balance, then regularize the answer before use.

Output language follows the prompt language: English prompt → English webpage, Chinese → Chinese. Record it in the spec meta.language。

Step 2: Use the kernel for exact computation (do not do mental math)

According to the modeling conventions of references/conventions.md , call lib/reaction_kernel.py：

• balanced_coefficients(...) use sympy nullspace tobalance automatically(equation coefficients are guaranteed);
• assemble_data(spec) expand molecule instances,verify atom conservation and atom mapping bijection、derive bond breaking/forming (difference set), and compute the world coordinates of each atom in the reactant state/product state, producing the data。

Can first self-check on the command line:

python3 lib/reaction_kernel.py     # 配平 + 守恒 + 键差 自检
python3 lib/molecules.py           # 分子库自检

Step 3: Write build_* to assemble the spec and inject it into the template

📍 Output location (important): Always write the finished HTML tothe user's current working directory (Path.cwd()）, unless the user explicitly specifies a path. Neverwrite into the skill's own directory (skills/edu-chem-reaction/output/ , etc.)—that is the skill's internal development sample directory.

Just follow scripts/generate.py in build_* and modify it, then render_html(K.assemble_data(spec), out)：

from pathlib import Path
out = Path.cwd() / "reaction-<反应简述>.html"   # 落在用户当前目录
render_html(K.assemble_data(spec), out)

Examples (copy and modify directly)：

• build_combustion_ch4(methane combustion · morph · flame · energy)—a template for high-level species + atom_map ;
• build_redox_na_cl2(sodium + chlorine gas · redox · electron transfer)—overlay electrons；
• build_esterification(esterification · mechanism · catalyst · transition state)—a template for low-level atoms + fragments + 关键帧 .

generate.py can directly produce registered reactions;without a path it writes to cwd by default：

python3 <技能目录>/scripts/generate.py combustion_ch4 ./reaction.html
python3 <技能目录>/scripts/generate.py list

Step 4: Self-check (corresponds to the correctness plan)

• sympy balancing coefficients == equation display coefficients == number of each molecule instance (assemble_data already asserted within).
• The atom mapping is a reactant↔product atombijection, with consistent elements; all bond endpoints exist (already verified by the kernel).
• The atom conservation counter is unchanged before and after the reaction (catalysts are not counted).
• Start a local static service (servingthe directory containing the output file) and check with a preview: no console errors, KaTeX equations render correctly, and when dragging the slider the bond-breaking/bond-forming highlights match the step-by-step explanation.

⚠️ You must close any ports/services you opened: stop the local service immediately once the preview check is finished,never leave a process occupying a port. If opened with the preview tool: immediately preview_stopafter checking. Before delivery, confirm the port has been released, then tell the user the result.

Step 5: Delivery

The finished product is written tothe user's current working directory (cwd), named like reaction-<反应简述>.html, tell the user the path, and it can be opened directly in a browser. Before delivery, confirm:(1) the finished product is in cwd, not in the skill directory;(2) no local service/port opened by this preview is left behind.

Two engines and automatic selection

The template has a built-in unified renderer and two per-frame positioning modes (sharing key-difference drawing/labels/overlays/UI):

• morph(atomic morphing): atoms each interpolate from the reactant state to the product state, naturally showingatom conservation/rearrangement, suitable for any reaction.
• mechanism(mechanism keyframes): atoms belong to rigid fragments, which move as a whole according to the K0/K1/K2 keyframes, groups do not deform, suitable forcatalyst/transition state/leaving grouptype organic mechanisms.

assemble_data according to meta.engine（auto/morph/mechanism) choose:auto when, the category is organic or with fragments go mechanism, otherwise go morph. The overlays are all data switches (see schema): flame(combustion/strongly exothermic),catalyst(catalyst proton + switch),transitionGlow(transition state energy glow), electrons(redox electron transfer),energy(energy-reaction progress curve), atom conservation counter (on by default).

Color scheme: Overall in a bright style (textbook ball-and-stick diagram style: atoms with dark outlines + soft shadows + white background panels), each reaction uses meta.accent distinct accent colors (combustion amber, esterification indigo, sodium chloride violet…).

Extension

• Add reaction: In generate.py add a build_*(high-level species+atom_map, or low-level atoms+fragments), register it in REGISTRY。
• Add molecule/ion: In lib/molecules.py add an entry to _LIBRARY_BUILDERS (VSEPR geometry + display metadata + internal bonds).
• Add overlay: In template/reaction.html add an optional module driven by the data field.

Contents

• template/reaction.html — data-driven template (unified renderer + dual engine + data island __REACTION_DATA__）
• lib/molecules.py — VSEPR ideal molecular geometry library (including element table/colors/radii)
• lib/reaction_kernel.py — sympy balancing + conservation/mapping validation + bond difference + scene assembly + optional RDKit detection
• scripts/generate.py — injection template + example build_* (including REGISTRY and CLI)
• references/problem-schema.md — data format for reaction spec and data
• references/conventions.md — modeling conventions, engine selection, overlays, balancing, and self-check