liquid_structure_step package#

Submodules#

liquid_structure_step.analysis module#

The structural analysis of the Liquid Structure step, independent of SEAMM.

Species and sites: each molecule is named by its formula, and a site is an element of a species (“O(H2O)”), an element in every species (“O”), or an MDAnalysis selection (“select: name O and resname 1”).
Radial distribution functions accumulated frame by frame, with errors from blocks of frames – the independent runs, or blocks of a single run; the first peak and minimum; coordination numbers.
The classification of cation-anion pairs as free, solvent-separated (SSIP), contact (CIP) or aggregated (AGG), from distances only, so it also works without a periodic cell.

exception liquid_structure_step.analysis.AnalysisError[source]#

Bases: ValueError

A problem with what was asked for.

liquid_structure_step.analysis.CATIONS = {'Ba', 'Ca', 'Cs', 'K', 'Li', 'Mg', 'Na', 'Rb', 'Sr', 'Zn'}#: Monatomic species taken as cations or anions when there are no charges

class liquid_structure_step.analysis.PairingAccumulator[source]#

Bases: object

The fractions of cations in each pairing class, over frames, with errors from blocks.

add_frame(classes)[source]#

result(blocks=5)[source]#: The fractions of the cations in each class and their standard errors (None with one block); blocks as for RDF.result().

class liquid_structure_step.analysis.RDF(a, b, molecule_of_atom, r_max=12.0, dr=0.02)[source]#

Bases: object

A radial distribution function accumulated over frames.

Pairs within the same molecule are left out.

Parameters:

a (numpy.ndarray of int) – The atoms of the two sites.
b (numpy.ndarray of int) – The atoms of the two sites.
molecule_of_atom (numpy.ndarray of int) – The molecule of each atom.
r_max (float) – The range, Å.
dr (float) – The width of the bins, Å.

add_frame(positions, box=None, volume=None)[source]#

Add a frame.

Parameters:

positions (numpy.ndarray(n_atoms, 3)) – All the positions, Å.
box (numpy.ndarray(6) or None) – The MDAnalysis box (a, b, c, alpha, beta, gamma), or None without a cell.
volume (float or None) – The volume of the cell, Å^3; needed for g(r), not for the counts.

property r#: The centres of the bins, Å.

result(blocks=5)[source]#

The g(r) and running coordination number, with errors from blocks.

Parameters:: blocks (int or [int]) – The number of equal blocks of frames, or the number of frames in each block (e.g. the frames of each independent run).
Returns:: r; g and g_err (None without a cell); n and n_err, the running coordination number (neighbours within r); the errors are standard errors, None with one block. g_blocks and n_by_block, the g(r) (None without a cell) and running coordination number of each block; n_frames and n_blocks.
Return type:: dict

class liquid_structure_step.analysis.ShellAccumulator(solute_atoms, solute_ids, solvents)[source]#

Bases: object

The solvation shells of the molecules of one solute species.

A solvent molecule is in a solute’s shell when any of its atoms is within the cutoff of any of the solute’s atoms.

Parameters:

solute_atoms (numpy.ndarray of int) – The atoms of the solute molecules.
solute_ids (numpy.ndarray of int) – The solute molecule (0, 1, …) of each of those atoms.
solvents ({str: (numpy.ndarray of int, numpy.ndarray of int, float)}) – For each solvent species: its atoms, the molecule of each, and the cutoff (Å).

add_frame(positions, box=None)[source]#

result(blocks=5, dt=None, top=10, runs=None)[source]#

The coordination numbers, shell compositions, pairing and (with dt, the interval between frames in ps) residence times.

Parameters:

blocks (int or [int]) – The blocks for the errors, as for RDF.result().
dt (float) – The interval between frames, ps, for the residence times.
top (int) – The number of the most common shells to give.
runs ([int]) – The number of frames of each run, so that the residence times are not taken across runs; by default the frames are one run.

Returns:

coordination and coordination_err: {solvent: number}; pairing and pairing_err: {solvent: fraction of solutes with at least one}; speciation: [(composition, fraction, error)], most common first, the composition as {solvent: count}; residence: {solvent: ps} or None, the mean over the runs, and residence_blocks: {solvent: [ps or None]}, from each block. The errors are standard errors over the blocks, None with one block.

Return type:

dict

class liquid_structure_step.analysis.Species(symbols, molecules)[source]#

Bases: object

The species of a system: the formula of each molecule and of each atom.

Parameters:

symbols ([str]) – The element of each atom.
molecules ([[int]]) – The atoms (0-based) of each molecule.

count(species)[source]#

element_pairs()[source]#: Every pair of elements, each pair once.

heavy_atoms(species)[source]#: The atoms of a species other than hydrogens (all of them if it has only hydrogens): its coordinating atoms, for shells and ion pairing.

ions(charges=None)[source]#

The monatomic species, split into cations and anions by their charges (or, without charges, by element: the alkali and alkaline-earth metals are cations, the halogens anions); and the polyatomic ions (anions such as BF4) when the charges show them.

Returns:: The cation and anion species.
Return type:: ([str], [str])

property names#: The species, in order of appearance.

site(text, universe=None)[source]#

The atoms (0-based indices) of a site.

Parameters:

text (str) – “O(H2O)”, an element of a species; “O”, the element in every species; “H2O”, every atom of a species; or “select: <MDAnalysis selection>”.
universe (MDAnalysis.Universe) – Needed for a selection.

Return type:

numpy.ndarray of int

site_label(atoms)[source]#: A short label for a set of atoms: ‘O(H2O)’ if they are one element of one species, else the element or the species.

liquid_structure_step.analysis.classify_ion_pairs(cations, anions, r1, r2, box=None, anion_ids=None)[source]#

Classify each cation of one frame.

Parameters:

cations (numpy.ndarray(n, 3)) – The positions of the cations.
anions (numpy.ndarray(m, 3)) – The positions of the anions’ atoms: one row per anion for monatomic anions, or every atom of polyatomic ones, with anion_ids giving the anion of each row. An anion is within a cutoff when any of its atoms is.
r1 (float) – The contact cutoff, Å (the first minimum of their g(r)).
r2 (float) – The solvent-separated cutoff, Å (the second minimum).
box (numpy.ndarray(6) or None)

Returns:

For each cation: “free” (no anion within r2), “SSIP” (none within r1, one or more within r2), “CIP” (exactly one within r1, in contact with no other cation) or “AGG” (an anion within r1 that is also within r1 of another cation, or more than one within r1).

Return type:

numpy.ndarray of str

liquid_structure_step.analysis.coordination_by_block(rdf_result, cutoff)[source]#: The coordination number within cutoff in each block (run).

liquid_structure_step.analysis.coordination_number(rdf_result, cutoff)[source]#: The coordination number within cutoff and its error, from the running coordination number: the neighbours in the bins wholly within the cutoff.

liquid_structure_step.analysis.find_cutoff(cutoffs, a, b)[source]#: The fixed cutoffs for a pair, in either order, or None.

liquid_structure_step.analysis.hill_formula(symbols)[source]#: The formula of a molecule in Hill order: C, then H, then alphabetical; with no carbon, all alphabetical.

liquid_structure_step.analysis.parse_cutoffs(text)[source]#

Fixed cutoffs: ‘Na-O(H2O): 3.2, Na-Cl: 3.5 5.6’ -> {(a, b): [3.2]…}.

The key is the pair of sites in the order given; one value is a cutoff, two a contact and solvent-separated cutoff for ion pairing.

liquid_structure_step.analysis.parse_pairs(text)[source]#: The pairs in a comma-separated list: [(site, site)].

liquid_structure_step.analysis.peak_and_minimum(r, g, width=0.2, sustain=0.2)[source]#

