ChemAnim

Translate Chinese chemistry animation requirements into verifiable Manim scenes: DeepSeek handles requirement understanding and provides English canonical names and candidate isomeric SMILES; the program then queries PubChem, compares candidate structures using Morgan fingerprints, and uses RDKit to verify molecular formulas, formal charges, and equation conservation. Manim only reads the final JSON and does not execute model-generated code.

Preparation

Requires Python 3.12 and a DeepSeek API key. Equations use Unicode chemical subscripts for display and no longer depend on MiKTeX. First installation:

cd C:\Users\i\Documents\chemenv
py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .

Do not write the key into source code or .env. Set it in the current PowerShell session:

$secureKey = Read-Host "DeepSeek API Key" -AsSecureString
$env:DEEPSEEK_API_KEY = [Net.NetworkCredential]::new("", $secureKey).Password

To persist it across new terminals, add it to the Windows user environment variables as DEEPSEEK_API_KEY, then reopen PowerShell. Verify the environment:

.\check_environment.ps1

Related MCP server: ChemCP

Usage

First generate and check the scene, structure, and verification report only:

.\.venv\Scripts\chemanim.exe "演示乙烯与溴的加成反应。生成物为1,2-二溴乙烷，展示所有物质的结构式。" --no-render

Render the 2D or 3D animation:

.\.venv\Scripts\chemanim.exe "演示乙烯与溴的加成反应。生成物为1,2-二溴乙烷。" --quality high
.\.venv\Scripts\chemanim.exe "演示乙烯与溴的加成反应。生成物为1,2-二溴乙烷。" --quality high --structure-mode 3d

--structure-mode 3d enables OpenGL/GPU by default; 2D structures use the more compatible Cairo by default. For quick previews, use --quality medium; for manual selection, add --renderer opengl or --renderer cairo.

In 2D mode, structures in the same scene share a scale, so small molecules are no longer forcibly enlarged to match complex molecules.

Output is located at:

• build/scene.json: final scene and verification summary

• build/verification.json: PubChem CID, InChIKey, candidate/verified SMILES, and Morgan Tanimoto similarity

• build/molecule_*.svg or 3D atom/bond data in the scene

• media/: Manim videos

The workflow automatically retries up to three times when the DeepSeek JSON is invalid. If PubChem is temporarily unavailable, it keeps the candidate structures and performs local RDKit verification; if verification fails, it stops and does not render erroneous results.

By default, it uses the faster deepseek-v4-flash; chemical structures are still verified by PubChem and RDKit. For stronger planning, add --model deepseek-v4-pro --request-timeout 180.

More Examples

.\.venv\Scripts\chemanim.exe "演示甲苯被氧气选择性氧化为苯甲醛和水，展示全部结构式。" --quality medium
.\.venv\Scripts\chemanim.exe "制作阿莫西林半合成原理动画，保持正确立体化学，不要虚构实验条件。" --no-render

MCP Server

The project provides a standard stdio MCP entry point:

.\.venv\Scripts\chemanim-mcp.exe

MCP client configuration example (the key is inherited from the client process; do not write it into JSON):

{
  "mcpServers": {
    "chemanim": {
      "command": "C:\\Users\\i\\Documents\\chemenv\\.venv\\Scripts\\chemanim-mcp.exe"
    }
  }
}

The server exposes the generate_chemistry_animation tool with parameters including prompt, quality, structure_mode, render, model, and request_timeout. It only invokes the constrained ChemAnim CLI and does not execute model-submitted Python code.