Input file reference manual
===========================

SolvHybrid execution is controlled by editing a single input file (e.g.
``solv_input.inp``). In this file, all **mandatory** and **optional**
parameters are specified using a ``keyword = value`` pair.

Keywords are grouped into the following sections: :ref:`global`, :ref:`surface`,
:ref:`bulk`, and :ref:`forcefield`.

Keywords are classified as:

* *mandatory* – must always be provided (e.g. **run_type**)
* *keyword-dependent* – mandatory depending on another keyword
* *optional* – get a default value if not provided (e.g. **lambda_windows**)

For some keywords, more than one value is possible. Values can be separated by
whitespace (``" "``), comma (``","``) or semicolon (``";"``). Certain values must be
given in groups (e.g. vectors of a cell matrix), which are enclosed using
parenthesis-like characters: ``()`` or ``[]`` or ``{}``. Example:
``(a1 a2 a3) [b1 b2 b3] {c1; c2; c3}``.

.. _global:

Global
^^^^^^
Parameters in this section affect the entire SolvHybrid execution.

| **project_name** (*mandatory*): Root name of the project.
| Accepted values: Any non-empty string.

| **run_type** (*mandatory*): Which workflows to run.
| Accepted values: ``surface``, ``bulk`` (one or both can be provided, e.g. ``surface bulk``).

| **code** (*mandatory*): MD engine to use, for the moment only ``amber`` is supported.
| Accepted values: ``amber`` (current option).

| **batch_q_sys** (*optional*): Queueing system for job submission. If ``False``, it does a dry run.
| Accepted values: ``slurm``, ``local`` or ``False``.
| Default value: ``local``.

| **subm_script** (*optional*): Full submission script template.  
| If provided, it will be used as-is for job submission.  

