htpolynet package

htpolynet

htpolynet.analysis

Handles the analyze subcommand.

Author: Cameron F. Abrams <cfa22@drexel.edu>

class htpolynet.analysis.analyze.Analyze(indict, strict=True)

Bases: object

allowed_keys = ['gromacs', 'command', 'subdir', 'options', 'links', 'outfile', 'console-input', 'matchlines']

default_params = {'gromacs': {'gmx': 'gmx'}}

do(**gromacs_dict)

Handles executing the analysis.

parse_console_output()

required_keys = ['command', 'subdir']

class htpolynet.analysis.analyze.AnalyzeConfiguration

Bases: object

handles reading and parsing an analysis input config file. Config file format

• { key1: {<paramdict>}}

• { key2: {<paramdict>}}

…

The config file is a list of single-element dictionaries, whose single keyword indicates the type of analysis to be run; analyses are run in the order they appear in the config file.

default_class

alias of Analyze

parse(**kwargs)

Parses a PostsimConfiguration file to build the list of stages to run.

predefined_classes = {'density': <class 'htpolynet.analysis.analyze.AnalyzeDensity'>, 'freevolume': <class 'htpolynet.analysis.analyze.AnalyzeFFV'>}

classmethod read(filename, parse=True, **kwargs)

Generates a new PostsimConfiguration object by reading in the JSON or YAML file indicated by filename.

Parameters:

• filename (str) – name of file from which to read new PostsimConfiguration object

• parse (bool) – if True, parse the input configuration file, defaults to True

Raises:

Exception – if extension of filename is not ‘.json’ or ‘.yaml’ or ‘.yml’

Returns:

a new PostsimConfiguration object

Return type:

PostsimConfiguration

class htpolynet.analysis.analyze.AnalyzeDensity(indict, strict=True)

Bases: Analyze

Analyze class for handling trajectory density profile calculation

default_params = {'command': 'density', 'console-input': ['0'], 'gromacs': {'gmx': 'gmx'}, 'links': ['postsim/equilibrate/equilibrate.tpr', 'postsim/equilibrate/equilibrate.trr'], 'options': {'b': 0, 'd': 'Z', 'f': 'equilibrate.trr', 'o': 'density.xvg', 's': 'equilibrate.tpr', 'sl': 50, 'xvg': 'none'}, 'subdir': 'analyze/density'}

class htpolynet.analysis.analyze.AnalyzeFFV(indict, strict=True)

Bases: Analyze

default_params = {'command': 'freevolume', 'gromacs': {'gmx': 'gmx'}, 'links': ['postsim/equilibrate/equilibrate.tpr', 'postsim/equilibrate/equilibrate.trr'], 'matchlines': ['Free volume', 'Total volume', 'Number of molecules', 'Average molar mass', 'Density', 'Molecular volume Vm assuming homogeneity:', 'Molecular van der Waals volume assuming homogeneity:', 'Fractional free volume'], 'options': {'b': 0.0, 'f': 'equilibrate.trr', 'o': 'ffv.xvg', 's': 'equilibrate.tpr', 'xvg': 'none'}, 'outfile': 'ffv.dat', 'subdir': 'analyze/freevolume'}

htpolynet.analysis.analyze.analyze(args)

Handles the analyze subcommand for managing gromacs-based trajectory analyses.

Parameters:

args (argparse.Namespace) – command-line arguments

Provides plotting functionality.

Author: Cameron F. Abrams <cfa22@drexel.edu>

htpolynet.analysis.plot.build_plots(args)

htpolynet.analysis.plot.diag_plots(args)

htpolynet.analysis.plot.diagnostics_graphs(logfiles, filename, **kwargs)

Extracts selected data from the diagnostic output and generates plots.

Parameters:

• logfiles (list) – list of names of diagnostic log files to treat in parallel

• filename (str) – name of output image file

htpolynet.analysis.plot.do_E_plots(phases, projdirs, outfile='e.png', fit_domain=[10, 200], save_data='E.csv')

htpolynet.analysis.plot.do_tg_plots(phases, projdirs, outfile='tg.png', save_data='data.csv', n_points=[10, 20])

htpolynet.analysis.plot.global_trace(df, names, outfile='plot.png', transition_times=[], markers=[], interval_labels=[], y2names=[], **kwargs)

Generates custom-formatted multiplots of energy-like quantities named in ‘names’ in the input dataframe df.

Parameters:

• df (pd.DataFrame) – pandas dataframe containing all data

• names (list) – list of quantity names (Density, Temperature, etc)

• outfile (str) – name of output image file, defaults to ‘plot.png’

• transition_times (list) – time values at which vertical lines are drawn, defaults to []

• markers (list) – time values at which transitions are marked, defaults to []

• interval_labels (list) – list of labels of intervals defined by markers, defaults to []

• y2names (list) – names of quantities to be plotted on a secondary y axis, defaults to []

htpolynet.analysis.plot.init_molecule_graph(proj_dir)

Creates and initializes an inter-molecular graph to show network connectivity.

Parameters:

proj_dir (str) – name of project directory

Returns:

a nodes-only Graph enumerating all molecules; this will be further processed elsewhere to add connectivity information

Return type:

networkx.Graph

htpolynet.analysis.plot.multi_trace(dfL, xnames, ynames, labels=[], xlabel='time [ps]', ylabel='', outfile='plot.png', **kwargs)

Generates a plot of each y vs x in df.

Parameters:

• dfL (list of pandas.DataFrame) – list of dataframes, one per trace

• xnames (list) – list of x-column names

• ynames (list) – list of y-column names, parallel to xnames

• outfile (str) – name of output image file, defaults to ‘plot.png’

htpolynet.analysis.plot.network_graph(G, filename, **kwargs)

Draws a custom formatted network plot from graph G.

Parameters:

• G (nx.Graph or nx.DiGraph) – a graph from networkx

• filename (str) – name of output image filename

htpolynet.analysis.plot.plots(args)

Handles the plots subcommand.

Parameters:

args (argparse.Namespace) – command-line arguments

htpolynet.analysis.plot.post_plots(args)

htpolynet.analysis.plot.scatter(df, xcolumn, columns=[], outfile='plot.png', **kwargs)

Generic scatter plot generator.

Parameters:

• df (pd.DataFrame) – dataframe containing data

• xcolumn (str) – name of column holding x-data

• columns (list) – list of y-value columns to be plotted vs. x, defaults to []

• outfile (str) – name of output image file, defaults to ‘plot.png’

htpolynet.analysis.plot.trace(qty, edrs, outfile='plot.png', **kwargs)

Generates a plot of the energy-like quantity named by ‘qty’ vs time by reading data from the list of edr files named in ‘edrs’.

Parameters:

• qty (str) – name of energy-like quantity; must conform to menu generated by ‘gmx energy’

• edrs (list) – list of names of edr files to scan, in order

• outfile (str) – name of output image file, defaults to ‘plot.png’

Returns:

the list of average values

Return type:

list

Handles the postsim subcommand.

Author: Cameron F. Abrams <cfa22@drexel.edu>

class htpolynet.analysis.postsim.PostSimAnneal(indict, strict=True)

Bases: PostSimMD

a class to handle temperature annealing MD simulation

build_mdp(mdpname, **kwargs)

Builds the GROMACS mdp file required for an annealing MD simulation.

Parameters:

mdpname (str) – name of mdp file

default_params = {'P': 1, 'T0': 300, 'T0_ps': 1000, 'T0_to_T1_ps': 1000, 'T1': 600, 'T1_ps': 1000, 'T1_to_T0_ps': 1000, 'gromacs': {'gmx': 'gmx', 'mdrun': 'gmx mdrun', 'mdrun_single_molecule': 'gmx mdrun', 'options': '-quiet -nobackup'}, 'input_gro': 'systems/final-results/final.gro', 'input_grx': 'systems/final-results/final.grx', 'input_top': 'systems/final-results/final.top', 'ncycles': 1, 'output_deffnm': 'anneal', 'scatter': ('time(ps)', ['Density'], 'rho_v_ns.png'), 'subdir': 'postsim/anneal', 'traces': ['Temperature', 'Density', 'Volume']}

class htpolynet.analysis.postsim.PostSimDeform(indict, strict=True)

Bases: PostSimMD

a class to handle a uniaxial deformation MD simulation

build_mdp(mdpname, **kwargs)

Builds the GROMACS mdp file required for a uniaxial deformation MD simulation.

Parameters:

mdpname (str) – name of mdp file

default_params = {'P': 1.0, 'T': 300.0, 'direction': 'x', 'edot': 0.001, 'gromacs': {'gmx': 'gmx', 'mdrun': 'gmx mdrun', 'mdrun_single_molecule': 'gmx mdrun mdrun', 'options': '-quiet -nobackup'}, 'input_gro': 'postsim/equilibrate/equilibrate.gro', 'input_grx': 'systems/final-results/final.grx', 'input_top': 'systems/final-results/final.top', 'output_deffnm': 'deform-x', 'ps': 1000, 'scatter': ('Box-X', ['Pres-XX'], 'tension_v_xlength.png'), 'subdir': 'postsim/deform-x', 'traces': ['Box-X', 'Pres-XX']}

class htpolynet.analysis.postsim.PostSimLadder(indict, strict=True)

Bases: PostSimMD

a class to handle a temperature-ladder MD simulation

build_mdp(mdpname, **kwargs)

Builds the GROMACS mdp file required for a temperature-ladder MD simulation.

Parameters:

mdpname (str) – name of mdp file

default_params = {'P': 1, 'Thi': 600.0, 'Tlo': 300.0, 'deltaT': 5, 'gromacs': {'gmx': 'gmx', 'mdrun': 'gmx mdrun', 'mdrun_single_molecule': 'gmx mdrun mdrun', 'options': '-quiet -nobackup'}, 'input_gro': 'systems/final-results/final.gro', 'input_grx': 'systems/final-results/final.grx', 'input_top': 'systems/final-results/final.top', 'output_deffnm': 'ladder', 'ps_per_rise': 1000, 'ps_per_run': 1000, 'scatter': ('time(ps)', ['Density'], 'rho_v_ns.png'), 'subdir': 'postsim/ladder', 'traces': ['Temperature', 'Density', 'Volume'], 'warmup_ps': 5000}

class htpolynet.analysis.postsim.PostSimMD(indict, strict=True)

Bases: object

Generic class for handling post-cure md simulations; this one just does simple NPT MD equilibration; Classes that inherit from this class should define their own default_params and build_npt

build_mdp(mdpname, **kwargs)

Builds the GROMACS mdp file required for an NPT equilibration.

Parameters:

mdpname (str) – name of mdp file

default_params = {'P': 1, 'T': 300, 'gromacs': {'gmx': 'gmx', 'mdrun': 'gmx mdrun', 'mdrun_single_molecule': 'gmx mdrun mdrun', 'options': '-quiet -nobackup'}, 'input_gro': 'systems/final-results/final.gro', 'input_grx': 'systems/final-results/final.grx', 'input_top': 'systems/final-results/final.top', 'output_deffnm': 'equilibrate', 'ps': 1000, 'scatter': ('time(ps)', ['Density'], 'rho_v_ns.png'), 'subdir': 'postsim/equilibrate', 'traces': ['Temperature', 'Density', 'Volume']}

do(mdp_pfx='npt', **gromacs_dict)

Handles executing the postsim MD simulation.

Parameters:

mdp_pfx (str) – filename prefix for output files, defaults to ‘npt’

class htpolynet.analysis.postsim.PostsimConfiguration

Bases: object

handles reading and parsing a postcure simulation input config file. Config file format

• { key1: {<paramdict>}}

• { key2: {<paramdict>}}

…

The config file is a list of single-element dictionaries, whose single keyword indicates the type of MD simulation to be run; simulations are run in the order they appear in the config file.

Currently allowed simulation types:

• ‘equilibrate’: simple NPT equilibration;

• ‘anneal’: simple simulated annealing;

• ‘ladder’: temperature ladder;

• ‘deform: constant strain-rate uniaxial deformation;

default_classes = {'anneal': <class 'htpolynet.analysis.postsim.PostSimAnneal'>, 'deform': <class 'htpolynet.analysis.postsim.PostSimDeform'>, 'equilibrate': <class 'htpolynet.analysis.postsim.PostSimMD'>, 'ladder': <class 'htpolynet.analysis.postsim.PostSimLadder'>}

parse(**kwargs)

Parses a PostsimConfiguration file to build the list of stages to run.

classmethod read(filename, parse=True, **kwargs)

Generates a new PostsimConfiguration object by reading in the JSON or YAML file indicated by filename.

Parameters:

• filename (str) – name of file from which to read new PostsimConfiguration object

• parse (bool) – if True, parse the input configuration file, defaults to True

Raises:

Exception – if extension of filename is not ‘.json’ or ‘.yaml’ or ‘.yml’

Returns:

a new PostsimConfiguration object

Return type:

PostsimConfiguration

htpolynet.analysis.postsim.postsim(args)

Handles the postsim subcommand for managing post-cure production MD simulations.

Parameters:

args (argparse.Namespace) – command-line arguments

Various utility methods for plotting and postprocessing.

Author: Cameron F. Abrams <cfa22@drexel.edu>

htpolynet.analysis.utils.clusters(G: Graph)

Performs a clustering analysis and returns a histogram of cluster sizes (in numbers of molecules) as a pandas DataFrame.

Parameters:

G (nx.Graph) – molecular connectivity graph

Returns:

cluster size histogram

Return type:

pd.DataFrame

htpolynet.analysis.utils.compute_E(strain, stress, fit_domain=[10, 100])

Computes the Young’s modulus by performing a linear fit to an elastic regime in stress-vs-strain data.

Parameters:

• strain (numpy.array) – strain values

• stress (numpy.array) – stress values

• fit_domain (list) – domain over which fit is made, defaults to [10,100]

Returns:

E and R2 from fit

Return type:

tuple(float,float)

htpolynet.analysis.utils.compute_tg(T, v, n_points=[10, 20])

