.. _InstalltionGuide:

SPARC Installation Guide
========================

This guide provides step-by-step instructions to set up SPARC and its
core dependencies.


Core Software Dependencies
--------------------------

* Python 3.10 (recommended)
* `DeepMD-kit v3+ <dpmd_install_>`_
* `ASE <ase_>`_ — Atomic Simulation Environment
* At least one DFT engine (`VASP <vasp_>`_, `CP2K <cp2k_>`_, `ORCA <orca_>`_, `Quantum ESPRESSO <qe_>`_, `xTB <xtb_>`_, or `Gaussian <gaussian_>`_)
* `PLUMED <plumed_>`_ — optional, for enhanced sampling

Python Package Dependencies
----------------------------

* numpy, pandas, dpdata, scipy

Step-by-Step Installation
-------------------------

1. Create and activate a conda environment:

   .. code-block:: bash

      conda create -n sparc python=3.10
      conda activate sparc

2. Install `DeepMD-kit v3 <dpmd_install_>`_:

   .. code-block:: bash

      pip install deepmd-kit

   Refer to the `DeepMD-kit installation guide <dpmd_install_>`_ for GPU-enabled
   or backend-specific (PyTorch / TensorFlow) installation options.

3. Clone and install SPARC:

   .. code-block:: bash

      git clone https://github.com/rahulumrao/sparc.git
      cd sparc
      pip install .

.. _InstallPlumed:

4. Install PLUMED (optional):

   For standard CVs, install directly from conda-forge:

   .. code-block:: bash

      conda install -c conda-forge py-plumed

   .. note::

      Some Collective Variables (e.g., ``SPRINT``) require the additional
      module and are not included in the standard PLUMED build. To enable
      them, build from source:

      .. code-block:: bash

         ./configure --enable-mpi=no --enable-modules=all \
             PYTHON_BIN=$(which python) --prefix=$CONDA_PREFIX

         make -j$(nproc) && make install

      To verify PLUMED installation:

      .. code-block:: python

         >>> from ase.calculators import plumed
         >>> from plumed import Plumed

5. Install xTB (optional):

   .. code-block:: bash

      conda install -c conda-forge xtb-python


DFT Engine Requirements
-----------------------

SPARC supports the following DFT engines. Only install what you need:

.. list-table::
   :header-rows: 1
   :widths: 15 20 65

   * - Engine
     - Use case
     - Notes
   * - `VASP <vasp_>`_
     - Periodic solids
     - License required; set ``VASP_PP_PATH`` env variable
   * - `CP2K <cp2k_>`_
     - Periodic solids / molecules
     - Free; ASE CP2K interface included
   * - `ORCA <orca_>`_
     - Molecules
     - Free for academia; set ``exe_command`` in ``input.yaml``
   * - `Quantum ESPRESSO <qe_>`_
     - Periodic solids
     - Free; set ``exe_command``
   * - `xTB <xtb_>`_
     - Semi-empirical (fast)
     - ``conda install -c conda-forge xtb-python``
   * - `Gaussian <gaussian_>`_
     - Molecules
     - License required


Environment Setup
-----------------

For VASP, set the POTCAR files path:

.. code-block:: bash

   export VASP_PP_PATH=/path/to/vasp/potcar_files

If PLUMED was installed from source (not conda-forge):

.. code-block:: bash

   export PLUMED_KERNEL="$CONDA_PREFIX/lib/libplumedKernel.so"
   export PYTHONPATH="$CONDA_PREFIX/lib/plumed/python:$PYTHONPATH"


Verification
------------

.. code-block:: bash

   sparc -h

Expected output:

.. code-block:: text

   sparc [-h] [-i INPUT_FILE]

   options:
     -h, --help            show this help message and exit
     -i INPUT_FILE, --input_file INPUT_FILE
                           Input YAML file


.. important::

   The ``pip install tensorflow[and-cuda]`` installation may not always detect
   the GPU due to potential configuration issues. To verify whether TensorFlow
   has successfully recognized the GPU, run:

   .. code-block:: bash

      python -c "import tensorflow as tf; print(tf.config.list_physical_devices('GPU'))"

   If the output is an empty list, check:

   - Your NVIDIA driver and CUDA toolkit installation
   - The CUDA version compatibility with TensorFlow
   - That environment variables (e.g., ``LD_LIBRARY_PATH``) are correctly set

   Refer to the `TensorFlow GPU troubleshooting guide <tf_>`_ for details.


.. _dpmd_install: https://docs.deepmodeling.com/projects/deepmd/en/stable/getting-started/install.html
.. _plumed: https://www.plumed.org/download
.. _ase: https://wiki.fysik.dtu.dk/ase/
.. _tf: https://www.tensorflow.org/install/pip
.. _vasp: https://www.vasp.at/
.. _cp2k: https://www.cp2k.org/
.. _orca: https://orcaforum.kofo.mpg.de/
.. _qe: https://www.quantum-espresso.org/
.. _xtb: https://xtb-docs.readthedocs.io/
.. _gaussian: https://gaussian.com/