energy_step package

Submodules

energy_step.energy module

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

The Energy step evaluates the energy, and optionally the gradients (forces) and stress, of one or many structures using the Model Chemistry published upstream (the _model_chemistry workspace variable), through seamm_exec’s Evaluator, which chooses how:

• over MDI: the program as a resident engine, started once per distinct topology (elements, charge, multiplicity, periodicity) and fed the structures one after another over the warm connection, so labelling hundreds of structures – e.g. with a machine-learned force field – costs a single engine start-up;

• as tasks: one calculation per structure, run concurrently in the local pool or bundled on the job’s queue (ORCA, which runs once per structure anyway, and any model chemistry whose job sends its tasks to a cluster). A rerun keeps the finished ones.

Results are stored per configuration: the energy, gradients and stress as properties, and the gradients also on the atoms (so downstream writers such as the extended-XYZ format emit them as forces).

class energy_step.energy.Energy(flowchart=None, title='Energy', extension=None, logger=<Logger energy_step.energy (WARNING)>)

Bases: Node

The non-graphical part of an Energy 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 Energy.

Type:

EnergyParameters

See also

TkEnergy, Energy, EnergyParameters

analyze(P=None, rows=None, model_chemistry='', n_engines=1, how=None, elapsed=0.0, directory=None, indent='', **kwargs)

Summarize the results to the step’s output and energies.csv.

description_text(P=None)

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()

Run an Energy step.

Returns:

The next node object in the flowchart.

Return type:

seamm.Node

property version

The semantic version of this module.

energy_step.energy_parameters module

Control parameters for the Energy step in a SEAMM flowchart

class energy_step.energy_parameters.EnergyParameters(defaults={}, data=None)

Bases: Parameters

The control parameters for the Energy step.

The step evaluates the energy (and optionally the gradients and, for periodic systems, the stress) of one or many structures with the Model Chemistry published upstream, driving the program as a resident MDI engine so that hundreds of structures cost one engine start-up.

See also

Energy, TkEnergy, EnergyParameters, EnergyStep

parameters = {'gradients': {'default': 'yes', 'default_units': '', 'description': 'Calculate the gradients (forces):', 'enumeration': ('yes', 'no'), 'format_string': '', 'help_text': "Whether to also calculate the gradients (forces) on the atoms. They are stored on the atoms of each configuration, so e.g. the Write Structure step's extended XYZ output carries them as REF_forces, and as the property gradients#Energy#<model>.", 'kind': 'boolean'}, 'results': {'default': {}, 'default_units': None, 'description': 'results', 'enumeration': (), 'format_string': '', 'help_text': 'The results to save to variables or in tables.', 'kind': 'dictionary'}, 'source configuration name': {'default': '', 'default_units': '', 'description': '', 'enumeration': (), 'format_string': 's', 'help_text': 'The configuration name, wildcard pattern or regular expression.', 'kind': 'string'}, 'source configurations': {'default': 'current', 'default_units': '', 'description': 'Configurations:', 'enumeration': ('current', 'all', 'last', 'first', 'name is', 'name matches', 'name regexp'), 'format_string': 's', 'help_text': 'Which configurations of each selected system to use: its current configuration, all of them, the last or first, or those whose name is / matches (shell wildcards) / matches the regular expression given.', 'kind': 'string'}, 'source system name': {'default': '', 'default_units': '', 'description': '', 'enumeration': (), 'format_string': 's', 'help_text': 'The system name, wildcard pattern or regular expression.', 'kind': 'string'}, 'source systems': {'default': 'current', 'default_units': '', 'description': 'Systems:', 'enumeration': ('current', 'all', 'name is', 'name matches', 'name regexp'), 'format_string': 's', 'help_text': 'Which systems to take the structures from: the current system, all systems, or those whose name is / matches (shell wildcards) / matches the regular expression given. A variable ($name) holding a list of configurations or of systems may also be given.', 'kind': 'string'}, 'stress': {'default': 'yes', 'default_units': '', 'description': 'Calculate the stress (periodic systems):', 'enumeration': ('yes', 'no'), 'format_string': '', 'help_text': 'Whether to also calculate the stress tensor for periodic systems. Ignored for molecular systems.', 'kind': 'boolean'}}

