QCBlender

English | 简体中文

QCBlender brings quantum chemistry data directly into Blender. It calculates orbital, density, and electrostatic potential grids from supported HF/DFT wavefunctions, and lets you inspect and adjust structures, isosurfaces, materials, and vibrations with native Geometry Nodes while retaining scientific units and provenance.

QCBlender 0.1.0 Alpha Preview targets Windows x64 and Blender 5.1.1. Release packages and status are listed on GitHub Releases. The capability table describes the current repository and locally validated candidates. Later additions are not guaranteed to be in the published Alpha ZIP or tutorial package; check the candidate identities and validation scope.

---

Repository Structure

QCBlender/
├── qcblender/              # Add-on source package
│   ├── *.py                # Scientific evaluation, parsers, and data model
│   └── blender/            # Operators, UI, materials, and Geometry Nodes integration
├── docs/                   # User and developer documentation
│   ├── agents/             # Agent workflows and project rules
│   ├── adr/                # Architectural Decision Records
│   └── releases/           # Release notes
├── validation/             # User SOPs, validation scripts, and sample datasets
│   ├── human/              # Human SOP and topic guides with figures
│   ├── agent/              # Automated verification scripts and acceptance records
│   └── shared/data/        # Public, local-only, and benchmark chemistry data
└── tools/                  # Development scripts and CLI workflow helpers

Local checkouts may also contain ignored research, historical records, and interface contracts under docs/research/, docs/archive/, and docs/specs/. These are not included in a new public checkout.

---

Capabilities

Task	Input	Output
Molecular orbitals & electron densities	Gaussian .fchk/.fch or existing .cube/.cub	Positive/negative orbital phases; total, alpha, beta, and spin density surfaces or volumes
Electrostatic potential (ESP)	Supported FCHK or density/ESP Cube	Colored density surfaces, fixed-range legends, slices, probes, and line profiles
Molecular properties	Gaussian .log/.out, property-rich FCHK, or ORCA .out	Recognized energies, atomic charges and dipoles, with source and geometry association
Vibrations & spectra	Gaussian .log/.out, ORCA .out or .hess	Normal modes and available IR/Raman records; paired OUT/HESS checks retain source identities. FCHK vibration fields are not imported (ORCA guide)
Geometric trajectories	Gaussian optimization logs, ordered IRC FCHK, or multi-frame XYZ	Step navigation and convergence profiles; original XYZ-frame playback at a display rate, without interpolation or a physical-time assumption
External scene analyses	Paired Cube, point/path files, or native tables	IGMH/IRI, ESP extrema/area, NBO/E(2), AIM, Mayer, ETS-NOCV, surface-distance projection, and AICD tensor views
Scientific result tables & quantitative analysis	Native records or imported analysis outputs	Filter/sort/page/source-row inspection; atomic charge, static bond order, Hirshfeld MO composition, IGMH contributions, ESP regions/distributions, and Bader basin integrals (atomic results)
ALIE & RDG/NCI	Externally generated field pairs	Explicit quantity roles, units, density-domain masks, and quantitative surface records; no built-in ALIE/RDG solver
Frozen-frontier reactivity (FMO)	Same-source closed-shell canonical FCHK, SCF log, and provenance receipt	Global indices and optional Hirshfeld frontier contributions; a frozen-orbital approximation, distinct from ΔSCF (FMO guide)
Spectra & static scientific plots	Existing modes, tables, path energies, or profiles	IR/non-resonant Raman broadening, orbital energy levels, IRC/Mayer/profile plots, CSV/metadata and SVG (spectra guide)
Citation checklist	Evidence of actual source parsing/evaluation	JSON/text checklist with verified/candidate/unmapped entries; verified references in BibTeX/RIS
Appearance & zero-anchored colors	QC views with supported materials	Appearance presets, free or zero-anchored ranges, and upgrades for older color mappings; scientific arrays remain unchanged
vdW shell & labels	Atom views and annotations	Independent translucent vdW shells, result-driven atom colors, locate/pin, and one-time label layout
Display comparison & keyframe copies	Explicit atom pairs or original optimization/IRC/XYZ frames	Rigid display alignment with RMSD and geometry-only copies; neither establishes scientific source association
Images & vibration media	Existing camera, lights, and a selected mode	3D PNG, one-cycle vibration PNG sequence or MP4; output settings restored after export
Project source recovery	Self-contained .blend + .qcdata/	Grouped source/evidence/cache diagnostics, data relocation, and display-cache rebuilding

Note

External analyses must be generated by their respective quantum chemistry software beforehand. QCBlender reads and visualizes the results; it does not perform SCF calculations.

---

File formats and scientific data

Bold means implemented parsing (stored data), computation (derived data), or export (output profiles), within the stated conditions. Plain text means format-carried but unsupported/unverified data. Bold does not imply all pipeline stages, every producer version, or independent scientific validation.