Performs a Tg determination from (volume or density) vs temperature data by fitting lines to the low-T region and another to the high-T region, taking Tg as the temperature at which they intersect.

Parameters:

• T (numpy.array) – temperature values

• v (numpy.array) – volume or density data

• n_points (list) – number of points on the low and high side to fit lines to, defaults to [10,20]

htpolynet.analysis.utils.density_evolution(proj_dir)

Returns a single dataframe containing density, temperature, number of bonds vs time by reading all edrs in the correct order from a complete project directory.

Parameters:

proj_dir (str) – name of complete project directory

Returns:

the dataframe

Return type:

pandas.DataFrame

htpolynet.analysis.utils.density_from_gro(gro, mollib='./lib/molecules/parameterized', units='SI')

Computes density from a Gromacs gro file.

Parameters:

• gro (str) – name of gro file

• mollib (str) – location of parameterized molecular templates, defaults to ‘./lib/molecules/parameterized’

• units (str) – string indicating unit system, defaults to ‘SI’

Returns:

density

Return type:

float

htpolynet.analysis.utils.graph_from_bondsfile(bondsfile)

Generates a networkx Graph in which each node is a molecule (from ‘mi’ and ‘mj’ records in the bondsfile) and edges indicate two molecules are joined by a covalent bond.

Parameters:

bondsfile (str) – name of bondsfile

Returns:

the graph

Return type:

networkx.Graph

htpolynet.analysis.utils.mwbxl(G: Graph, crosslinker='GMA', monomer='STY')

Computes the histogram of monomer counts ‘n’ between crosslinking sites using a molecular connectivity graph; used mainly for vinyl-based polymerizations.

Parameters:

• G (nx.Graph) – molecular connectivity graph

• crosslinker (str) – name of crosslinker molecule, defaults to ‘GMA’

• monomer (str) – name of monomer, defaults to ‘STY’

Returns:

a dataframe of ‘n’ and ‘count’

Return type:

pd.DataFrame

htpolynet.analysis.utils.postsim_density_evolution(proj_dir, append_dirname=False)

Returns a single dataframe that is a concatenation of the csv files in the ‘postsim’ subdirectories.

Parameters:

proj_dir (str) – name of complete project directory

Returns:

the dataframe

Return type:

pandas.DataFrame

htpolynet.core

Manages reading and parsing of YAML configuration files.

Author: Cameron F. Abrams <cfa22@drexel.edu>

class htpolynet.core.configuration.Configuration

Bases: object

Pure data container for a build configuration file.

Reads and validates a YAML or JSON file and exposes each top-level section as a named attribute. Does NOT create Molecule or Reaction objects; that is the responsibility of Runtime.

classmethod read(filename)

Reads a JSON or YAML configuration file and returns a populated Configuration.

Parameters:

filename (str) – path to configuration file

Raises:

Exception – if the file extension is not .json, .yaml, or .yml

Returns:

populated configuration object

Return type:

Configuration

Class for managing atom coordinate data.

Author: Cameron F. Abrams <cfa22@drexel.edu>

class htpolynet.core.coordinates.Coordinates(name='')

Bases: object

Handles atom coordinates.

The primary object is A, a pandas DataFrame with one row per atom. Each atom has attributes that may be found in a gro file and/or a mol2 file, along with so-called extended attributes, which are used solely by HTPolyNet.

atomcount()

Returns the number of atoms in the Coordinates object.

Returns:

number of atoms

Return type:

int

checkbox()

Checks that all atom positions fit within the designated box.

Returns:

True,True if both lower-leftmost and upper-rightmost points are within the box

Return type:

tuple(bool, bool)

claim_parent(parent)

copy_coords(other)

Copies the posX, posY, and posZ atom attributes, and the box size, from other.A to self.A.

Parameters:

other (Coordinates) – the other Coordinates instance

delete_atoms(idx=[], reindex=True)

Deletes atoms whose global indices appear in idx.

If reindex is True, global indices are recalculated to be sequential starting at 1 with no gaps, and two new columns are added: ‘oldGlobalIdx’ (pre-deletion indices) and ‘globalIdxShift’ (change from old to new index for each atom).

Parameters:

• idx (list) – atom indexes to delete, defaults to []

• reindex (bool) – reindex remaining atoms, defaults to True

classmethod fcc(a: float, nc=[1, 1, 1])

Generates a Coordinates object that represents an FCC crystal.

Parameters:

• a (float) – lattice parameter

• nc (list) – number of unit cells in the three lattice vector directions, defaults to [1,1,1]

Returns:

a Coordinates object

Return type:

Coordinates

geometric_center()

Computes and returns the geometric center of the atoms in self’s A dataframe.

Returns:

geometric center

Return type:

np.ndarray(3,float)

get_R(idx: int) → ndarray

Returns the cartesian position of atom with global index idx.

Parameters:

idx (int) – global index of atom

Returns:

cartesian position of the atom, shape (3,)

Return type:

numpy.ndarray

get_atom_attribute(name, attributes)

Returns values of attributes listed in name from atoms specified by attribute:value pairs.

Parameters:

• name (str or list) – attribute(s) whose values are to be returned

• attributes (dict) – attribute:value pairs that specify the set of atoms to be considered

Returns:

attribute value(s) of the matching row

Return type:

scalar or Series

get_atoms_w_attribute(name, attributes)

Returns rows of atoms dataframe with columns named in name for atoms matching attributes.

Parameters:

• name (list) – attribute names for the columns to be returned

• attributes (dict) – attribute:value pairs that specify the set of atoms to be considered

Returns:

matching dataframe segment

Return type:

pd.DataFrame

gro_attributes = ['resNum', 'resName', 'atomName', 'globalIdx', 'posX', 'posY', 'posZ', 'velX', 'velY', 'velZ']

homog_trans(M: Matrix4, indices=None)

Applies homogeneous transformation matrix M to coordinates.

Parameters:

• M (Matrix4) – homogeneous transformation matrix

• indices (list, optional) – atom globalIdx values to transform; if None transforms all

linkcell_initialize(cutoff=0.0, populate=True, force_repopulate=False, save=True)

Initializes the link-cell structure for ring-pierce testing.

Assigns a linkcell_idx attribute to each ring atom and reactive atom (z > 0) directly in self.A; all other atoms get -1. Results are cached to a .grx file keyed by cutoff value.

Parameters:

• cutoff (float) – cell side length (nm), defaults to 0.0

• populate (bool) – if True, perform the assignment; defaults to True

• force_repopulate (bool) – if True, ignore any cached file; defaults to False

• save (bool) – if True, write the linkcell_idx column to a cache file; defaults to True

maxspan()

Returns dimensions of orthorhombic convex hull enclosing Coordinates.

Returns:

array of x-span, y-span, z-span

Return type:

numpy.ndarray

merge(other)

Merges two Coordinates objects.

Parameters:

other (Coordinates) – the other Coordinates object

Returns:

integer shifts in atom index, bond index, and residue index

Return type:

tuple

mic(r, pbc=None)

Applies minimum image convention to displacement vector r.

Parameters:

• r (np.ndarray(3,float)) – displacement vector

• pbc (array-like, optional) – PBC flags per axis, defaults to [1,1,1]

Returns:

minimum-image displacement vector

Return type:

np.ndarray(3,float)

minimum_distance(other, self_excludes=None, other_excludes=None)

Computes and returns distance of closest approach between two sets of atoms.

Parameters:

• other (Coordinates) – other Coordinates instance

• self_excludes (list, optional) – atom globalIdx values in self to exclude, defaults to None

• other_excludes (list, optional) – atom globalIdx values in other to exclude, defaults to None

Returns:

minimum interatomic distance (nm)

Return type:

float

minmax()

Returns the lower-leftmost and upper-rightmost positions in the atoms dataframe.

Returns:

lower-leftmost and upper-rightmost points, respectively

Return type:

tuple(np.ndarray, np.ndarray)

mol2_atom_attributes = ['globalIdx', 'atomName', 'posX', 'posY', 'posZ', 'type', 'resNum', 'resName', 'charge']

mol2_bond_attributes = ['bondIdx', 'ai', 'aj', 'order']

mol2_bond_types = {'ai': <class 'int'>, 'aj': <class 'int'>, 'bondIdx': <class 'int'>, 'order': <class 'str'>}

pierces(B: DataFrame, C: DataFrame, pbc)

Determines whether or not bond represented by two points in B pierces ring represented by N points in C.

Parameters:

• B (pd.DataFrame) – two points defining a bond

• C (pd.DataFrame) – N points defining a ring

• pbc (list) – periodic boundary condition flags, one per dimension

Returns:

True if ring is pierced

Return type:

bool

read_atomset_attributes(filename, attributes=[])

Reads atomic attributes from a GRX-format file into self.A.

Parameters:

• filename (str) – name of file

• attributes (list) – list of attributes to take, defaults to [] (take all)

Returns:

names of attributes that were read

Return type:

list

classmethod read_gro(filename, wrap_coords=True)

Reads a Gromacs gro file.

Parameters:

• filename (str) – name of gro file

• wrap_coords (bool) – if True, wrap atom coordinates into the box, defaults to True

Returns:

a new Coordinates instance

Return type:

Coordinates

classmethod read_mol2(filename)

Reads in a Sybyl MOL2 file into a Coordinates instance.

Note that this method only reads in MOLECULE, ATOM, and BOND sections. All lengths are converted from Ångström to nm.

Parameters:

filename (str) – name of input mol2 file

Returns:

a new Coordinates instance

Return type:

Coordinates

classmethod read_pdb(filename)

Reads a PDB file into a Coordinates instance.

CONECT records are parsed to build a bond table. Repeated entries for the same atom pair within one CONECT line are interpreted as higher-order bonds (e.g. two appearances → double bond, order ‘2’). Positions are converted from Ångström to nm.

Parameters:

filename (str) – path to the PDB file

Returns:

a new Coordinates instance with mol2_bonds populated

Return type:

Coordinates

return_bond_lengths(bdf)

Returns an ordered list of bond lengths for bonds in bdf.

Parameters:

bdf (pd.DataFrame) – dataframe with ‘ai’ and ‘aj’ columns of atom indices indicating bonds

Returns:

atom distances

Return type:

list

rij(i, j, pbc=None)

Computes distance between atoms i and j.

Parameters:

• i (int) – globalIdx of first atom

• j (int) – globalIdx of second atom

• pbc (array-like, optional) – PBC flags per axis, defaults to [1,1,1]

Returns:

distance between i and j (nm)

Return type:

float

rotate(R)

Rotates all coordinate vectors by rotation matrix R.

Parameters:

R (numpy.ndarray) – rotation matrix (3x3)

set_atom_attribute(name, value, attributes)

Sets the attributes named in name to the given values for atoms matching attributes.

Parameters:

• name (list) – names of attributes to set

• value (list) – values of attributes to set (parallel to name)

• attributes (dict) – attribute:value pairs that specify the set of atoms to be considered

set_atomset_attribute(attribute, srs)

Sets attribute of atoms to srs.

Parameters:

• attribute (str) – name of attribute

• srs (scalar or list-like) – attribute values in same ordering as self.A

set_box(box: ndarray)

Sets the box size from box.

Parameters:

box (numpy.ndarray) – 3-by-1 or 3-by-3 box size matrix

show_z_report()

Generates a text-based histogram of atom z-values (0-3), keyed by resname:atomname.

subcoords(sub_adf: DataFrame)

Generates a new Coordinates object to hold the atoms dataframe in ‘sub_adf’ parameter.

Parameters:

sub_adf (pd.DataFrame) – an atom dataframe

Returns:

a new Coordinates object

Return type:

Coordinates

total_volume(units='gromacs')

Returns total volume of box.

Parameters:

units (str) – unit system designation; if ‘SI’ returns m^3, defaults to ‘gromacs’

Returns:

volume (in nm^3 if units is ‘gromacs’ or m^3 if units is ‘SI’)

Return type:

float

translate(L)

Translates all coordinate vectors by displacement vector L.

Parameters:

L (numpy.ndarray) – displacement vector (nm)

unwrap(P, O, pbc)

Shifts point P to its unwrapped closest periodic image to point O.

Parameters:

• P (np.ndarray(3,float)) – a point

• O (np.ndarray(3,float)) – origin

• pbc (np.ndarray(3,int)) – directions in which pbc are applied

Returns:

a point

Return type:

np.ndarray(3,float)

wrap_coords()

Wraps all atomic coordinates into box.

wrap_point(ri)

Wraps point ri into the central periodic image.

Parameters:

ri (np.ndarray(3,float)) – a point

Returns:

the wrapped point and number of box lengths shifted per dimension

Return type:

tuple

write_atomset_attributes(attributes, filename, formatters=[])

Writes atom attributes to a GRX-format file.

Parameters:

• attributes (list) – list of attribute names to write

• filename (str) – name of file to write

• formatters (list) – formatting methods per attribute, defaults to []

Raises:

Exception – if any item in attributes does not exist in the coordinates dataframe

write_gro(filename, grotitle='')

Writes coordinates and, if present, velocities to a GROMACS-format coordinate file.

Parameters:

• filename (str) – name of file to write

• grotitle (str) – title line for the .gro file, defaults to ‘’

write_mol2(filename, bondsDF=Empty DataFrame Columns: [] Index: [], molname='', other_attributes=Empty DataFrame Columns: [] Index: [])

Writes a mol2-format file from coordinates and an optional bonds DataFrame.

Parameters:

• filename (str) – name of file to write

• bondsDF (pandas.DataFrame) – dataframe of bonds [‘ai’,’aj’], defaults to empty DataFrame

• molname (str) – name of molecule, defaults to ‘’

• other_attributes (pandas.DataFrame) – auxiliary dataframe of attributes, defaults to empty DataFrame

Manages generation of molecular templates.

Author: Cameron F. Abrams <cfa22@drexel.edu>

class htpolynet.core.molecule.Molecule(name='', generator: Reaction = None, origin: str = None)

