Metadata-Version: 2.4
Name: vqkit
Version: 1.1
Summary: Unified VASP + Quantum ESPRESSO pre- and post-processing toolkit
Author: Rajkamal Anand
License: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20
Requires-Dist: matplotlib>=3.4
Requires-Dist: scipy>=1.7
Requires-Dist: spglib==2.3.0; python_version == "3.9"
Requires-Dist: spglib>=2.3; python_version >= "3.10"
Requires-Dist: seekpath>=2.0
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# VQkit 1.1
QE NEB endpoint workflow (v1.16): VQkit now requests only `initial.in` and `final.in`. It generates the native `neb.x` input and a matching `VQkit_NEB_CIF_images/` directory containing P1 CIF files for the initial endpoint, every interpolated image, and the final endpoint. The user is explicitly asked to confirm that the intermediate CIF path has been visually checked before submission.
# VQkit 1.1

**VQkit** is a unified command-line pre- and post-processing toolkit for **VASP** and **Quantum ESPRESSO**.

**Lead Developer:** RAJKAMAL Anand, PhD

> Build carefully. Analyze clearly. Discover confidently.

## Installation

VQkit requires Python 3.9 or newer.

```bash
cd VQkit_v1.0_Software_Package
python3 -m venv vqkit_env
source vqkit_env/bin/activate
python -m pip install --upgrade pip setuptools wheel
python -m pip install --upgrade installable/vqkit-1.0-py3-none-any.whl
hash -r
vqkit version
vqkit
```

Expected version:

```text
VQkit 1.1
```

## Current preprocessing menu

```text
===== CALCULATION SETUP =====
[1]  Create a new calculation
[2]  Convert CIF to input file
[3]  Convert output file to input

===== STRUCTURE EDITING =====
[4]  Freeze / fix atoms
[5]  Delete atoms

===== VALIDATION =====
[6]  Pre-flight calculation check

===== PSEUDOPOTENTIALS =====
[7]  Create POTCAR from POSCAR
[8]  Pseudopotential library setup

===== RECIPROCAL SPACE / CONVERGENCE =====
[9]  Generate band-structure K-path
[10] K-points
[11] Convergence tests

===== REACTION-PATH PREPARATION =====
[12] Generate NEB intermediate images
```

## CIF to Quantum ESPRESSO

Supported calculation types:

1. Geometry optimization (`relax`)
2. SCF
3. Variable-cell relaxation (`vc-relax`)
4. NSCF
5. DOS
6. PDOS
7. Band structure
8. Optical properties
9. Phonons
10. Fermi surface
11. Thermo_PW
12. AIMD
13. NEB starter input
14. Custom input

For calculations using a uniform mesh, VQkit reads the CIF lattice and atomic geometry, estimates whether the system is **3D bulk, 2D layer/slab, or 1D wire/chain**, and generates a dimensionality-aware k-mesh. Non-periodic directions are kept at `k = 1`.

## QE pseudopotential library integration

If the QE UPF library is already configured through preprocessing option `[8]`, CIF-to-QE conversion:

- detects the elements in the CIF
- searches the configured UPF library
- lists available pseudopotentials
- identifies PAW, ultrasoft, norm-conserving, or unknown type when possible
- inserts the selected exact UPF filenames into `ATOMIC_SPECIES`
- uses the configured library path as `pseudo_dir`

## Automatic QE cutoffs

VQkit reads recommended `ecutwfc` and `ecutrho` values from selected UPF metadata when available and uses the maximum requirement across species.

Fallback starting rules when UPF recommendations are unavailable:

- norm-conserving: `ecutrho = 4 × ecutwfc`
- ultrasoft: `ecutrho = 8 × ecutwfc`
- PAW: `ecutrho = 8 × ecutwfc`

If no `ecutwfc` recommendation is available, VQkit uses **50 Ry as a starter value**. A cutoff-convergence calculation is still recommended before production calculations.

## K-points

The K-point preprocessing module supports VASP and QE structures defined by:

- VASP POSCAR/CONTCAR
- QE `ibrav = 0` + `CELL_PARAMETERS`
- QE nonzero `ibrav` + `A/B/C`
- QE nonzero `ibrav` + `celldm(...)`

For 2D and 1D systems, non-periodic directions are kept at Gamma-only sampling.

For QE automatic grids:
- odd mesh dimension → shift 0
- even mesh dimension → shift 1
- `nk = 1` → shift 0

Example:

