Installing Qbics
===================

.. contents::
   :local:

General Considerations
----------------------------

After compiling or downloading Qbics, you can find the following files:

.. code-block:: bash

    qbics
    |------ basis    
    |------ pseudopotential    
    |------ xtbparams
    |------ tools
    |------ qbics-linux-cpu

These files are:

- ``basis`` Basis set files. Qbics will automatically use basis sets in this directory.
- ``pseudopotential`` Pseudopotential files. Qbics will automatically use pseudopentials in this directory.
- ``xtbparams`` xTB parameter files. Usually they are not used directly, since parameters are stored inside Qbics executable.
- ``tools`` Some tools for computations.
- ``qbics-linux-cpu`` The Qbics executable. On other operating systems, it may be called ``qbics-mac-cpu`` or ``qbics-win-cpu``, etc.

All available versions of Qbics are:

.. list-table::
   :widths: 2 10
   :header-rows: 1
   
   * - Name
     - Version
   * - ``qbics-linux-cpu``
     - CPU version on Linux (OpenMP parallelized)
   * - ``qbics-linux-gpu``
     - GPU version on Linux (OpenMP parallelized)
   * - ``qbics-linux-cpu-mpi``
     - MPI parallelized CPU version on Linux (OpenMP parallelized)
   * - ``qbics-mac-cpu``
     - CPU version on macOS (OpenMP parallelized)
   * - ``qbics-win-cpu``
     - CPU version on Windows (OpenMP parallelized)

You can run Qbics by using absolute path. On Windows, assume you put ``qbics`` in ``D:\software``, then:

.. code-block:: bash

    $ D:\software\qbics\qbics-win-cpu water.inp > water.out

On Linux or macOS, assume you put ``qbics`` in ``/home/zhang``, then:

.. code-block:: bash

    $ /home/zhang/qbics/qbics-linux-cpu water.inp > water.out

Of course, you can also put ``D:\software\qbics`` or ``/opt/qbics`` to ``PATH`` variable so you need not to type absolute path, but this is not mandated.

You do **NOT** need to set other environment variables, since Qbics can automatically detect it absolute path and use this to locate paths like ``basis`` or ``pseudopotential``.

GPU Version
----------------------------

The GPU version of Qbics is designed to run on NVIDIA GPUs with CUDA support. To use the GPU version, ensure that you have the appropriate NVIDIA drivers and CUDA toolkit for your hardware installed on your system for your.

MPI Version
----------------------------

The MPI version of Qbics is designed to run on multi-node clusters. Ensure that you have an MPI implementation (like OpenMPI or MPICH) installed on your system. Such MPI implementation must be **the same version** as the one used to compile Qbics.