Audit baseline: 658b68691568 · 2026-11-06. Source review, not a new Blender/scientific runtime qualification. Optional fields depend on the file contents. Pinned local commits and new site routes may not be published yet.

Format / profile	Atomic structure / wavefunction	3D field data	Properties / trajectories	Conditions and limitations
Gaussian FCHK .fchk / .fch	Elements and atomic coordinates; Basis functions; MO coefficients, occupations and energies	Derived: Molecular orbital amplitude ψᵢ(r); Total, α, β and spin electron densities; Electrostatic potential (nuclear + electronic)	Printed total energy, atomic charges and dipole; Cartesian Hessian / force constants and dipole derivatives	Real, non-periodic, all-electron HF/DFT within evaluate.prepare() gates; a parsed file is not proof of convergence.
Gaussian output .log / .out	Atomic coordinates; qualified optimization frames	—	Method-resolved energies and convergence records; Atomic charges and dipole; Normal-mode displacements, frequencies and IR intensities; Raman activities and depolarization ratios; Oscillator strengths and transition properties	Gaussian jobs use the Gaussian parser; ORCA headers route to a separate reader. Atomic properties require an unambiguous geometry association. Raman attachment checks source and mode identity.
Gaussian Cube / scalar-grid profiles .cube / .cub	Atomic coordinates and affine sampling grid	Stored: Sampled MO amplitudes (single / multiple); Electron / spin / α / β density grids; Electrostatic-potential grids; Density-plus-gradient / tensor-specific combined layouts	—	Single or interleaved multiple scalar datasets, including indexed MO cubes; full affine grids. Positive-count scalar files remain unknown until quantity/unit assignment. No automatic unit conversion.
Standard XYZ .xyz	Elements and Cartesian coordinates	—	Multiple geometry frames	Exactly element/atomic number + three finite Å coordinates. Same atom count/order in all frames; discrete navigation. No extxyz, extra columns, lattice/PBC or implicit energies.
ORCA printed output .out / .log	Last explicit atomic geometry	—	Printed energies, charges, dipole and thermochemistry; Normal modes, frequencies and IR records; Raman activities and depolarization ratios	Selected ORCA job and its last explicit geometry; no optimization-frame importer. Qualified OUT fixtures: 4.0.1.2/5.0.0/6.0.1/6.1.0; other versions are flagged unverified. No MO/basis import.
ORCA native HESS .hess	Elements, coordinates and atomic masses	—	Native normal modes and frequencies; Optional IR and Raman tables	Native sections; optional OUT must be chosen explicitly. Pairing checks ordered atoms, masses, coordinates up to translation, frequencies and normal modes. Qualified pairs: 4.0.1.2/6.1.0; legacy 3.0.2 Raman layout is separate.

Full bilingual format reference

Dedicated analysis-input profiles · External conversion · Result export · Project persistence

Candidate formats — not implemented

P1/P2/P3 are recommendations from this audit, not accepted milestones or release dates. All candidate importers remain unsupported.

• P1: Molden, ORCA JSON (orca_2json), Multiwfn MWFN
• P2: AIM WFX, AIM WFN, Extended XYZ (libAtoms profile), APBS OpenDX scalar profile, VTK ImageData
• P3: ORCA binary wavefunction, VASP CHGCAR / CHG, VASP LOCPOT, VASP ELFCAR

Compatibility & Installation

• Tested Environment: Windows x64, Blender 5.1.1 (manifest minimum: 5.1.1; upper version boundary: 5.2.0). Other versions and platforms are not covered by this validation.
• Scope: Non-periodic, real-valued, all-electron HF and DFT wavefunctions. Supported basis sets and methods are listed in Validation Status.
• Dependencies: The extension bundles required scientific libraries. No external Python setup is needed.

Method 1: Install from ZIP (Recommended)