```text
K_POINTS automatic
9 9 1 0 0 0
```


### QE cutoff formatting

UPF-derived decimal cutoff recommendations are valid in Quantum ESPRESSO. VQkit now rounds automatically selected cutoffs **upward to whole Ry values** for cleaner inputs and to avoid undershooting a recommendation. For fallback `ecutrho/ecutwfc` ratios, the ratio is applied after rounding `ecutwfc`.

### Bulk k-mesh parity

For 3D bulk systems, VQkit does **not** force every k-mesh component to be odd. A Gamma-centered zero-shift mesh such as `11 11 2 0 0 0` is valid and is preserved when it follows from the requested k-spacing. For 2D/1D systems, non-periodic directions remain fixed at `1`.

## Band-structure K-path

VQkit uses **spglib + SeeK-path** for symmetry-guided band paths.

If `N` points are requested between two high-symmetry endpoints, VQkit generates exactly `N` interior interpolated k-points plus the two endpoints.

## AIMD / trajectory analysis

Available workflows:

- trajectory summary
- atomic position versus time
- energy versus time
- lattice / volume versus time
- bond distance versus time
- mean-squared displacement
- diffusion coefficient
- radial distribution function
- coordination number versus time

## Phonon-derived descriptors

VQkit includes group velocity, Grüneisen, and Debye-temperature workflows.

For `gruneisen_band.dat`, acoustic branches are reported as:

- TA
- TA'
- LA

with:

```text
G_RMS = sqrt(mean(G(q)^2))
```

## Other analysis modules

VQkit also includes workflows for electronic structure, DOS/PDOS, band analysis, work function, Bader charge, energetics, batteries, catalysis, supercapacitors, vibrational analysis, elasticity, directional mechanical properties, and NEB analysis.

## Documentation

- `README.txt` — installation guide
- `START_HERE.txt` — quick start
- `RELEASE_NOTES.txt` — release history
- `CHANGELOG.md` — development history
- `documentation/` — feature-specific documentation

Current release: **VQkit 1.1**

## QE NEB endpoint workflow

For preprocessing option `[12] Generate NEB intermediate images` with Quantum ESPRESSO, VQkit asks for four current-directory files:

- `initial.cif` — optimized initial endpoint geometry
- `final.cif` — optimized final endpoint geometry
- `initial.in` — initial QE `pw.x` input/settings
- `final.in` — final QE `pw.x` input/settings

The CIF files are used as the authoritative endpoint coordinates, while the QE inputs provide species ordering, constraints and calculation settings. Atom count/order and cell compatibility are validated before interpolation. VQkit can then create separate image folders, a native `neb.x` input, or both.

## Smart Command Interface

VQkit 1.1 adds an offline Smart Command Interface. The numbered menus remain available, but users can jump directly to common workflows by typing requests such as:

```text
generate kpoints
convert cif to qe
freeze atoms
neb images
gruneisen
aimd
bader
```

The parser is deterministic and local: no internet connection, API key, or external AI service is required. Smart commands dispatch to the existing tested VQkit workflows rather than generating scientific inputs independently. At the main menu, choose `[4] Smart command`, or type a recognized command directly instead of a menu number.

## Global Smart Keyword navigation

Every menu prompt labeled `Enter your choice` accepts either its normal numeric option or a Smart Keyword. No separate Smart Command menu is required. Broad keywords show all matching workflows; for example `cif` and `convert` show the available conversion routes, while specific commands such as `generate kpoints` open the corresponding workflow directly. A keyword may be entered from a nested workflow to jump to another VQkit workflow without repeatedly selecting Back.

Examples: `cif`, `convert`, `kpoints`, `neb`, `phonon`, `aimd`, `bader`, `cutoff`.


## Windows PowerShell installation

On Windows, use `python` or the Windows Python launcher `py`. The command `python3` is not always registered on Windows.

First check which command is available:

```powershell
python --version
```

If that is not recognized, try:

```powershell
py --version
```

Create and activate a virtual environment with one of these forms:

```powershell
python -m venv vqkit_env
.\vqkit_env\Scripts\Activate.ps1
```

or:

```powershell
py -m venv vqkit_env
.\vqkit_env\Scripts\Activate.ps1
```

Then install VQkit:

```powershell
python -m pip install --upgrade pip setuptools wheel
python -m pip install --upgrade .\installable\vqkit-1.0-py3-none-any.whl
vqkit version
vqkit
```

Expected version:

```text
VQkit 1.1
```