The first peak and first minimum of a g(r).

The g(r) is smoothed over width Å, and a crossing of 1 counts only when it lasts sustain Å, so that the noise of a sparse pair (a few ions) is not taken for structure. The first peak is the highest point (of the unsmoothed g(r)) of the first stretch above 1; the first minimum the lowest point of the smoothed g(r) between it and the next stretch above 1.

Returns:: peak and peak_height, minimum and minimum_height; None where they cannot be found.
Return type:: dict

liquid_structure_step.analysis.residence_time(members, dt)[source]#

The residence time of solvent molecules in shells, ps: the time at which the normalized autocorrelation of the occupancy, <h(0) h(t)> / <h>, first falls below 1/e (interpolated), or None if it does not within half the run.

Parameters:

members ([set of (solute, solvent molecule)]) – The pairs in contact in each frame.
dt (float) – The interval between frames, ps.

liquid_structure_step.analysis.second_minimum(r, g, first, width=0.2, sustain=0.2)[source]#: The second minimum of a g(r): the lowest point between the peak after the first minimum and the next stretch above 1, or None.

liquid_structure_step.analysis.split_blocks(rows, blocks)[source]#

Consecutive blocks of the rows (frames).

Parameters:

rows (numpy.ndarray or list) – The frames, along the first axis.
blocks (int or [int]) – The number of (nearly) equal blocks, at most one per frame; or the number of frames in each block, which must add up to the number of frames.

Returns:

The blocks; empty blocks are dropped.

Return type:

[numpy.ndarray or list]

liquid_structure_step.analysis.split_pair(text)[source]#: Two sites joined by ‘ - ‘ or, when neither contains a hyphen, ‘-‘.

liquid_structure_step.liquid_structure module#

Non-graphical part of the Liquid Structure step in a SEAMM flowchart

The structure of liquids and solutions from the positions sampled in MD: partial radial distribution functions and coordination numbers, the classification of ion pairs (free, solvent-separated, contact, aggregated), and the solvation shells of solutes (coordination numbers per solvent, the shells’ composition, pairing and residence times). The analysis itself is in liquid_structure_step.analysis.

The MD is run before this step – in a Loop for independent runs – or read from files; the step analyzes it. The errors are from the independent runs, or from blocks of a single run.

class liquid_structure_step.liquid_structure.LiquidStructure(flowchart=None, title='Liquid Structure', extension=None, logger=<Logger liquid_structure_step.liquid_structure (WARNING)>)[source]#

Bases: Node

The non-graphical part of a Liquid Structure step in a flowchart.

parameters#

The control parameters for Liquid Structure.

Type:: LiquidStructureParameters

liquid_structure_step.liquid_structure_parameters module#

Control parameters for the Liquid Structure step in a SEAMM flowchart

class liquid_structure_step.liquid_structure_parameters.LiquidStructureParameters(defaults={}, data=None)[source]#

Bases: Parameters

The control parameters for Liquid Structure.

The MD to analyze is run earlier in the flowchart – in a Loop for independent runs – or in other jobs (see seamm_md_analysis.step_support.source_parameters).

