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: Global, Surface, Bulk, and 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

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

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

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

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:

\[\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)}}\]