Bases: object

classmethod New(mol_name, generator: Reaction, molrec: dict | None = None)

Generates a new, partially populated Molecule based on directives in the configuration input.

Parameters:

• mol_name (str) – name of molecule

• generator (Reaction) – reaction that generates this molecule, if applicable

• molrec (dict, optional) – dictionary of directives for this molecule, defaults to None

Returns:

a new Molecule object

Return type:

Molecule

atoms_w_same_attribute_as(find_dict={}, same_attribute='', return_attribute='')

Returns a list of atom attributes named in return_attribute from atoms that share an attribute named in same_attribute with the atom identified by find_dict.

Parameters:

• find_dict (dict, optional) – dictionary of attribute:value pairs that should uniquely identify an atom, defaults to {}

• same_attribute (str, optional) – name of attribute used to screen atoms, defaults to ‘’

• return_attribute (str, optional) – attribute value to return a list of from the screened atoms, defaults to ‘’

Returns:

list of attribute values

Return type:

list

center_coords(new_boxsize: ndarray = None)

Wrapper for the TopoCoord.center_coords method.

Parameters:

new_boxsize (np.ndarray, optional) – new box size, defaults to None

create_new_stereoisomers()

Generates new molecules to hold stereoisomers of self.

Returns:

returns early if no action taken

Return type:

None

determine_sequence(moldict)

Recursively determines the sequence of a molecule using the network of reactions that must be executed to generate it from primitives.

Parameters:

moldict (dict) – dictionary of available molecules

Returns:

list of resnames in order of sequence

Return type:

list

flip_stereocenters(idxlist)

Flips stereochemistry of atoms in idxlist.

Parameters:

idxlist (list) – global indices of chiral atoms

generate(outname='', available_molecules={}, gaff={}, ambertools={})

Manages generating topology and coordinates for self.

Parameters:

• outname (str, optional) – output file basename, defaults to ‘’

• available_molecules (dict, optional) – dictionary of available molecules, defaults to {}

• gaff (dict) – GAFF configuration directives, defaults to {}

• ambertools (dict) – ambertools configuration directives, defaults to {}

generate_conformers()

generate_conformers generates this molecule’s conformer instances using either gromacs or obabel

generate_stereoisomers()

Generates list of Molecule shells, one for each stereoisomer.

Returns:

returns early if no stereoisomers need to be generated

Return type:

None

get_angles_dihedrals(bond)

Returns copies of selections from the Topology interaction-type dataframes that contain the two atoms indicated in the bond.

Parameters:

bond – 2-element list-like container of ints

Raises:

Exception – if a NaN is found in any selection

Returns:

copies of the dataframe selections for angles, dihedrals, and 1-4 pairs

Return type:

tuple

get_molecular_weight()

Returns the molecular weight of self.

Returns:

molecular weight in g/mol

Return type:

float

get_resname(internal_resid)

Returns the residue name at position internal_resid in the molecule’s sequence.

Parameters:

internal_resid (int) – molecule-internal residue index

Returns:

residue name

Return type:

str

idx_mappers(otherTC: TopoCoord, other_bond, bystanders, oneaways, uniq_atom_idx: set)

Computes the mapping dictionary from molecule template index to instance index in the other TopoCoord.

Parameters:

• otherTC (TopoCoord) – the other TopoCoord

• other_bond – 2 atom indices of the bond in the other TopoCoord

• bystanders – bystander lists, one for each reacting atom

• oneaways – oneaways, one for each atom in the bond

• uniq_atom_idx (set) – set of unique atoms in template that must be mapped to instance

Raises:

Exception – if there is a buggy double-counting of one or more indexes

Returns:

two-way dictionaries of index mappers instance<->template

Return type:

tuple

initialize_molecule_rings()

initialize_molecule_rings generates the dictionary of rings

the dictionary of rings is keyed on ring size

initialize_monomer_grx_attributes()

initialize_monomer_grx_attributes initializes all GRX attributes of atoms in molecule

load_top_gro(topfilename, grofilename, tpxfilename='', mol2filename='', wrap_coords=False, ignore_bonds=False, overwrite_coordinates=False)

Generates a new TopoCoord member object for this molecule by reading in a Gromacs topology file and a Gromacs gro file.

Parameters:

• topfilename (str) – Gromacs topology file

• grofilename (str) – Gromacs gro file

• tpxfilename (str, optional) – extended topology file, defaults to ‘’

• mol2filename (str, optional) – alternative coordinate mol2 file, defaults to ‘’

• wrap_coords (bool) – if True, wrap coordinates into the box after reading gro, defaults to False

• ignore_bonds (bool) – if True, skip reading bonds from mol2, defaults to False

• overwrite_coordinates (bool) – if True, overwrite existing coordinates when reading mol2, defaults to False

make_bonds(bdf: DataFrame, moldict, stage)

Adds new bonds to the molecule’s topology and deletes any sacrificial hydrogens.

Parameters:

• bdf (pd.DataFrame) – pandas dataframe identifying new bonds

• moldict (dict) – dictionary of available molecular templates

• stage (reaction_stage) – enumerated parameter indicating reaction_stage

merge(other)

Merges TopoCoord from other into self’s TopoCoord.

Parameters:

other (Molecule) – another Molecule

Returns:

a shift tuple (returned by Coordinates.merge())

Return type:

tuple

minimize(outname='')

Manages invocation of vacuum minimization.

Parameters:

outname (str, optional) – output file basename, defaults to ‘’

parameterize(outname='', input_structure_format='mol2', ambertools={})

Manages GAFF parameterization of this molecule.

Parameters:

• outname (str, optional) – output file basename, defaults to ‘’

• input_structure_format (str, optional) – input structure format, defaults to ‘mol2’ (‘pdb’ is other possibility)

• ambertools (dict) – ambertools configuration directives, defaults to {}

prepare_new_bonds(available_molecules={})

Populates the bond templates and reaction bonds for self.

Parameters:

available_molecules (dict, optional) – dictionary of available molecules, defaults to {}

previously_parameterized()

Returns True if a gro file exists in the project molecule/parameterized directory for this molecule.

Returns:

True if gro file found

Return type:

bool

read_gro_attributes(grxfilename, attribute_list=[])

Reads attributes from file into self.TopoCoord.Coordinates.A.

Parameters:

• grxfilename (str) – name of input file

• attribute_list (list, optional) – list of attributes to take, defaults to [] (take all)

relax(relax_dict)

Manages invocation of MD relaxations.

Parameters:

relax_dict (dict) – dictionary of simulation directives

rotate_bond(a, b, deg)

Rotates all atoms in molecule on b-side of a-b bond by deg degrees.

Parameters:

• a (int) – index of a

• b (int) – index of b

• deg (float) – angle of rotation in degrees

set_gro_attribute(attribute, srs)

Sets attribute of atoms to srs (drills through to Coordinates.set_atomset_attributes()).

Parameters:

• attribute (str) – name of attribute

• srs – scalar or list-like attribute values in same ordering as self.A

set_sequence_from_coordinates()

set_sequence Establish the sequence-list (residue names in order) based on resNum attributes in atom list

set_sequence_from_moldict(moldict)

Sets the sequence of this molecule using the recursive determine_sequence method.

Parameters:

moldict (dict) – dictionary of available molecules

Returns:

self

Return type:

Molecule

transrot(at_idx, at_resid, from_idx, from_resid, connected_resids=[])

Given a composite molecule, translates and rotates the piece downstream of the yet-to-be-created bond to minimize steric overlaps and identify the best two sacrificial hydrogens.

Parameters:

• at_idx (int) – global index of left-hand atom in new bond

• at_resid (int) – resid of left-hand residue

• from_idx (int) – global index of right-hand atom in new bond

• from_resid (int) – resid of right-hand residue

• connected_resids (list, optional) – list of all other resids attached to right-hand residue that should move with it, defaults to []

Returns:

2-tuple containing global indices of the sacrificial hydrogens

Return type:

tuple

update_zrecs(zrecs, moldict)

Updates the “z-records” based on z’s declared in the input configuration file.

Parameters:

• zrecs (dict) – zrecs extracted from configuration file for this molecule

• moldict (dict) – dictionary of available molecules

write_gro_attributes(attribute_list, grxfilename)

Writes atomic attributes to a file.

Parameters:

• attribute_list (list) – list of attributes to write

• grxfilename (str) – name of output file

Handles project filesystems and local caching of molecule data.

Author: Cameron F. Abrams <cfa22@drexel.edu>

class htpolynet.core.projectfilesystem.Dirs

Bases: object

Canonical directory names used throughout the project filesystem.

Use these instead of bare strings so that renaming a directory requires only a change here.

analyze = 'analyze'

analyze_topdirs = ['molecules', 'systems', 'plots', 'postsim', 'analyze']

mdp = 'mdp'

static mdp_file(name)

Returns the library path for an mdp file by base name.

molecules = 'molecules'

molecules_inputs = 'molecules/inputs'

molecules_parameterized = 'molecules/parameterized'

plots = 'plots'

postsim = 'postsim'

postsim_topdirs = ['molecules', 'systems', 'plots', 'postsim']

run_topdirs = ['molecules', 'systems', 'plots']

systems = 'systems'

systems_capping = 'systems/capping'

systems_densification = 'systems/densification'

systems_final = 'systems/final-results'

systems_init = 'systems/init'

static systems_iter(n)

Returns the path for CURE iteration directory n.

systems_postcure = 'systems/postcure'

systems_precure = 'systems/precure'

class htpolynet.core.projectfilesystem.ProjectFileSystem(root='.', topdirs=['molecules', 'systems', 'plots'], projdir='next', verbose=False, reProject=False, userlibrary=None, mock=False)

Bases: object

Handles all aspects of the creation and organization of a project filesystem.

cdproj()

Changes the cwd to the toplevel project directory.

cdroot()

Changes the cwd to the root directory.

go_to(subPath, make=False)

Changes the cwd to the directory named by subPath.

Parameters:

• subPath (str) – directory relative to project directory

• make (bool) – create directory if missing, defaults to False

class htpolynet.core.projectfilesystem.SystemLibrary

Bases: object

Read-only access to bundled package resources via importlib.resources.

checkout(filename)

Copies filename from the system library to the current working directory.

Parameters:

filename (str) – path relative to resource root

Returns:

True if successful

Return type:

bool

exists(filename)

Checks if filename exists in the system library.

Parameters:

filename (str) – path relative to resource root

Returns:

True if found

Return type:

bool

get_example_depot_location()

Returns the filesystem path of the example depot directory.

Returns:

path to example_depot

Return type:

str

get_example_names()

Returns sorted list of example names available in the depot.

Recognises both .sh scripts and legacy .tgz tarballs; returns unique names (without extension) in numeric-prefix order.

Returns:

example names without extension

Return type:

list

get_molecule_names()

Returns sorted list of molecule names available as inputs in the system library.

Returns:

molecule names (stems of files in molecules/inputs/)

Return type:

list

info()

Returns a description string.

Returns:

description

Return type:

str

property root

Filesystem path of the resource root, for display.

class htpolynet.core.projectfilesystem.UserCache(path=None)

Bases: object

Writable cache for user-generated files such as parameterized molecules.

The cache location defaults to ~/.htpolynet but can be overridden by setting the HTPOLYNET_CACHE environment variable.

checkin(filename, overwrite=False)

Copies a file from the current working directory into the cache.

Parameters:

• filename (str) – destination path relative to cache root

• overwrite (bool) – overwrite if already cached, defaults to False

Returns:

False if source not found in cwd; True otherwise

Return type:

bool

checkout(filename)

Copies filename from the cache to the current working directory.

Parameters:

filename (str) – path relative to cache root

Returns:

True if successful

Return type:

bool

exists(filename)

Checks if filename exists in the cache.

Parameters:

filename (str) – path relative to cache root

Returns:

True if found

Return type:

bool

get_molecule_names()

Returns sorted list of parameterized molecule names in the cache.

Returns:

molecule names (stems of files in molecules/parameterized/)

Return type:

list

info()

Returns a description string.

Returns:

description

Return type:

str

class htpolynet.core.projectfilesystem.UserLibrary(pathname='.')

Bases: object

User-specified directory of molecule input files.

checkout(filename, searchpath=[], altpath=[])

Copies filename from the user library to the current working directory.

Parameters:

• filename (str) – path relative to library root

• searchpath (list) – additional directories to search, defaults to []

• altpath (list) – extra directories to append to the search path, defaults to []

Returns:

True if successful

Return type:

bool

exists(filename)

Checks if filename exists in the user library.

Parameters:

filename (str) – path relative to library root

Returns:

True if found

Return type:

bool

info()

Returns a description string.

Returns:

description

Return type:

str

htpolynet.core.projectfilesystem.checkin(filename, overwrite=False)

Checks a file from cwd into the user cache.

Parameters:

• filename (str) – destination path relative to cache root

• overwrite (bool) – overwrite if already cached, defaults to False

htpolynet.core.projectfilesystem.checkout(filename, altpath=[])

Copies a file to cwd; searches user library, then user cache, then system library.

Parameters:

• filename (str) – path relative to library root

• altpath (list) – extra search directories, defaults to []

Returns:

True if checkout was successful

Return type:

bool

htpolynet.core.projectfilesystem.cwd()

Returns the current working directory relative to the root path.

Returns:

relative path of current working directory

Return type:

str

htpolynet.core.projectfilesystem.exists(filename)

Checks for filename in user library, user cache, then system library.

Parameters:

filename (str) – path relative to library root

Returns:

True if found anywhere

Return type:

bool

htpolynet.core.projectfilesystem.fetch_molecule_files(mname)

Fetches all relevant molecule data files for the named molecule.

Parameters:

mname (str) – molecule name

Returns:

file extensions found and fetched

Return type:

list

htpolynet.core.projectfilesystem.get_molecule_info()

Returns molecule names available in the system library and user cache.

Returns:

(system_molecules, cached_molecules) each a sorted list of names

Return type:

tuple

