Molden and Trexio support.

[mathieulinares]

PR Note: QM Source Integration, TREXIO Support, and AO Ordering

Summary

This PR extends VIAMD's quantum/electronic-structure file support and makes the user-facing QM workflow more consistent across source formats.

The main changes are:

• add TREXIO file support with summary and orbital-grid visualization
• improve Molden AO-order handling, including Cartesian higher-angular-momentum shells, and simplify its UI
• treat VeloxChem, Molden, and TREXIO as QM/electronic-structure sources internally
• keep the GUI source-specific, so users still see VeloxChem, Molden, or TREXIO
• add validation examples and loader tests for Molden
• document the AO-ordering policy for future maintenance

Molden

Molden support was cleaned up around AO ordering, Cartesian shell handling, and validation.

User-facing changes

• Molden still appears as Molden in the GUI.
• The Molden summary window is now source-focused and less verbose.
• AO ordering is automatic for normal use.
• Manual AO-order override remains available under Source Details / Advanced.

AO-order handling

Molden files vary by producer, especially for p shells, SP-derived p functions, and higher-angular-momentum shell ordering. The default is now automatic resolution:

• GANSU-generated files resolve to Standard P Order.
• files with only SP-derived p shells resolve to SP-Derived P Order.
• otherwise Molden defaults to Standard P Order.

For spherical shells, the Molden adapter remaps source coefficients into VIAMD/mdlib order for p, d, f, and g shells.

For Cartesian shells, the Molden adapter now supports higher-angular-momentum shell remapping for 6D, 10F, and 15G source order before evaluation.

Mixed-format Molden tags such as [5D10F], [7F], and [9G] are now interpreted per angular momentum instead of being collapsed into one global basis mode.

Manual modes are kept only as an advanced/debug override:

• Auto
• Source Order
• Standard P Order
• SP-Derived P Order

The Molden component resets its settings between files so an override from one file does not leak into the next file.

Validation

The Molden loader test was updated to current mdlib APIs and extended with new examples:

• h2o_sto3g.molden
• h2_sto3g.molden
• Ammonia_NH3.molden
• Anthracene_C14H10.molden
• Selenium-trioxide_SeO3.molden

All intended Molden examples parse and load successfully. The Selenium example specifically covers the previously unsupported Cartesian d-shell path.

Parser coverage also includes mixed-format tag handling such as spherical d, Cartesian f, and spherical g combinations.

The NTO Molden example is intentionally excluded from this PR.

TREXIO

This PR adds optional TREXIO support behind VIAMD_ENABLE_TREXIO.

Build integration

• CMake detects TREXIO through pkg-config or a direct header/library search.
• If TREXIO is unavailable and VIAMD_ENABLE_TREXIO=ON, CMake fetches and builds the configured TREXIO release automatically.
• If TREXIO is not desired, it can be disabled cleanly with -DVIAMD_ENABLE_TREXIO=OFF.
• The TREXIO library directories are passed to the linker to handle installations where pkg-config exposes dependent libraries such as HDF5 separately.

Loader integration

TREXIO files are treated as QM system sources. Detection supports:

• .trexio
• .h5
• .hdf5

For HDF5-like extensions, the loader probes the file before selecting the TREXIO loader so it does not steal non-TREXIO HDF5 files such as VeloxChem files.

GUI and representations

TREXIO exposes:

• TREXIO Summary
• TREXIO Orbital Grid
• molecular-orbital electronic-structure representations

The GUI shows the source as TREXIO, not generic QM.

TREXIO example

A proper ORCA-derived TREXIO water example is included under datasets/trexio_examples/.

This file is independent of the VeloxChem reference path and is intended as the TREXIO validation example.

AO-ordering policy

The central rule is:

Source-specific parsers/adapters must map AO/MO coefficients into VIAMD/mdlib-compatible order before evaluation.

The rendering and representation path should not need to know about producer-specific AO quirks.

VIAMD/mdlib internal order

The internal GTO evaluation path expects shell-contiguous ordering sorted by:

angular momentum -> atom -> radial shell/function -> shell component

VeloxChem

VeloxChem raw data has its own ordering. mdlib's VeloxChem reader remaps the raw VeloxChem AO/MO data into VIAMD/mdlib order before orbital evaluation.

Molden

Molden ordering is producer-dependent. The Molden component resolves this automatically by default and exposes manual override only under advanced source details. This includes the required remaps for spherical d/f/g and Cartesian d/f/g shells.

TREXIO

TREXIO spherical AO order follows the official convention:

m = 0,+1,-1,+2,-2,...

The TREXIO component maps this official spherical order into VIAMD/mdlib shell-contiguous order. The default TREXIO mode must remain TREXIO spherical.

Source / mdlib order and Source p: px,py,pz are debug overrides for unusual or synthetic files only.

