qmatsuite 1.2.3

QMatSuite calculation backend and automation toolkit for Quantum ESPRESSO and related engines.

Status (2025): The original Java GUI is now in maintenance / deprecated mode. I am working on a full Python rewrite (v2) with a modern calculation engine, cross-platform GUI (PySide6), and easier integration with Quantum ESPRESSO, Wannier90, LAMMPS and online materials databases.

Java v1 releases are still available below. Python v2 is under active development in the v2-python branch.

QMatSuite (Quantum Visualization Interactive Toolkit for Ab-initio Simulations) is a graphical user interface designed for the Quantum ESPRESSO ab-initio suite. It aims to make ab-initio simulations easily accessible and intuitively controllable across major operating systems. QMatSuite integrates input file generation, calculation job control, result analysis, and data management into a single interface. Additional engines beyond Quantum ESPRESSO may be integrated in the future. For more information, feel free to check out my introduction video.

Download releases

The project is actively evolving, and we have released three early-access builds with detailed feature lists. We appreciate any bug report or feature suggestion for the next milestones. Download and quick-start guides are available on the official website.

Requirements

• Java Runtime Environment (JRE) 1.8: https://java.com/en/download/
• Windows/Linux/Mac OS

Developer Setup (Python v2)

The Python rewrite lives under src/qmatsuite. Install it in editable mode so interactive sessions, scripts, and tests can import qmatsuite without manual sys.path hacks:

python -m venv .venv
source .venv/bin/activate        # or .venv\Scripts\activate on Windows
pip install --upgrade pip
pip install -e .                 # add -e .[dev] to include pytest/pytest-cov

After the editable install you can run the quick tests directly:

python -m pytest tests/ -v --tb=short

Extended tests still live under extended-tests/; they continue to work when invoked from the repository root and benefit from the same editable install.

AI Agent Quick Start (MCP)

QMatSuite exposes an MCP (Model Context Protocol) server so AI agents can manage projects, install engines, run calculations, and retrieve results programmatically.

Automatic setup (recommended):

# Claude Code (project-scoped, default)
qms mcp config --write

# OpenAI Codex CLI
qms mcp config --agent codex --write

# Google Gemini CLI
qms mcp config --agent gemini --write

Add --scope user for global (user-level) configuration, or --project /path/to/project to set a default project directory.

Manual configuration

Claude Code — create .mcp.json in your project root:

{
  "mcpServers": {
    "qmatsuite": {
      "type": "stdio",
      "command": "/path/to/.venv/bin/python",
      "args": ["-m", "qmatsuite.mcp.server"]
    }
  }
}

OpenAI Codex CLI — add to .codex/config.toml:

[mcp_servers.qmatsuite]
command = "/path/to/.venv/bin/python"
args = ["-m", "qmatsuite.mcp.server"]

Google Gemini CLI — add to .gemini/settings.json:

{
  "mcpServers": {
    "qmatsuite": {
      "command": "/path/to/.venv/bin/python",
      "args": ["-m", "qmatsuite.mcp.server"]
    }
  }
}

Available tool categories: project management, engine discovery and installation, workflow configuration, structure import, calculation execution, results analysis, k-path generation, and demo store.

Command-Line Interface (Typer CLI)

The new runtime exposes a Typer-powered CLI named qms. Key commands:

📖 For detailed documentation with examples, see docs/CLI_API_REFERENCE.md and docs/STRUCTURE_AND_CLI_USAGE.md
📋 For output file naming, artifacts, and pipeline behavior, see docs/PIPELINE_OUTPUTS_AND_ARTIFACTS.md

# Create a scaffolded project (defaults to ./project1 if no path is provided)
qms init

# Or specify the target directory explicitly
qms init my_project

# Detect QE binaries/test-suite without needing a project checkout
# Detection order: QE_HOME env var → PATH → shell configs → home directory scan
qms detect-qe

# Run a QE input *or* step YAML in isolation (auto working dir + overrides)
qms run step calculations/si_dos/raw/si.1_scf.in --ecutwfc=60 --SYSTEM.degauss=0.01
qms run step calculations/si_dos/steps/nscf_1.step.yaml --workdir temp/nscf

# Import, rename, or delete structures/calculations registered in project.qv.yml
qms import-structure path/to/si.cif --id si_bulk
qms rename structure si_bulk --name "Si DOS" --path structures/si_dos.json
qms delete structure si_bulk
qms delete calculation si_dos --cascade

# Generate & run QE input directly from stored structures + overrides
qms run structure si_bulk --ecutwfc=60 --SYSTEM.degauss=0.01

# Author and edit step specs (YAML) with CLI helpers
qms init step scf --structure si --SYSTEM.ecutwfc=60
qms init step bands --structure si --auto-kpath  # Auto-generate k-path
qms configure step calculations/si_dos/steps/nscf_1.step.yaml --remove --SYSTEM.tprnfor