htpolynet.core.projectfilesystem.go_proj()

Changes the current working directory to the project directory.

htpolynet.core.projectfilesystem.go_root()

Changes the current working directory to the root directory.

htpolynet.core.projectfilesystem.go_to(pathstr)

Changes the current working directory to pathstr relative to the project root.

Parameters:

pathstr (str) – directory path relative to project root

Returns:

True if the directory already existed, False if newly created

Return type:

bool

htpolynet.core.projectfilesystem.info()

Prints summary information about active libraries to the console.

htpolynet.core.projectfilesystem.lib_setup()

Sets up the system library and user cache.

Returns:

the system library object

Return type:

SystemLibrary

htpolynet.core.projectfilesystem.local_data_searchpath()

Returns root and project paths for local data searches.

Returns:

[rootPath, projPath]

Return type:

list

htpolynet.core.projectfilesystem.pfs_setup(root='.', topdirs=['molecules', 'systems', 'plots'], projdir='next', verbose=False, reProject=False, userlibrary=None, mock=False)

Sets up the global ProjectFileSystem.

Parameters:

• root (str) – parent directory, defaults to ‘.’

• topdirs (list) – toplevel subdirectories, defaults to [‘molecules’,’systems’,’plots’]

• projdir (str) – project directory name, defaults to ‘next’

• verbose (bool) – verbose flag, defaults to False

• reProject (bool) – restart flag, defaults to False

• userlibrary (str) – user library path, defaults to None

• mock (bool) – mock flag, defaults to False

htpolynet.core.projectfilesystem.proj()

Returns the project directory path.

Returns:

project directory path

Return type:

str

htpolynet.core.projectfilesystem.proj_abspath(filename)

Returns the path of filename relative to the project directory.

Parameters:

filename (str) – filename to resolve

Returns:

path relative to the project directory

Return type:

str

htpolynet.core.projectfilesystem.root()

Returns the root directory path.

Returns:

root directory path

Return type:

str

htpolynet.core.projectfilesystem.subpath(name)

Returns the path of the named project subdirectory.

Parameters:

name (str) – subdirectory name

Returns:

path of subdirectory

Return type:

str

htpolynet.core.projectfilesystem.system()

Returns the system library object.

Returns:

the system library

Return type:

SystemLibrary

Handles the HTPolyNet runtime workflow.

Author: Cameron F. Abrams <cfa22@drexel.edu>

class htpolynet.core.runtime.Runtime(cfgfile='', restart=False)

Bases: object

Runtime class manages all aspects of a system build using HTPolyNet.

default_edict = {'ensemble': 'npt', 'nsteps': -2, 'pressure': 10, 'ps': 200, 'repeat': 0, 'temperature': 300}

do_cure()

Manages CURE algorithm execution.

Returns:

only returns None if CURE cannot execute

Return type:

None

do_densification(deffnm='densified')

Manages execution of gmx mdrun to perform minimization and NPT MD simulation of the initial liquid system. Final coordinates are loaded into the global TopoCoord.

Parameters:

deffnm (str) – deffnm prefix fed to gmx mdrun, defaults to ‘densified’

Returns:

dictionary of Gromacs file names

Return type:

dict

do_initialization(inpfnm='init')

Manages creation of the global system topology file and the execution of ‘gmx insert-molecules’ to create the initial simulation box.

Parameters:

inpfnm (str) – basename for output files, defaults to ‘init’

Returns:

dictionary of Gromacs files

Return type:

dict

do_postcure()

Manages execution of mdrun to perform any post-cure MD simulation(s).

Returns:

dictionary of Gromacs file names

Return type:

dict

do_precure()

Manages execution of mdrun to perform any pre-cure MD simulation(s).

Returns:

dictionary of Gromacs file names

Return type:

dict

do_workflow(**kwargs)

do_workflow manages runtime for one entire system-build workflow

generate_molecules(force_parameterization=False, force_checkin=False)

Manages creation and parameterization of all monomers and oligomer templates.

Parameters:

• force_parameterization (bool) – forces AmberTools to run parameterizations, defaults to False

• force_checkin (bool) – forces HTPolyNet to overwrite molecule library, defaults to False

runtime_defaults = {'CURE': {}, 'ambertools': {'charge_method': 'gas'}, 'densification': {'aspect_ratio': array([1., 1., 1.]), 'equilibration': [{'ensemble': 'min'}, {'ensemble': 'nvt', 'ps': 10, 'temperature': 300}, {'ensemble': 'npt', 'pressure': 10, 'ps': 200, 'temperature': 300}], 'initial_density': 200.0}, 'gromacs': {'gmx': 'gmx', 'gmx_options': '-quiet -nobackup', 'mdrun': 'gmx mdrun'}, 'postcure': {'anneal': {'cycle_segments': [{'T': 300, 'ps': 0}, {'T': 600, 'ps': 20}, {'T': 600, 'ps': 20}, {'T': 300, 'ps': 20}, {'T': 300, 'ps': 20}], 'initial_temperature': 300, 'ncycles': 0}, 'postequilibration': {'ensemble': 'npt', 'pressure': 1, 'ps': 0, 'temperature': 300}}, 'precure': {'anneal': {'cycle_segments': [{'T': 300, 'ps': 0}, {'T': 600, 'ps': 20}, {'T': 600, 'ps': 20}, {'T': 300, 'ps': 20}, {'T': 300, 'ps': 20}], 'initial_temperature': 300, 'ncycles': 0}, 'postequilibration': {'ensemble': 'npt', 'pressure': 1, 'ps': 0, 'temperature': 300}, 'preequilibration': {'ensemble': 'npt', 'pressure': 1, 'ps': 100, 'temperature': 300}}}

save_data(result_name='final')

Writes ‘gro’, ‘top’, ‘tpx’, and ‘grx’ files for system.

Parameters:

result_name (str) – output file basename, defaults to ‘final’

Returns:

dictionary of Gromacs file basenames

Return type:

dict

htpolynet.core.runtime.logrotate(filename)

Renames any existing log file with name ‘filename’ using a pattern that prevents overwriting any old logs.

Parameters:

filename (str) – name of log file

Class for jointly handling Topology and Coordinate objects.

Author: Cameron F. Abrams <cfa22@drexel.edu>

class htpolynet.core.topocoord.BTRC(*values)

Bases: Enum

Bond test return codes: bond tests are applied to those bond-candidates that are within search radius of each other.

failed_pierced_ring = 1

failed_shortcircuit = 2

passed = 0

unset = 99

class htpolynet.core.topocoord.TopoCoord(topfilename='', tpxfilename='', grofilename='', grxfilename='', mol2filename='', system_name='htpolynet', wrap_coords=False, ignore_bonds=False, overwrite_coordinates=False)

Bases: object

Container for Topology and Coordinates, along with methods that use either or both of them

add_length_attribute(bdf: DataFrame, attr_name='length')

Computes bond lengths based on bonds indicated by the parallel ‘ai’ and ‘aj’ columns of the parameter dataframe bdf and stores result in a new column called attr_name.

Parameters:

• bdf (pd.DataFrame) – a pandas dataframe with ‘ai’ and ‘aj’ columns of atom indices indicating bonds

• attr_name (str) – name of length attribute column, defaults to ‘length’

add_restraints(pairdf, typ=6)

Adds bonds of type typ to the topology from the dataframe pairdf.

Parameters:

• pairdf (pandas.DataFrame) – dataframe with ai, aj, initial-distance columns

• typ (int) – bond type to add, defaults to 6 (non-topological restraint)

atom_count()

Checks to be sure the Coordinate and Topology members contain the same number of atoms.

Returns:

the number of atoms

Return type:

int

bondcycle_collective(bdf: DataFrame, chain_manager=None)

Checks to see if, when considered as a collective, this set of bond records leads to one or more cyclic bondchains; if so, longest bonds that break bondcycles are removed from the bond records list and the resulting list is returned.

Parameters:

• bdf (pandas.DataFrame) – bonds data frame, sorted in ascending order by bondlength

• chain_manager – optional ChainManager owned by the caller; used read-only (deep-copied for simulation)

Returns:

bond records that results in no new bondcycles

Return type:

pandas.DataFrame

bondtest(b, pbc=[1, 1, 1], show_piercings=True)

Determines if bond b is to be allowed to form based on geometric and topological criteria.

Parameters:

• b (tuple) – bond as tuple (ai, aj, rij)

• pbc (list) – periodic boundary condition flags in each direction, defaults to [1,1,1]

• show_piercings (bool) – flag indicating you want to write gro files showing pierced rings, defaults to True

Returns:

BTRC enum instance

Return type:

BTRC

bondtest_df(df: DataFrame, pbc=[1, 1, 1], show_piercings=True)

Applies bond filters to all bonds in the dataframe.

Parameters:

• df (pd.DataFrame) – dataframe of possible bonds with columns ‘ai’, ‘aj’ and ‘r’; this method adds the column ‘results’

• pbc (list) – flags indicating dimensions in which pbc are used, defaults to [1,1,1]

• show_piercings (bool) – toggles diagnostic output for pierced rings, defaults to True

Returns:

input data frame with new ‘results’ column

Return type:

pandas.DataFrame

center_coords(new_boxsize: ndarray = None)

Centers all coordinates in box.

Parameters:

new_boxsize (numpy.ndarray) – new boxsize if desired, defaults to None

check_your_topology()

Checks topology for duplicate 1-4 pair interactions and deletes them.

checkbox()

Checks that the entire constellation of points in the atoms dataframe fits within the designated box for this Configuration object.

Returns:

(bool, bool), True for each of lower-leftmost and upper-rightmost points if they are within the box

Return type:

tuple

copy_coords(other)

Copies coordinates and box size from other to self.

Parameters:

other (TopoCoord) – a TopoCoord instance

count_H(idx)

Counts the number of hydrogens bound to atom with index idx; any atom whose name begins with the character ‘H’ or ‘h’ is assumed to be a hydrogen.

Parameters:

idx (int) – atom global index

Returns:

number of H atoms bound to this atom

Return type:

int

decrement_gro_attribute_by_attributes(att_name, attribute_dict)

Subtracts one from attribute att_name of all atoms identified by attribute:value pairs in attribute_dict.

Parameters:

• att_name (str) – name of attribute to decrement

• attribute_dict (dict) – attribute:value pairs that specify atoms to which to apply this decrementation

delete_atoms(atomlist)

Deletes atoms from both the Topology and Coordinates instances.

Parameters:

atomlist (list) – list of global indexes of atoms to delete

Returns:

old-to-new atom global index mapper dictionary resulting from reindexing remaining atoms to make sure global indexes are sequential

Return type:

dict

density(units='SI')

Returns system density.

Parameters:

units (str) – unit designation, defaults to ‘SI’

Returns:

density

Return type:

float

enumerate_1_4_pairs(at_idx)

Enumerates all 1-4 pair interactions resulting from new bonds in at_idx.

Parameters:

at_idx (list) – list of 2-tuples, each containing global indices of atoms that bond to each other

Returns:

dataframe of all pairs

Return type:

pandas.DataFrame

equilibrate(deffnm='equilibrate', edict={}, gromacs_dict={})

Performs an MD simulation using mdrun.

Parameters:

• deffnm (str) – output file basename, defaults to ‘equilibrate’

• edict (dict) – dictionary of simulation directives, defaults to {}

• gromacs_dict (dict) – dictionary of gromacs directives, defaults to {}

Returns:

list of edr files this equilibration generates

Return type:

list

flip_stereocenters(idxlist)

Flips stereochemistry of atoms in idxlist.

Parameters:

idxlist (list) – global indices of chiral atoms

classmethod from_top_gro(top, gro)

Constructs a TopoCoord object from a top / gro pair.

Parameters:

• top (str) – Gromacs topology file

• gro (str) – Gromacs gro coordinate file

Returns:

TopoCoord instance with the top / gro read in

Return type:

TopoCoord

get_R(idx)

Returns the cartesian position of atom with global index idx.

Parameters:

idx (int) – atom global index

Returns:

position of atom as array of shape (3,)

Return type:

numpy.ndarray

get_bystanders(atom_idx)

Identifies and returns bystanders at a particular proposed bond specified by atom_idx.

Parameters:

atom_idx – container of two global atom indices specifying a proposed bond

Returns:

4-tuple of special bystander info containers

Return type:

tuple

get_gro_attribute_by_attributes(att_name, attribute_dict)

Returns values of attributes listed in att_name from atoms specified by attribute:value pairs in attribute_dict.

Parameters:

• att_name – name or list of names of attributes whose values are to be returned

• attribute_dict (dict) – dictionary of attribute:value pairs that specify the set of atoms to be considered

Returns:

one or more return attribute values (list if att_name is a list; scalar otherwise)

Return type:

scalar or list

get_gro_attributelist_by_attributes(attribute_list, attribute_dict)

Returns all rows of atoms dataframe and columns named in attribute_list for atoms identified by the attribute_dict.

Parameters:

• attribute_list (list) – list of attributes to be in the rows that are returned

• attribute_dict (dict) – dictionary of attribute:value pairs that specify the set of atoms to be considered

Returns:

a dataframe segment

Return type:

pd.DataFrame

get_oneaways(atom_idx, chain_manager=None)

Identifies and returns one-aways for a particular proposed bond specified by atom_idx.

Parameters:

• atom_idx (list) – two-element container of atom indices specifying proposed bond

• chain_manager – optional ChainManager owned by the caller; returns empty lists if None

Returns:

tuple of oneaways-lists

Return type:

tuple

get_resid_sets(atom_pair)

Identifies individual sets of separate resids owned by unbonded atoms i and j.

Parameters:

atom_pair (tuple) – tuple of i, j atom indices

Returns:

tuple containing the two apposing residue sets

Return type:

tuple

grab_files()

Using absolute pathname information, grabs the most up-to-date gromacs files for this system and deposits them into the cwd.

gro_DataFrame(name)

Returns the appropriate Coordinates dataframe based on the directive in ‘name’.

Parameters:

name (str) – either ‘atoms’ or ‘mol2_bonds’

Returns:

the desired dataframe

Return type:

pandas.DataFrame

grompp_and_mdrun(out, mdp, mylogger=<bound method Logger.debug of <Logger htpolynet.core.topocoord (INFO)>>, **kwargs)

Manages invoking a single Gromacs run using the current TopoCoord.

Parameters:

• out (str) – output filename basename

• mdp (str) – name of mdp file

• mylogger – a logger, defaults to logger.debug

Returns:

any message generated by gromacs.grompp_and_mdrun

Return type:

str

increment_gro_attribute_by_attributes(att_name, attribute_dict)

Adds one to attribute att_name of all atoms identified by attribute:value pairs in attribute_dict.

Parameters:

• att_name (str) – name of attribute to increment

• attribute_dict (dict) – attribute:value pairs that specify atoms to which to apply this incrementation

inherit_grx_attributes_from_molecules(molecule_dict, initial_composition, globally_unique=[False, False, False, True, True, False, True, False], unset_defaults=[0, 0, 'UNSET', -1, -1, -1, -1, 'UNSET'], overall_default=0)

Copies non-Gromacs-standard atom attributes from molecule templates in molecule_dict according to molecule counts in dict initial_composition.

Parameters:

• molecule_dict (dict) – dictionary of available molecules (name:Molecule)

• initial_composition (dict) – dictionary of initial composition (name:count)

• globally_unique (list) – boolean list indicating attributes that must be globally unique, defaults to GRX_GLOBALLY_UNIQUE

• unset_defaults (list) – list of values, one per attribute, that signify UNSET, defaults to GRX_UNSET_DEFAULTS

• overall_default (int) – default UNSET value for all attributes if unset_defaults is empty, defaults to 0

interresidue_partners_of(i)

Returns list of atom indices that are bonded partners of atom i and are not in the residue of atom i.

Parameters:

i (int) – atom global index

Returns:

list of atom indices of atoms that are partners of i not in i’s residue

Return type:

list

linkcell_cleanup()

Removes linkcell_idx attribute from Coordinate.A.

linkcell_initialize(cutoff, force_repopulate=True)

Initializes the linkcell structure; a wrapper for Coordinates.

Parameters:

• cutoff (float) – cell side length (nm)

• force_repopulate (bool) – if True, ignore any cached linkcell_idx file, defaults to True

load_files(filenames: dict)

Loads all gromacs files into TopoCoord.

Parameters:

filenames (dict) – dictionary of extension:filename

make_bonds(pairs, explicit_sacH={}, chain_manager=None)

Adds new bonds to the global topology.

Parameters:

• pairs (list) – list of pairs of atom global indices indicating each new bond

• explicit_sacH (dict) – explicit mapping of sacrificial H atoms, defaults to {}

• chain_manager – optional ChainManager owned by the caller; updated in place if provided

Returns:

list of indexes of atoms that must now be deleted (sacrificial H’s)

Return type:

list

makes_shortcircuit(i, j)

Determines whether atoms i and j, if bonded, would produce a short circuit, defined as an instance in which i and j belong to residues that are already bonded to each other.

Parameters:

• i (int) – global index of first atom

• j (int) – global index of second atom

Returns:

True if a short circuit would happen, False otherwise

Return type:

bool

map_from_templates(bdf, moldict, overcharge_threshhold=0.1, chain_manager=None)

Updates angles, pairs, dihedrals, atom types, and charges, based on product templates associated with each bond in ‘bdf’.

Parameters:

• bdf (pandas.DataFrame) – dataframe with columns ‘ai’, ‘aj’, ‘reactantName’

• moldict (dict) – dictionary of template Molecules keyed by name

• overcharge_threshhold (float) – threshold for charge adjustment, defaults to 0.1

• chain_manager – optional ChainManager owned by the caller; passed to get_oneaways

Raises:

• Exception – if nan found in any attribute of any new system angle

• Exception – if nan found in any attribute of any new system dihedral

• Exception – if nan found in any attribute of any new system pair that came along with a dihedral

• Exception – if nan found in ai attribute of any template pair

• Exception – if nan found in aj attribute of any template pair

• Exception – if nan found in any system pair

maxspan()

Returns the maxspan of the Coordinates (dimensions of orthorhombic convex hull enclosing Coordinates). Just a wrapper.

Returns:

array of x-span, y-span, z-span

Return type:

numpy.ndarray

merge(other, self_cm=None, other_cm=None)

Merges the TopoCoord instance “other” to self.

Parameters:

• other (TopoCoord) – another TopoCoord instance

• self_cm – optional ChainManager for self, updated in place if provided

• other_cm – optional ChainManager for other, shifted in place if provided

Returns:

a shift tuple (returned by Coordinates.merge())

Return type:

tuple

minimum_distance(other, self_excludes=None, other_excludes=None)

Computes the distance of closest approach between self’s Coordinates and other’s Coordinates.

Parameters:

• other (TopoCoord) – another TopoCoord object

• self_excludes (list, optional) – atom globalIdx values to ignore in self, defaults to None

• other_excludes (list, optional) – atom globalIdx values to ignore in other, defaults to None

Returns:

distance of closest approach (nm)

Return type:

float

minmax()

Returns the coordinates of the atoms at the lower-leftmost and upper-rightmost positions in the constellation of points in the atoms dataframe.

Returns:

two numpy arrays, lower-leftmost and upper-rightmost positions, respectively

Return type:

tuple

overwrite_coords(other)

Overwrites coordinates in self by those in other.

Parameters:

other (TopoCoord) – another TopoCoord object

pierces_ring(i, j, pbc=[1, 1, 1], show_piercings=True)

Checks to see if bond i-j would pierce any covalent ring structure.

Parameters:

• i (int) – global index of an atom

• j (int) – global index of another atom

• pbc (list) – flags indicating which dimensions have pbc applied, defaults to [1,1,1]

• show_piercings (bool) – toggles diagnostic output of ring piercings, defaults to True

Returns:

True if a ring is pierced; False otherwise

Return type:

bool

read_gro(grofilename, preserve_box=False, wrap_coords=False)

Creates a new Coordinates member by reading from a Gromacs-style coordinates file. Just a wrapper for the read_gro method of Coordinates.

Parameters:

• grofilename (str) – name of gro file

• preserve_box (bool) – if True, preserve the existing box, defaults to False

• wrap_coords (bool) – if True, wrap coordinates into the box, defaults to False

read_gro_attributes(grxfilename, attribute_list=[], chain_manager=None)

Reads attributes from file into self.Coordinates.A.

Parameters:

• grxfilename (str) – name of input file

• attribute_list (list) – list of attributes to take, defaults to [] (take all)

• chain_manager – optional ChainManager owned by the caller; reconstructed from the data if provided

read_mol2(mol2filename, ignore_bonds=False, overwrite_coordinates=False)

Creates a new Coordinates member by reading from a SYBYL-style MOL2 file. A wrapper for read_mol2 from Coordinates, but also sets the ‘mol2_bonds’ dataframe in the Topology if the parameter ignore_bonds is False. If the mol2_bonds dataframe is created, and the Topology already has a ‘bonds’ dataframe, a consistency check is performed.

Parameters:

• mol2filename (str) – name of mol2 file

• ignore_bonds (bool) – if True, skip reading bonds from mol2, defaults to False

• overwrite_coordinates (bool) – if True, overwrite existing coordinates, defaults to False

read_top(topfilename)

Creates a new Topology member by reading from a Gromacs-style top file. Just a wrapper for the read_top method of the Topology class.

Parameters:

topfilename (str) – name of topology file

read_top_gro(topfilename, grofilename)

Wrapper for read_top and read_gro; generates new Topology and Coordinates members.

Parameters:

• topfilename (str) – name of topology file

• grofilename (str) – name of coordinates file (Gromacs format)

read_tpx(tpxfilename)

Reads in extended topology information.

Parameters:

tpxfilename (str) – name of tpx file

reset_grx_attributes_from_idx_list(list_name)

Uses information in the “index lists” to repopulate appropriate GRX attributes. Currently, there is only one index list, for bondchains. Each index list is a list of lists; each element corresponds to a unique structure (bondchain) and is a list of global atom indices for atoms that make up that structural instance.

Parameters:

list_name (str) – only allowed value currently is ‘bondchain’

reset_idx_list_from_grx_attributes(list_name)

Is the inverse of reset_grx_attributes_from_idx_list: it uses the GRX attributes to rebuild index lists.

Parameters:

list_name (str) – only allowed value currently is ‘bondchain’

resid_partners_of(ri)

Returns list of resid partners of resid ri.

Parameters:

ri (int) – residue index

Returns:

list of partner residue indices (two residues are partners if there is at least one interatomic bond joining them)

Return type:

list

return_bond_lengths(bdf)

Returns the length of all bonds in bdf.

Parameters:

bdf (pandas.DataFrame) – bonds dataframe with columns ‘ai’, ‘aj’, ‘reactantName’

Returns:

list of lengths parallel to bonds

Return type:

list

rotate(R)

Applies rotation matrix R to all atom positions.

Parameters:

R (numpy.ndarray) – rotation matrix of shape (3, 3)

set_gro_attribute(attribute, srs)

Sets attribute of atoms to srs (drills through to Coordinates.set_atomset_attributes()).

Parameters:

• attribute (str) – name of attribute

• srs – scalar or list-like attribute values in same ordering as self.A

set_gro_attribute_by_attributes(att_name, att_value, attribute_dict)

Sets the attribute named att_name to att_value for the set of atoms specified by attribute_dict.

Parameters:

• att_name (str) – name of attribute to set

• att_value – value to set the attribute to

• attribute_dict (dict) – dictionary of attribute:value pairs that specify the set of atoms to be considered

set_grx_attributes(attributes=[])

Overrides the global GRX_ATTRIBUTES.

Parameters:

attributes (list) – new GRX attributes to use, defaults to []

swap_atom_names(ai, aj)

Swaps the names of the two atoms with global indices ai and aj. This is used when automatically selecting which of several possible sacrificial H’s will actually be selected. Surviving H’s are renamed so it always appears that the H with the “least important” name (lowest order if sorted) is the sacrificial H, giving perfect control of the names of the atoms that survive a bond.

Parameters:

• ai (int) – global index of first atom

• aj (int) – global index of second atom

total_volume(units='SI')

Returns total volume represented by the system’s Coordinates.

Parameters:

units (str) – unit designation, defaults to ‘SI’

Returns:

box volume

Return type:

float

translate(L)

Applies translation vector L to all atom positions.

Parameters:

L (numpy.ndarray) – translation vector of shape (3,)

update_topology_and_coordinates(bdf, template_dict={}, write_mapper_to=None, chain_manager=None, **kwargs)

Updates global topology and necessary atom attributes in the configuration to reflect formation of all bonds listed in bdf.

Parameters:

• bdf (pandas.DataFrame) – bonds dataframe with columns ‘ai’, ‘aj’, ‘reactantName’

• template_dict (dict) – dictionary of molecule templates keyed on molecule name, defaults to {}

• write_mapper_to (str) – filename to write index mapper to, defaults to None

• chain_manager – optional ChainManager owned by the caller; updated in place if provided

Returns:

bonds dataframe and pairs dataframe with atom indices updated to reflect any atom deletions

Return type:

tuple

vacuum_minimize(outname='minimized', **kwargs)

The minimize analog to grompp_and_mdrun; performs an energy minimization using mdrun.

Parameters:

outname (str) – output file basename, defaults to ‘minimized’

vacuum_simulate(outname='simulated', **kwargs)

Performs a vacuum MD simulation using mdrun.

Parameters:

outname (str) – output file basename, defaults to ‘simulated’

wrap_coords()

Wraps all coordinates into center periodic box.

write_gro(grofilename, grotitle='')

Writes a Gromacs-format coordinate file; wrapper for Coordinates.write_gro().

Parameters:

• grofilename (str) – name of file to write

• grotitle (str) – title to put in gro file, defaults to ‘’

write_gro_attributes(attributes_list, grxfilename)

Writes atomic attributes to a file.

Parameters:

• attributes_list (list) – list of attributes to write

• grxfilename (str) – name of output file

write_grx_attributes(grxfilename)

Writes GRX attributes to a file.

Parameters:

grxfilename (str) – name of output file

write_mol2(filename, molname='', element_names_as_types=False)

Writes a SYBYL MOL2-format file using Coordinates, with certain atom attributes borrowed from the Topology.

Parameters:

• filename (str) – name of file to write

• molname (str) – name of molecule to put in mol2 file, defaults to ‘’

• element_names_as_types (bool) – if True, use element names as atom types, defaults to False

write_top(topfilename)

Writes a Gromacs-format topology file; this will only write an in-line version, no itp; wrapper for Topology.write_top().

Parameters:

topfilename (str) – name of file to write

write_tpx(tpxfilename)

htpolynet.core.topocoord.find_template(BT: BondTemplate, moldict)

Searches the dictionary of available molecules to identify a bond template that matches the passed-in template, returning the corresponding template molecule and reaction-bond.

Parameters:

• BT (BondTemplate) – bond template to search for

• moldict (MoleculeDict) – dictionary of available molecules

Raises:

Exception – if no matching template is found

Returns:

template Molecule object, corresponding ReactionBond object from that template, and a boolean flag indicating whether or not the match required a symmetric-reversal of the template

Return type:

tuple

Class for managing gromacs .top file data.

Author: Cameron F. Abrams <cfa22@drexel.edu>

class htpolynet.core.topology.Topology(system_name='')

Bases: object

Class for handling gromacs topology data

add_bonds(pairs=[])

Adds bonds indicated in list pairs to the topology.

Parameters:

pairs (list) – list of (ai, aj, order) tuples, defaults to []

Raises:

Exception – if an existing bond is in the list of pairs

add_restraints(pairdf, typ=6, kb=300000.0)

Adds type-6 (non-topological) bonds to help drag atoms toward each other.

Parameters:

• pairdf (pandas.DataFrame) – dataframe of pairs [‘ai’,’aj’]

• typ (int) – bond type, defaults to 6

• kb (float) – bond spring constant (kJ/mol/nm^2), defaults to 300000

adjust_charges(atoms=[], desired_charge=0.0, overcharge_threshhold=0.1, msg='')

Adjusts atom partial charges so that total system charge equals the desired value.

Parameters:

• atoms (list) – global atom indices to adjust, defaults to []

• desired_charge (float) – target system charge, defaults to 0.0

• overcharge_threshhold (float) – threshold overcharge that triggers a warning message, defaults to 0.1

• msg (str) – message to write if pre-adjusted system charge is too high, defaults to ‘’

Returns:

self

Return type:

Topology

atomcount()

Returns the total number of atoms.

Returns:

number of atoms

Return type:

int

attenuate_bond_parameters(bondsdf, stage, max_stages, minimum_distance=0.0, init_colname='initial_distance')

Alters the kb and b0 parameters for new crosslink bonds according to the values prior to relaxation, their equilibrium values, and the ratio stage/max_stages.

Let stage/max_stages be x, and 1/max_stages <= x <= 1. The spring constant for each bond is multiplied by x and the distance is 1/x of the way from its maximum value to its equilibrium value.

Parameters:

• bondsdf (pandas.DataFrame) – dataframe of bonds managed by runtime, ‘ai’,’aj’,’reactantName’

• stage (int) – index of stage in the series of post-bond-formation relaxation

• max_stages (int) – total number of relaxation stages for this iteration

• minimum_distance (float) – minimum bond length allowed, overriding type-specific b0 if greater than 0

attenuate_pair_parameters(pairsdf, stage, max_stages, draglimit_nm=0.3)

Alters the kb and b0 parameters for new pre-crosslink pairs according to the values prior to dragging, the desired lower limit of interatomic distance, and the ratio stage/max_stages.

Parameters:

• pairsdf (pandas.DataFrame) – pairs dataframe ([‘ai’],[‘aj’],[‘initial_distance’])

• stage (int) – index of stage in the series of pre-bond-formation dragging

• max_stages (int) – total number of drag stages for this iteration

• draglimit_nm (float) – lower limit of interatomic distance requested from drag

bond_source_check()

Checks that the ‘bonds’ and ‘mol2_bonds’ dataframes contain the same bonds.

build_interresidue_graph(G, ri)

copy_bond_parameters(bonds)

Generates and returns a copy of a bonds dataframe that contains all bonds listed in bonds.

Parameters:

bonds (pandas.DataFrame) – dataframe of bonds managed by runtime, ‘ai’,’aj’,’reactantName’

Returns:

bonds dataframe extracted from system with all parameters

Return type:

pandas.DataFrame

delete_atoms(idx=[], reindex=True, return_idx_of=[], **kwargs)

Deletes atoms from topology.

Parameters:

• idx (list) – atom indexes to delete, defaults to []

• reindex (bool) – reindex atoms after deleting, defaults to True

• return_idx_of (list) – old indices whose new indices should be returned, defaults to []

Returns:

old-index-to-new-index mapper

Return type:

dict

detect_rings()

Detects unique rings in the topology.

dup_check(die=True)

Checks for duplicate type-like topology records.

Parameters:

die (bool) – if True, raise an exception when a duplicate is found, defaults to True

Raises:

Exception – if a duplicate type with different parameters is detected and die is True

classmethod from_ex(other)

Makes a new Topology instance by copying only the extensive dataframes from an existing topology.

Parameters:

other (Topology) – the other topology

Returns:

a new Topology built from the extensive dataframes of other

Return type:

Topology

get_atom_attribute(idx, attribute)

Returns value of attribute of atom idx.

Parameters:

• idx (int) – global atom index

• attribute (str) – atom attribute name

Returns:

atom attribute value

get_atomtype(idx)

Gets atom type of atom with global index idx.

Parameters:

idx (int) – atom global index

Returns:

atom type

Return type:

str

get_bond_parameters(ai, aj)

Gets b0 and kb for bond between atoms with global indexes ai and aj.

Parameters:

• ai (int) – global atom index

• aj (int) – global atom index

Returns:

b0, kb — equilibrium bond length and spring constant

Return type:

tuple

local_resid_cluster(ri)

make_resid_graph(json_file=None)

merge(other)

Merges another topology into self.

Parameters:

other (Topology) – topology to merge in

merge_ex(other)

merge_types(other)

Merges type-like topology dataframes from other to self.

Parameters:

other (Topology) – topology containing attribute D, a dictionary of dataframes

null_check(msg='')

Checks for NaNs in dataframe locations that should never have NaNs.

Parameters:

msg (str) – context message, defaults to ‘’

Raises:

Exception – if a NaN is found in a required field

classmethod read_top(filename, pad=-99.99)

Reads a GROMACS-style topology file and returns a Topology instance.

Each directive section is stored as a pandas DataFrame. Duplicate ‘dihedrals’ and ‘dihedraltypes’ sections are merged.

Parameters:

• filename (str) – name of GROMACS top file to read

• pad (float) – padding value for missing fields, defaults to _PAD_

Raises:

KeyError – if an unrecognized topology directive is encountered

Returns:

a new Topology instance

Return type:

Topology

read_tpx(filename)

remove_restraints(pairdf)

Removes all non-topological restraint bonds represented in pairdf.

Deleting these bonds does not influence angles or dihedrals.

Parameters:

pairdf (pandas.DataFrame) – dataframe of pairs [‘ai’,’aj’]

rep_ex(count=0)

Replicates extensive topology components (atoms, pairs, bonds, angles, dihedrals).

Parameters:

count (int) – number of replicas to generate, defaults to 0

Raises:

Exception – if self is missing an atoms dataframe

report_duplicate_types(other, typename='', funcidx=4)

report_type(typidx_q, typename='', funcidx=-1)

reset_override_from_type(interactionname, typename, inst_idx)

reset_type(typename, typidx_t, values)

restore_bond_parameters(df)

Copies data from all bonds in dataframe df to global dataframe.

Parameters:

df (pandas.DataFrame) – dataframe of bonds [‘ai’,’aj’,’c0’,’c1’]

shiftatomsidx(idxshift, directive, rows=[], idxlabels=[])

Shifts all atom indexes in a topology directive dataframe.

Parameters:

• idxshift (int) – integer index shift

• directive (str) – name of GROMACS topology directive (‘atoms’,’bonds’,’pairs’,’angles’,’dihedrals’)

• rows (list) – row boundaries [start, end], defaults to []

• idxlabels (list) – names of columns that contain atom indexes, defaults to []

total_charge()

Computes and returns total system charge.

Returns:

total system charge

Return type:

float

total_mass(units='gromacs')

Returns total mass of all atoms in the Topology.

Parameters:

units (str) – unit system; ‘SI’ returns kg, ‘gromacs’ returns amu, defaults to ‘gromacs’

Returns:

total mass in amu (gromacs) or kg (SI)

Return type:

float

write_top(filename)

Writes topology to a GROMACS-format top file.

Parameters:

filename (str) – name of top file to write

write_tpx(filename)

htpolynet.core.topology.df_typeorder(df, typs)

Type-orders the atom type attributes in each row of dataframe df.

Parameters:

• df (pandas.DataFrame) – a Topology type-directive dataframe; [ atomtypes ], [ bondtypes ], etc.

• typs (list) – list of type-attribute names; typically [‘i’,’j’,…]

htpolynet.core.topology.idxorder(a)

Correctly orders the tuple of atom types for particular interaction types.

Parameters:

a (tuple) – atom indices/types from a [ bond ], [ pair ], [ angle ], or [ dihedral ] record

Returns:

same atom indices/types correctly ordered to allow for easy searching/sorting

Return type:

tuple

htpolynet.core.topology.repeat_check(t, msg='')

Checks for repeated index tuples.

Parameters:

• t (list) – list of index tuples

• msg (str) – optional message, defaults to ‘’

htpolynet.core.topology.select_topology_type_option(options, typename='dihedraltypes', rule='stiffest')

Selects from a list of topological interaction options of type typename using the provided rule.

Parameters:

• options (list) – list of parameterization options for a particular interaction

• typename (str) – string designation of interaction type, defaults to ‘dihedraltypes’

• rule (str) – string describing the selection rule, defaults to ‘stiffest’

Returns:

the selected parameterization option (an element of options)

Return type:

dict

htpolynet.core.topology.typedata(h, s)

htpolynet.core.topology.typeorder(a)

Correctly orders the tuple of atom types for particular interaction types.

Parameters:

a (tuple) – atom indices/types from a [ bond ], [ pair ], [ angle ], or [ dihedral ] record

Returns:

same atom indices/types correctly ordered to allow for easy searching/sorting

Return type:

tuple

htpolynet.io

GROMACS .gro and HTPolyNet .grx file reader/writer.

Author: Cameron F. Abrams <cfa22@drexel.edu>

htpolynet.io.gro.GRX_ATTRIBUTES = ['z', 'nreactions', 'reactantName', 'sea_idx', 'bondchain', 'bondchain_idx', 'molecule', 'molecule_name']

Extended per-atom attributes stored in .grx files.

• z number of sacrificial H’s available on this atom

• nreactions number of bonds this atom has formed

• reactantName name of the most recent reactant this atom belonged to

• sea_idx symmetry-equivalent-atom group index within a residue

• bondchain index of the C-C bondchain this atom belongs to

• bondchain_idx position of this atom within its bondchain

• molecule index of the molecule this atom belongs to

• molecule_name name of that molecule

htpolynet.io.gro.GRX_GLOBALLY_UNIQUE = [False, False, False, True, True, False, True, False]

True if the attribute must be globally unique across the system.

Type:

Parallel to GRX_ATTRIBUTES

htpolynet.io.gro.GRX_UNSET_DEFAULTS = [0, 0, 'UNSET', -1, -1, -1, -1, 'UNSET']

sentinel value that means ‘not yet assigned’.

Type:

Parallel to GRX_ATTRIBUTES

htpolynet.io.gro.read(filename)

Parse a GROMACS .gro file.

Parameters:

filename (str) – path to the .gro file

Returns:

parsed data with keys:

• ’name’ (str): title line

• ’N’ (int): atom count

• ’metadat’ (dict): metadata (currently just {‘N’: N})

• ’A’ (pd.DataFrame): atom data frame

• ’box’ (np.ndarray, shape 3×3): box matrix

Return type:

dict

htpolynet.io.gro.read_grx(filename, attributes=[])

Read an HTPolyNet .grx extended-attribute file.

Parameters:

• filename (str) – path to read

• attributes (list) – attribute names to read; if empty, all columns are read

Returns:

(df, attributes_read) where df has a ‘globalIdx’ column plus the

attribute columns, and attributes_read is the list of attribute names that were actually read.

Return type:

tuple

Raises:

AssertionError – if the file does not exist or lacks a ‘globalIdx’ column

htpolynet.io.gro.write(filename, A, box, name, grotitle='')

Write a GROMACS .gro file.

Parameters:

• filename (str) – path to write

• A (pd.DataFrame) – atom data frame; must contain the gro_attributes columns

• box (np.ndarray, shape 3×3) – box matrix

• name (str) – molecule/system name used as the title when grotitle is empty

• grotitle (str) – explicit title line, defaults to ‘’

htpolynet.io.gro.write_grx(filename, A, attributes, formatters=[])

Write a subset of atom attributes to an HTPolyNet .grx file.

The file is a whitespace-delimited table with ‘globalIdx’ as the first column followed by the requested attribute columns.

Parameters:

• filename (str) – path to write

• A (pd.DataFrame) – atom data frame

• attributes (list) – attribute names to include

• formatters (list) – optional per-column formatter callables, defaults to []

Raises:

Exception – if any attribute in attributes is absent from A

Sybyl MOL2 file reader and writer.

Author: Cameron F. Abrams <cfa22@drexel.edu>

htpolynet.io.mol2.read(filename)

Parse a Sybyl MOL2 file.

Only MOLECULE, ATOM, and BOND sections are read. All lengths are converted from Ångström to nm.

Parameters:

filename (str) – path to the .mol2 file

Returns:

parsed data with keys:

• ’name’ (str)

• ’N’ (int): atom count

• ’metadat’ (dict): nBonds, nSubs, nFeatures, nSets, mol2type, mol2chargetype

• ’A’ (pd.DataFrame): atom data frame (positions in nm)

• ’mol2_bonds’ (pd.DataFrame)

• ’mol2_bondlist’ (Bondlist)

Return type:

dict

htpolynet.io.mol2.write(filename, A, mol2_bonds, metadat, name, bondsDF=None, molname='', other_attributes=None)

Write a Sybyl MOL2 file.

All coordinates are written in Ångström (positions in A are assumed to be in nm and are multiplied by 10 after centering).

Parameters:

• filename (str) – path to write

• A (pd.DataFrame) – atom data frame

• mol2_bonds (pd.DataFrame) – internal mol2 bonds (may be empty)

• metadat (dict) – molecule metadata (nFeatures, nSets, mol2type, mol2chargetype …)

• name (str) – molecule name used when molname is empty

• bondsDF (pd.DataFrame or None) – caller-supplied bonds, overrides mol2_bonds when present

• molname (str) – explicit molecule name for the MOLECULE section, defaults to ‘’

• other_attributes (pd.DataFrame or None) – additional per-atom columns to merge into A

PDB file reader for ATOM/HETATM coordinates and CONECT-record bond orders.

Interprets repeated CONECT entries for a given atom pair as higher-order bonds:

a partner listed twice → double bond (order ‘2’) a partner listed three times → triple bond (order ‘3’)

Author: Cameron F. Abrams <cfa22@drexel.edu>

htpolynet.io.pdb.read(filename)

Parse a PDB file into coordinate and bond data compatible with mol2 conventions.

Bond orders are inferred from CONECT records: if the same bonded-atom serial appears N times in one CONECT record, that bond has order N.

