atomic_charges_step package#

Submodules#

atomic_charges_step.atomic_charges module#

Non-graphical part of the Atomic Charges step in a SEAMM flowchart.

This is a post-processing step: a preceding quantum-chemistry step produces an electron density, and this step partitions that density into per-atom charges using an external program (Chargemol for DDEC6, the Henkelman code for Bader). The resulting charges are written back onto the configuration as a labeled charge set, charges_<label> – the same convention used by seamm_ff_util – so several schemes can coexist on one structure.

Status:

Molecular DDEC6 via Chargemol from a Gaussian .wfx is implemented and validated end-to-end (g09 -> wfx -> Chargemol -> parse -> store). ORCA feeds the same path: its Energy substep writes orca.wfx via orca_2aim, validated end-to-end (ORCA -> wfx -> Chargemol).
ORCA’s orca_2aim always writes <Net Charge> 0.0 in the .wfx, regardless of the molecule’s actual charge (confirmed on ORCA 6.1.1, for both a cation and an anion) – right only by coincidence for a neutral system. Chargemol cross-checks that field against the (correct) electron count from the wavefunction itself and refuses to run when they disagree, reporting that “the quantum chemistry program … contains a bug.” _run_ddec6 works around this by rewriting <Net Charge> to configuration.charge (which SEAMM already knows, and which is exactly what drove the preceding ORCA job) before Chargemol ever sees the file.
The density handoff (_locate_density) reads a .wfx from the preceding step’s directory (preferred), recognizing .cube as well. A uniform cube cannot represent the all-electron core, so molecular cube input is rejected; periodic CHGCAR/AECCAR support will come with VASP.
The Bader backend raises a clear NotImplementedError: the Henkelman code reads a density grid (molecular cube or VASP CHGCAR/AECCAR), never a .wfx, and molecular all-electron cubes hit the same core-cusp limit as cube-based DDEC6. It will be implemented with periodic (VASP) support.
Citations: the DDEC6 (Manz & Limas) and Bader (Henkelman group) methodology papers are cited per the method actually run.

class atomic_charges_step.atomic_charges.AtomicCharges(flowchart=None, title='Atomic Charges', extension=None, logger=<Logger atomic_charges_step.atomic_charges (WARNING)>)[source]#

Bases: Node

The non-graphical part of an Atomic Charges step in a flowchart.

See also

TkAtomicCharges, AtomicCharges, AtomicChargesParameters

analyze(indent='', P=None, results=None, **kwargs)[source]#

Report the charge results: always write a CSV, and print a per-atom table for small systems.

Parameters:: indent (str) – An extra indentation for the output

create_parser()[source]#

Set up the command-line / seamm.ini parser for this step.

Adds --max-atoms-to-print (default 20), overridable in the [atomic-charges-step] section of seamm.ini.

description_text(P=None)[source]#

Create the text description of what this step will do.

Parameters:: P (dict) – An optional dictionary of the current values of the control parameters.
Returns:: A description of the current step.
Return type:: str

property git_revision#: The git version of this module.

run()[source]#

Run an Atomic Charges step.

Returns:: The next node object in the flowchart.
Return type:: seamm.Node

property version#: The semantic version of this module.

atomic_charges_step.atomic_charges_parameters module#

Control parameters for the Atomic Charges step in a SEAMM flowchart

class atomic_charges_step.atomic_charges_parameters.AtomicChargesParameters(defaults={}, data=None)[source]#

Bases: Parameters

The control parameters for the Atomic Charges step.

Parameters:: parameters ({str: {str: str}}) – A dictionary describing each control parameter, keyed by the parameter name. See seamm.Parameters for the full description of each field (“default”, “kind”, “default_units”, “enumeration”, “format_string”, “description”, “help_text”).

See also

AtomicCharges, TkAtomicCharges