QM layer / UI organization

The implementation now treats VeloxChem, Molden, and TREXIO as sources of QM/electronic-structure data. A small shared UI helper centralizes common source-window labels and source display.

Important UI decision:

• internally, these formats share the QM/electronic-structure concept
• externally, the GUI continues to show the concrete source name

So users see:

• VeloxChem Summary, VeloxChem Orbital Grid
• Molden Summary, Molden Orbital Grid
• TREXIO Summary, TREXIO Orbital Grid

Source-specific details and AO-order overrides belong under Source Details / Advanced.

Validation performed

• full VIAMD build succeeds with TREXIO enabled
• full VIAMD build succeeds after the mdlib Cartesian-shell extension used by Molden
• Molden parser validation passed for the intended examples
• Molden loader validation coverage includes H2O, H2, ammonia, anthracene, and Selenium trioxide examples
• TREXIO water example was generated from ORCA JSON using official TREXIO tooling and validated through the TREXIO path

Out of scope

• Molden NTO support
• one-off helper tools for VLX-to-TREXIO conversion or TREXIO probing
• broad unification of all source-specific backends into a single canonical data structure

The current PR keeps source-specific parsing/remapping localized and unifies the GUI/representation behavior where it is safe to do so.

[Copilot]

Pull request overview

This PR expands VIAMD’s quantum/electronic-structure source support by adding optional TREXIO loading, integrating a Molden parser/loader path with new example datasets, and unifying QM UI window labeling/behavior across VeloxChem, Molden, and TREXIO.

Changes:

• Add optional TREXIO support (CMake detection, file probing for .h5/.hdf5, TREXIO parsing + md_system conversion).
• Add Molden parsing utilities, loader integration, and multiple Molden example datasets plus standalone validation programs.
• Introduce shared QM UI helpers and improve electronic-structure orbital selection (incl. beta spin handling) + minor VeloxChem safety checks.

Reviewed changes

Copilot reviewed 33 out of 37 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
CMakeLists.txt	Adds optional TREXIO detection/linking and conditionally builds TREXIO component.
src/loader.h	Extends loader types (Molden/Mold/TREXIO) and adds allocator parameter to loader::load.
src/loader.cpp	Adds Molden/TREXIO loader integration and TREXIO probing for .h5/.hdf5.
src/viamd.cpp	Passes allocator into loader and adds error handling around postprocess step.
src/main.cpp	Improves MO selection UI to respect beta spin orbital labels/counts.
src/qm_ui.h	Adds shared ImGui window-label helpers for QM sources.
src/components/veloxchem/veloxchem.cpp	Uses shared QM UI labels/windows and adds guards when vlx is null.
src/trexio_data.h	Defines TREXIO data structures and parse/probe API (behind VIAMD_TREXIO).
src/trexio_data.cpp	Implements TREXIO probing and parsing via TREXIO C API.
src/md_trexio_loader.h	Declares TREXIO → md_system_t loader hooks (behind VIAMD_TREXIO).
src/md_trexio_loader.cpp	Converts parsed TREXIO nuclei into md_system_t and infers bonds.
src/molden.h	Defines Molden data model + parsing function declarations.
src/molden.cpp	Implements Molden utilities and Phase-2 parsing functions.
src/md_molden_loader.h	Declares Molden → md_system_t loader hooks.
src/md_molden_loader.cpp	Converts parsed Molden atoms into md_system_t and infers bonds.
src/QM_FORMAT_NOTES.md	Documents QM source integration model and AO-ordering policy.
src/MOLDEN_FORMAT_NOTES.md	Expanded Molden format edge-case documentation.
src/MOLDEN_PARSER_USAGE.md	Adds user/developer usage documentation for the Molden parser.
src/PHASE1_SUMMARY.md	Phase-1 historical summary documentation (added).
src/PHASE2_SUMMARY.md	Phase-2 historical summary documentation (added).
PR_NOTE.md	PR-level summary and validation notes (added).
README.md	Notes Molden support work in the project description.
test/test_molden_loader.cpp	Standalone Molden loader integration smoke test (added).
test/molden_test.cpp	Standalone Molden data-structure/demo test (added).
test/molden_parser_test.cpp	Standalone Molden parser unit-style tests (added).
datasets/molden_examples/README.md	Documents included Molden example datasets.
datasets/molden_examples/h2o_sto3g.molden	Adds H2O STO-3G Molden example dataset.
datasets/molden_examples/h2_sto3g.molden	Adds H2 STO-3G Molden example dataset.
datasets/molden_examples/Ammonia_NH3.molden	Adds ammonia Molden example dataset.
datasets/molden_examples/Acetaldehyde_C2H4O.molden	Adds acetaldehyde Molden example dataset.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.