Positions are converted from Ångström (PDB) to nm (htpolynet internal).

Parameters:

filename (str) – path to the PDB file

Returns:

‘name’ (str) ‘N’ (int): atom count ‘metadat’ (dict): mol2-compatible metadata ‘A’ (pd.DataFrame): atom data with MOL2_ATOM_ATTRIBUTES columns ‘mol2_bonds’ (pd.DataFrame): bond table with MOL2_BOND_ATTRIBUTES columns ‘mol2_bondlist’ (Bondlist)

Return type:

dict with keys

htpolynet.core

Bond-context descriptor classes.

These are pure data objects that describe a bond by the chemical context (atom names, residue names, order, bystanders, one-aways) of its two participating atoms. They carry no cure-specific logic and have no htpolynet dependencies.

Author: Cameron F. Abrams <cfa22@drexel.edu>

class htpolynet.core.bondtemplate.BondTemplate(names, resnames, intraresidue, order, bystander_resnames, bystander_atomnames, oneaway_resnames, oneaway_atomnames)

Bases: object

is_reverse_of(other)

Returns True if self and other are reverse of each other.

Parameters:

other (BondTemplate) – another BondTemplate object

Returns:

True if self and other are reverse copies of each other

Return type:

bool

reverse()

Reverses the order of all parallel lists in a BondTemplate object.

class htpolynet.core.bondtemplate.ReactionBond(idx, resids, order, bystanders, bystanders_atomidx, oneaways, oneaways_atomidx)

Bases: object

reverse()

htpolynet.cure

class htpolynet.cure.chain.Chain(head=-1, tail=-1, idx=-1)

Bases: object

is_head(a)

is_tail(a)

merge(other)

remap_idx(idx_mapper)

shift(shift)

class htpolynet.cure.chain.ChainManager(**kwargs)

Bases: object

chain_of(a)

from_dataframe(D, lidx_col='bondchain_idx', gidx_col='bondchain')

injest_bond(ai, aj)

injest_bonds(bondlist)

injest_other(other)

mergechains(dst, src)

new_chain(head, tail)

reindex()

remap(idx_mapper)

shift(shift)

to_dataframe(D, lidx_col='bondchain_idx', gidx_col='bondchain')

Manages execution of the CURE algorithm.

Author: Cameron F. Abrams <cfa22@drexel.edu>

class htpolynet.cure.curecontroller.CureController(curedict={})

Bases: object

curedict_defaults = {'controls': {'desired_conversion': 0.5, 'late_threshold': 0.85, 'max_conversion_per_iteration': 1.0, 'max_iterations': 100, 'min_allowable_bondcycle_length': -1, 'ncpu': 4, 'radial_increment': 0.05, 'search_radius': 0.5}, 'drag': {'cutoff_pad': 0.2, 'equilibration': [{'ensemble': 'min'}, {'ensemble': 'nvt', 'nsteps': 1000, 'temperature': 600}, {'ensemble': 'npt', 'nsteps': 2000, 'pressure': 1, 'temperature': 600}], 'increment': 0.0, 'kb': 300000.0, 'limit': 0.0, 'nstages': 0, 'trigger_distance': 0.0}, 'equilibrate': {'ensemble': 'npt', 'nsteps': 50000, 'pressure': 1, 'temperature': 300}, 'gromacs': {'rdefault': 0.9}, 'output': {'bonds_file': 'bonds.csv'}, 'relax': {'cutoff_pad': 0.2, 'equilibration': [{'ensemble': 'min'}, {'ensemble': 'nvt', 'nsteps': 1000, 'temperature': 600}, {'ensemble': 'npt', 'nsteps': 2000, 'pressure': 1, 'temperature': 600}], 'increment': 0.0, 'nstages': 6}}

default_equilibration_sequence = [{'ensemble': 'min'}, {'ensemble': 'nvt', 'nsteps': 1000, 'temperature': 600}, {'ensemble': 'npt', 'nsteps': 2000, 'pressure': 1, 'temperature': 600}]

do_capping(TC: TopoCoord, RL: list[Reaction], MD: dict[str, Molecule], gromacs_dict={})

Manages generation of all capping bonds.

Parameters:

• TC (TopoCoord) – TopoCoord object containing all topology and coordinate information

• RL (ReactionList) – list of all reaction types

• MD (MoleculeDict) – dictionary of all molecule information

• gromacs_dict (dict) – dictionary of custom gromacs parameters, defaults to {}

Returns:

dictionary of resulting output files, keyed by extension (‘gro’, ‘top’, ‘grx’)

Return type:

dict

do_iter(TC: TopoCoord, RL: list[Reaction], MD: dict[str, Molecule], gromacs_dict={})

Performs one CURE iteration.

Parameters:

• TC (TopoCoord) – TopoCoord object; all topological and coordinate information is in here

• RL (ReactionList) – list of all reaction types

• MD (MoleculeDict) – dictionary of all molecules, keyed by name

• gromacs_dict (dict) – dictionary of custom gromacs parameters, defaults to {}

Returns:

dictionary of resulting output file names

Return type:

dict

is_cured()

Returns True if system is cured.

Returns:

True if system is cured; False otherwise

Return type:

bool

next_iter()

Resets this CureController for the next CURE iteration.

Returns:

True if new iteration index exceeds the maximum number of iterations allowed by runtime

Return type:

bool

reset()

Resets this CureController object by resetting its CureState, its bonds dataframe, and its search_failed member.

setup(max_nxlinkbonds=0, desired_nxlinkbonds=0, max_search_radius=0.0)

Sets up this CureController object.

Parameters:

• max_nxlinkbonds (int) – maximum allowable number of bonds, defaults to 0

• desired_nxlinkbonds (int) – desired number of bonds, defaults to 0

• max_search_radius (float) – maximum search radius (nm), defaults to 0.0

class htpolynet.cure.curecontroller.CureState

Bases: object

classmethod from_yaml(filename='cure_state.yaml')

Returns a new CureState object generated by reading in the YAML file.

Parameters:

filename (str) – input file name, defaults to ‘cure_state.yaml’

Returns:

new CureState object returned by yaml.load

Return type:

CureState

reset()

Resets this CureState object to begin a new CURE iteration.

class htpolynet.cure.curecontroller.cure_step(*values)

Bases: Enum

Enumerated CURE step

basename()

cap_bondsearch = 5

cap_equilibrate = 8

cap_relax = 7

cap_update = 6

cure_bondsearch = 0

cure_drag = 1

cure_equilibrate = 4

cure_relax = 3

cure_update = 2

finished = 9

unknown = 99

Handles expansion of reactions based on chains, stereoisomers, and symmetry.

Author: Cameron F. Abrams <cfa22@drexel.edu>

htpolynet.cure.expandreactions.bondchain_expand_reactions(molecules: dict[str, Molecule])

Handles generation of new reactions and molecular templates implied by any C-C bondchains.

Note

Must be called after all grx attributes are set for all molecules.

Parameters:

molecules (MoleculeDict) – dictionary of molecular templates constructed from explicit declarations

Returns:

the list of new reactions and dictionary of new molecules

Return type:

tuple(ReactionList, MoleculeDict)

htpolynet.cure.expandreactions.generate_stereo_reactions(RL: list[Reaction], MD: dict[str, Molecule])

Scans the list of reactions and generates any additional reactions in which all possible stereoisomers are reactants.

Parameters:

• RL (ReactionList) – list of Reactions

• MD (MoleculeDict) – dictionary of available Molecules

Returns:

number of new reactions/molecular products created

Return type:

int

htpolynet.cure.expandreactions.generate_symmetry_reactions(RL: list[Reaction], MD: dict[str, Molecule])

Scans reaction list to generate any new reactions implied by symmetry-equivalent atoms.

Parameters:

• RL (ReactionList) – list of Reactions

• MD (MoleculeDict) – dict of available molecules

Returns:

number of new reactions/molecular products created

Return type:

int

Handles Reaction objects.

Author: Cameron F. Abrams <cfa22@drexel.edu>

class htpolynet.cure.reaction.Reaction(jsondict={})

Bases: object

default_directives = {'atoms': {}, 'bonds': [], 'name': '', 'probability': 1.0, 'procession': {}, 'product': '', 'reactants': {}, 'stage': reaction_stage.unset}

htpolynet.cure.reaction.extract_molecule_reactions(rlist: list[Reaction], plot=True)

Establishes the correct order of reactions so that molecular templates are created in a sensible order (reactants before products for all reactions).

Parameters:

• rlist (ReactionList) – list of all reactions

• plot (bool) – flag to plot the reaction network, defaults to True

Returns:

ordered list of tuples, each of the form (name-of-product-molecule, Reaction)

Return type:

list of tuples

htpolynet.cure.reaction.generate_product_name(R: Reaction)

Automatically generates the name of the product based on the names of the reactants and the bonds in R.

Parameters:

R (Reaction) – a Reaction

Returns:

suggested name of product

Return type:

str

htpolynet.cure.reaction.get_r(mname, RL: list[Reaction])

Returns the Reaction that generates molecule mname as a product, if it exists, otherwise None.

Parameters:

• mname (str) – name of molecule to search

• RL (ReactionList) – list of all Reactions

Returns:

Reaction that generates mname, or None

Return type:

Reaction or None

htpolynet.cure.reaction.is_reactant(name: str, reaction_list: list[Reaction], stage=reaction_stage.cure)

Tests to see if molecule ‘name’ appears as a reactant in any reaction in reaction_list.

Parameters:

• name (str) – name of molecule

• reaction_list (ReactionList) – list of all Reactions

• stage (reaction_stage) – stage of reactions to search, defaults to reaction_stage.cure

Returns:

True if molecule is a reactant, False otherwise

Return type:

bool

htpolynet.cure.reaction.molname_sequence_resnames(molname: str, reactions: list[Reaction])

Determines monomer sequence of the molecule with name molname based on a traversal of the reaction network.

Parameters:

• molname (str) – name of molecule

• reactions (ReactionList) – list of all Reactions

Returns:

monomer sequence of molecule as a list of monomer names

Return type:

list

htpolynet.cure.reaction.parse_reaction_list(baselist: list[Reaction])

Generates any new reactions inferred by procession (i.e., linear polymerization).

Parameters:

baselist (ReactionList) – list of unprocessed reaction dicts read directly from configuration file

Returns:

entire set of all reactions, including new ones added here

Return type:

ReactionList

htpolynet.cure.reaction.product_sequence_resnames(R: Reaction, reactions: list[Reaction])

Recursively generates sequence of product of R by traversing network of reactions; sequence is by definition an ordered list of monomer names.

Parameters:

• R (Reaction) – a Reaction

• reactions (ReactionList) – list of all Reactions

Returns:

the sequence of R’s product molecule as a list of monomer names

Return type:

list

htpolynet.cure.reaction.reactant_resid_to_presid(R: Reaction, reactantName: str, resid: int, reactions: list[Reaction])

Maps the resid of a reactant monomer to its inferred resid in the associated product in reaction R, by traversing the reaction network.

Parameters:

• R (Reaction) – a Reaction

• reactantName (str) – the name of one of the reactants in R

• resid (int) – the resid in that reactant we want mapped to the product

• reactions (ReactionList) – list of all Reactions

Returns:

resid of this residue in the product of R

Return type:

int

class htpolynet.cure.reaction.reaction_stage(*values)

Bases: Enum

Enumerated reaction stage

build = 0

cap = 3

cure = 2

param = 1

unset = 99

htpolynet.external

Manages execution of AmberTools antechamber, parmchk2.

Author: Cameron F. Abrams <cfa22@drexel.edu>

htpolynet.external.ambertools.GAFFParameterize(inputPrefix, outputPrefix, input_structure_format='mol2', ambertools=None)

Manages execution of antechamber, parmchk2, and tleap to generate GAFF parameters, then converts the result to Gromacs gro/top files via parmed.

Parameters:

• inputPrefix (str) – basename of input structure file

• outputPrefix (str) – basename of output files

• input_structure_format (str) – format of input structure file, defaults to ‘mol2’; ‘pdb’ is other option

• ambertools (dict | None) – ambertools configuration directives, defaults to None

Raises:

parmed.exceptions.GromacsError – if parmed fails to convert tleap output

Thin wrapper around subprocess for running external commands.

Author: Cameron F. Abrams <cfa22@drexel.edu>

htpolynet.external.command.opts(**kwargs)

Format keyword arguments as ‘-key value’ flag pairs.

Useful for building command strings from option dicts, e.g.:

opts(f='in.gro', o='out.gro')  ->  '-f in.gro -o out.gro'

Parameters:

**kwargs – option name/value pairs

Returns:

space-separated ‘-key value’ string

Return type:

str

htpolynet.external.command.run(command, ignore_codes=(), override=None, quiet=True)

Run a shell command and return its output.

Parameters:

• command (str) – shell command to run

• ignore_codes (tuple | list) – return codes to treat as success, defaults to ()

• override (tuple[str, str] | None) – (needle, msg) — if needle appears in stdout or stderr, raise even when returncode == 0, defaults to None

• quiet (bool) – if False, log the command before running, defaults to True

Returns:

(stdout, stderr)

Return type:

tuple[str, str]

Raises:

subprocess.SubprocessError – on non-zero return code (unless in ignore_codes), or when the override needle is found in output

Methods for handling the gmx suite of executables.

Author: Cameron F. Abrams <cfa22@drexel.edu>

htpolynet.external.gromacs.get_energy_menu(edr, **kwargs)

Gets the menu provided by ‘gmx energy’ when applied to a particular edr file.

Parameters:

edr (str) – name of edr file

Returns:

menu dictionary

Return type:

dict

htpolynet.external.gromacs.gmx_command(name, options={}, console_in='')

htpolynet.external.gromacs.gmx_energy_trace(edr, names=[], report_averages=False, keep_files=False, **kwargs)

Generates traces of data in edr file.

Parameters:

• edr (str) – name of edr file

• names (list) – list of data names, defaults to []

• report_averages (bool) – flag to indicate if averages of all data are to be computed here, defaults to False

