schrodinger.application.ligprep.ionizer module

Ionizer module. Ported from on February 2014.

Copyright (c) Schrodinger, LLC. All rights reserved.


Return a string representation of the charge. “-” will be prepended for negative numbers, “+” for positive, and nothing for zero.


Return a list of atom numbers of all Hydrogens bonded to given atom.


Add the given path to the mmfile search path. This makes it possible to search for the mmfrag.ini file in custom locations.


For a given pKa - pH difference X, this function calculates and returns RT.ln(10^X + 1) and RT.ln(10^(-X) + 1)

exception schrodinger.application.ligprep.ionizer.TolerableError

Bases: Exception

Raised when the structure could not be processed due to a non-fatal error.

__init__(*args, **kwargs)

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception schrodinger.application.ligprep.ionizer.TooManyGroupsError

Bases: Exception

Raised when the structure could not be processed because it has too many ionizable groups.

__init__(*args, **kwargs)

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class schrodinger.application.ligprep.ionizer.Fragment(st, connect_to, chargef)

Bases: object

Class representing a fragment from the ionizer library.

__init__(st, connect_to, chargef)
class schrodinger.application.ligprep.ionizer.Spec(cmd, linenum, mmsubs_pattern, mmsubs_handle)

Bases: object

This class represents a specification line in the ionizer data file.

__init__(cmd, linenum, mmsubs_pattern, mmsubs_handle)

Run a substracture search for this pattern in the specified structure.

Return type

list of int lists.


A list of matches, where each list is a list of atom indices.

class schrodinger.application.ligprep.ionizer.Ionizer(loglevel=0, specfile=None, ph=None, ph_thresh=None, pk_thresh=None)

Bases: object

Class for ionizing structures (part of LigPrep).

To ionize a structure, do:

i = Ionizer() out_sts = i.ionizeStructure(st)

These options can be adjusted after instantiating the class:

  • max_ions – Maximum number of ionizations.

  • max_abstotq – Maximum absolute value of total charge.

  • max_groups – Maximum ionizational groups to handle (up to MAX_GROUPS_MAX).

  • max_outcts – Maximum output CTs per input CT.

  • retain – Whether to retain the input structure in the output.

  • retain_lab – Retain the input structure that has “i_lp_orig_ion_str” property set.

  • show_match_atoms – Whether to report substructure pattern matches to the logger (log file).

  • show_skips – Whether to show skipped state generations. Applies only to log levels 1 and up.

  • keep_props – Whether to keep any structure-based properties from the input CT in the output CTs.

  • retitle_with – Prefix for adding ion state numbers to output CT titles.

  • logger – Logger instance. When processing CTs, any info, warning, and error messages will be redirected here.

  • show_final_list – Report final ionization candidate list to logger.

__init__(loglevel=0, specfile=None, ph=None, ph_thresh=None, pk_thresh=None)
  • logleve – Reporting log level. Use 0 for quietest (default); use 1 to log state generations; use 2 to log ion frag fusions also.

  • specfile (str or None) – Path to the non-standard patterns spec file to use.

  • ph (float or None) – Effective pH of active site. Does not apply to pK-only mode.

  • ph_thresh (float or None) – De-protonated |pKa-pH| difference limit. Does not apply to pK-only mode.

  • pk_thresh (float or None) – Strong/weak pK threshold (no default). Overrides pH-based rejection mode and activates pK-only mode. Reject on pKa values only (no pH).


Initialize the mmlibs libraries.


Read the ionized frag library and populate self.frags dictionary.

The ionized frag lib contains a fairly small number of fragments, all or most of which will be fused in a typical run; therefore we just collect information on all of them now.


Put cwd and $HOME/.schrodinger/mmshare at the front of the mmfile search path, to allow user “ionizer.ini” in either of those dirs to override installed data file in the mmshare data dir.

Note: We wait as late as possible to do this, to prevent any similar override of the mmfrag data files, which we currently consider to be inviolate, that is, the user must not be allowed to override them, even accidentally.

ionizeCommandParser(linenum, cmd, subs_patt, frag_name, pka)

Validate mmsubs pattern spec; if all goes well, will store compiled pattern matcher below

Parses both Acid and Base specs.

  • linenum (int) – Line number that is being parsed

  • cmd (str) – Spec command that is being parsed. Either “acid” or “base”.

  • subs_patt (str) – Substructure pattern for this specification.

  • frag_name (str) – Name of the fragment to use (from the “ionized” fragment library).

  • pka (str) – String representation of the pKa for this ionizable group.

Return type



The Spec instance representing this ionizable group.

excludeCommandParser(linenum, subs_patt)

Validate an “exclude” mmsubs pattern spec.

  • linenum (int) – Line number that is being parsed

  • subs_patt (str) – Substructure pattern for this specification.


Check CT for matches to Acid/Base/Exclude patterns, in same order as supplied in control spec file; for non-Excluded, final Acid/Base matches, store specs in hash indexed on ion center atom number; also get ordered list of candidate atom numbers.

generateStateCT(st, total_charge, state_num, state_fuse_atoms, ion_candidates, ycost_total, zcost_total)

Generate the CT for the specificed ionization state.

  • st (structure.Structure) – Input structure.

  • total_charge (int) – Total charge of this ionization state.

  • state_num (int) – The number of this state (0-indexed)

  • state_fuse_atoms (list of ints) – List of atoms to which the new fragment will be attached to.

  • ion_candidates (dict; key: atom index; value: Spec) – Specifications for this state change.

  • ycost_total (float) – Charging ionization penalty for this state

  • zcost_total (float) – Neutral ionization penalty for this state

fuseIonFragment(output_st, fuse_atom_orig, pre_fuse_center, renumbered_fuse_atoms, cand)

This function coordinates the ionization of one ionizable group, via mmbuild_fuse() of the appropriate ionizing fragment onto the group’s ionization center atom (same method as Maestro builder uses for Place onto non-terminal atom); function also takes care of various property adjustments in the modified CT.

saveIonCenterProps(st, center_anum)

Save certain properties of an ion center atom before the ionizing fuse.

restoreIonCenterProps(st, iatom)

Restores the atom properties saved by the method above. Also sets the default display color property based on the atom’s new (i.e., post-fuse) atom type. Pass in post-fuse atom number (new ionized group center or bonded H).

reviseIonizedGroup(st, center_atom)

Function to apply above reset function to all atoms of newly ionized group. Pass in post-fuse ionized group center atom number Collect list of newly ionized group’s atoms (new ionized center + all Hydrogens bonded to it); revise certain atom properties to match original ion center

addIonProperties(st, state_num, total_charge, center_atoms_string, center_types_string, center_atoms_orig_string)

This function writes CT-level properties recording several details of a particular ionization state; it’s intended to be used on CTs generated for output; the values expressed in the properties must be calculated beforehand; all of these properties get marked as dependent on CONNECTIVITY.

addCostProperties(st, ycost_total, zcost_total)

For use in pH mode only, this function adds CT-level properties recording the free energy costs associated with this particular ionization state.


This is the public interface method. The specified CT will be ionized, and the output structures will be returned as a list.


st (structure.Structure object) – Structure to ionize.

Return type

List of structures.


Returns a list of ionized output structures.