# Execute calculations (id, slug, or explicit path); --strict enforces references
qms run calculation si_dos --strict -v

# Inspect overrides suggested by an existing QE input
qms get-command calculations/si_dos/raw/si.1_scf.in

# Lightweight analysis (energy / band / dos summaries) and metadata
qms analyze scf calculations/si_dos/raw/si.1_scf.out
qms analyze dos si.dos.dat --plot --energy-range -5,5
qms analyze band si.bands.dat.gnu --symmetry si.bands.pp.out --plot

# Query QE parameter documentation
qms params pw --section CONTROL

Overrides now cover namelists, cards, and species rows:

• --SYSTEM.ecutwfc=60 adds/updates namelist parameters.
• --k_points=automatic:6,6,6,0,0,0 (or --CARD.K_POINTS.data=[[...]]) rewrites cards.
• --CARD.K_POINTS.rows.row1=0,0,1 edits individual mesh rows; combine with --remove via qms configure step.
• --SPECIES.Si.mass=28.0855 / --SPECIES.Si.pseudopot=Si.pbe-n-rrkjus_psl.1.0.0.UPF keep pseudopotentials consistent.

Need a pre-populated layout? qms init exposes a --template flag (reserved for future bundles). By default it always creates a clean skeleton so you can wire structures and calculations manually.

qms run calculation automatically locates project.qv.yml (walking up from the current directory). Each calculation owns an I/O directory (default raw/, configurable via working_dir in calculation.yaml) where all QE input/output data lives, so restart files persist between steps. Reference outputs belong in calculations/<id>/reference/, and strict calculations compare against the files named in calculation.yaml:

id: si_dos
mode: strict
calculation:
  working_dir: raw  # I/O directory name (default: "raw")
steps:
  - id: scf
    input: si.1_scf.in
    reference: reference/si.1_scf.out
  - id: nscf
    input: si.2_nscf.in
    reference: reference/si.2_nscf.out
  - id: dos
    input: si.3_dos.in
    reference: reference/si.3_dos.out

QE Detection in CI/CD

For reliable QE detection in CI environments (GitHub Actions, etc.), always set the QE_HOME environment variable. Detection priorities are:

1. QE_HOME environment variable (recommended for CI)
2. System PATH (which pw.x)
3. Shell configuration files (~/.zshrc, ~/.bashrc)
4. Home directory scan ($HOME/**/q-e-qe*)

# GitHub Actions example
- name: Run tests
  run: pytest tests/ -v
  env:
    QE_HOME: $HOME/src/q-e-qe-7.5

Test slices

The quick suite is split into three markers:

pytest -m unit    # parser/project tests (no QE binaries)
pytest -m qe_core # QE integration via run_and_verify_step/calculation runner
pytest -m qe_cli  # QE integration driven through the Typer CLI

Testing Overview (for Contributors)

QMatSuite uses a pytest-based test suite with 412 tests organized by subsystem. Detailed documentation is available in docs/tests_overview.md. This section provides a quick "map" to help you know which tests to run when you make changes.

Test Organization by Subsystem:

Area / Subsystem	Key Test Locations	Notes
Core models & DAG	tests/unit/test_models.py, tests/unit/test_project_and_cli.py, tests/unit/test_calculation_dag_constitution.py	Project/calculation/step schemas, ULID validation, DAG structure
CLI commands	tests/cli/	qms init, qms run, qms configure, qms analyze, error handling
Daemon / RPC	tests/daemon/	JSON-RPC endpoints for GUI, job management, step operations
QE calculations	tests/integration/test_si_*.py, tests/cli/test_si_*_calculation_*.py	Full calculation execution (requires QE installation)
Analysis & plotting	tests/unit/test_analysis_*.py	SCF/DOS/bands output parsing, plotting, artifacts
Structure I/O	tests/unit/test_structure_*.py, tests/examples/test_structure_io_examples.py	Structure import/export, format conversion, roundtrip
Resource resolution	tests/unit/test_resolution.py	Selector resolution (ULID, slug, path, name)
Legacy migration	tests/unit/test_legacy_migration.py	Legacy project format detection and migration
QE engine	tests/integration/test_qe_engine.py, tests/integration/test_qe_executable_*.py	QE input generation, executable detection (requires QE)
API service	tests/unit/test_api_service*.py	QVService API methods for project/calculation/step operations

What to Run When You Change Things:

• Core project/calculation/step models (qmatsuite.core.models, qmatsuite.project.model)

  • pytest tests/unit/test_models.py tests/unit/test_project_and_cli.py tests/unit/test_calculation_dag_constitution.py

• CLI behavior (qmatsuite.cli.main)

  • pytest tests/cli/ (some tests require QE installation)

