htmd.builder.ionize module#

htmd.builder.ionize.ionize(mol, netcharge, nwater, neutralize=True, saltconc=None, cation=None, anion=None, ff=None)#

Calculate the number of ions required to neutralize or salt a system.

Computes the anion and cation counts needed to neutralize the system’s net charge, and optionally adds extra ions to reach a target salt concentration. Ion stoichiometry is inferred from the ion charges (e.g. MgCl2 for Mg2+/Cl-).

Parameters:

  • mol (Molecule) – The molecular system (used to count existing ions when saltconc is set).

  • netcharge (float) – Net charge of the molecular system (e.g. from partial charges).

  • nwater (int) – Number of water molecules in the system (used to estimate box volume for salt concentration calculations).

  • neutralize (bool) – If True, return only the counts needed for neutralization. If saltconc is not None, this is automatically set to False.

  • saltconc (float | None) – Target salt concentration in molar. If given, additional ions are added on top of the neutralizing ions to reach this concentration.

  • cation (str | None) – Cation residue name. Accepts canonical keys ("NA", "K", "MG", "CA", "CS"), full names ("sodium"), AMBER names ("Na+"), or CHARMM names ("SOD"). If None, defaults to "NA".

  • anion (str | None) – Anion residue name. Accepts canonical keys ("CL"), full names ("chloride"), AMBER names ("Cl-"), or CHARMM names ("CLA"). If None, defaults to "CL".

  • ff (str | None) – Deprecated. No longer needed; pass standard ion names via cation / anion.

Returns:

When neutralize is True: (anion, cation, nanion, ncation). When saltconc is given: (anion, cation, anion, cation, nanion, ncation).

Return type:

tuple

Raises:

NameError – If the ion charges cannot neutralize the system, if no waters are found, or if the requested salt concentration is already exceeded.

htmd.builder.ionize.ionizePlace(solvent_mol, solute_mol, anion_resname, cation_resname, anion_name, cation_name, nanion, ncation, dfrom=5, dbetween=5, segname=None)#

Place a given number of negative and positive ions in the solvent.

Uses farthest point sampling to produce well-spaced ion positions and randomly assigns ion types for uniform spatial mixing. Replaces water molecules as long as they respect the given distance criteria.

Parameters:

  • solvent_mol (Molecule) – The solvent (water) molecule.

  • solute_mol (Molecule | None) – The solute molecule used for minimum-distance filtering. If None or empty, no minimum distance from solute is enforced.

  • anion_resname (str) – Resname of the added anions.

  • cation_resname (str) – Resname of the added cations.

  • anion_name (str) – Name of the added anions.

  • cation_name (str) – Name of the added cations.

  • nanion (int) – Number of anions to add.

  • ncation (int) – Number of cations to add.

  • dfrom (float) – Minimum distance of ions from solute molecule in Angstroms.

  • dbetween (float) – Minimum distance between ions in Angstroms.

  • segname (str | None) – Segment name to assign to the ions.

Returns:

mol – The solvent molecule with ions replacing some water molecules.

Return type:

Molecule

htmd.builder.ionize.ionizeSalts(resnames, netcharge, nwater, salts)#

Number of each ion to add to neutralize a system and reach several salt concentrations.

The first salt’s ions neutralize the system, as in ionize(). Every salt then adds the formula units for its concentration on top, like a single saltconc.

Parameters:

  • resnames (array) – Residue names of the system’s atoms, to count ions already present.

  • netcharge (float) – Net charge of the system.

  • nwater (int) – Number of water molecules, which sets the volume for the concentrations.

  • salts (list) – [(cation, anion, concentration), ...] with canonical ion names, as returned by resolveSalts().

Returns:

counts – Number of ions to add, keyed by canonical ion name.

Return type:

dict

htmd.builder.ionize.placeIons(solvent_mol, solute_mol, counts, dfrom=5, dbetween=5)#

Place ions of any number of types in the solvent, replacing waters.

Like ionizePlace(), but for the {ion: count} of ionizeSalts(). Each ion’s residue and atom name is its canonical name.

Parameters:

  • solvent_mol (Molecule) – The solvent (water) molecule.

  • solute_mol (Molecule | None) – The solute molecule used for minimum-distance filtering.

  • counts (dict) – Number of ions to add, keyed by canonical ion name.

  • dfrom (float) – Minimum distance of ions from solute molecule in Angstroms.

  • dbetween (float) – Minimum distance between ions in Angstroms.

Returns:

mol – The solvent molecule with ions replacing some water molecules.

Return type:

Molecule

htmd.builder.ionize.resolveSalts(salts=None, saltconc=0, cation=None, anion=None)#

Normalize the salts of a build into [(cation, anion, concentration), ...].

Builders take either a list of salts or the single-salt shorthand saltconc / saltcation / saltanion, not both.

Parameters:

  • salts (list | None) – [(formula, concentration), ...] with concentrations in molar, e.g. [("KCl", 0.15), ("MgCl2", 0.001)]. A formula pairs Na, K, Cs, Mg, Ca or Zn with Cl, F, Br or I (e.g. "NaBr", "CaI2"), in any case. The first salt also neutralizes the system.

  • saltconc (float | None) – Concentration (M) of the single salt, when salts is not given.

  • cation (str | None) – Cation of the single salt. Defaults to "NA". Deprecated in favour of salts.

  • anion (str | None) – Anion of the single salt. Defaults to "CL". Deprecated in favour of salts.

Returns:

salts – [(cation, anion, concentration), ...] with canonical ion keys.

Return type:

list