VQkit 1.1.15 - INSTALLATION GUIDE
===========================================

This guide is for a new user after unzipping the VQkit package.

VQkit requires Python 3.9 or newer.
Recommended Python versions: 3.9 - 3.12

IMPORTANT
---------
The recommended installation method is direct installation from the
included wheel file.

Normal users do NOT need to use install.sh, verify.sh, or the bin/ folder.


============================================================
LINUX / macOS - FIRST INSTALLATION
============================================================

1. Open a terminal.

2. Go to the unzipped VQkit folder:

    cd VQkit_v1.15_Software_Package

3. Check Python:

    python3 --version

   Python 3.9 or newer is required.

4. Create a virtual environment:

    python3 -m venv vqkit_env

5. Activate the virtual environment:

    source vqkit_env/bin/activate

6. Confirm the environment:

    python --version
    which python

   The Python path should point inside vqkit_env/.

7. Upgrade pip and packaging tools:

    python -m pip install --upgrade pip setuptools wheel

8. Install VQkit from the included wheel:

    python -m pip install --upgrade installable/vqkit-1.15-py3-none-any.whl

9. Verify the installation:

    python -m pip show vqkit
    which vqkit
    vqkit version

   The version should be:

    1.15

10. Start VQkit:

    vqkit


============================================================
WINDOWS - FIRST INSTALLATION
============================================================

1. Open Command Prompt or PowerShell.

2. Go to the unzipped VQkit folder.

3. Check Python:

    py --version

   Python 3.9 or newer is required.

4. Create a virtual environment:

    py -m venv vqkit_env

5. Activate it.

   Command Prompt:

    vqkit_env\Scripts\activate

   PowerShell:

    .\vqkit_env\Scripts\Activate.ps1

6. Upgrade pip and packaging tools:

    python -m pip install --upgrade pip setuptools wheel

7. Install VQkit:

    python -m pip install --upgrade installable\vqkit-1.15-py3-none-any.whl

8. Verify:

    python -m pip show vqkit
    where vqkit
    vqkit version

9. Start:

    vqkit


============================================================
HPC / CLUSTER - FIRST INSTALLATION
============================================================

Some HPC systems use Python 2.7 as the default `python`.

1. Check available Python modules:

    module avail python

2. Load a Python 3.9 or newer module.

   Example:

    module load python/3.9.5

3. Check Python 3:

    python3 --version
    which python3

4. Create the virtual environment OUTSIDE the VQkit bin/ folder.

   Example:

    cd /scratch/your_account/your_work_directory
    python3 -m venv vqkit_env

5. Activate it:

    source vqkit_env/bin/activate

6. Confirm the active Python:

    python --version
    which python

   The Python version must be 3.9 or newer.

   The path should point inside:

    vqkit_env/bin/python

7. Upgrade pip and packaging tools:

    python -m pip install --upgrade pip setuptools wheel

8. Go to the unzipped VQkit package:

    cd /path/to/VQkit_v1.15_Software_Package

9. Install VQkit directly from the wheel:

    python -m pip install --upgrade installable/vqkit-1.15-py3-none-any.whl

10. Verify:

    python -m pip show vqkit
    which vqkit
    vqkit version

11. Start:

    vqkit


============================================================
IF `python3 -m venv` FAILS
============================================================

If you see:

    No module named venv

use virtualenv:

    python3 -m pip install --user virtualenv
    python3 -m virtualenv vqkit_env
    source vqkit_env/bin/activate

Then continue with:

    python -m pip install --upgrade pip setuptools wheel

and install VQkit from the included wheel.


============================================================
NEXT TIME YOU USE VQkit
============================================================

You do NOT need to reinstall VQkit.

Linux / macOS:

    source vqkit_env/bin/activate
    vqkit

HPC:

    module load python/3.9.5
    source /path/to/vqkit_env/bin/activate
    vqkit

Windows:

    vqkit_env\Scripts\activate
    vqkit


============================================================
UPGRADING VQkit
============================================================

1. Unzip the newer VQkit package.
2. Activate your existing virtual environment.
3. Go to the new package folder.
4. Install the newer wheel:

    python -m pip install --upgrade installable/vqkit-NEW_VERSION-py3-none-any.whl

5. Verify:

    python -m pip show vqkit
    vqkit version


============================================================
TROUBLESHOOTING
============================================================

If `vqkit` is not found:

    python -m pip show vqkit
    which vqkit

On Windows:

    where vqkit

If Python is older than 3.9:

    python3 --version

Load or install a newer Python version before creating the environment.

If a dependency such as Pillow fails to install:

    python --version
    python -m pip --version

Then upgrade the packaging tools:

    python -m pip install --upgrade pip setuptools wheel

and reinstall the VQkit wheel.


============================================================
PACKAGE CONTENTS
============================================================

installable/
    Installable VQkit wheel.

developer_source/
    Source package for developers.

documentation/
    Documentation and supporting information.

bin/
    Helper and fallback scripts. Normal users do not need this folder.

LICENSE
    GNU General Public License version 3 or later.


============================================================
QUICK INSTALL - LINUX / macOS
============================================================

    cd VQkit_v1.15_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.15-py3-none-any.whl
    vqkit version
    vqkit


============================================================
QUICK INSTALL - HPC
============================================================

    module load python/3.9.5
    python3 -m venv vqkit_env
    source vqkit_env/bin/activate
    python -m pip install --upgrade pip setuptools wheel
    cd /path/to/VQkit_v1.15_Software_Package
    python -m pip install --upgrade installable/vqkit-1.15-py3-none-any.whl
    vqkit version
    vqkit


============================================================
NORMAL START COMMAND
============================================================

After installation, start VQkit with:

    vqkit


BADER CHARGE ANALYSIS
=====================

VQkit includes a VASP Bader workflow. It can create CHGCAR_sum from
AECCAR0 + AECCAR2, run an external Bader executable, parse ACF.dat,
calculate net charges using POTCAR ZVAL values, and export CSV results.

The external `bader` executable is not bundled with VQkit and must be
installed separately and available in PATH.

Check the setup with:

    vqkit bader status .

See documentation/BADER_CHARGE.md for the complete workflow.
