Tensor Product State Quantum Chemistry
A desktop GUI connecting PySCF checkpoints to TPSChem.jl — from orbital visualization and cluster definition through CMF and TPSCI export, all without touching a script.
Workflow
Each step passes its outputs directly to the next. Resume from any saved intermediate — no rerunning from scratch.
Features
From checkpoint to SLURM submission without leaving the GUI.
Active Space
Manual mode: click MO rows to assign them to clusters. SPADE mode: assign atoms per cluster and filter by AO type (s/p/d/f) — designed for bimetallic and fragment systems where the orbital character matters as much as the geometry.
CMF
Choose between cmf_oo_newton, cmf_oo BFGS, and DIIS directly from the UI. Live Julia output streams into the log pane. Convergence thresholds and sequential/parallel sweep options are all exposed — no script editing required.
Export
TPSCI, SPT, PT2, CEPA, and FCI-solve drivers rendered from Jinja2 templates. Run locally with live output, or package everything — driver, CMF result, SLURM script — into a single zip for cluster submission.
Orbitals
MO isosurfaces rendered in-browser via the VibeMol viewer (MIT, evangelistalab). Switch between all-active and per-cluster molden files from a dropdown. Works fully offline — no network requests at runtime.
Resume
Skip steps you've already run. If h0/h1/h2.npy and clusters.json are present, the load screen enables "Jump to CMF". If cmf_result.jld2 exists, it enables "Jump to TPSCI/Export". No restarting from scratch.
Setup
On first launch, TPSChemVIS downloads VibeMol, clones TPSChem.jl from GitHub, runs Pkg.instantiate, builds PyCall against the active Python, and precompiles the Julia environment. The configured path persists in ~/.asbuilder/config.json for every subsequent launch.
Clustering modes
Mode A
Click rows in the orbital table to assign MOs to clusters. Occupation numbers are read from the checkpoint: α-only for open shells, doubly-occupied for closed. The fspace (nα, nβ) per cluster is derived automatically from mo_occ.
Best for: small active spaces, H chains, transition metal monomersMode B
Assign atoms to clusters, then select which AO types (s / p / d / f) contribute to the SPADE projector for each cluster. The SVD subspace partitioning runs automatically and reorders the active columns by cluster before saving.
Best for: bimetallic systems, dimers, Fe₂S₂, mixed-metal clustersExample walkthrough
Six hydrogen atoms in a linear chain, equally spaced at 1.8 Å. Three bonding/antibonding pairs → three two-orbital clusters, each with fspace (1,1).
Step 01
Point TPSChemVIS at a h6.chk file produced by a PySCF RHF run.
The app reads geometry, basis, MO coefficients, and occupation numbers.
No configuration needed — provenance is shown immediately.
If you're starting fresh you can run the SCF directly from the app's Load screen using the built-in PySCF runner, or supply an existing checkpoint.
Step 02
VibeMol renders each MO isosurface in the browser — cyan for the positive lobe, coral for the negative lobe. For H₆ STO-3G you get six σ-type MOs ordered by number of nodal planes (zero to five).
The three occupied MOs (occ = 2.0) have predominantly bonding character; the three virtuals (occ = 0.0) are their antibonding partners. Each bonding/antibonding pair will form one cluster in the next step.
Phase bar: ■ positive ■ negative · each segment = one H atom
Step 03
Switch to Manual mode. Click MO 1 → Cluster 1, MO 4 → Cluster 1 (the bonding/antibonding pair sharing the same nodal structure). Repeat for MOs (2,5) → Cluster 2 and (3,6) → Cluster 3.
Each cluster gets exactly 2 orbitals — one occupied, one virtual — so the fspace will be automatically derived as (1,1) per cluster from the mo_occ values.
Validated
| # | occ | ε (Eₕ) | character | cluster |
|---|---|---|---|---|
| 1 | 2.0 | −0.584 | σ₁ bond | Cluster 1 |
| 2 | 2.0 | −0.476 | σ₂ bond | Cluster 2 |
| 3 | 2.0 | −0.391 | σ₃ bond | Cluster 3 |
| 4 | 0.0 | +0.391 | σ₃* anti | Cluster 1 |
| 5 | 0.0 | +0.476 | σ₂* anti | Cluster 2 |
| 6 | 0.0 | +0.584 | σ₁* anti | Cluster 3 |
Step 04
TPSChemVIS groups the active columns by cluster (1,4 → cols 0,1 ; 2,5 → cols 2,3 ; 3,6 → cols 4,5) before computing integrals, so orbital indices are sequential within each cluster in the saved files.
Per-cluster .molden files are written first so you can inspect the active MOs in VibeMol before the integrals are saved. Edit nα / nβ here if the auto-derived fspace needs correction.
Saved to active_space/
| Cluster | n_orb | nα | nβ | Orbitals |
|---|---|---|---|---|
| 1 σ₁ pair | 2 | 1 | 1 | 1, 2 |
| 2 σ₂ pair | 2 | 1 | 1 | 3, 4 |
| 3 σ₃ pair | 2 | 1 | 1 | 5, 6 |
Step 05
Select Newton (cmf_oo_newton) for quadratic convergence. The app writes driver_cmf.jl, runs it as a Julia subprocess, and streams output line-by-line into the log.
For H₆ STO-3G the Newton optimizer converges in around 18 macro-iterations. The CMF energy of −3.2294 Eₕ is slightly below the RHF energy, reflecting the CASSCF-like intra-cluster correlation captured in the orbital rotation.
Saved to cmf/
Step 06
Set the variational threshold thresh_var = 1e-2 and click Run locally. The rendered Julia driver reads the CMF result bundle and runs the selected CI method.
TPSCI selects 48 determinants for H₆ STO-3G at this threshold. The PT2 correction accounts for the remaining dynamic correlation, giving a final energy of −3.465 Eₕ — well below the FCI reference, confirming convergence.
Saved to export/
Installation
Requires Python ≥ 3.11 and Julia ≥ 1.11. VibeMol and TPSChem.jl are installed automatically on first launch.
Clone the repository
No submodules are required; VibeMol is downloaded automatically on first launch.
git clone https://github.com/arnab82/TPSChemVIS.git cd TPSChemVIS
Install Python dependencies
Installs PyQt6, PySCF, NumPy, SciPy, and the asbuilder command.
pip install -e .
Install Julia
Download from julialang.org or use juliaup:
curl -fsSL https://install.julialang.org | sh
Launch — first-run bootstrap handles the rest
On first launch TPSChemVIS downloads VibeMol, clones or updates TPSChem.jl, instantiates packages, builds PyCall, and precompiles. Subsequent launches start immediately.
asbuilder # opens the last project asbuilder ~/calcs/fe2s2.qcproj # open or create a named project asbuilder --setup # re-run the TPSChem.jl wizard
Requirements
| Package | Version | Type | Purpose |
|---|---|---|---|
| PyQt6 | ≥ 6.6 | Python | GUI framework |
| PyQt6-WebEngine | ≥ 6.6 | Python | Embedded VibeMol viewer |
| PySCF | ≥ 2.4 | Python | SCF and integral generation |
| NumPy | ≥ 1.24 | Python | Array operations |
| SciPy | ≥ 1.11 | Python | SPADE SVD partitioning |
| h5py | ≥ 3.9 | Python | Checkpoint file reading |
| Jinja2 | ≥ 3.1 | Python | Julia driver templating |
| TPSChem.jl | latest | Julia | CMF / TPSCI / SPT engine |
| VibeMol | latest | First launch | 3D orbital visualization (MIT) |
| Julia | ≥ 1.11 | System | Julia runtime |
| Python | ≥ 3.11 | System | Python runtime |