Gaussian Molecule Workflow

Gaussian molecule workflow v1.6.2

Use this standalone Windows skill for finite-molecule Gaussian 16 jobs. Treat the four bundled analysis skills as one post-Gaussian pipeline: ESP, HOMO/LUMO, ELF, and molecular box.

Mandatory preflight and setup

Run this before preparing, running, or visualizing a molecule:

python scripts/gaussian_workflow.py preflight --scope full --json

The gate checks:

• Gaussian console executable (g16.exe) and formchk.exe;
• Multiwfn (Multiwfn.exe, the WFN/wavefunction analyzer) plus its settings.ini;
• VMD (vmd.exe);
• Python 3.8 or newer and PyYAML, NumPy, Pillow, and Matplotlib.

Dependency discovery uses this order: explicit environment variables, the local configuration file, PATH, common installation directories, and finally one read-only fallback search across all mounted local logical drives. The fallback search happens only after a required native executable is still missing, and its roots can be extended with GAUSSIAN_WORKFLOW_SEARCH_ROOTS (semicolon-separated on Windows). It searches for Gaussian, formchk, Multiwfn, and VMD once per preflight instead of scanning the drives once per program.

If Python packages are missing and installation is authorized, rerun with:

python scripts/gaussian_workflow.py preflight --scope full --install-python --write-config

Gaussian, Multiwfn, and VMD are external/proprietary applications and are not bundled or silently downloaded. If the global search still cannot resolve a required component, stop and ask explicitly: “未找到上述软件或配置不完整，是否需要我协助配置？如果已经安装，请提供安装目录；Gaussian、Multiwfn 和 VMD 需要用户自行安装并拥有许可。” Do not write machine configuration or install Python packages until the user authorizes it. After authorization, accept an installation directory or executable path, set GAUSSIAN_EXE, FORMCHK_EXE, MULTIWFN_BIN, MULTIWFNPATH, or VMD_BIN as appropriate, and rerun preflight. --write-config can persist discovered Gaussian/formchk, Multiwfn/settings, and VMD paths in a local config/gaussian.local.json; never share that machine-specific file.

Do not start Gaussian or visualization while preflight is BLOCKED. Do not claim that discovering an executable automatically changes the parent process environment. The bundled analyze command propagates discovered paths to every substage; when running a substage manually, set the reported environment variables first.

Initial structures from PubChem

When the user gives a molecule name, formula, SMILES, InChI, or CID but no usable coordinates, retrieve the starting structure before Gaussian preparation:

python scripts/gaussian_workflow.py fetch `
  --query "TTE" --name TTE --output-dir molecule_sources --json

fetch resolves the PubChem CID through PUG REST, tries the 3-D SDF first, saves the structure, and writes .pubchem.json with the CID, identity properties, source URL, record type, warnings, electron count, charge, multiplicity, and an unconfirmed structure gate. It uses the standard-library HTTP client; if the network or PubChem is unavailable, report the exact error and do not invent coordinates.

Ambiguous battery abbreviations are pinned in references/pubchem_aliases.json (including TTE, LiFSI, and FSI-); use --cid when a query has multiple legitimate identities.

For a compound without a PubChem 3-D conformer, the default is an explicitly flagged 2-D fallback. Use --strict-3d when a planar starting geometry is unacceptable. For a dot-separated salt such as LiFSI, use:

python scripts/gaussian_workflow.py fetch `
  --query "LiFSI" --name LiFSI --output-dir molecule_sources `
  --assemble-disconnected --charge 0 --multiplicity 1 --json

The salt option fetches separately available component geometries and writes a non-overlapping XYZ ion-pair starting guess. It is not a crystal or solvent structure; optimize it and, when the result is final, run a frequency calculation to check for imaginary modes. The manifest must remain alongside the XYZ.

Mandatory structure confirmation gate

Never generate a GJF or launch Gaussian from a PubChem-derived structure until the user has inspected and approved the actual structure. Show the user the resolved name/formula/CID, record type (3-D, 2-D fallback, or assembled ion pair), charge/multiplicity, and a view of the coordinates in VMD/Multiwfn. Ask explicitly whether the structure is correct. Do not issue --yes on the user's behalf.

Inspect the sidecar first:

python scripts/gaussian_workflow.py confirm-structure --input molecule_sources/TTE.sdf --json

After the user explicitly confirms the structure, record the approval:

python scripts/gaussian_workflow.py confirm-structure `
  --input molecule_sources/TTE.sdf --yes `
  --note "User confirmed the PubChem structure after visual inspection."

The command stores the confirmation time, note, and structure SHA256 in the sidecar. gaussian_pipeline.py refuses to generate the Gaussian input while the gate is unconfirmed or when the structure has changed after approval. Manual/local structures without a PubChem sidecar do not use this particular structure-identity gate, but charge/multiplicity validation still applies.

Never continue to Gaussian if the fetch manifest reports unknown charge/multiplicity or a parity mismatch. For a resolved structure, pass the manifest values explicitly to the GJF pipeline, for example --charge -1 --multiplicity 1 for FSI-. PubChem identity and formula do not by themselves prove a spin state; use the species rules or ask the user when the state is ambiguous.

Core Gaussian workflow

Use prepare to validate the structure and generate GJF, run to execute an explicitly approved GJF, parse to parse an existing job, resume/status to determine the next safe action, and full for prepare -> Gaussian -> formchk -> parse. Never launch a real Gaussian calculation without explicit user authorization and a satisfied command-template safety gate.

Default non-monatomic task: single-point plus Opt/Freq. Default theory: B3LYP/6-311+G(d,p), GD3BJ, SCF=(Tight,XQC), Int=UltraFine, Opt=Tight. Resolve charge/multiplicity from the user, species rules, and fragment validation; never silently assume unknown 0 1. Automatic HOMO/LUMO selection is restricted to closed-shell systems; require explicit spin-channel/index instructions for UHF, ROHF, open-shell, or fractional occupations.

Complete post-Gaussian analysis

After Gaussian and formchk produce analysis/fch/.fch, run one command from the skill root or analysis folder:

python scripts/gaussian_workflow.py analyze `
  --input analysis/fch --output analysis/output --render

analyze runs, in order, the bundled ESP, frontier-orbital, ELF, and molecular-box stages. It performs a second full dependency preflight, propagates executable/settings paths, stops on failed required outputs, and writes analysis_manifest.json. Use --install-python on the first run if Python packages are missing. To generate cubes and TXT files without VMD PNGs, omit --render.

Output contract per molecule ``

The complete rendered run must contain:

• ESP: _density.cub, _ESP.cub, _ESP.png, _esp_stats.txt, and _dimensions.txt. The statistics and color scale use the actual Multiwfn ESP minimum/maximum on the rho=0.001 surface. The dimensions file is the electron-density isosurface extent and is distinct from the molecular box.
• HOMO/LUMO: the selected _orb######.cub files, _HOMO.png, _LUMO.png, _energies.txt, and root-level orbital_indices.txt. The energy TXT contains orbital indices, Hartree, eV, kcal/mol, and the gap.
• ELF: _ELF.cub, VMD 3D _ELF.png, default 2D XY maps _ELF_fill_xy.png and _ELF_shaded+proj_xy.png, plus the exported plane TXT/log files. Use --plane xy|xz|yz|atoms for another plane.
• Molecular box: .pdb, new.pdb, _box_dimensions.txt, and _BOX.png. The TXT and PNG dimensions come from the PDB CRYST1 record and are reported as X x Y x Z in Angstrom.

Keep per-molecule Multiwfn, VMD, and Matplotlib logs. Do not reuse an old cube, plane file, PDB, TGA, or PNG when the current stage failed.

Sharing and portability

Share only the clean skill directory containing SKILL.md, requirements.txt, config/gaussian.local.example.json, references/, scripts/ (including pubchem_structure.py), and the four bundled skills/ subdirectories. Exclude config/gaussian.local.json, __pycache__/, test/visual-test outputs, Gaussian jobs, downloaded structures, sidecars with approvals, and analysis results. The recipient must have network access for PubChem retrieval and install or already possess licensed Gaussian, Multiwfn, and VMD, then run preflight and configure their own executable paths. The skill contains no machine-specific executable paths in its shareable configuration.

Failure handling

Report the failed stage, executable path, return code, and corresponding log. Preserve valid outputs from earlier completed stages, but do not report the complete pipeline as successful unless all requested required files pass readability and existence checks.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Nanhuai-X
• Source: Nanhuai-X/gaussian-molecule-workflow
• License: MIT

Install and usage instructions live in the source repository linked above.