• Daemon / RPC / backend (qmatsuite.daemon.server, qmatsuite.api.QVService)

  • pytest tests/daemon/ tests/unit/test_daemon.py tests/unit/test_qvservice_gui.py

• QE calculations (calculation execution, QE integration)

  • pytest tests/integration/test_si_*.py (requires QE installation)
  • pytest tests/cli/test_si_*_calculation_*.py (requires QE installation)

• Analysis / parsing / plotting (qmatsuite.analysis.*)

  • pytest tests/unit/test_analysis_*.py

• Structure I/O (qmatsuite.io.structure_io)

  • pytest tests/unit/test_structure_*.py tests/examples/test_structure_io_examples.py

• Resource resolution (qmatsuite.core.resolution)

  • pytest tests/unit/test_resolution.py

• Legacy migration (qmatsuite.legacy.migrate)

  • pytest tests/unit/test_legacy_migration.py

Running Tests Without QE Installation:

For environments without Quantum ESPRESSO installed, you can run only unit tests that don't require QE:

# Run all unit tests (no QE required)
pytest tests/unit

# Skip QE-dependent tests using markers
pytest -m "not qe_core and not qe_cli"

# Run only quick tests (excludes extended-tests/)
pytest -m quick

Note: Tests in tests/integration/ and some tests in tests/cli/ require QE installation. These are marked with @pytest.mark.qe_core or @pytest.mark.qe_cli and will be skipped if QE is not available.

The QE parameter helper (qms params) is backed by the generated metadata in src/qmatsuite/data/qe_module_parameters.json. Regenerate it when upgrading QE docs via:

# NOTE: The v1 extractor is deprecated. Use v2 tooling when available.
# For now, use the deprecated v1 extractor:
python tools/extract_qe_parameters_v1.py --pretty

qms run-step accepts arbitrary --parameter=value overrides. Parameters are mapped to the correct namelist using the metadata above; for ambiguous cases provide a prefix such as --SYSTEM.ecutrho=200. Lists can be expressed with Python/JSON syntax (e.g., --k_points="[4,4,4]"), booleans with --flag or --flag=false.

Structure Management:

• qms import-structure <file> --id <name>: Import structures from CIF/POSCAR/QE inputs
• qms run-structure <id-or-path>: Generate QE input from structure and run with parameter overrides

See docs/STRUCTURE_AND_CLI_USAGE.md for comprehensive examples.

qms import-structure ingests CIF/POSCAR/QE inputs (and more) via pymatgen, normalises them into structures/<id>.json, and registers them in project.qv.yml. qms run-structure loads those JSON structures (or an arbitrary structure file), converts them into a QE input via qe_input_from_structure, applies CLI overrides, and executes the step.

qms run step loads a declarative step YAML (structure id/path, calculation type, parameters) and generates the QE input via the same helper functions. This is useful for scripting repeatable QE steps outside full calculations.

QE Input Roundtrip Helper

Need to parse a QE input, optionally tweak it, and regenerate the file?

from pathlib import Path
from qmatsuite.io import QEInputParser

qe_input = QEInputParser.roundtrip_file(
    input_file=Path("tests/integration/ci_test_data/4_Si_DOS/si.1_scf.in"),
    output_file=Path("temp/roundtrip/si.1_scf.in"),
)

# qe_input.namelists / qe_input.cards are now available for inspection

roundtrip_file parses the original file and writes it back (default: in-place), so you can inspect or modify the structured representation before regenerating.

Highlighted features

Please refer to the release page for a detailed feature list. We would like to highlight the following features below:

• Calculations implemented:
  • Self-consistency (SCF)
    • Magnetism and spin orbital coupling (SOC)
    • DFT+U
    • Hybrid functionals
    • Van der Waals corrections
  • Structural optimization/relaxation (OPT)
  • Density of states (DOS)
  • Band structure (including spin polarized and SOC)
  • Molecular dynamics (Born–Oppenheimer MD)
  • Time-dependent density-functional theory (TDDFT)
  • Phonon (gamma point, DOS, dispersion, raman, dielectric constant)
  • NEB (Nudged Elastic Band) for transition energy barrier calculation
  • Projection to atomic orbitals (to each atom or to each element, also in the spin polarized case and SOC)
    • Projected DOS calculation
    • Projected band structure (fat bands)
• Parallel/multicore computing supported (both openmp and mpirun) and job control
• Visualizations:
  • 3D viewer
  • Visualizations of the output of all calculations

Main user interface

License

Copyright (c) 2025 QuantumNerd.

QMatSuite (Quantum Visualization Interactive Toolkit for Ab-initio Simulations) is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or any later version.

QMatSuite is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with QMatSuite. If not, see https://www.gnu.org/licenses/gpl-3.0.txt.