mbe_step package#

Submodules#

mbe_step.counterpoise module#

Pairwise counterpoise for the MBE step, through seamm_bsse.

For a selected pair, the Boys-Bernardi correction needs each monomer in the pair’s basis (the other monomer’s atoms as ghosts): two extra calculations per pair at each molecular level. With the pair itself and the two monomers (both already computed as fragments), seamm_bsse.combine gives the counterpoise- corrected pair energy and gradient, guarded against unphysical ghost gradients.

The correction enters the sum only (seamm_mbe’s corrections): with [high - low] for the pair,

correction = (E_high^CP - E_high) - (E_low^CP - E_low)

the second term only when the pair is referenced to the molecular low level (a plane-wave periodic level has no basis-set superposition error). Triples still subtract the uncorrected pairs.

mbe_step.counterpoise.correction(system, fragments, pair, results, prefix)[source]#

The counterpoise correction of one pair at one level.

Parameters:

results ({str: EvaluatorResult}) – The level’s results by key (the pair, its monomers and its ghost jobs).

Returns:

energy (float) – E^CP - E for the pair, eV.
forces (numpy.ndarray) – (n_atoms, 3) the change of the pair’s forces, eV/Å.
fallback (bool) – Whether seamm_bsse kept the uncorrected gradient (unphysical ghost gradients: the energy is corrected, the forces are not).

mbe_step.counterpoise.ghost_jobs(system, pair)[source]#: The extra calculations for a pair: {label: (structure, options)} for each monomer in the pair’s basis.

mbe_step.counterpoise.key(prefix, pair_name, label)[source]#: The task key of a ghost job.

mbe_step.counterpoise.specs(system, pair)[source]#: The seamm_bsse job specs for a pair (atom indices within the pair).

mbe_step.labels module#

Helpers of the MBE step that need no flowchart: parsing the cutoff and offset tables, the stress layout, and the extended XYZ labels file.

mbe_step.labels.counts_text(fragments)[source]#: ‘64 monomers, 391 pairs (+268 outer), 559 triples’.

mbe_step.labels.parse_offsets(text)[source]#: Energy offsets in eV per molecule by type, from entries ‘type value’ separated by ‘;’ or new lines, or None for ‘none’ or an empty text.

mbe_step.labels.parse_table(text, what='cutoff')[source]#

A table of values by molecule-type pair.

Parameters:: text (str) – Entries ‘type type value’ separated by ‘;’ or new lines, e.g. ‘water water 4.5; Li+ * 3.0’. ‘*’ matches any type.
Returns:: {(str, str)
Return type:: float}

mbe_step.labels.to_seamm(labels, volume)[source]#: The labels in SEAMM’s units for store_results: energies kJ/mol, gradients kJ/mol/Å, stress Voigt [6] in GPa as sigma = -P, pressures in atm.

mbe_step.labels.voigt(tensor)[source]#: A (3, 3) tensor as Voigt [6]: xx yy zz yz xz xy (symmetrized).

mbe_step.labels.write_extxyz(path, system, labels, *, name, model, identifier=None, counterpoise=False, extra='')[source]#

Add one configuration’s labels to an extended XYZ file.

The file collects configurations (several in one step, or across a loop’s iterations when it is a job-level file). Writing is idempotent: an earlier frame with the same identifier (SEAMM/configuration_id) is replaced, so rerunning a job does not duplicate labels.

The columns are species, pos and REF_forces (eV/Å); the header carries REF_energy (eV, the reference scale), REF_stress (the nine values of sigma = -P in eV/Å³, for a cell), the Lattice and pbc, the model, whether counterpoise was used and the configuration’s name. Note that ASE reads the nine-value REF_stress as a flat vector: a reader must reshape it.

mbe_step.levels module#

The MBE step’s levels of theory: resolving their model chemistries and evaluating structures with each through seamm_exec’s Evaluator.

The step uses up to four levels:

high: every fragment (by default the flowchart’s current Model Chemistry);
molecular: the molecular low level, on the fragments referenced to it;
periodic: the periodic low level, on the compact fragments referenced to it;
cell: the low level of the whole cell (or cluster).

Each level is one Evaluator with its own directory, so each keeps its own task manifest (restart) and bundles; the Evaluator chooses how the level runs (batch tasks or an MDI engine). In this phase the levels run one after the other; running them concurrently is a seamm_exec follow-up.

mbe_step.levels.CURRENT = 'current model chemistry'#: The sentinel for the flowchart’s current Model Chemistry

class mbe_step.levels.Level(name, mc, *, ranks, memory, bundle, walltime, archive)[source]#

Bases: object

One level of theory and how it runs.

Parameters:

name (str) – “high”, “molecular”, “periodic” or “cell”; also the directory name.
mc (dict) – The _model_chemistry wrapper.
ranks (int) – MPI ranks per calculation.
memory (float) – Memory per rank, in MB.
bundle (int) – Calculations per batch job on a queue.
walltime (float) – Seconds per batch job.
archive (bool) – Tar finished bundles.

evaluate(node, structures, *, stress=False)[source]#

Evaluate structures at this level.

Parameters:

node (seamm.Node) – The MBE step.
structures ({str: object}) – Configurations or seamm_exec.Geometry objects by key.
stress (bool) – Request the stress (for a periodic cell).

Returns:

{str

Return type:

seamm_exec.EvaluatorResult}

property level#

resources()[source]#

mbe_step.levels.geometry(system, fragment)[source]#: The isolated fragment as a seamm_exec.Geometry: its atoms in fragment order at the fragment’s coordinates, with its charge and multiplicity.

mbe_step.levels.resolve(text, context, current=None, periodic=False)[source]#

The _model_chemistry wrapper for a level given as text.

Parameters:

text (str) – A level spec such as "ORCA:DFT@r2SCAN-D4/def2-TZVPPD", possibly with $variable components, or CURRENT.
context (dict) – The flowchart variables, to dereference any $variable.
current (dict or None) – The flowchart’s _model_chemistry, for CURRENT.
periodic (bool) – Whether the level must handle periodic systems.

Returns:

The _model_chemistry wrapper: level, step, options, …

Return type:

dict

mbe_step.levels.stress_convention(mc)[source]#: The sign convention of a level’s stress, as its provider declares it (“pressure” or “stress”); refuse a periodic level that does not.

mbe_step.levels.to_library(result, *, volume=None, convention=None)[source]#: An EvaluatorResult in seamm_mbe’s units: (energy eV, forces eV/Å), plus the virial (eV) when the result has a stress.

mbe_step.levels.whole(system)[source]#: The whole cell or cluster as a seamm_exec.Geometry with the charge the molecules add up to (their types’ charges, from the formal charges or the catalog) – the same charges the fragments use – and multiplicity 1 (open-shell molecules are refused before this).

mbe_step.mbe module#

Non-graphical part of the MBE step in a SEAMM flowchart

class mbe_step.mbe.Mbe(flowchart=None, title='MBE', extension=None, logger=<Logger mbe_step.mbe (WARNING)>)[source]#

Bases: Node

The non-graphical part of a MBE step in a flowchart.

parser#

The parser object.

Type:: configargparse.ArgParser

options#

It contains a two item tuple containing the populated namespace and the list of remaining argument strings.

Type:: tuple

parameters#

The control parameters for MBE.

Type:: MbeParameters

mbe_step.mbe_parameters module#

Control parameters for the MBE step in a SEAMM flowchart

mbe_step.mbe_parameters.CRITERIA = {'center of geometry': 'cog', 'center of mass': 'com', 'closest contact': 'contact', 'closest heavy-atom contact': 'heavy contact', 'designated atoms': 'designated'}#: The distance criteria, as shown, and their names in seamm_mbe

class mbe_step.mbe_parameters.MbeParameters(defaults={}, data=None)[source]#

Bases: Parameters

The control parameters for the MBE step.

The step corrects a cheap calculation of a whole periodic cell (or cluster) with many-body increments of [high - low] computed on small isolated fragments: monomers, selected pairs and triples. The bookkeeping is in the seamm_mbe library; this step runs the calculations through each level’s Model Chemistry.

mbe_step.mbe_step module#