| **subm_header** (*optional*): Header file prepended to auto-generated submission scripts.  
| Useful for including scheduler directives (e.g., ``#SBATCH``, ``#PBS``).  

.. note::  
   You may provide either ``subm_script`` or ``subm_header``:  
   - Use ``subm_script`` if you want SolvHybrid to use your custom script exactly as given.  
   - Use ``subm_header`` if you only need to prepend standard scheduler options and let SolvHybrid generate the rest of the script.  
   If neither is given, a minimal default script will be generated for ``batch_q_sys = local`` or ``batch_q_sys = slurm`` runs.

| **cm5pac_dir** (*optional*): Directory containing ``cm5pac.exe`` (legacy CM5 tool).
| Accepted values: Directory path that contains ``cm5pac.exe``.

.. note::  
   If ``cm5pac_dir`` is provided it will not use the Python implementation of CM5 charges.

| **dry** (*optional*): If ``true``, prepare directories and inputs but do not run calculations.
| Accepted values: ``true``/``false``.
| Default value: ``true``.

| **special_atoms** (*optional*): Map non-standard labels to base elements for masses/radii.
| Accepted values: Groups like ``(H1 H) (H2 H) (Fe1 Fe)`` or ``False``.
| Default value: ``False``.

| **soft** (*optional*): Enable GALsoft/GALunsoft soft stages. If ``soft = false``, the TI_surface will only include 3 TI phases (decharge, vdw_bonded, recharge).
| Accepted values: ``true``/``false``.
| Default value: ``true``.

.. _surface:

Surface
^^^^^^^
Parameters for the **TI_surface** workflow (adsorbate-on-surface → surface).

| **slab_coord_file** (*mandatory*): Slab structure (ASE-compatible, e.g. POSCAR/CONTCAR).
| Accepted values: Existing file path.

| **ads_coord_file** (*mandatory*): Adsorbate-on-surface structure (ASE-compatible).
| Accepted values: Existing file path.

| **slab_charge_file** (*mandatory*): VASP ``OUTCAR`` with Hirshfeld charges for the slab.
| Accepted values: Existing file path.

| **ads_charge_file** (*mandatory*): VASP ``OUTCAR`` with Hirshfeld charges for the adsorbed system.
| Accepted values: Existing file path.

| **scale_factor** (*optional*): Replication factor applied in x/y to build a supercell.
| Accepted values: Positive integer.
| Default value: 3.

| **box_size** (*optional*): Thickness of water layer (Å) used during solvation.
| Accepted values: Positive float.
| Default value: 30.0

| **pbc_cell** (*optional*): Periodic boundary cell matrix.
| Accepted values: ``(a1 a2 a3) (b1 b2 b3) (c1 c2 c3)`` or ``False``.
| Default value: ``False`` (auto-detected from ``slab_coord_file`` if available).

| **lambda_windows** (*optional*): Number of λ-windows for TI_surface.
| Accepted values: Positive integer.
| Default value: 11.

| **sp_mm** (*optional*): Run MM single-point energy for the surface/adsorbate systems in vacuum.
| Accepted values: ``true``/``false``.
| Default value: ``false``.

.. _bulk:

Bulk
^^^^
Parameters for the **TI_bulk** workflow (molecule-in-water → pure solvent).

| **mol_coord_file** (*mandatory*): Isolated molecule structure (ASE-compatible).
| Accepted values: Existing file path.

| **mol_charge_file** (*mandatory*): VASP ``OUTCAR`` with Hirshfeld charges for the molecule.
| Accepted values: Existing file path.

| **bulk_solvation_thickness** (*mandatory*): Water padding (Å) around the molecule.
| Accepted values: Positive float.

| **lambda_windows_bulk** (*optional*): Number of λ-windows for TI_bulk.
| Accepted values: Positive integer.
| Default value: 11.

| **sp_mm_bulk** (*optional*): Run MM single-point energy for the isolated molecule in vacuum.
| Accepted values: ``true``/``false``.
| Default value: ``false``.

.. _forcefield:

ForceField
^^^^^^^^^^
Parameters defining the Amber force field setup. Paths are resolved under the package
``modules/`` unless noted.

| **leaprc** (*optional*): Leaprc file for ``tleap``.  
| Default value: ``leaprc.uff`` (under ``modules/``).

| **params** (*optional*): Additional parameter files (comma-separated).  
| Default value: ``Lib/uff.dat, Lib/music.dat`` (under ``modules/``).

| **libs** (*optional*): Additional library files (comma-separated).  
| Default value: ``Lib/uff.lib`` (under ``modules/``).

| **water_model** (*optional*): Water model token for ``tleap`` (OFF file will be used).  
| Accepted values: e.g. ``TIP3PBOX``, ``TIP4PEWBOX``, ``OPC``.  
| Default value: ``TIP3PBOX``.

| **water_off** (*optional*): OFF library path or ``auto`` to resolve via ``$AMBERHOME``.  
| Default value: ``auto``.

| **amberhome_only** (*optional*): If ``true``, force OFF libraries to be loaded from ``$AMBERHOME``.  
| Accepted values: ``true``/``false``.  
| Default value: ``true``.

| **leaprc_soft**, **params_soft** (*optional*): Additional force field assets used for GALsoft stages.  
| These are only loaded when **soft = true** in the [Global] section *and* both files exist.  
| Default value: none (soft assets disabled unless explicitly set).

.. note::  
   If ``soft = true`` but ``leaprc_soft`` or ``params_soft`` are missing, SolvHybrid automatically disables the soft stages and falls back to the standard force field setup.

.. note::  
  * If **pbc_cell** is ``False``, SolvHybrid attempts to auto-detect it from the slab structure when possible.
  * DFT single-point adsorption energies are read from ``Input/OUTCAR_*`` (VASP) or recognized CP2K logs; TI energies are parsed from Amber outputs.
  * The final adsorption free energy in solution is computed as::

.. math::

   \Delta G_{\mathrm{ads}}^{\mathrm{solv}}
   \;=\;
   E_{\mathrm{ads}}^{\mathrm{DFT(vac)}} \;-\;
   E_{\mathrm{ads}}^{\mathrm{MM(vac)}} \;+\;
   \Delta G_{\mathrm{bulk\,(TI2)}} \;-\;
   \Delta G_{\mathrm{surface\,(TI1)}}