parameters = {'bin width': {'default': 0.02, 'default_units': 'Å', 'description': 'Bin width:', 'enumeration': (), 'format_string': '.3f', 'help_text': 'The width of the bins of the radial distribution functions.', 'kind': 'float'}, 'cutoffs': {'default': '', 'default_units': '', 'description': 'Fixed cutoffs:', 'enumeration': (), 'format_string': 's', 'help_text': "Cutoffs for coordination numbers and ion pairing instead of the minima of the radial distribution functions, e.g. 'Na-O(H2O): 3.2, Na-Cl: 3.5' (Å). Two values for a cation-anion pair give the contact and solvent-separated cutoffs: 'Na-Cl: 3.5 5.6'.", 'kind': 'string'}, 'frame interval': {'default': 1.0, 'default_units': 'ps', 'description': 'Longest interval between frames:', 'enumeration': (), 'format_string': '.2f', 'help_text': 'The positions must be sampled at least this often. The structure changes slowly, so about a picosecond is enough; the residence times need frames ten times as often.', 'kind': 'float'}, 'ion pairing': {'default': 'yes', 'default_units': '', 'description': 'Ion pairing:', 'enumeration': ('yes', 'no'), 'format_string': 's', 'help_text': 'Classify each cation as free, solvent-separated (SSIP), in contact with one anion (CIP), or in an aggregate (AGG).', 'kind': 'boolean'}, 'md files': {'applies_when': {'md source': 'files'}, 'default': '', 'default_units': '', 'description': 'H5MD files:', 'enumeration': (), 'format_string': 's', 'help_text': 'The md.h5md files to analyze, separated by spaces or commas. Each is an independent run. A relative path is in this job; job://<n>/<path> is in job n.', 'kind': 'string'}, 'md source': {'default': 'the last MD run of each loop iteration', 'default_units': '', 'description': 'MD to analyze:', 'enumeration': ('the last MD run', 'the last MD run of each loop iteration', 'files'), 'format_string': 's', 'help_text': "Where the MD for the structure comes from: the last MD run of each iteration of the loop around the MD, as independent runs (or the one run, without a loop); the last MD run earlier in the flowchart; or the H5MD files (md.h5md) of earlier runs, including other jobs' (job://<n>/<path>).", 'kind': 'enum'}, 'number of blocks': {'default': 5, 'default_units': '', 'description': 'Blocks for errors from one run:', 'enumeration': (), 'format_string': 'd', 'help_text': 'When a single MD run is analyzed, it is divided into this many consecutive blocks, which are analyzed separately to estimate the errors. Each block must be much longer than the correlation time.', 'kind': 'integer'}, 'pair list': {'applies_when': {'pairs': 'the pairs given'}, 'default': '', 'default_units': '', 'description': 'Pairs:', 'enumeration': (), 'format_string': 's', 'help_text': "The pairs of sites, separated by commas, each two sites joined by '-' or ' - ': e.g. 'O(H2O)-O(H2O), Na-O(H2O), Na-Cl'. A site is an element of a species, 'O(H2O)'; an element, 'Na'; a species, 'BF4'; or an MDAnalysis selection, 'select: name O'.", 'kind': 'string'}, 'pairs': {'default': 'every pair of elements', 'default_units': '', 'description': 'Radial distribution functions for:', 'enumeration': ('every pair of elements', 'the pairs given'), 'format_string': 's', 'help_text': 'The pairs of sites for the radial distribution functions and coordination numbers.', 'kind': 'enumeration'}, 'r max': {'default': 12.0, 'default_units': 'Å', 'description': 'Range:', 'enumeration': (), 'format_string': '.1f', 'help_text': 'The range of the radial distribution functions, at most half the shortest width of the cell.', 'kind': 'float'}, 'residence times': {'applies_when': {'solvation shells': 'yes'}, 'default': 'no', 'default_units': '', 'description': 'Residence times:', 'enumeration': ('yes', 'no'), 'format_string': 's', 'help_text': 'Also the residence times of the solvents in the solvation shells. They need frames about every 0.1 ps.', 'kind': 'boolean'}, 'solute list': {'applies_when': {'solutes': 'the solutes given', 'solvation shells': 'yes'}, 'default': '', 'default_units': '', 'description': 'Solutes:', 'enumeration': (), 'format_string': 's', 'help_text': "The solute species, separated by commas, e.g. 'Li, Na'.", 'kind': 'string'}, 'solutes': {'applies_when': {'solvation shells': 'yes'}, 'default': 'the monatomic ions', 'default_units': '', 'description': 'Solutes:', 'enumeration': ('the monatomic ions', 'the solutes given'), 'format_string': 's', 'help_text': 'The species whose solvation shells are analyzed.', 'kind': 'enumeration'}, 'solvation shells': {'default': 'yes', 'default_units': '', 'description': 'Solvation shells:', 'enumeration': ('yes', 'no'), 'format_string': 's', 'help_text': "Analyze the solvation shells of the solutes: the coordination number of each species, the shells' composition, and pairing. Without a periodic cell, only for the species given fixed cutoffs.", 'kind': 'boolean'}, 'store': {'default': 'no', 'default_units': '', 'description': 'Store as properties:', 'enumeration': ('yes', 'no'), 'format_string': 's', 'help_text': 'Store the coordination numbers and ion-pairing fractions as properties of the configuration.', 'kind': 'boolean'}}#