class mbe_step.mbe_step.MbeStep(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 MBE 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:

Mbe

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:

TkMbe

description()[source]#

Return a description of what this step does.

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

my_description = {'description': 'Many-body expansion (MBE) corrections of periodic cells and clusters', 'group': 'Simulations', 'name': 'MBE'}#

mbe_step.metadata module#

This file contains metadata describing the results from Mbe

mbe_step.metadata.metadata = {'results': {'MBE energy': {'description': 'The many-body correction to the energy', 'dimensionality': 'scalar', 'type': 'float', 'units': 'kJ/mol'}, 'MBE pressure': {'description': "The many-body correction's contribution to the pressure", 'dimensionality': 'scalar', 'format': '.1f', 'type': 'float', 'units': 'atm'}, 'configuration name': {'description': 'The configuration', 'dimensionality': 'scalar', 'type': 'string', 'units': ''}, 'counterpoise correction': {'description': 'The pairwise counterpoise correction to the energy', 'dimensionality': 'scalar', 'format': '.3f', 'type': 'float', 'units': 'kJ/mol'}, 'counterpoise fallbacks': {'description': 'Pairs whose counterpoise gradient was unphysical (forces left uncorrected)', 'dimensionality': 'scalar', 'type': 'integer', 'units': ''}, 'energy': {'description': 'The MBE-corrected total energy', 'dimensionality': 'scalar', 'format': '.3f', 'property': 'energy#MBE#{model}', 'type': 'float', 'units': 'kJ/mol'}, 'fragment counts': {'description': 'The selected and auxiliary fragments by order', 'dimensionality': 'json', 'type': 'json', 'units': ''}, 'gradients': {'description': 'The MBE-corrected gradients', 'dimensionality': '[n_atoms, 3]', 'property': 'gradients#MBE#{model}', 'type': 'json', 'units': 'kJ/mol/Å'}, 'maximum force': {'description': 'The largest Cartesian component of the forces', 'dimensionality': 'scalar', 'type': 'float', 'units': 'kJ/mol/Å'}, 'maximum increment net force': {'description': "The largest component of any increment's net force (ideally zero)", 'dimensionality': 'scalar', 'type': 'float', 'units': 'kJ/mol/Å'}, 'model chemistry': {'description': 'The high level', 'dimensionality': 'scalar', 'type': 'string', 'units': ''}, 'molecular pressure': {'description': 'The molecular configurational pressure', 'dimensionality': 'scalar', 'format': '.1f', 'type': 'float', 'units': 'atm'}, 'per-body energies': {'description': 'The correction to the energy by order, in kJ/mol', 'dimensionality': 'json', 'type': 'json', 'units': ''}, 'per-body pressures': {'description': 'The correction to the pressure by order, in atm', 'dimensionality': 'json', 'type': 'json', 'units': ''}, 'pressure': {'description': 'The atomic configurational pressure', 'dimensionality': 'scalar', 'format': '.1f', 'type': 'float', 'units': 'atm'}, 'reference energy': {'description': 'The energy on the reference scale of the labels (with the offsets)', 'dimensionality': 'scalar', 'format': '.3f', 'type': 'float', 'units': 'kJ/mol'}, 'rms force': {'description': 'The RMS force on the atoms', 'dimensionality': 'scalar', 'type': 'float', 'units': 'kJ/mol/Å'}, 'stress': {'description': 'The MBE-corrected stress, Voigt xx yy zz yz xz xy, sigma = -P', 'dimensionality': '[6]', 'format': '.4f', 'property': 'stress#MBE#{model}', 'type': 'json', 'units': 'GPa'}}}#

Description of the computational models for Mbe.

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",
                    },
                },
            },
        },
    },
}

mbe_step.tk_mbe module#

The graphical part of a MBE step

mbe_step.tk_mbe.DRIVERS = ('maximum order', 'cutoffs', 'triple rule', 'periodic low level')#: Parameters whose value changes the layout

mbe_step.tk_mbe.GROUPS = {'assignment': ('Periodic low level', ('periodic monomers', 'periodic pair cutoff', 'grid spacing', 'box padding')), 'execution': ('Execution', ('molecular ranks', 'molecular memory', 'molecular bundle', 'periodic ranks', 'periodic memory', 'periodic bundle', 'cell ranks', 'cell memory', 'bundle walltime', 'archive')), 'fragments': ('Fragments', ('maximum order', 'distance criterion', 'cutoffs', 'pair cutoff', 'pair cutoff table', 'triple rule', 'triple cutoff', 'triple cutoff table', 'counterpoise')), 'labels': ('Labels', ('energy offsets', 'extxyz file')), 'levels': ('Levels of theory', ('high level', 'molecular low level', 'periodic low level', 'cell low level'))}#: The parameters of each group, in order

class mbe_step.tk_mbe.TkMbe(tk_flowchart=None, node=None, canvas=None, x=None, y=None, w=200, h=50)[source]#

Bases: TkNode

The graphical part of a MBE step in a flowchart.

The dialog shows only what applies (Paul’s rule: invalid combinations are not offered): the triple controls only for order 3, the pair controls only from order 2, single cutoffs or the type-pair tables but not both, and the periodic-assignment controls only with a periodic low level. The order is capped at 3 here; 4-body terms are designed for in seamm_mbe but not yet validated. The level fields offer the installed model chemistries and accept a typed one, or a $variable.

create_dialog()[source]#: Create the dialog: a Parameters tab and the standard Results tab.

reset_dialog(widget=None)[source]#: Lay out the dialog for the current choices.

right_click(event)[source]#: Handle a right-click: add the Edit… item and post the menu.

shown()[source]#: The parameters that apply to the current choices.

Module contents#

mbe_step A SEAMM plug-in for many-body expansion (MBE) corrections of periodic cells and clusters