parameters = {'apply to structure': {'default': 'no', 'default_units': '', 'description': 'Set as the atomic charges on the structure:', 'enumeration': ('no', 'yes'), 'format_string': '', 'help_text': "Also store the computed charges as the structure's per-atom charge (the standard 'charge' attribute), in addition to the labeled 'charges_<label>' column. Turn this on to have the charges written out with the structure -- e.g. to an extended XYZ (extxyz) file for machine-learning training. With more than one charge method, the last one applied wins.", 'kind': 'enum'}, 'atomic densities directory': {'default': '~/SEAMM/atomic_charges/atomic_densities', 'default_units': '', 'description': 'DDEC reference densities:', 'enumeration': (), 'format_string': '', 'help_text': 'Directory containing the reference atomic densities required by Chargemol for DDEC6. If this path does not exist, the copy bundled in the seamm-chargemol conda environment is used automatically. Ignored for the Bader method.', 'kind': 'string'}, 'charge label': {'default': '<method>', 'default_units': '', 'description': 'Store charges as:', 'enumeration': ('<method>',), 'format_string': '', 'help_text': "Label for the charge set written onto the atoms. The charges are stored in the configuration as the attribute 'charges_<label>', so several schemes can coexist on the same structure. The default '<method>' uses the method name, e.g. 'charges_DDEC6'.", 'kind': 'string'}, 'density files': {'default': '', 'default_units': '', 'description': 'Density file(s):', 'enumeration': (), 'format_string': '', 'help_text': 'Explicit path(s) to the density grid/cube file(s) when not taking them from the previous step. For VASP this is the directory holding CHGCAR plus AECCAR0/AECCAR2; for molecular codes a .cube or .wfx.', 'kind': 'string'}, 'density source': {'default': 'from the previous step in the flowchart', 'default_units': '', 'description': 'Electron density:', 'enumeration': ('from the previous step in the flowchart', 'from files'), 'format_string': '', 'help_text': 'Where to obtain the electron density. Normally it is taken from the quantum-chemistry step immediately preceding this one, which must have been told to write its (all-electron) density.', 'kind': 'enum'}, 'enforce net charge': {'default': 'yes', 'default_units': '', 'description': 'Enforce the total charge:', 'enumeration': ('yes', 'no'), 'format_string': '', 'help_text': 'Shift the charges uniformly so they sum exactly to the known net charge of the system, removing the small residual left by grid / numerical integration. The residual is reported. Turn off to keep the raw charges from the partitioning program.', 'kind': 'enum'}, 'method': {'default': 'DDEC6', 'default_units': '', 'description': 'Charge method:', 'enumeration': ('DDEC6', 'Bader', 'DDEC6 and Bader'), 'format_string': '', 'help_text': 'The density-partitioning scheme used to assign atomic charges. DDEC6 (via Chargemol) gives ESP-faithful, transferable charges; Bader (via the Henkelman code) gives a rigorous topological partition. Both work for molecular and periodic systems.', 'kind': 'enum'}, 'results': {'default': {}, 'default_units': '', 'description': 'results', 'enumeration': (), 'format_string': '', 'help_text': 'The results to save to variables or in tables.', 'kind': 'dictionary'}}#

atomic_charges_step.atomic_charges_step module#

class atomic_charges_step.atomic_charges_step.AtomicChargesStep(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.

my_description#

A human-readable description of this step, with the keys “description”, “group”, and “name”.

Type:: {str, str}

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

Create and return the new node object.

Parameters:: flowchart (seamm.Flowchart) – The non-graphical flowchart this node is part of.
Return type:: AtomicCharges

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

Create and return the graphical Tk node object.

Parameters:: canvas (tk.Canvas) – The Tk Canvas widget
Return type:: TkAtomicCharges

description()[source]#

Return a description of what this step does.

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

my_description = {'description': 'Compute atomic (partial) charges from the electron density produced by a preceding quantum-chemistry step.', 'group': 'Analysis', 'name': 'Atomic Charges'}#

atomic_charges_step.installer module#

atomic_charges_step.metadata module#

This file contains metadata describing the results from the Atomic Charges step.

atomic_charges_step.metadata.metadata = {'computational models': {'Charge Partitioning': {'models': {'Bader': {'parameterizations': {'Bader': {'description': 'Bader / QTAIM topological partition of the density into zero-flux basins.', 'periodic': True, 'program': 'bader', 'reference': 'Henkelman, Arnaldsson & Jonsson, Comput. Mater. Sci. 36, 354 (2006)'}}}, 'DDEC6': {'parameterizations': {'DDEC6': {'description': 'Density Derived Electrostatic and Chemical charges; ESP-faithful and chemically transferable.', 'periodic': True, 'program': 'Chargemol', 'reference': 'Manz & Limas, RSC Adv. 6, 47771 (2016)'}}}}}}, 'results': {'atomic charges': {'description': 'The partial charge on each atom', 'dimensionality': ['n_atoms'], 'type': 'float', 'units': 'e'}, 'charge residual': {'description': 'Residual removed (raw sum minus the system charge) when enforcing the net charge', 'dimensionality': 'scalar', 'type': 'float', 'units': 'e'}, 'method': {'description': 'The charge-partitioning method used', 'dimensionality': 'scalar', 'type': 'string'}, 'net charge': {'description': 'Sum of the atomic charges (check against the system charge)', 'dimensionality': 'scalar', 'type': 'float', 'units': 'e'}}}#

Description of the computational models for Atomic Charges.

Atomic charges are not a single well-defined quantity, so this step exposes the partitioning schemes it can run. This mirrors the metadata["computational models"] convention used by the QM steps, kept deliberately small here.

atomic_charges_step.tk_atomic_charges module#

The graphical part of an Atomic Charges step

class atomic_charges_step.tk_atomic_charges.TkAtomicCharges(tk_flowchart=None, node=None, canvas=None, x=None, y=None, w=200, h=50)[source]#

Bases: TkNode

The graphical part of an Atomic Charges step in a flowchart.

See also

AtomicCharges, AtomicChargesParameters

create_dialog()[source]#: Create the dialog, building the widgets from the parameters.

See also

TkAtomicCharges.reset_dialog

reset_dialog(widget=None)[source]#

Lay out the widgets, showing only those relevant to the choices.

Parameters:: widget (Tk Widget = None) – The widget that triggered the reset, if any.

right_click(event)[source]#

Handle the right-click event on the node.

Parameters:: event (Tk Event)

See also

TkAtomicCharges.edit

Module contents#

atomic_charges_step A SEAMM plug-in for computing atomic (partial) charges from a converged electron density (DDEC6 via Chargemol, Bader via the Henkelman code).