retired = ('nruns', 'errors')#

an older flowchart that stores them can still be read, and they are ignored. Any other unknown parameter is an error. A plug-in’s Parameters class sets this.

Type:: Parameters the step had once and has dropped

liquid_structure_step.liquid_structure_step module#

class liquid_structure_step.liquid_structure_step.LiquidStructureStep(flowchart=None, gui=None)[source]#

Bases: object

Helper class needed for the stevedore integration.

This must provide a description() method that returns a dict containing a description of this node, and create_node() and create_tk_node() methods for creating the graphical and non-graphical nodes.

The dictionary for the description is the class variable just below these comments. The felds are as follows:

my_description{str, str}
A human-readable description of this step. It can be several lines long, and needs to be clear to non-expert users. It contains the following keys: description, group, name.

my_description[“description”]tuple
A description of the Liquid Structure step. It must be clear to non-experts.

my_description[“group”]str
Which group in the menus to put this step. If the group does not exist it will be created. Common groups are “Building”, “Control”, “Custom”, “Data”, and “Simulations”.

my_description[“name”]str
The name of this step, to be displayed in the menus.

create_node(flowchart=None, **kwargs)[source]#

Create and return the new node object.

Parameters:

flowchart (seamm.Node) – A non-graphical SEAMM node
**kwargs (keyword arguments) – Various keyword arguments such as title, namespace or extension representing the title displayed in the flowchart, the namespace for the plugins of a subflowchart and the extension, respectively.

Return type:

LiquidStructure

create_tk_node(canvas=None, **kwargs)[source]#

Create and return the graphical Tk node object.

Parameters:

canvas (tk.Canvas) – The Tk Canvas widget
**kwargs (keyword arguments) – Various keyword arguments such as tk_flowchart, node, x, y, w, h representing a graphical flowchart object, a non-graphical node for a step, and dimensions of the graphical node.

Return type:

TkLiquidStructure

description()[source]#

Return a description of what this step does.

Returns:: description
Return type:: dict(str, str)

my_description = {'description': 'The structure of liquids and solutions from MD: radial distribution functions, coordination numbers, ion pairing and solvation shells', 'group': 'Analysis', 'name': 'Liquid Structure'}#

liquid_structure_step.metadata module#

This file contains metadata describing the results from LiquidStructure

