model_chemistry_step package#

Submodules#

model_chemistry_step.grammar module#

The model-chemistry grammar for SEAMM.

A model chemistry names what was done (the task), at what level of theory (the potential energy surface), and by which code(s) (provenance), in one parseable string:

[driver:]task | [owner:]type@method[/basis[@cutoff]]   [ // <unit> ]

driver – the code performing the task (always present).
task – SP | OPT | MD | FREQ | … (explicit and required).
owner – the code evaluating the PES, written only when it differs from the driver (i.e. under MDI delegation).
type@method[/basis[@cutoff]] – the level of theory (“level spec”).
// – optionally joins an energy unit to the geometry unit it was evaluated at (the Pople convention); lowest precedence.

Examples:

MOPAC:OPT|SQM@PM6-ORG               driver=owner=MOPAC, task=OPT
LAMMPS:MD|VFF@OPLS-AA               LAMMPS evaluates OPLS-AA itself
LAMMPS:MD|MOPAC:SQM@PM6-ORG         LAMMPS drives, MOPAC owns the PES (MDI)
VASP:OPT|DFT@PBE/PAW@500eV          basis PAW, cutoff 500eV
Psi4:SP|QC@CCSD(T)/cc-pVTZ//Psi4:OPT|DFT@B3LYP/def2-SVP   compound

Stripping driver: and owner: yields the program-free comparability key task|theory – two results with the same key are comparable regardless of which code produced them.

The reserved characters : @ / | must not appear inside any token. A cutoff requires a basis. See molssi-seamm.github.io :: background/model_chemistry_naming.rst for the full standard.

model_chemistry_step.grammar.comparability_key(parsed)[source]#

Return the program-free comparability key task|theory.

Drops driver and owner from each unit, so results from different codes at the same task and level of theory share a key.

Parameters:: parsed (dict) – The dict returned by parse_model_chemistry() (needs task, type, method, basis, cutoff and optionally geometry).
Returns:: task|theory (or task|theory//task|theory for a compound).
Return type:: str

model_chemistry_step.grammar.compose_model_chemistry(driver, task, *, owner=None, type, method, basis=None, cutoff=None, geometry=None)[source]#

Build the canonical model-chemistry string. Inverse of the parser.

Parameters:

driver (str) – The code performing the task.
task (str) – SP | OPT | MD | FREQ | …
owner (str, optional) – The PES-owning code. Omitted from the output when None or equal to driver (driver == owner needs no explicit owner).
type (str) – The level-of-theory family and specific method.
method (str) – The level-of-theory family and specific method.
basis (str, optional) – cutoff requires basis.
cutoff (str, optional) – cutoff requires basis.
geometry (dict, optional) – A dict of the same keyword arguments; appended as //<unit> (the geometry the energy was evaluated at).

Returns:

The canonical driver:task|[owner:]theory[//<unit>] string.

Return type:

str

model_chemistry_step.grammar.parse_level(text)[source]#

Parse a bare level spec [owner:]type@method[/basis[@cutoff]].

This is what a program step advertises (via get_model_chemistry_options) and what the Model Chemistry step selects; it carries no driver or task.

Parameters:: text (str) – A level spec, e.g. "SQM@PM6-ORG" or "MOPAC:SQM@PM6-ORG".
Returns:: Keys owner (None when absent), type, method, basis, cutoff (the last two may be None), and level echoing the input.
Return type:: dict
Raises:: ValueError – If the @ separating type from method is missing.

model_chemistry_step.grammar.parse_model_chemistry(text)[source]#

Parse a full model-chemistry string into its components.

Parameters:: text (str) – A full string [driver:]task | [owner:]theory [ // <unit> ].
Returns:: Keys driver, task, owner, type, method, basis, cutoff, level (the bare level spec), geometry (a nested parse of the // unit, or None), and comparability_key.
Return type:: dict
Raises:: ValueError – If the | (driver:task vs. level) or driver: / @ delimiters are missing.

model_chemistry_step.metadata module#

Metadata for the Model Chemistry step.

The Model Chemistry step does not run a calculation. It lets the user select a model chemistry and stores it as the workspace variable _model_chemistry for downstream steps (e.g. LAMMPS) to consume. It therefore produces no computational properties of its own, so metadata is an empty dictionary.

The available model chemistries are discovered at runtime from the installed program plug-ins – each program step (e.g. mopac_step) exposes a get_model_chemistry_options() classmethod – so they are not declared here.

model_chemistry_step.model_chemistry module#

Non-graphical part of the Model Chemistry step in a SEAMM flowchart

class model_chemistry_step.model_chemistry.ModelChemistry(flowchart=None, title='Model Chemistry', extension=None, logger=<Logger model_chemistry_step.model_chemistry (WARNING)>)[source]#

Bases: Node

The non-graphical part of a Model Chemistry 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 Model Chemistry.

Type:: ModelChemistryParameters

See also

TkModelChemistry, ModelChemistry, ModelChemistryParameters

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

Do any analysis of the output from this step.

Also print important results to the local step.out file using “printer”.

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

description_text(P=None)[source]#

Create the text description of what this step will do. The dictionary of control values is passed in as P so that the code can test values, etc.

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.

model_chemistries(periodic_only=False, mdi_only=False)[source]#

The model chemistries the installed program steps offer.

See discover_model_chemistries(), which this calls.

run()[source]#

Run a Model Chemistry step.

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

property version#: The semantic version of this module.

model_chemistry_step.model_chemistry.availability_problem(selected, available, periodic=False)[source]#

Why a model chemistry is not available, or ‘’ if it is.

Shared by the step’s run-time check and its parameters’ rules, which the flowchart builder uses.

model_chemistry_step.model_chemistry.discover_model_chemistries(periodic_only=False, mdi_only=False)[source]#

Discover the model chemistries offered by the installed program steps.

Each program plug-in (e.g. mopac_step) may expose a get_model_chemistry_options() classmethod on its helper class. This method iterates the org.molssi.seamm Stevedore namespace, calls that method on every helper that defines it, and returns the union keyed by the canonical model-chemistry string.

Parameters:

periodic_only (bool) – Only return model chemistries validated for periodic systems.
mdi_only (bool) – Only return model chemistries launchable via MDI.

Returns:

Keyed by the advertised level spec [owner:]type@method string. Each value is a _model_chemistry wrapper:

{
    "level": key,                        # the level spec
    "owner": ..., "type": ..., "method": ...,  # parse_level(key)
    "basis": ..., "cutoff": ...,
    "step": "<stevedore plugin name>",   # resolution handle
    "options": { ... full get_model_chemistry_options() entry },
}

A program step advertises level specs only (it knows its levels of theory, not the task); the consuming step supplies the driver and task. See model_chemistry_naming.rst.

Return type:

dict

model_chemistry_step.model_chemistry.match_model_chemistry(selected, available)[source]#

Match selected to an offered owner/type/method, ignoring the basis.

Programs advertise only a few example basis sets, but the basis is the user’s free choice. If a program offers the same owner/type/method as selected, return a _model_chemistry wrapper built from that offering with the user’s basis/cutoff/level substituted; otherwise None.

model_chemistry_step.model_chemistry.resolve_level(selected, context)[source]#

Dereference any $variable/=expression component of a level spec string, returning the resolved string.

Needed because the model_chemistry parameter is one whole string ([owner:]type@method[/basis[@cutoff]]) – SEAMM’s own current_values_to_dict only substitutes a $var that is the entire parameter value, not one embedded inside a larger string like "DFT@$functional/def2-SVP". Each level-spec component (owner, type, method, basis, cutoff) is dereferenced separately here instead, so a preceding Loop step can vary any one of them – most usefully type/method, typed into the GUI’s Type/Method comboboxes, which now accept a $variable – see TkModelChemistry.

Parameters:

selected (str) – The (already whole-value-dereferenced) model_chemistry string.
context (dict) – The flowchart-variables mapping to evaluate any expression against.

Returns:

selected unchanged if it does not parse as a level spec, or none of its components is an expression; otherwise the same level spec with every expression component evaluated and substituted.

Return type:

str

model_chemistry_step.model_chemistry_parameters module#

Control parameters for the Model Chemistry step in a SEAMM flowchart

class model_chemistry_step.model_chemistry_parameters.ModelChemistryParameters(defaults={}, data=None)[source]#

Bases: Parameters

The control parameters for Model Chemistry.

You need to replace the “time” entry in dictionary below these comments with the definitions of parameters to control this step. The keys are parameters for the current plugin,the values are dictionaries as outlined below.

Examples

parameters = {
    "time": {
        "default": 100.0,
        "kind": "float",
        "default_units": "ps",
        "enumeration": tuple(),
        "format_string": ".1f",
        "description": "Simulation time:",
        "help_text": ("The time to simulate in the dynamics run.")
    },
}

parameters{str: {str: str}}

A dictionary containing the parameters for the current step. Each key of the dictionary is a dictionary that contains the the following keys:

parameters[“default”] :

The default value of the parameter, used to reset it.

parameters[“kind”]enum()

Specifies the kind of a variable. One of “integer”, “float”, “string”, “boolean”, or “enum”

While the “kind” of a variable might be a numeric value, it may still have enumerated custom values meaningful to the user. For instance, if the parameter is a convergence criterion for an optimizer, custom values like “normal”, “precise”, etc, might be adequate. In addition, any parameter can be set to a variable of expression, indicated by having “$” as the first character in the field. For example, $OPTIMIZER_CONV.

parameters[“default_units”]str

The default units, used for resetting the value.

parameters[“enumeration”]tuple

A tuple of enumerated values.

parameters[“format_string”]str

A format string for “pretty” output.

parameters[“description”]str

A short string used as a prompt in the GUI.

parameters[“help_text”]str

A longer string to display as help for the user.

See also

ModelChemistry, TkModelChemistry, ModelChemistryParameters, Model

parameters = {'basis elements': {'default': '', 'default_units': '', 'description': 'Basis elements:', 'enumeration': (), 'format_string': '', 'help_text': 'GUI-only: the elements (comma-separated symbols) last selected in the basis-set picker, remembered so the picker can be reconstructed. Not used when running; the basis itself is part of the model-chemistry string.', 'kind': 'string'}, 'model_chemistry': {'default': 'MOPAC:SQM@PM6-ORG', 'default_units': '', 'description': 'Model chemistry:', 'enumeration': (), 'format_string': '', 'help_text': "The model chemistry to provide to subsequent steps, given as the canonical string 'Program:Type@Method[/Basis[@Cutoff]]'. The available choices are discovered from the installed program plug-ins.", 'kind': 'string'}, 'periodic': {'default': 'no', 'default_units': '', 'description': 'Periodic system:', 'enumeration': ('yes', 'no'), 'format_string': 's', 'help_text': "Whether the model chemistry must support periodic systems. If 'yes', only model chemistries validated for periodic systems are offered.", 'kind': 'enum'}}#

problems(values=None)[source]#: The model chemistry must be one the installed programs offer (the basis is a free choice), as the step checks when it runs.

model_chemistry_step.model_chemistry_step module#

class model_chemistry_step.model_chemistry_step.ModelChemistryStep(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 Model Chemistry 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:

ModelChemistry

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:

TkModelChemistry

description()[source]#

Return a description of what this step does.

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

my_description = {'description': 'An interface for Model Chemistry', 'group': 'Simulations', 'name': 'Model Chemistry'}#

model_chemistry_step.tk_model_chemistry module#

The graphical part of a Model Chemistry step.

The step persists a single level spec ([owner:]type@method[/basis [@cutoff]]) in the model_chemistry parameter – the level of theory, with no driver or task (those belong to the consuming step). The dialog presents it two ways, toggled by a checkbox:

Guided (default) – a cascading set of selectors, Type -> Method -> Program (where Program is the PES owner), plus a Basis field, plus a periodic-system filter:
- on open, the stored level spec is decomposed (parse_level) to preset the three selectors;
- the choices are discovered live from the installed program steps (node.model_chemistries(...)), narrowed by the periodic filter;
- Type narrows Method narrows Program; Program auto-selects when only one program implements the chosen type@method;
- on OK, the discovered level spec matching the three selections is composed and stored back into the model_chemistry parameter.
- Type/Method/Program also accept typed text, including a $variable/ =expression (see ModelChemistry.resolve_level), for driving the model chemistry from a preceding Loop step.
Direct entry – one plain text field bound straight to the model_chemistry parameter, for typing the whole canonical string (or a single $variable standing for it) by hand – the simplest way to use a variable, since it sidesteps the picker’s discovery/validation machinery entirely. The dialog switches to this mode automatically when the stored value cannot be decomposed by the picker (an expression, or a string the grammar can’t parse).

class model_chemistry_step.tk_model_chemistry.TkModelChemistry(tk_flowchart=None, node=None, canvas=None, x=None, y=None, w=200, h=50)[source]#

Bases: TkNode

The graphical part of a Model Chemistry 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

namespace#

The namespace of the current step.

Type:: str

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 Model Chemistry_parameters.py

Type:: dict

See also

ModelChemistry, TkModelChemistry, ModelChemistryParameters

create_dialog()[source]#

Create the dialog for editing the Model Chemistry step.

The periodic filter is a normal parameter widget, so the base class captures it on OK. Type/Method/Program are GUI-only comboboxes; the canonical model_chemistry string is composed from them in handle_dialog().

A checkbox switches between that guided picker and typing the whole model_chemistry string directly – much the simplest way to use a $variable (either for the whole level, or embedded in it), since it sidesteps the picker’s discovery/validation entirely. The direct- entry field is the real model_chemistry parameter’s own widget (a plain text entry), so the base class captures it on OK the same way it does periodic – handle_dialog() only needs to keep it in sync with the picker’s composed value when direct entry is off.

See also

TkModelChemistry.reset_dialog

edit()[source]#: Present the dialog, presetting the selectors from the stored value.

handle_dialog(result)[source]#

On OK, store the value that should be kept – the typed text as-is in direct-entry mode, or the string composed from the Type/ Method/Program/Basis selectors otherwise – into the model_chemistry parameter, keeping its widget in sync (so a reopened dialog, or the base class’s own widget-capture pass in seamm.TkNode.handle_dialog(), sees the same value).

Parameters:: result (str) – The button that closed the dialog ("OK", "Cancel", …).

reset_dialog(widget=None)[source]#

Lay out the widgets: the periodic filter, the direct-entry toggle, then either the direct-entry text field or the Type/Method/Program( /Basis) cascade, depending on the toggle.

Parameters:: widget (Tk Widget = None)

See also

TkModelChemistry.create_dialog

right_click(event)[source]#

Handles the right click event on the node.

Parameters:: event (Tk Event)
Return type:: None

See also

TkModelChemistry.edit

Module contents#

model_chemistry_step A SEAMM plug-in for defining the model chemistry for subsequent steps