Common issues

A warning about unavailable parameters for electronegativity calculation is printed

The relaxation of hydrogen atoms requires partial charges for each atom. If they are not explicitly given via the Python API, they are automatically calculated using the PEOE method. However, this method requires element-specific parameters, which are only available for a limited set of elements. If these parameters are missing for an element the following warning is printed

Parameters required for computation of electronegativity aren't available
for the following atoms: <element>. Their electronegativity is given as NaN.

As consequence the formal charge is used for such atoms instead of a proper partial charge in the relaxation step. This warning has no effect on the hydrogen addition.

A group has an unexpected number of hydrogen atoms, e.g. a carboxy group is protonated

Probably, the formal charge for the concerning heavy atom is incorrect. If the formal charge of the oxygen atom of a carboxy group is set to 0, a protonated form is assumed.

The reason for incorrect charges is simply that the structure files contain improper charge values. For amino acids the charges can be corrected using the --charges/-c parameter from the Hydride command line interface, or via the estimate_amino_acid_charges() function from the Python API. For all other molecules, this problem can be solved by fixing the input structure file or by editing the charge attribute of the input AtomArray in the Python API.

A fragment is missing for a heavy atom and no hydrogen atom can be assigned to it

Although, most molecules are covered by the fragment library, some uncommon groups within a molecule may be not. If this happens, Hydride will give you a warning However, most of these exotic groups do not bear hydrogen atoms, so you can ignore the warning in those cases.

If an expected hydrogen atom is missing, you can add a template of such a molecule to the fragment library. This template is a molecular model of this molecule containing hydrogen atoms. Such a template structure file for a molecule can be e.g. downloaded from a ligand database. In the command line interface the template structure file is provided via the --fragments/-f parameter. Note that the MMTF, MOL and SDF formats are currently the only reasonable formats, since the bond information can be read exclusively from these formats. In the Python API the template can be added to the standard fragment library.

library = copy.deepcopy(hydride.FragmentLibrary.standard_library())
library.add_molecule(ligand)
structure_with_h, _ = hydride.add_hydrogen(structure, fragment_library=library)

Terminal hydrogen coordinates remain unchanged after relaxation

Note that the relaxation only rotates about bonds of terminal heavy atoms carrying hydrogen atoms.

If you are using the Python API a possible reason for this issue are undefined bond types (BondType.ANY) in the BondList of the input AtomArray. These appear, if the BondList was created using connect_via_distances().