• keep_files (bool) – flag indicating caller would like to keep the raw input and output files for gmx energy, defaults to False

Returns:

dataframe of traces

Return type:

pandas.DataFrame

htpolynet.external.gromacs.gmx_traj_info(trr)

htpolynet.external.gromacs.gro_from_trr(pfx, nzero=2, b=0, outpfx='')

htpolynet.external.gromacs.gromacs_distance(idf, gro, new_column_name='r', pfx='tmp', force_recalculate=False, keep_files=False)

Uses ‘gmx distance’ to measure interatomic distances.

Parameters:

• idf (pandas.DataFrame) – dataframe of atom indexes in pairs [‘ai’,’aj’]

• gro (str) – name of gromacs input file for ‘gmx distance’ to use

• new_column_name (str) – name of column in idf where distances are stored, defaults to ‘r’

• force_recalculate (bool) – flag to force calculation of distances even if a distance column exists in idf, defaults to False

• keep_files (bool) – flag indicating caller would like to keep the raw input and output files for gmx energy, defaults to False

Returns:

list of distances parallel to idf columns

Return type:

numpy.ndarray

htpolynet.external.gromacs.grompp_and_mdrun(gro='', top='', out='', mdp='', boxSize=[], single_molecule=False, **kwargs)

Launcher for grompp and mdrun.

Parameters:

• gro (str) – input gro file, defaults to ‘’

• top (str) – input top file, defaults to ‘’

• out (str) – output file basename, defaults to ‘’

• mdp (str) – input mdp file, defaults to ‘’

• boxSize (list) – explicit box size, defaults to []

• single_molecule (bool) – if true, a single-molecule system is simulated, defaults to False

htpolynet.external.gromacs.insert_molecules(composition, boxSize, outName, inputs_dir='.', **kwargs)

Launcher for gmx insert-molecules.

Parameters:

• composition (dict) – dictionary of molecule_name:count

• boxSize (list(3,float) or float) – size of box as 3 floats or 1 float (if cubic box)

• outName (str) – basename of output files

• inputs_dir (str) – directory to search for input structures, defaults to ‘.’

Raises:

Exception – if gmx-insert molecules fails to insert the requested number of molecules

htpolynet.external.gromacs.mdp_get(mdp_filename, key)

htpolynet.external.gromacs.mdp_modify(mdp_filename, opt_dict, new_filename=None, add_if_missing=True)

Modifies a gromacs mdp file.

Parameters:

• mdp_filename (str) – name of mdp file to modify; overwritten if new_filename==None

• opt_dict (dict) – keyword:value dictionary of mdp options

• new_filename (str) – name of output file, defaults to None

• add_if_missing (bool) – flag indicating whether to insert key:value into mdp file if not already there, defaults to True

htpolynet.external.gromacs.mdp_to_dict(mdp_filename)

Handles identification of available software needed by HTPolyNet.

Author: Cameron F. Abrams <cfa22@drexel.edu>

htpolynet.external.software.info()

Logs the software version info.

htpolynet.external.software.set_gmx_preferences(gromacs_dict={})

Sets the global Gromacs preferences.

Parameters:

gromacs_dict (dict) – gromacs section from the configuration, defaults to {}

htpolynet.external.software.sw_setup()

Checks that all required AmberTools executables are accessible and queries their version.

htpolynet.external.software.to_string()

Returns a formatted string listing HTPolyNet commit, AmberTools, GROMACS, and GPU info.

htpolynet.geometry

Manages bidirectional interatomic bondlists.

Author: Cameron F. Abrams <cfa22@drexel.edu>

class htpolynet.geometry.bondlist.Bondlist

Bases: object

The member “B” is a dictionary keyed on atom index whose values of lists of atom indices indicating bond partners of the key atom

adjacency_matrix()

Generates and returns an adjacency matrix built from the bondlist.

Returns:

adjacency matrix

Return type:

numpy.ndarray

append(pair)

Appends the bonded pair in parameter ‘pair’ to the bondlist.

Parameters:

pair (list-like container) – pair atom indices

are_bonded(idx, jdx)

Returns True if atoms with indices idx and jdx are bonded neighbors.

Parameters:

• idx (int) – atom index

• jdx (int) – another atom index

Returns:

True if idx and jdx are bonded neighbors

Return type:

bool

as_list(root, depth)

Recursively builds a list of all atoms that form a bonded cluster by traversing maximally depth bonds.

Parameters:

• root (list-like container of two ints) – root bond

• depth (int) – number of bonds to traverse to define bonded cluster

Returns:

list of atom indices in the bonded cluster

Return type:

list

delete_atoms(idx)

Deletes all instances of atoms in the list idx from the bondlist.

Parameters:

idx (list) – list of indices for atoms to delete

classmethod fromDataFrame(df: DataFrame)

graph()

Generates a networkx Graph object from the bondlist.

Returns:

a networkx Graph object

Return type:

networkx.Graph

half_as_list(root, depth)

Returns bonded cluster defined by atom b in root found by traversing depth bonds excluding the bond to atom a in root.

Parameters:

• root (list-like container of two ints) – root bond

• depth (int) – number of bonds to traverse

Returns:

list of atom indices in bonded cluster “owned” by atom b not containing atom a

Return type:

list

partners_of(idx)

Returns a copy of the value of self.B[idx].

Parameters:

idx (int) – atom index

Returns:

list of indices of atoms to which atom ‘idx’ is bound

Return type:

list

update(df: DataFrame)

Updates the bondlist using data in the parameter dataframe df.

Parameters:

df (pd.DataFrame) – dataframe with minimally columns named ‘ai’ and ‘aj’

Raises:

Exception – if no column ‘ai’ or ‘aj’ in df

Manages the link-cell structure used for ring-pierce testing.

Author: Cameron F. Abrams <cfa22@drexel.edu>

class htpolynet.geometry.linkcell.Linkcell(box=[], cutoff=None, pbc_wrapper=None)

Bases: object

Spatial hash grid for efficient ring-pierce candidate pruning.

Workflow:

1. create(cutoff, box) — build the grid geometry and precompute per-cell neighbour lists.

2. assign(A, mask) — vectorised, in-place assignment of linkcell_idx to every atom row in A that satisfies mask; all other rows get linkcell_idx = -1.

3. neighbor_cell_set(ci) — returns the set of cell indices (including ci itself) that are spatially adjacent to cell ci.

4. nearby_atom_ids(A, cell_set) — vectorised isin query; returns the globalIdx values of atoms assigned to any cell in cell_set.

No memberlists are maintained; all proximity queries operate directly on the linkcell_idx column of the atom DataFrame.

are_cellndx_neighbors(Ci, Cj)

Return True if cells Ci and Cj are adjacent (with PBC).

assign(A, mask=None)

Assign linkcell_idx to atoms in A in-place, no copies.

All atoms start with linkcell_idx = -1. Those selected by mask (a boolean Series aligned with A) are assigned the correct cell index via a single vectorised numpy operation.

Parameters:

• A (pd.DataFrame) – atom data frame; must contain posX/posY/posZ

• mask (pd.Series of bool, optional) – selects atoms to assign; if None, all atoms are assigned

cellndx_in_structure(C)

Return True if (i,j,k)-index C is within the grid.

cellndx_of_ldx(i)

Return (i,j,k)-index of cell with scalar index i.

cellndx_of_point(R)

Return the (i,j,k) cell index of point R (uses pbc_wrapper).

corners_of_cellndx(C)

Return lower-left and upper-right corners of cell C.

create(cutoff, box, origin=array([0., 0., 0.]))

Build the link-cell grid and precompute per-cell neighbour lists.

Parameters:

• cutoff (float) – minimum cell side length (nm)

• box (numpy.ndarray) – simulation box; shape (3,) or (3,3)

• origin (numpy.ndarray) – grid origin, defaults to [0,0,0]

ldx_of_cellndx(C)

Return scalar index of cell with (i,j,k)-index C.

make_neighborlists()

Precompute per-cell neighbour lists (26 neighbours each, with PBC).

nearby_atom_ids(A, cell_set)

Return globalIdx values of atoms whose cell is in cell_set.

Parameters:

• A (pd.DataFrame) – atom data frame with linkcell_idx column

• cell_set (set) – cell indices to search

Returns:

globalIdx values

Return type:

numpy.ndarray

neighbor_cell_set(cell_idx)

Return the set of cell indices adjacent to cell_idx, including itself.

Parameters:

cell_idx (int) – scalar cell index

Returns:

neighbour cell indices plus cell_idx

Return type:

set

neighbors_of_cellndx(Ci)

Return the 26 (i,j,k)-index neighbours of cell Ci, with PBC wrapping.

point_in_cellndx(R, C)

Return True if point R is located in cell C.

class htpolynet.geometry.matrix4.Matrix4(*args)

Bases: object

Class for handling 4x4 homogeneous transformation matrices

rot(degrees: float, axis: str)

Apply a rotation around a Cartesian axis by a certain number of degrees; right-hand rule applies

rotate_axis(degrees: float, axis: ndarray)

transform(point3D: ndarray) → ndarray

transinvec(x, y, z)

translate(*args)

transvec(x, y, z)

Handles ring-piercing determinations.

Author: Cameron F. Abrams <cfa22@drexel.edu>

class htpolynet.geometry.ring.Ring(idx)

Bases: object

copy()

injest_coordinates(A, idx_key='globalIdx', pos_key=['posX', 'posY', 'posZ'])

pierced_by(P)

Determines if segment with endpoints P[0] and P[1] pierces ring; uses ray projection method and fact that scaled length must be between 0 and 1 for a plane intersection.

Parameters:

P (numpy.ndarray) – a 2-element numpy array of 3-space points

Returns:

True if P[0]-P[1] pierces self’s ring, along with the intersection point

Return type:

tuple (bool, numpy.ndarray(3))

remap(mapper)

shift(shift)

treadmill()

yield the treadmilled versions of the list

unwrap(P, unwrapf=None, pbc=[1, 1, 1])

class htpolynet.geometry.ring.RingList(input_obj)

Bases: UserList

all_atoms()

filter(idxlist)

injest_coordinates(A, idx_key='globalIdx', pos_key=['posX', 'posY', 'posZ'])

remap(mapper)

shift(shift)

class htpolynet.geometry.ring.Segment(P)

Bases: object

a segment object owns a list of Points P with two elements representing segment endpoints, and a vector that points from the first point to the second, V

htpolynet.geometry.ring.lawofcos(a, b)

Returns the cosine of the angle defined by vectors a and b if they share a vertex (the LAW OF COSINES).

Parameters:

• a (numpy.ndarray(3,float)) – a vector

• b (numpy.ndarray(3,float)) – another vector

Returns:

cosine of the angle formed by a and b

Return type:

float

htpolynet.utils

htpolynet.utils.banner.banner(logf)

Implements a simple checkpointing scheme using a wrapper.

Author: Cameron F. Abrams <cfa22@drexel.edu>

class htpolynet.utils.checkpoint.Checkpoint(input_dict={})

Bases: object

default_filename = 'checkpoint_state.yaml'

classmethod from_yaml()

to_yaml()

htpolynet.utils.checkpoint.enableCheckpoint(method)

Wraps any method so that every call is registered in a history of calls in a written checkpoint file.

Parameters:

method – name of method to be wrapped

Returns:

wrapped method

Return type:

method

htpolynet.utils.checkpoint.read_checkpoint()

Creates a new global Checkpoint object by reading from the default file.

Returns:

current results dictionary with any pathnames resolved as absolute

Return type:

dict

Some convenient tools for handling pandas dataframes in the context of htpolynet coordinates.

Author: Cameron F. Abrams <cfa22@drexel.edu>

htpolynet.utils.dataframetools.get_row_as_string(df: DataFrame, attributes)

Returns the selected rows as a string, with rows expected to be uniquely defined by attributes dict.

Parameters:

• df (pd.DataFrame) – a pandas dataframe

• attributes (dict(str,obj)) – dictionary of column names (keys) and values that specify set of rows to be returned

Returns:

selected dataframe converted to a string

Return type:

str

htpolynet.utils.dataframetools.get_rows_w_attribute(df: DataFrame, name, attributes: dict)

Returns a series of values of attribute “name” from all rows matching attributes dict.

Returns:

list of values from selected rows

Return type:

values

htpolynet.utils.dataframetools.set_row_attribute(df: DataFrame, name, value, attributes)

Sets value of attribute name to value in all rows matching attributes dict.

Parameters:

• df (pd.DataFrame) – a pandas dataframe

• name (str) – name of attribute whose value is to be set

• value (scalar) – value the attribute is to be set to

• attributes (dict) – dictionary of attribute:value pairs that specify the atoms whose attribute is to be set

htpolynet.utils.dataframetools.set_rows_attributes_from_dict(df: DataFrame, valdict, attributes)

Sets values of attributes in valdict dict of all rows matching attributes dict.

Parameters:

• df (pd.DataFrame) – a pandas dataframe

• valdict (dict) – dictionary of attribute:value pairs to set

• attributes (dict) – dictionary of attribute:value pairs that specify the atoms whose attribute is to be set

Manages the inputcheck subcommand.

Author: Cameron F. Abrams <cfa22@drexel.edu>

htpolynet.utils.inputcheck.input_check(args)

Manages the input-check subcommand.

Parameters:

args (argparse.Namespace) – parsed arguments

Shared logging configuration for HTPolyNet subcommands.

Author: Cameron F. Abrams <cfa22@drexel.edu>

htpolynet.utils.logsetup.setup_logging(loglevel, diag=None, no_banner=False)

Configures the root logger with optional file and console handlers.

Parameters:

• loglevel (str) – log level name for the diagnostic file (e.g. ‘debug’, ‘info’)

• diag (str) – path to the diagnostic log file; if None, file logging is skipped

• no_banner (bool) – if True, suppresses the HTPolyNet startup banner

htpolynet.utils.stringthings.my_logger(msg, logf, width=67, fill='*', sep=', ', just='^')