Installation

Requirements

VQkit requires:

  • Python 3.9 or newer

  • NumPy

  • SciPy

  • Matplotlib

  • spglib

  • SeeK-path

Additional Python packages may be required by specific workflows. These dependencies are normally installed automatically when VQkit is installed from the packaged wheel or source distribution.

VASP and Quantum ESPRESSO are external electronic-structure programs and are not distributed with VQkit. Users must install and configure those programs separately according to their respective licenses and computing environments.

Windows

Create a dedicated Python environment:

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

Upgrade pip:

python -m pip install --upgrade pip

Install the wheel:

python -m pip install vqkit-1.1-py3-none-any.whl

Start VQkit:

vqkit

If PowerShell prevents activation of the environment because of the execution policy, the environment can also be activated from Command Prompt:

vqkit_env\Scripts\activate.bat

Linux

Create and activate a virtual environment:

python3 -m venv vqkit_env
source vqkit_env/bin/activate

Upgrade pip:

python -m pip install --upgrade pip

Install the wheel:

python -m pip install vqkit-1.1-py3-none-any.whl

Start VQkit:

vqkit

Linux / HPC

On an HPC system, first load a supported Python module provided by the cluster.

For example:

module avail python
module load python/3.9.5

Verify that the expected Python interpreter is active:

which python
python --version

Create a user-space virtual environment:

python -m venv vqkit_env
source vqkit_env/bin/activate

Upgrade pip:

python -m pip install --upgrade pip

Install VQkit from the wheel:

python -m pip install vqkit-1.1-py3-none-any.whl

Start VQkit:

vqkit

The exact module name may differ between HPC systems. Use the Python version provided by the local computing center when possible.

Verify installation

To verify the installed version:

vqkit version

Expected output for the current release:

VQkit 1.1

You can also verify that the command is available by starting VQkit:

vqkit

A successful installation should open the main VQkit command-line interface.

Install from source

Users who have the VQkit source distribution can install directly from the project directory.

Change to the directory containing pyproject.toml and run:

python -m pip install .

For a clean reinstall:

python -m pip install --force-reinstall .

Development installation

For development, use editable mode so that source-code changes are immediately available without reinstalling the package after every modification.

From the VQkit source directory:

python -m pip install -e .

After installation:

vqkit

Updating VQkit

When a newer VQkit wheel is available, activate the same Python environment and install the newer wheel with:

python -m pip install --upgrade vqkit-X.Y-py3-none-any.whl

Replace X.Y with the release version being installed.

Uninstalling VQkit

VQkit can be removed from the active Python environment with:

python -m pip uninstall vqkit

Troubleshooting

Command not found

If the vqkit command is not recognized, verify that the intended Python environment is active.

Windows:

where python
where vqkit

Linux / HPC:

which python
which vqkit

Python version

Verify that Python 3.9 or newer is being used:

python --version

Package information

Check the installed VQkit package with:

python -m pip show vqkit

Reinstall if necessary

If the package installation is incomplete or corrupted:

python -m pip install --force-reinstall vqkit-1.1-py3-none-any.whl