liquid_structure_step.metadata.metadata = {'results': {'P': {'description': 'The mean pressure', 'dimensionality': 'scalar', 'type': 'float', 'units': 'atm'}, 'P,stderr': {'description': 'The standard error of the pressure', 'dimensionality': 'scalar', 'type': 'float', 'units': 'atm'}, 'T': {'description': 'The mean temperature', 'dimensionality': 'scalar', 'type': 'float', 'units': 'K'}, 'T,stderr': {'description': 'The standard error of the temperature', 'dimensionality': 'scalar', 'type': 'float', 'units': 'K'}, 'V': {'description': 'The mean volume', 'dimensionality': 'scalar', 'type': 'float', 'units': 'Å^3'}, 'bulk modulus': {'description': 'The bulk modulus used for the equilibrium density, from an NPT run', 'dimensionality': 'scalar', 'type': 'float', 'units': 'atm'}, 'coordination numbers': {'description': "For each pair of sites, the first peak (Å), its height and the first minimum (Å) of g(r), the cutoff (Å) and the coordination number (CN), each with its standard error (e.g. 'CN,stderr')", 'dimensionality': '{pair: {key: value}}', 'property': 'coordination numbers#Liquid Structure#{model}', 'type': 'json'}, 'density': {'description': 'The mean density', 'dimensionality': 'scalar', 'type': 'float', 'units': 'g/mL'}, 'density,stderr': {'description': 'The standard error of the density', 'dimensionality': 'scalar', 'type': 'float', 'units': 'g/mL'}, 'equilibrium density': {'description': 'The estimated density at the target pressure of runs at constant volume', 'dimensionality': 'scalar', 'type': 'float', 'units': 'g/mL'}, 'equilibrium density,stderr': {'description': 'The standard error of the estimated equilibrium density', 'dimensionality': 'scalar', 'type': 'float', 'units': 'g/mL'}, 'error source': {'description': "What the standard errors are from: the independent 'runs', or 'blocks' of a single run", 'dimensionality': 'scalar', 'type': 'string'}, 'ion pairing': {'description': "For each cation-anion pair, the cutoffs r1 and r2 (Å) and the fractions of the cations that are free, SSIP, CIP and AGG, with their standard errors ('fractions,stderr')", 'dimensionality': '{pair: {key: value}}', 'property': 'ion pairing#Liquid Structure#{model}', 'type': 'json'}, 'n_frames': {'description': 'The number of frames analyzed', 'dimensionality': 'scalar', 'type': 'integer'}, 'n_samples': {'description': 'The number of runs or blocks the standard errors are from', 'dimensionality': 'scalar', 'type': 'integer'}, 'nruns': {'description': 'The number of MD runs analyzed', 'dimensionality': 'scalar', 'type': 'integer'}, 'solvation shells': {'description': "For each solute, the cutoff, coordination number and pairing of each species, the most common shells, and the residence times (ps), each with its standard error (e.g. 'coordination,stderr')", 'dimensionality': '{solute: {key: value}}', 'type': 'json'}}}#

Description of the computational models for LiquidStructure.

Hamiltonians, approximations, and basis set or parameterizations, only if appropriate for this code. For example:

metadata["computational models"] = {
    "Hartree-Fock": {
        "models": {
            "PM7": {
                "parameterizations": {
                    "PM7": {
                        "elements": "1-60,62-83",
                        "periodic": True,
                        "reactions": True,
                        "optimization": True,
                        "code": "mopac",
                    },
                    "PM7-TS": {
                        "elements": "1-60,62-83",
                        "periodic": True,
                        "reactions": True,
                        "optimization": False,
                        "code": "mopac",
                    },
                },
            },
        },
    },
}

liquid_structure_step.tk_liquid_structure module#

The graphical part of a LiquidStructure step

class liquid_structure_step.tk_liquid_structure.TkLiquidStructure(tk_flowchart=None, node=None, namespace='org.molssi.seamm.tk', canvas=None, x=None, y=None, w=200, h=50)[source]#

Bases: TkNode

The graphical part of a LiquidStructure step in a flowchart.

tk_flowchart#

The flowchart that we belong to.

Type:: TkFlowchart = None

node#

The corresponding node of the non-graphical flowchart

Type:: Node = None

canvas#

The Tk Canvas to draw on

Type:: tkCanvas = None

dialog#

The Pmw dialog object

Type:: Dialog

x#

The x-coordinate of the center of the picture of the node

Type:: int = None

y#

The y-coordinate of the center of the picture of the node

Type:: int = None

w#

The width in pixels of the picture of the node

Type:: int = 200

h#

The height in pixels of the picture of the node

Type:: int = 50

self[widget]#

A dictionary of tk widgets built using the information contained in LiquidStructure parameterss.py

Type:: dict

Module contents#

liquid_structure_step A SEAMM plug-in for Liquid Structure