energy_step.energy_step module

class energy_step.energy_step.EnergyStep(flowchart=None, gui=None)

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. It can be several lines long, and needs to be clear to non-expert users. It contains the following keys: description, group, name.

Type:

{description, group, name}

my_description[]

A description of the Energy step. It must be clear to non-experts.

Type:

tuple

my_description[]

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

Type:

str

my_description[]

The name of this step, to be displayed in the menus.

Type:

str

create_node(flowchart=None, **kwargs)

Create and return the new node object.

Parameters:

• flowchart (seamm.Node) – A non-graphical SEAMM node

• **kwargs (keyworded arguments) – Various keyworded 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:

Energy

See also

Energy

create_tk_node(canvas=None, **kwargs)

Create and return the graphical Tk node object.

Parameters:

• canvas (tk.Canvas) – The Tk Canvas widget

• **kwargs (keyworded arguments) – Various keyworded 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:

TkEnergy

See also

TkEnergy

description()

Return a description of what this extension does.

my_description = {'description': 'An interface for Energy', 'group': 'Simulations', 'name': 'Energy'}

energy_step.metadata module

This file contains metadata describing the results from the Energy step.

energy_step.metadata.metadata = {'results': {'configuration name': {'description': 'The name of the configuration evaluated', 'dimensionality': 'scalar', 'type': 'string'}, 'elapsed time': {'description': 'Wall-clock time for this evaluation', 'dimensionality': 'scalar', 'format': '.3f', 'type': 'float', 'units': 's'}, 'energy': {'description': 'The energy of the structure', 'dimensionality': 'scalar', 'format': '.3f', 'property': 'energy#Energy#{model}', 'type': 'float', 'units': 'kJ/mol'}, 'gradients': {'description': 'The gradients on the atoms', 'dimensionality': '[n_atoms][3]', 'format': '.3f', 'property': 'gradients#Energy#{model}', 'type': 'json', 'units': 'kJ/mol/Å'}, 'maximum force': {'description': 'The largest force component on any atom', 'dimensionality': 'scalar', 'format': '.3f', 'type': 'float', 'units': 'kJ/mol/Å'}, 'model chemistry': {'description': 'The model chemistry (level spec) used', 'dimensionality': 'scalar', 'type': 'string'}, 'rms force': {'description': 'The root-mean-square force component', 'dimensionality': 'scalar', 'format': '.3f', 'type': 'float', 'units': 'kJ/mol/Å'}, 'stress': {'description': 'The stress tensor (periodic systems only)', 'dimensionality': '[3][3]', 'format': '.4f', 'property': 'stress#Energy#{model}', 'type': 'json', 'units': 'GPa'}}}

Results that the Energy step produces.

The step carries no computational model of its own – the energy comes from the Model Chemistry published upstream, driven over MDI – so only results is populated. {model} in the property names is filled from the model chemistry’s level spec at run time (e.g. xnn:MLFF@water or MOPAC:SQM@PM6-ORG).

The energy, gradients and stress are always stored as properties on every configuration evaluated (that is the point of the step); the entries here additionally let the user save them, and the summary values, to variables or tables. store_results is called once per configuration, so a table gets one row per structure.

energy_step.tk_energy module

The graphical part of an Energy step

class energy_step.tk_energy.TkEnergy(tk_flowchart=None, node=None, canvas=None, x=None, y=None, w=200, h=50)

Bases: TkNode

The graphical part of an Energy 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

self[widget]

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

Type:

dict

See also

Energy, TkEnergy, EnergyParameters

create_dialog()

Create the dialog, with a Parameters tab and the standard Results tab.

edit()

Present the dialog, re-laying it out first so the reminder about a Model Chemistry step reflects the flowchart as it is now connected.

reset_dialog(widget=None)

Lay out the parameters frame in the Parameters tab.

reset_parameters_frame()

Lay out the control parameters for the current choices.

right_click(event)

Handle a right-click: add the Edit… item and post the menu.

Module contents

energy_step A SEAMM plug-in for calculating the energy and forces for many structures, using MDI.