control_parameters_step package#

Submodules#

control_parameters_step.control_parameters module#

Non-graphical part of the Control Parameters step in a SEAMM flowchart

The Control Parameters step allows the person creating the flowchart to specify an arbitrary number of parameters that can be set when the flowchart is run, typically by command-line arguments. Parameters may be positional or optional, in which case they indicated by a ‘flag’ on the command line, e.g. –n 10.

By default, these parameters will not replace a current value if it already exists, though this can be changed. This allows embedding flowcharts within other flowcharts without overriding parameters, but ensuring that all parameters are set.

Parameters have a specified type:

str     A text string
int     An integer
float   A floating point number
bool    A boolean value: 1/0, True/False, Yes/No

Typically parameters have one value associated with them; however, any parameter may have a specified or variable number of values, including none. The possibilities are:

a single value          This is the default
N values                Where N is an integer >= 1
an optional value       If not present, the default is used
zero or more values
one or more values

An optional parameter need not have a default, in which case if it does not appear on the command-line it is not set in the SEAMM environment.

Rather than allow any value of the correct type, an option can be restricted to a list of choices. For example, a convergence citerion might be ‘normal’, ‘tight’ or ‘loose’ or an MPn quantum calculation might allow n to be 2, 3, or 4.

In addition to command-line arguments, this module supports environment variables and a control file with a simple format of key = value. If a parameter appears in multiple places, the precedence is command-line > environment variable > file > default.

Positional parameters must appear in the right place on the command line. Optional parameters are given with a flag of form ‘–<name>’, e.g. ‘–P’ or ‘–nsteps’.

The environment variable by default is SEAMM_<name>, in all capital letters, e.g. SEAMM_P or SEAMM_nsteps.

In a control file, the variable name is used as-is followed by the value, or = value or : value. Or it can look like a command line argument:

P 1.0
P=1.0
P: 10
--P 50
nsteps 50
nsteps = 50
nsteps:50
--nsteps 50

Positional arguments cannot be put in a control file. If the value is a list, encase it in square brackets:

pressures = [1.0, 2.0, 5.0, 10.0]

Internally the parameter definitions are stored in a dictionary with the parameter name as key and the value is itself a dictionary labeled by the item in the definition, e.g. ‘name’, ‘default’, and ‘nargs’:

"T": {
    "type": "float",
    "nargs": "a single value",
    "optional": "Yes",
    "default": "298.15",
    "choices": "[]",
    "overwrite": "No",
    "help": "The temperature"
},

class control_parameters_step.control_parameters.ControlParameters(flowchart=None, title='Parameters', extension=None, logger=<Logger control_parameters_step.control_parameters (WARNING)>)[source]#

Bases: Node

The non-graphical part of a Control Parameters step in a flowchart.

options#

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

Type:: tuple

subflowchart#

A SEAMM Flowchart object that represents a subflowchart, if needed.

Type:: seamm.Flowchart

parameters#

The control parameters for Control Parameters.

Type:: ControlParametersParameters

See also

TkControlParameters, ControlParameters, ControlParametersParameters

create_parser()[source]#: Setup the command-line / config file parser

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.

run()[source]#

Run a Control Parameters step.

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

property version#: The semantic version of this module.

control_parameters_step.control_parameters_parameters module#

Control parameters for the Control Parameters step in a SEAMM flowchart

class control_parameters_step.control_parameters_parameters.ControlParametersParameters(defaults={}, data=None)[source]#

Bases: Parameters

The control parameters for Control Parameters.

The developer will add a dictionary of Parameters to this class. The keys are parameters for the current plugin, which themselves might be dictionaries.

You need to replace the ‘time’ example below with one or more definitions of the control parameters for your plugin and application.

Parameters:

parameters ({'kind', 'default', 'default_units', 'enumeration',) –
'format_string' – A dictionary containing the parameters for the current step. Each key of the dictionary is a dictionary that contains the the following keys: kind, default, default_units, enumeration, format_string, description and help text.
description' – A dictionary containing the parameters for the current step. Each key of the dictionary is a dictionary that contains the the following keys: kind, default, default_units, enumeration, format_string, description and help text.
help_text'} – A dictionary containing the parameters for the current step. Each key of the dictionary is a dictionary that contains the the following keys: kind, default, default_units, enumeration, format_string, description and help text.
parameters['kind'] (custom) – Specifies the kind of a variable. 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'] ('integer' or 'float' or 'string' or 'boolean' or) – ‘enum’ The default value of the parameter, used to reset it.
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'] (tuple) – A longer string to display as help for the user.

See also

ControlParameters, TkControlParameters, ControlParameters, ControlParametersParameters, Control

parameters = {'variables': {'default': {}, 'default_units': '', 'description': 'variables', 'enumeration': (), 'format_string': '', 'help_text': 'The variables to handle, with defaults, etc.', 'kind': 'dictionary'}}#

control_parameters_step.control_parameters_step module#

class control_parameters_step.control_parameters_step.ControlParametersStep(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.

Parameters:

my_description ({description, group, name}) – 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 Control Parameters 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’, ‘Calculations’, ‘Control’ and ‘Data’.
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 (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:

ControlParameters

See also

ControlParameters

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

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:

TkControlParameters

See also

TkControlParameters

description()[source]#: Return a description of what this extension does

my_description = {'description': 'An interface for Control Parameters', 'group': 'Control', 'name': 'Parameters'}#

control_parameters_step.tk_control_parameters module#

The graphical part of a Control Parameters step

class control_parameters_step.tk_control_parameters.TkControlParameters(tk_flowchart=None, node=None, canvas=None, x=None, y=None, w=200, h=50)[source]#

Bases: TkNode

The graphical part of a Control Parameters 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

sub_tk_flowchart#

A graphical Flowchart representing a subflowchart

Type:: TkFlowchart

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 Control Parameters_parameters.py

Type:: dict

See also

ControlParameters, TkControlParameters, ControlParametersParameters

add_variable()[source]#: Add a new variable to the table.

create_dialog()[source]#

Create the dialog. A set of widgets will be chosen by default based on what is specified in the Control Parameters_parameters module.

Parameters:: None –
Return type:: None

See also

TkControlParameters.reset_dialog

create_edit_variable_dialog()[source]#

Create a dialog for adding edit variables.

Parameters:: None –
Return type:: None

create_new_variable_dialog()[source]#

Create a dialog for adding new variables.

Parameters:: None –
Return type:: None

edit()[source]#

Present a dialog for editing the Control Parameters input

Parameters:: None –
Return type:: None

See also

TkControlParameters.right_click

edit_variable(name)[source]#: Edit the values associated with a variable.

handle_dialog(result)[source]#

Handle the closing of the edit dialog

What to do depends on the button used to close the dialog. If the user closes it by clicking the ‘x’ of the dialog window, None is returned, which we take as equivalent to cancel.

Parameters:: result (None or str) – The value of this variable depends on what the button the user clicked.
Return type:: None

handle_edit_variable_dialog(name, result)[source]#

Handle the closing of the edit variable dialog

What to do depends on the button used to close the dialog. If the user closes it by clicking the ‘x’ of the dialog window, None is returned, which we take as equivalent to cancel.

Parameters:: result (None or str) – The value of this variable depends on what the button the user clicked.
Return type:: None

handle_help()[source]#

Shows the help to the user when click on help button.

Parameters:: None –
Return type:: None

handle_new_variable_dialog(result)[source]#

Handle the closing of the new variable dialog

What to do depends on the button used to close the dialog. If the user closes it by clicking the ‘x’ of the dialog window, None is returned, which we take as equivalent to cancel.

Parameters:: result (None or str) – The value of this variable depends on what the button the user clicked.
Return type:: None

remove_variable(name)[source]#: Remove a variable variable.

reset_dialog(widget=None)[source]#

Layout the widgets in the dialog.

The widgets are chosen by default from the information in Control Parameters_parameter.

This function simply lays them out row by row with aligned labels. You may wish a more complicated layout that is controlled by values of some of the control parameters. If so, edit or override this method

Parameters:: widget (Tk Widget = None) –
Return type:: None

See also

TkControlParameters.create_dialog

reset_edit_variable_dialog()[source]#: Lay the dialog out based on the contents.

reset_new_variable_dialog()[source]#: Lay the dialog out based on the contents.

reset_table()[source]#: Update the table of variables to the current data.

right_click(event)[source]#

Handles the right click event on the node.

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

See also

TkControlParameters.edit

Module contents#

control_parameters_step A step for control parameters in SEAMM