1. Download qcblender-0.1.0.zip and verify its SHA-256 against SHA256SUMS.txt on GitHub Releases. (Do not use GitHub's source code archive ZIP).
2. In Blender, go to Edit → Preferences → Get Extensions, click the top-right menu icon, choose Install from Disk, and select the ZIP file.
3. Switch to Add-ons in the Preferences sidebar, find QCBlender, enable it, expand its card, and click Check Scientific Runtime. Continue after the module status text reports that all checks passed.

Method 2: Install from Remote Repository

1. In Blender, open Edit → Preferences → System → Network and enable Allow Online Access.
2. Go to Get Extensions → Repositories → ＋ → Add Remote Repository, enter https://notes.psiqaq.cn/QCBlender/index.json, and add it.
3. Refresh the repository, locate QCBlender, and click install. Check the runtime in Add-ons as described above.

The tutorial package (qcblender-tutorial-0.1.0.zip) contains the complete tutorial, screenshot assets, and sample files. Extract it while preserving the directory structure.

---

Quickstart: Your First Molecular Orbital

Try the P01 oxygen molecule example in the tutorial package. Its FCHK contains the basis set and MOs needed for evaluation; follow the full orbital walkthrough for a fixed Alpha MO9 example. Positive and negative surfaces represent orbital phase.

1. Import Structure: In the 3D Viewport, press N to open the sidebar. Go to QCBlender → Import and Export → Import → Import Gaussian / Cube / XYZ / ORCA, then select the FCHK file.
2. Open Object Settings: Select the imported atom object. In the sidebar under Current QC Object, click Open Object Properties.
3. Generate Field: In Create Views and Tools → Compute, click Generate Quantum Field. Wait for the independent scientific preflight to pass, then use the parameter dialog:
   • Set Quantity to Molecular orbital, Spin to Alpha.
   • Select the target orbital by HOMO/LUMO or source number.
   • Adjust grid resolution (defaults to 0.2 Å spacing, 3 Å margin) and click OK.
4. Tune Display: Select the new field object and open its Object Properties. Under Geometry Representation, adjust the isovalue and toggles for positive/negative phases. Adjust surface colors under Blender's native Material Properties.
5. Save Project: In the N-panel under Project and Maintenance → Save and Archive, click Save Self-Contained Project. This creates a .blend file paired with a .qcdata/ folder containing cached arrays.
6. Render: Position your camera, add scene lights, and press F12 to render.

Default Grid Parameters and View Initial Values

• Initial grid: Spacing 0.2 Å, margin 3 Å, memory budget 512 MiB.
• Atom view quality defaults to Quality=3; slice views sample 201 points per axis.
• Standard geometry node assets retain their bundled defaults.

Exporting Data & Parameter Summaries

Select the QC object containing the target records and navigate to N sidebar → Import and Export → Export → Export Data and Parameter Summary. The available data types depend on that object. Export original IR frequencies, optimization energy/convergence records, IRC records, Mayer bond orders, line-profile samples, paired-field voxels, or ESP area records as UTF-8 CSV files with metadata.json. Current View Parameter Summary instead exports view-summary.md and metadata.json. For filtered tables, spectra, static SVG, and citations use Scientific Results → Export Scientific CSV / SVG. For rendered images or vibration media use Render Properties → Image and Vibration Output. See the import/export routing guide and shared export steps.

Export files are saved to a dedicated subfolder within your project directory (or the system Documents folder if unsaved). You can set a global default path in add-on preferences.

---

Project Saving & Scientific Constraints

• Saving: The .blend file holds nodes, materials, and scene layouts; the matching .qcdata/ directory stores scientific arrays and provenance metadata. Always keep both together when moving or archiving projects.
• Inputs: Binary .chk files must be converted to text .fchk via Gaussian's formchk before import. For generic Cube files with unknown quantity or units, use Identify Cube Quantity and Unit after import, based on their generating calculation. Declaring a unit does not convert array values.
• Current Limits: Periodic boundary conditions (PBC), effective core potentials (ECP), complex wavefunctions, ORCA binary wavefunctions (.gbw), and Multiwfn .mwfn files are not supported.
• Scientific Caveats: Display bonds are inferred from atomic distances and do not represent calculated bond orders. Vibration playback is a visual representation and does not alter static wavefunction fields into time-dependent solutions.

Standard XYZ uses element symbols or atomic numbers and finite coordinates in Å. Multiple frames must retain atom count and element order. Navigate discrete frames or use Object Properties → XYZ Frames → Original XYZ Playback to play them in source order. Playback does not interpolate or assign physical time; stopping or saving preserves the current source frame. Multi-frame XYZ cannot be associated as a static scientific reference. Single-frame association checks the actual geometry.

Save the latest project state before archiving; the archive uses the saved .blend and matching .qcdata/. Keep original calculation outputs separately. Supported result-table, ALIE/RDG, and FMO imports also preserve their evidence files in .qcdata/; this does not imply that every legacy importer copies its raw sources. For research figures, retain method, basis, source identity, quantity/units, grid, isovalue and color range. The current data notice distinguishes owned public samples from historical restricted inputs; candidate checks and independent human/scientific acceptance are recorded separately in Validation Status.

---

Developer Documentation

See the Documentation Index for full architecture and development references:

Category	Guides
Building & Validation	Development Guide & Validation Status
Architecture & Specs	Single-Extension ADR; local-only design and interface contracts are under docs/QCBLENDER_V1_DESIGN.md and docs/specs/
Scientific Foundation	Domain Vocabulary; local-only studies are indexed in docs/research/README.md
Tutorials & Verification	Human SOP, Shared Datasets, Complex Examples (local only: docs/COMPLEX_EXAMPLES.md), Agent Workflows
Guidelines & Tracking	Agent Rules, Issue Tracker Rules, Development Pitfalls
Licensing & History	LICENSE, Third-Party Notices, CHANGELOG

For your first Alpha session, follow the P01/MO9 workflow. Under Import and Export → Export → Export Data and Parameter Summary, select Current View Parameter Summary to save Chinese Markdown and JSON. The release study is available locally at docs/research/engineering/github-release-workflow.md.