Installation
============

This page explains how to install and set up SolvHybrid before running it.

Clone the repository:

.. code-block:: bash

   git clone https://gitlab.com/lch_interfaces/solvhybrid
   cd solvhybrid

Add SolvHybrid to your ``PATH`` (for example in ``.bashrc`` or ``.zshrc``):

.. code-block:: bash

   export PATH="$PATH:$HOME/solvhybrid/"

Python environment
------------------

To run the SolvHybrid workflow, you need Python **3.10+** and the dependencies
listed in ``environment.yml``.  
You can set up the environment using **venv**, **Miniforge**, **Conda**, or **Mamba**.

Example with Conda, using the provided ``environment.yml`` file:

.. code-block:: bash

   conda env create -f environment.yml
   conda activate SolvHybrid

External dependencies
---------------------

Once the environment is created and activated, you can run SolvHybrid locally
with **AmberTools** (without MPI).  
Note, however, that such runs may be slow depending on the system size.
In addition, some Amber modules (e.g. **MUSIC**) are not distributed with
AmberTools.  

For best performance, we recommend installing the full **Amber** package with
MPI support.

* **Amber** (``sander.MPI``) or **AmberTools** (``sander``, ``tleap``, ``cpptraj``)  

CM5 charges are computed by default using the Python implementation from the
``charges`` package.  
Alternatively, you can use the standalone ``cm5pac.exe`` program by specifying
its directory in the input file. The executable is typically ~10% faster than
the Python implementation.

* **cm5pac** (optional, for CM5 charge correction)  

To start a run you must also provide:

* The structures of the isolated molecule, the clean surface, and the adsorbed system  
* Corresponding charge files (Hirshfeld charges), usually extracted from
  **VASP** ``OUTCAR`` files (CP2K support is planned)

Therefore, you will need access to a **DFT engine**:

* **DFT engine** (VASP supported, CP2K experimental)  

.. note:: 
   For the structure, as it is read by ASE, you can use any format supported by ASE (e.g. POSCAR, CONTCAR, CIF, XYZ, etc.).
   But for charges, only VASP is supported at the moment.