seamm package

Submodules

seamm.builtins module

Helper class needed for the stevedore integration. Needs to provide a description() method that returns a dict containing a description of this node, and a factory() method for creating the graphical and non-graphical nodes.

class seamm.builtins.JoinStep(flowchart=None, gui=None)

Bases: object

create_node(flowchart=None, **kwargs)

Return the new node object

create_tk_node(canvas=None, **kwargs)

Return the graphical Tk node object

description()

Return a description of what this extension does

my_description = {'description': 'An interface for a node to join the control flow', 'group': 'Control', 'name': 'Join'}

class seamm.builtins.SplitStep(flowchart=None, gui=None)

Bases: object

create_node(flowchart=None, **kwargs)

Return the new node object

create_tk_node(canvas=None, **kwargs)

Return the graphical Tk node object

description()

Return a description of what this extension does

my_description = {'description': 'An interface for a node to split the control flow', 'group': 'Control', 'name': 'Split'}

seamm.dashboard_handler module

The interface for submitting SEAMM jobs.

A job in SEAMM is composed of a flowchart and any other files that the flowchart requires. This module provides the JobHandler class, which provides a use interface and the machinery to gather the necessary files and submit the job to a dashboard.

class seamm.dashboard_handler.DashboardHandler(user_agent=None)

Bases: object

add_dashboard(name, url, protocol)

Add a new dashboard to the config file

property credentials

The data Dashboard from ~/.seamm.d/seammrc.

property current_dashboard

The currently selected dashboard

property dashboards

The list of dashboards.

get_all_status()

Get the status of all the dashboards.

get_configuration()

Get the list of dashboards from the config file.

get_credentials(dashboard, ask=None)

The user for the dashboard.

Parameters:

dashboard (str) – The name of the dashboard to use.

Returns:

• str, str – The user name and password

• ask (function) – A function or method to call to get the user name and passwd.

get_dashboard(name)

Get the given dashboard object.

Parameters:

name (str) – The name of the Dashboard

Returns:

The Dashboard client object.

Return type:

seamm_dashboard_client.Dashboard

rename_dashboard(old, new)

Rename a dashboard from ‘old’ to ‘new’.

save_configuration()

Save the list of dashboards to disk.

update(dashboard)

Update the dashboard with that given.

seamm.dashboard_handler.safe_filename(filename)

seamm.data module

A module for holding data

seamm.flowchart module

A flowchart, which is a set of nodes. There must be a single ‘start’ node, with other nodes connected via their ports to describe the flowchart. There may be isolated nodes or groups of connected nodes; however, the flow starts at the ‘start’ node and follows the connections, so isolated nodes and fragments will not be executed.

class seamm.flowchart.Flowchart(parent=None, data=None, namespace='org.molssi.seamm', name='', description='', directory=None, output='files', parser_name='SEAMM')

Bases: object

add_edge(u, v, edge_type=None, edge_subtype='next', **attr)

add_node(n, **attr)

Add a single node n, ensuring that it knows the flowchart

clear(all=False)

Override the underlying clear() to ensure that the start node is present

create_node(extension_name)

Create a new node given the extension name

create_parsers()

Create the argument parsers for the nodes.

property data_path

A path to local and user data, such as forcefields.

digest(strict=False)

Generate a unique hash key for this flowchart.

Parameters:

strict (bool) – Whether to include version information. Default: False

Return type:

string

edges(node=None, direction='both')

property executor

The executor for tasks.

from_clipboard()

Read the flowchart from the clipboard

from_dict(data)

recreate the flowchart from the dict. Inverse of to_dict.

from_text(text)

Recreate the flowchart from text

get_node(uuid)

Return the node with a given uuid

get_nodes()

Return a list of all the nodes in the traversal.

graphics = 'Tk'

The default graphics to use for display, if needed. Default: ‘Tk’

Type:

str

property in_jobserver

Whether running in a JobServer.

property is_development

Check if any of nodes are development versions.

last_node(node='1')

Find the last node walking down the main execution path from the given node, which defaults to the start node

list_nodes()

List the nodes, for debugging

property output

Where to print output: files: to files in subdirectories stdout: to standard output (for intereactive use) both: to both files and standard output

property parser

The SEAMM parser associated with this flowchart.

print_edges(event=None)

Print all the edges. Useful for debugging!

read(filename)

Recreate the flowchart from the serialized form on disk

remove_node(node)

Delete a node from the flowchart, and from the graphics if necessary

reset_metadata(**kwargs)

Setup the metadata initially.

reset_visited()

Reset the ‘visited’ flag, which is used to detect loops during traversals

property root_directory

The root directory for files, etc for this flowchart

set_ids(node_id=())

Sequentially number all nodes, and subnodes

set_log_level(options)

Set the log level for each node based on the options

tag_exists(tag)

Check if the node with a given tag exists. A tag is a string like ‘node=<uuid>’, where <uuid> is the unique integer id for the node.

to_clipboard()

Copy the flowchart to the clipboard

to_dict()

Serialize the graph and everything it contains in a dict

to_json()

Ufff. Turn ourselves into JSON

to_text()

Return the text for the flowchart.

This is the representation written to disk, submitted as jobs, etc. There are two header lines followed by json representing the flowchart.

Returns:

str

Return type:

the text representation.

write(filename)

Write the serialized form to disk

seamm.graph module

class seamm.graph.Edge(graph, node1, node2, edge_type='execution', edge_subtype='next', **kwargs)

Bases: MutableMapping

copy()

Return a shallow copy of the dictionary

property edge_subtype

property edge_type

property node1

property node2

class seamm.graph.Graph

Bases: object

A datastructure for holding a directed graph with multiple (parallel) edges.

add_edge(u, v, edge_type=None, edge_subtype=None, edge_class=None, **kwargs)

add_node(node)

clear()

edges(node=None, direction='both')

has_edge(u, v, edge_type=None, edge_subtype=None)

remove_edge(u, v, edge_type=None, edge_subtype=None)

remove_node(node)

seamm.join_node module

A node to join together parallel flows in a flowchart

class seamm.join_node.Join(flowchart=None, extension='Join')

Bases: Node

description_text(P=None)

Return a short description of this step.

Return a nicely formatted string describing what this step will

do.

Keyword Arguments:

P – a dictionary of parameter values, which may be variables or final values. If None, then the parameters values will be used as is.

property git_revision

The git version of this module.

property version

The semantic version of this module.

seamm.node module

The base class for nodes (steps) in flowcharts.

class seamm.node.Node(flowchart=None, title='', extension=None, module=None, logger=<Logger seamm.node (WARNING)>, uid=None)

Bases: Hashable

The base class for nodes (steps) in flowcharts.

Parameters:

• flowchart (seamm.Flowchart) – The Flowchart object that contained this node.

• title (str, optional) – The title of this step for use in output.

• extension (str, optional) – Data used in serializing to the flowchart.

• module (str, optional) – The module for this step.

• logger (logging.Logger) – The logger to use for (debug) output. Defaults to the gloabl logger in the module.

• uid (str, optional) – The unigue ID for the step, used when reading a flowchart. If not given it is generated using uuid.uuid4().

• calculation

• description

• directory

• extension

• flowchart – The flowchart that this step is part of.

• global_options

• header

• indent

• job_path

• logger – The logger for debug, etc. output.

• metadata

• method

• model

• options

• parent (seamm.Node) – The node that is the parent, usually because this node is in a subflowchart of the parent.

• parameters (seamm.Parameters) – The control parameters for this step.

• references

• step_type

• tables

• title

• x (int) – The x-coordinate of the step in the GUI

• y (int) – The y-coordinate of the step in the GUI

• w (int) – The width of the step in the GUI

• h (int) – The height of the step in the GUI

• uuid

• visited

Notes

Handling results

The Node class takes most or all of the effort out of handling the results of calculations in steps. The developer needs to specify the information about possible results in metadata[“results”]. The keys are the steps internal names of the results, which match those in the data passed to store_results(). The fields of the dict for each key give human readable names, units, dimensions, etc.

The results can be filtered by the calculation attribute, and if further filtering is needed, the method attribute. While these two attirbutes have suggestive names, they are simply tags that should match those in the calculation filed of the the results metadata.

The model attribute is used to form the property name for the database. Often results depend on the model chemistry or something similar. The property names consist of up to three parts: the property, such as dipole moment; how the property was obtained, which is either experiment or the name of the code fo calculated results; and the model used, which is usually the model chemistry for calculated results.

property all_options

The complete set of all options.

analyze(indent='', **kwargs)

Analyze the output of the calculation

property calculation

The type of calculation for filtering available results.

close_printing(printer)

Close the handlers for printing, so that buffers are flushed, files closed, etc.

connections()

Return a list of all the incoming and outgoing edges for this node, giving the anchor points and other node

create_figure(title='', template='line.graph_template', module_path=None)

Create a new figure.

Parameters:

• title (str, optional) – The title of the figure

• template (str, optional) – The Jinja template for the desired graph. Defaults to ‘line.graph_template’

Return type:

seamm_util.Figure

create_parser(name=None)

Create the parser for this node.

All nodes have at least –log-level, which is setup here,

Parameters:

name (str) – The name of the parser. Defaults to a name derived from the module.

Returns:

The next node in the flowchart.

Return type:

seamm.Node()

property data_files

tuples of short name and path for any data files needed

property data_path

A path to local and user data, such as forcefields.

default_edge_subtype()

Return the default subtype of the edge. Usually this is ‘next’ but for nodes with two or more edges leaving them, such as a loop, this method will return an appropriate default for the current edge. For example, by default the first edge emanating from a loop-node is the ‘loop’ edge; the second, the ‘exit’ edge.

A return value of ‘too many’ indicates that the node exceeds the number of allowed exit edges.

delete_variable(variable)

Delete a variable in the workspace

describe()

Write out information about what this node will do

property description

A textual description of this node

description_text(P=None)

Return a short description of this step.

Return a nicely formatted string describing what this step will do.

Parameters:

P – a dictionary of parameter values, which may be variables or final values. If None, then the parameters values will be used as is.

digest(strict=False)

Generate a unique hash key for this node.

Parameters:

strict (bool) – Whether to include version information. Default: False

Return type:

string

property directory

The directory for output and files for this step.

existing_tables()

Tables from previous steps in the flowchart.

Returns:

Sorted list of existing tables.

Return type:

[str]

file_path(filename)

Remove any prefix from a filename and return the path.

Parameters:

filename (str) – The filename with optional prefix such as ‘job:’

Returns:

The normalized, full path.

Return type:

pathlib.Path

find_data_file(filename)

Using the data_path, find a file.

Parameters:

filename (str or pathlib.Path) – Name of the file to find – a relative path

Returns:

• path (pathlib.Path) – The path to the file

• Exceptions

• ———-

• FileNotFoundError if the file does not exist.

from_dict(data)

un-serialize object and everything it contains from a dict

get_gui_data(key, gui=None)

Return an element from the GUI dictionary

get_input()

Return the input from this subnode, usually used for building up the input for the executable.

get_system_configuration(P=None, same_as='current', first=True, **kwargs)

Get the current system and configuration.

Optionally use the standard structure handling to create new configuration or new system and configuration based on user input.

Note that if the system or configuration do not exist, they are automatically created as needed. This allows flowcharts to be started with and empty system database and “do the right” thing if a plug-in wants to use the curent configuration.

Parameters:

• P (dict(str, any) = None) – The dictionary of options and values. If none, the default system and configuration are returned as-is.

• same_as (_Configuration = "current"") – Share atoms, bonds, or cell with this configuration, depending on other flags. Defaults to “current”, which results in using the current configuration. If None, an empty configuration is created/used

• first (bool = True) – First configuration of several, which can have different handling than the subsequent ones.

Returns:

The system and configuration.

Return type:

(System, Configuration)

get_table(tablename, create=True)

Get the named table, creating if necessary

get_value(variable_or_value)

Return the value of the workspace variable is <variable_or_value> is the name of a variable. Otherwise, simply return the value of <variable_or_value>.

This provides a convenient way to handle both values and variables in widgets. A reference to a variable is $<name> or ${name}, and is replaced by the contents of the variable. If the text is not a reference to a variable then the value passed in is returned unchanged.

get_variable(variable)

Get the value of a variable, which must exist

glob_data_files(pattern)

Using the data_path, glob for files.

Parameters:

filename (str or pathlib.Path) – Name of the file to find – a relative path

Returns:

• paths ([pathlib.Path]) – A list of paths to the files

• Exceptions

• ———-

• FileNotFoundError if the file does not exist.

property global_options

Dictionary of global options

property header

A printable header for this section of output

property in_jobserver

Whether running in a jobserver

property indent

The amount to indent the output of this step in job.out.

static is_expr(value)

Return whether the value is an expression or constant.

Parameters:

value (str) – The value to test

Returns:

True for an expression, False otherwise.

Return type:

bool

job_output(text)

Temporary!

property job_path

Return the path to the job’s top-level directory

list_data_files()

Returns a list of auxilliary data files needed, like forcefields.

Returns:

Tuples with the local path or URI for the file, and its full pathlib.Path

Return type:

(shortname, pathlib.Path)

property metadata

Metadata describing aspects of the calculation.

The metadata is a dictionary of various types of metdata, often themselves dictionaries. Common types of metadata are:

Parameters:

• keywords – The keywords for programs with keyword-based input.

• results – The results that this step can produce.

property method

The method of a calculation, used for filtering metadata.

A calculation, such as energy or optimization, might return different results depending on the type of calculation or how it is carried out. The method can be used in the metadata to further filter the calculation results.

property model

The model (chemistry) used to obtain results.

Properties in the database use a trinomial naming scheme:

property`#`code`#`model

This is the last part of the name, or None if it is not relevant. It is often the model chemistry, such as mp2/6-31g or PM7.

next()

Return the next node in the flow

property options

Dictionary of options for this step

previous()

Return the previous node in the flow

property references

The reference handler for citations.

remove_edge(edge)

Remove a given edge, or all edges if ‘all’ is given

reset_id()

Reset the id for node

run(printer=None)

Do whatever we need to do! The base class does nothing except return the next node.

set_gui_data(key, value, gui=None)

Set an element of the GUI dictionary

set_id(node_id)

Set the id for node to a given tuple

set_uuid()

set_variable(variable, value)

Set the value of a variable in the workspace. The name of the variable maybe a plain string, or be $<name> or ${<name>}

setup_printing(printer)

Establish the handlers for printing as controlled by options

property step_type

The step type, e.g. ‘lammps-step’, used for e.g. options

store_results(configuration=None, data={}, create_tables=True)

Store results in the database, as variables,and in tables.

Parameters:

• configuration (molsystem._Configuration) – The configuration for storing properties in the database.

• data (dict(str, dict(str, any))) – The data resulting from running the step.

• create_tables (bool, optional) – Whether to create tables that do not yet exist, default is True.

property tables

Any tables this step creates.

A list of tables this step creates. If it is not easy to decide whether the tables are created or just used here, add them to the list. This data is used by subsequent steps to present possible tables in the GUI.

property tag

The string representation of the uuid of the node

property title

The title to display

to_dict()

serialize this object and everything it contains as a dict

to_json()

property uuid

The uuid of the node to give it a unique id.

variable_exists(variable)

Return whether a varable exists in the workspace

property visited

Whether this node has been visited in a traversal

seamm.node.scale(data, factor)

Recursive helper to scale e.g. nested lists by a factor.

seamm.parameters module

Control parameters for a step in a MolSSI flowchart

class seamm.parameters.Parameter(*args, **kwargs)

Bases: MutableMapping

A single parameter, with defaults, units, description, etc. This is object is a dict-like mutable mapping with properties to make it appear to be a simple object with attributes.

copy()

Return a shallow copy of the dictionary

debug_print()

property default

The current default of the parameter. May be a value, a Python expression containing variables prefix with $, standard operators or parenthesise, or a pint units quantity.

property default_units

The default units, as a string. These need to be compatible with pint

property description

Short description of this parameter, preferable just a few words

property enumeration

The possible values for an enumerated type.

property format_string

The format string for the value

get(context=None, formatted=False, units=True)

Return the value evaluated in the given context

property has_units

Does this parameter have units associated?

property help_text

A longer description of this parameter that is suitable for e.g. help text.

property is_expr

Is the current value a variable reference or expression?

property kind

integer, float, string, enum or special. This can be used to convert the value to the correct type in e.g. get_value.

Type:

The type of the parameter

reset()

Reset to an empty state

reset_widget()

Reset the values in the widget, if it has been created.

set(value)

Set the fields based on the type of value given

set_from_widget()

Set the value from the widget, ignoring if there is no widget.

to_dict()

Convert into a string suitable for editing

property units

The units, as a string. These need to be compatible with pint

update(data)

Update values from a dict

This assumes that the static data such as ‘kind’ and ‘default’ has been created already.

property value

The current value of the parameter. May be a value, a Python expression containing variables prefix with $, standard operators or parentheses.

widget(frame, **kwargs)

Return a widget for handling the parameter

class seamm.parameters.Parameters(defaults={}, data=None)

Bases: MutableMapping

A dict-like container for parameters

copy()

Return a shallow copy of the dictionary

current_values_to_dict(context=None, formatted=False, units=True)

Return the current values of the parameters, resolving any expressions, etc. in the given context or the root context is none is given.

from_dict(data)

Recreate the object from a dictionary

initialize()

reset_widgets()

Convenience function to reset the widgets to the current value.

set_from_widgets()

Convenience function to set the parameters from their widgets.

to_dict()

Return a new dictionary with the pertinent data

The Parameter class only saves the value and units, as everything else comes form the constructor below

update([E, ]**F) → None.  Update D from mapping/iterable E and F.

If E present and has a .keys() method, does: for k in E: D[k] = E[k] If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k, v in F.items(): D[k] = v

values_to_dict()

Return a dict of the raw values of the parameters formatted for printing

seamm.parameters.set_context(context)

Set the default root context for evaluating variables and expressions in parameters.

seamm.plugin_manager module

class seamm.plugin_manager.PluginManager(namespace)

Bases: object

get(name)

groups()

load_failure(mgr, ep, err)

Called when the extension manager can’t load an extension

plugins(group)

seamm.seammrc module

A singleton to ensure the ~.seammrc file is always up-to-date.

class seamm.seammrc.SEAMMrc(*args, **kwargs)

Bases: Singleton

add_section(section)

defaults()

get(section, option, raw=False, vars=None, fallback=<object object>)

getboolean(section, option, *, raw=False, vars=None, fallback=<object object>)

getfloat(section, option, *, raw=False, vars=None, fallback=<object object>)

getint(section, option, *, raw=False, vars=None, fallback=<object object>)

has_option(section, option)

has_section(section)

items(section=<object object>, raw=False, vars=None)

options(section)

re_read()

remove_option(section, option)

remove_section(section)

sections()

set(section, option, value)

class seamm.seammrc.Singleton(*args, **kwargs)

Bases: object

seamm.split_node module

A node to split the flow into parallel segements in a flowchart

class seamm.split_node.Split(flowchart=None, extension=None)

Bases: Node

description_text(P=None)

Return a short description of this step.

Return a nicely formatted string describing what this step will

do.

Keyword Arguments:

P – a dictionary of parameter values, which may be variables or final values. If None, then the parameters values will be used as is.

property git_revision

The git version of this module.

property version

The semantic version of this module.

seamm.standard_parameters module

Standard sets of parameters widely used in SEAMM.

param structure_handling_parameters:

Parameters for providing options for how to handle newly created structures. The options are:

• Overwrite the current configuration in the current system.

• Add a new configuration to the current system.

• Create new system and a configuration in it to hold the structure.

In addition, options are provided for naming the system and configuration whether or not new ones are created, i.e. the system and configuration can be renamed if they are reused.

type structure_handling_parameters:

dict(str, dict(str, str))

seamm.standard_parameters.multiple_structure_handling_description(P, **kwargs)

Return a standard description for how the new structures will be handled.

Parameters:

P (dict(str, any)) – The dictionary of parameter values, which must contain the standard structure handling parameters.

Returns:

The text for printing.

Return type:

str

seamm.standard_parameters.safe_format(s, *args, **kwargs)

seamm.standard_parameters.set_names(system, configuration, P, _first=True, **kwargs)

Set the names of the system and configuration.

Parameters:

• system (_System) – The system being named

• configuration (_Configuration) – The configuration being named

• P (dict(str, any)) – The dictionary of parameter values, which must contain the standard structure handling parameters.

• _first (bool) – Whether this is the first or a subseqnet structure.

• kwargs ({str: str}) – keyword arguments providing values that may be substituted in the names.

Returns:

The text for printing.

Return type:

str

seamm.standard_parameters.structure_handling_description(P, **kwargs)

Return a standard description for how the structure will be handled.

Parameters:

P (dict(str, any)) – The dictionary of parameter values, which must contain the standard structure handling parameters.

Returns:

The text for printing.

Return type:

str

seamm.start_node module

The start node in a flowchart

class seamm.start_node.StartNode(flowchart=None)

Bases: Node

description_text(P=None)

Return a short description of this step.

Return a nicely formatted string describing what this step will do.

Keyword Arguments:

P – a dictionary of parameter values, which may be variables or final values. If None, then the parameters values will be used as is.

property git_revision

The git version of this module.

run()

‘Run’ the start node, i.e. do nothing but print

set_uuid()

setup_printing(aprinter)

Establish the handlers for printing as controlled by options. The start step never writes to disk, so don’t create that handler.

property version

The semantic version of this module.

seamm.tk_edge module

The Tk graphical representation of an edge in the graph, i.e. an arrow connecting nodes.

The information is stored in the graph object as attributes of the edge so that the graphical representation can be restored as needed.

class seamm.tk_edge.TkEdge(graph, node1, node2, edge_type='execution', edge_subtype='next', canvas=None, anchor1='s', anchor2='n', coords=None, **kwargs)

Bases: Edge

property anchor1

property anchor2

property canvas

property coords

draw()

Draw the arrow for this edge

property has_label

property label_bg_id

property label_id

label_position(x0, y0, x1, y1, offset=15)

Work out the position for the label on an edge

move()

Redraw the arrow when the nodes have moved

str_to_object = <WeakValueDictionary>

tag()

Return a string tag for self

undraw()

Remove any graphics

seamm.tk_flowchart module

The flowchart is a visual representation of a flowchart drawn on a Tk canvas. The nodes of the graph are shown as ovals, rectangles, etc. with the edges indicated by arrows from one node to another.

The outline of a node has the following Tk tags:

node=xxxxx type=outline

The title:

node=xxxxx type=title

When the mouse is over the node, the anchor points are activated. They have the following tags:

node=xxxxx type=anchor anchor=<point>

When the mouse is over one of the active anchor points, it is covered with a larger circle, with tags:

node=xxxxx type=active_anchor anchor=<point>

Edges are indicated by directional arrows between nodes. The arrows have the following tags:

edge=xxxxx type=arrow

When the mouse if over an arrow, it is shown to be active by placing two red squares on the base and head of the arrow:

type=arrow_base arrow=<item> edge=xxxxx
type=arrow_head arrow=<item> edge=xxxxx

Clicking on either of these allows dragging the head or tail to another anchor point on the same or another node (but not on the same node as the tail/head for head/tail!). If the arrow is dropped anywhere else it just snaps back to its original place.

class seamm.tk_flowchart.TkFlowchart(master=None, flowchart=None, namespace='org.molssi.seamm.tk')

Bases: object

about(text='In about')

activate_node(node, point=None, exclude=())

Activate a node, i.e. display the anchor points, unless it is in the exclusion list. Also, if the anchor point is given, make it active.

add_edge(u, v, edge_type='execution', edge_subtype='next', **kwargs)

canvas_configure(event)

Redraw the background as the canvas changes size

Only after the process is idle!

canvas_configure_doit()

Redraw the background as the canvas changes size

This keeps the background image as large as possible and centered in the flowchart canvas.

clean_layout(event=None)

Clean the visual layout of the flowchart

clear(all=False)

Clear our graphics

click(event)

Handle a left-click on the canvas by finding out what the mouse is on/in/near and doing the appropriate thing, such as selecting to preparing to move the item.

copy_to_clipboard(event=None)

Copy the flowchart to the clipboard.

create_node(event)

Create a node using the type in menu. This is a bit tricky because we need to create both the node and its graphical partner, each of which needs to know the other.

create_start_node()

Create the start node

cut(event=None)

Cut the flowchart to the clipboard.

debug(event)

double_click(event)

Handle a double-click on the canvas by finding out what the mouse is on/in/near and doing the appropriate thing.

drag_arrow(event)

Drag an arrow from the anchor on the node to the mouse Used when creating a new edge.

drag_arrow_base(event)

Drag the base of an exisiting arrow

drag_arrow_head(event)

Drag the head of an arrow

draw()

drop_arrow(event)

The user has dropped a new arrow somewhere! If it is on another node, make the connection. If it is in empty space or on the original node, just cancel the operation.

drop_arrow_base(event)

The user has dropped the arrow somewhere! If it is on another node, make the connection. If it is in empty space or on the original node, just cancel the operation.

drop_arrow_head(event)

The user has dropped the arrow somewhere! If it is on another node, make the connection. If it is in empty space or on the original node, just cancel the operation.

edges(node=None, direction='both')

end_move(event)

End the move of selected items

find_items(x, y, exclude=())

Return the ‘top’ node under the mouse coordinates x, y

It appears that the canvas find_closest does not work properly in Python. Even if you give it a tag to look below, it always returns the topmost item, so we cannot loop through items.

Instead we use find_overlapping, which does return a list. However, if the mouse is e.g. inside a rectangle bat far enough from the edges find_overlapping does not find it. In this case we use the current tag to find the object.

property flowchart

The flowchart, which holds the nodes

flowchart_search(event=None)

Open a flowchart from Zenodo.

from_flowchart()

Recreate the graphics from the non-graphical flowchart

get_node(tag)

Return the node with a given tag

get_tags(item)

Return the tags of “item” as a dict. Any added tags like “active” are added to the “extra” dict entry.

help(event=None)

last_node(tk_node='1')

Find the last node walking down the main execution path from the given node, which defaults to the start node

last_node_helper(tk_node)

Helper routine to handle the recursion

property master

The window that is our master

mouse_motion(event, exclude=())

Track the mouse and highlight the node under the mouse

It appears that the canvas find_closest does not work properly in Python. Even if you give it a tag to look below, it always returns the topmost item, so we cannot loop through items.

Instead we use find_overlapping, which does return a list. However, if the mouse is e.g. inside a rectangle but far enough from the edges find_overlapping does not find it. In this case we use the current tag to find the object.

move(event)

Move selected items

new_file(event=None)

next_position()

Find a reasonable place to position the next step in the flowchart.

open(filename)

open_file(event=None)

paste_from_clipboard(event=None)

Paste the flowchart from the clipboard.

pop()

Replace the current flowchart with the version on the stack.

pop_and_discard()

Remove the saved copy from the stack

preferences()

print_edges(event=None)

Print all the edges. Useful for debugging!

print_items()

Print all the items on the canvas, for debugging

properties()

Get and set the properties of the flowchart.

publish(event=None)

Publish the flowchart to a repository such as Zenodo.

push()

Save a copy of the current flowchart on the stack.

remove_edge(item)

Remove an edge from the graph and visually

remove_node(node)

Remove the given node

right_click(event)

Handle a right-click on the canvas by finding out what the mouse is on/in/near and doing the appropriate thing, such as posting an action menu

right_click_on_arrow(event, item, tags)

Handle a right click on an arrow

run(event=None)

Run the current flowchart

save(event=None)

save_file(event=None)

tag_exists(tag)

Check if the node with a given tag exists

update_flowchart()

Update the non-graphical flowchart

xview(command, amount, *args)

Scroll in the x direction, keeping the background picture stationary

yview(command, amount, *args)

Scroll in the y direction, keeping the background picture stationary

seamm.tk_flowchart.grey(value)

seamm.tk_job_handler module

The graphical interface for submitting SEAMM jobs.

A job in SEAMM is composed of a flowchart and any other files that the flowchart requires. This module provides the TkJobHandler class, which provides a use interface and the machinery to gather the necessary files and submit the job to a dashboard.

class seamm.tk_job_handler.TkJobHandler(root=None)

Bases: object

add_dashboard_cb()

Post a dialog for adding a dashboard to the list.

ask_for_credentials(dashboard, user=None, password=None)

Prompt the user for the login for the dashboard

Parameters:

• dashboard (str) – The name of the dashboard.

• user (str) – The username for that dashboard.

• password (str) – The password for the user.

Returns:

A tuple with the username and password.

Return type:

(str, str)

check_status_cb()

Helper for checking the status of a dashboard.

clear_description()

clear_title()

create_submit_dialog(title='', description='')

Create the dialog for submitting a job.

Parameters:

flowchart (seamm.Flowchart) – The flowchart object

property current_dashboard

The current dashboard, from dashboard_handler

dashboard_cb(event=None)

The selected dashboard has been changed

property dashboard_handler

The connection to the dashboards.

display_dashboards()

Display a list of all the dashboards with their status.

Allow users to edit, remove and add dashboards.

edit_cb(dashboard)

Edit the information for a dashboard.

file_cb(table, row, name, data)

Method to handle parameters with files

Parameters:

• table (sw.ScrolledColumns) – The widget displaying the table of parameters.

• row (int) – The row of the table.

• name (str) – The name of the parameter.

• data (dict(str, str)) – The definition of the parameter.

fill_statuses()

fit_dialog(dialog)

Resize and fit the dialog to the current contents and the constraint of the window.

get_all_status(show_progress=True, master=None)

Get the status of all the dashboards.

Parameters:

show_progress (Boolean, optional) – Show a dialog with progress, default is True

handle_add_dialog(result)

Handle the dialog to add a dashboard to the list.

handle_dashboard_dialog(result)

Handle the dialog to add a dashboard to the list.

handle_dialog(result)

Handle the submit dialog being completed.

project_cb(event=None)

Handle a change in the project since it might be asking for adding a project in which case prompt for the new project’s name, create it, and sleect it in the widget.

reset_description()

reset_title()

submit_with_dialog(flowchart)

Allow the user to choose the dashboard and other parameters, and submit the job as requested.

Parameters:

flowchart (seamm.Flowchart) – The flowchart to use.

Returns:

job_id – The id of the submitted job.

Return type:

integer

seamm.tk_join_node module

A node to join the flow in a flowchart

class seamm.tk_join_node.TkJoin(tk_flowchart=None, node=None, canvas=None, x=120, y=20, w=30, h=30)

Bases: TkNode

The Tk-based graphical representation of a joining node

anchor_points = {'e': (0.5, 0.0), 'n': (0, -0.5), 's': (0, 0.5), 'w': (-0.5, 0.0)}

draw()

Draw the node on the given canvas, making it visible

right_click(event)

Handles the right click event on the node.

Parameters:

event (Tk Event)

Return type:

None

See also

TkGaussian.edit

seamm.tk_node module

The base class for Tk nodes (steps) in the GUI for flowcharts.

class seamm.tk_node.TkNode(tk_flowchart=None, node=None, node_type='simple', canvas=None, x=None, y=None, w=None, h=None, my_logger=<Logger seamm.tk_node (WARNING)>)

Bases: MutableMapping

The base class for Tk nodes (steps) in the GUI for flowcharts.

Parameters:

• tk_flowchart (seamm.TkFlowchart) – The graphical flowchart this step is in.

• node (seamm.Node) – The non-graphical node this corresponds to.

• node_type (enum("simple", "loop")) – The type of node on the graph. “simple” has an in and out arrow. “loop” has three arrows.

• canvas (tkinter.Canvas) – The Canvas widget that this node is drawn on.

• x (int) – The x-coordinate the drawing for the node on the canvas.

• y (int) – The y-coordinate of the drawing for the node on the canvas.

• w (int) – The width of the drawing for the node on the canvas.

• h (int) – The height of the drawing for the node on the canvas.

• my_logger (logging.Logger, optional) – The logger to use. Defaults to the global one defined in the module.

• Fields

• ------

• border

• canvas

• dialog (tkinter.Toplevel) – The dialog for editing the parameters.

• flowchart

• h

• logger (logging.Logger) – The logger for debug & warning output.

• node – The non-graphical node corresponding to this graphical one.

• node_type – The type of the node from the point of connectivity.

• popup_menu (tkinter.Menu) – The popup menu used for right-clicks.

• selected

• tag

• title

• title_label (tkinter.ttk.Label) – The label for the title of the step on the display.

• tk_flowchart – The Tk Flowchart that contains this step.

• tk_subflowchart (seamm.TkFlowchart) – The sub flowchart is if this step contains one.

• w

• x

• y

• uuid

Notes

The state is held in the corresponding non-graphical node, self.node. Many of the properties are thin-wrappers to the same property of the non-graphical node.

Results are stored in the following columns of the results table:

0  Result name
1  <separator>
2  Save in database
3  <separator>
4  Save as JSON
5  <separator>
6  checkbox
7  Save in variable named
8  <separator>
9  Save in table
10 as Column name
11 Units

activate()

Add active handles at the anchor points and change the cursor.

activate_anchor_point(point, halo)

Put a marker on the anchor point to indicate it is under the cursor.

anchor_point(anchor='all')

Where the anchor points are located. If “all” is given a dictionary of all points is returned

anchor_points = {'e': (0.5, 0.0), 'ene': (0.5, -0.25), 'ese': (0.5, 0.25), 'n': (0.0, -0.5), 'ne': (0.5, -0.5), 'nne': (0.25, -0.5), 'nnw': (-0.25, -0.5), 'nw': (-0.5, -0.5), 's': (0.0, 0.5), 'se': (0.5, 0.5), 'sse': (0.25, 0.5), 'ssw': (-0.25, 0.5), 'sw': (-0.5, 0.5), 'w': (-0.5, 0.0), 'wnw': (-0.5, -0.25), 'wsw': (-0.5, 0.25)}

property border

The border of the picture in the flowchart

property canvas

The canvas for drawing the node

check_anchor_points(x, y, halo)

If the position x, y is within halo or one of the anchor points activate the point and return the name of the anchor point

connections()

Return a list of all the incoming and outgoing edges for this node, giving the anchor points and other node

create_dialog(title='Edit step', widget='frame', results_tab=False)

Create the base dialog for editing the parameters for a step.

Parameters:

• title (str) – The title of the dialog.

• widget (enum) – Whether to use a simple dialog (“frame”) or use a notebook (“notebook”).

• results_tab (bool) – OBSOLETE Not longer used.

deactivate()

Remove the decorations that indicate active anchor points

default_edge_subtype()

Return the default subtype of the edge. Usually this is ‘’ but for nodes with two or more edges leaving them, such as a loop, this method will return an appropriate default for the current edge. For example, by default the first edge emanating from a loop-node is the ‘loop’ edge; the second, the ‘exit’ edge.

A return value of ‘too many’ indicates that the node exceeds the number of allowed exit edges.

double_click(event)

Handle a double-click on the node.

This method raises the dialog to edit the parameters. Subclasses should override this as appropriate!

draw()

Draw the node on the given canvas, making it visible

edit()

Present a dialog for editing this step’s parameters.

Subclasses can override this.

end_move(deltax, deltay)

End moving the node on the canvas.

Parameters:

• deltax (int) – The number of pixels to move in the x-direction.

• deltay (int) – The number of pixels to move in the y-direction.

fit_dialog()

Resize and fit the dialog to the current contents and the constraint of the window.

property flowchart

The flowchart object

from_flowchart(tk_flowchart=None, flowchart=None)

Recreate the graphics from the non-graphical flowchart. Only used in nodes that contain flowchart

property h

The height of the graphical node

handle_dialog(result)

Handle closing the dialog.

Parameters:

result (str) – The button that was pressed to close the dialog, or None if the x dialog close button was pressed.

help()

Base class for presenting help, does nothing.

Subclasses should override this.

initialize_results()

Initialize the results if empty.

When the GUI for the step is first created the results parameter is empty. However the default is to save properties to the database, so they need to be put into the results parameter.

static is_expr(value)

Return whether the value is an expression or constant.

Parameters:

value (str) – The value to test

Returns:

True for an expression, False otherwise.

Return type:

bool

is_inside(x, y, halo=0)

Return a boolean indicating whether the point x, y is inside this node, using halo as a size around the point

property metadata

Return the metadata for the node.

move(deltax, deltay)

Move the node on the canvas.

Parameters:

• deltax (int) – The number of pixels to move in the x-direction.

• deltay (int) – The number of pixels to move in the y-direction.

next_anchor()

Return where the next node should be positioned. The default is <gap> below the ‘s’ anchor point.

remove_edge(edge)

Remove a given edge, or all edges if ‘all’ is given

reset_dialog(widget=None)

Reset the layout of the dialog as needed for the parameters.

In this base class this does nothing. Override as needed in the subclasses derived from this class.

right_click(event)

Respond to a right-click by posting the popup menu.

This method provides a popup menu with a delete command.

Subclasses should override or extend this as appropriate! The menu created in this base method is accessible in subclasses which should make it easy to override.

property selected

Whether I am selected or not

set_uuid()

Set the unique id of the node to a new uuid.

setup_results()

Layout the results tab of the dialog

property tag

The string representation of the uuid of the node

property title

The title to display

to_dict()

Serialize to a dict

undraw()

Remove all the visual components from the canvas.

update_flowchart(tk_flowchart=None, flowchart=None)

Update the nongraphical flowchart. Only used in nodes that contain flowcharts

property uuid

The uuid of the node

property w

The width of the graphical node

property x

The x-position of the center of the graphical node

property y

The y-position of the center of the graphical node

seamm.tk_open module

The GUI for opening flowcharts.

class seamm.tk_open.TkOpen(toplevel)

Bases: MutableMapping

clear_tree()

Remove any contents from the tree.

create_dialog()

Create the dialog for opening.

property dashboard_handler

The connection to the dashboards.

directory_cb(event=None)

Invoked by the … button to get new directory.

fill_tree(job_list)

Fill the tree with a job list

The job list looks is a list of Job objects that are dicts like:

{
    'description': 'test of api',
    'finished': '2022-02-24 10:06',
    'flowchart_id': '1',
    'group': None,
    'group_id': None,
    'id': 18,
    'last_update': '2022-02-24 10:05',
    'owner': 'psaxe',
    'owner_id': 2,
    'parameters': {
         'cmdline': ['job:data/Users_psaxe_SEAMM_data_TiO2--anatase.cif']
    },
    'path': '/Users/psaxe/SEAMM_DEV/Jobs/projects/default/Job_000018',
    'projects': [{'id': 1, 'name': 'default'}],
    'started': '2022-02-24 10:06',
    'status': 'finished',
    'submitted': '2022-02-24 10:05',
    'title': 'test of api'
}

Parameters:

job_list ([seamm_dashboard_client._Job]) – List of Job objects contain info about the jobs

insert_node(parent, text, path, open=False)

Insert a new node in the tree, corresponding to a file or directory.

Parameters:

• parent (str) – The parent node in the tree, “” for toplevel.

• text (str) – The text to display for the node.

• path (pathlib.Path) – The absolute path of the file or directory.

open()

Present a dialog for opening.

open_node(event=None)

reset_dialog(event=None)

Layout the widgets in the dialog according to the parameters.

reset_tree(event=None)

Reset the file tree to start with the given directory.

search_cb()

Handle the search.

search_zenodo_for_flowcharts(sandbox=False)

Search for flowcharts in Zenodo.

Parameters:

sandbox (bool = False) – If true, search the Zenodo sandbox.

select_record(event)

The user clicked on the tree-view … handle the selected record.

update_dashboard(event=None)

The dashboard has been changed!

zenodo_callback(widget, criterion, event, what)

seamm.tk_publish module

The GUI for publishing – flowcharts for the moment.

class seamm.tk_publish.TkPublish(tk_flowchart)

Bases: MutableMapping

create_dialog()

Create the dialog for publishing.

edit()

Present a dialog for editing the parameters.

publish_flowchart_to_zenodo(sandbox=False)

Publish the flowchart to Zenodo.

Parameters:

sandbox (bool = False) – If true, publish to the Zenodo sandbox.

Returns:

The DOI.

Return type:

str

reset_dialog()

Layout the widgets in the dialog according to the parameters.

seamm.tk_split_node module

A node to split the flow in a flowchart

class seamm.tk_split_node.TkSplit(tk_flowchart=None, node=None, canvas=None, x=120, y=20, w=10, h=10)

Bases: TkNode

The Tk-based graphical representation of a splitting node

anchor_points = {'e': (0.5, 0.5), 'n': (0, 0), 's': (0, 1), 'w': (-0.5, 0.5)}

draw()

Draw the node on the given canvas, making it visible

seamm.tk_start_node module

The start node in a flowchart

class seamm.tk_start_node.TkStartNode(tk_flowchart=None, node=None, canvas=None, x=150, y=50, w=200, h=50)

Bases: TkNode

The Tk-based graphical representation of a Start node

add_author()

Add a new row to the author table.

anchor_points = {'e': (0.5, 0.0), 's': (0, 0.5), 'w': (-0.5, 0.0)}

capture_metadata()

Capture the metadata from the widgets and put to the flowchart.

cleanup_authors()

Destroy the internal widgets and reset the internal author data.

create_dialog()

Create a dialog for editing the flowchart properties.

create_frame(parent_widget)

Create a frame for editing the flowchart properties.

draw()

Draw the node on the given canvas, making it visible

edit()

Present a dialog for editing this step’s parameters.

Subclasses can override this.

handle_dialog(result)

Handle closing the dialog.

Parameters:

result (str) – The button that was pressed to close the dialog, or None if the x dialog close button was pressed.

layout_authors()

Layout the table of authors.

remove_author(row)

Remove a author entry from the table.

Parameters:

row (int) – The row in the table to remove. Note the first author is at row 1.

right_click(event)

Display the properties of the flowchart.

update_widgets()

Put the correct metadata into the widgets.

seamm.variables module

A dictionary-like object for holding variables accessible to the executing flowchart.

class seamm.variables.Variables(**kwargs)

Bases: MutableMapping

copy()

Return a shallow copy of the dictionary

delete(variable)

Return whether a variable exists. The variable may be specified as a simple string or start with a $ and optionally have braces around it, i.e.

<name> $<name>

or

${<name>}

exists(variable)

Return whether a variable exists. The variable may be specified as a simple string or start with a $ and optionally have braces around it, i.e.

<name> $<name>

or

${<name>}

filter_expression(string)

A variable or expression coming from the GUI uses ‘$’ to indicate a variable, optionally bracketing the variable with braces, i.e. ${name}.

This method filters out the variable markers, respecting quoted string, returning a string that can be eval’ed in the Python interpreter.

get_variable(variable)

Get the value of the variable. The variable may be a simple string or start with a $ and optionally have braces around it, i.e.

<name> $<name>

or

${<name>}

set_variable(variable, value)

Set the value of the variable. The variable may be a simple string or start with a $ and optionally have braces around it, i.e.

<name> $<name>

or

${<name>}

value(string)

Return the value of the variable or expression if it is an expression, i.e. starts with a $ and optionally has braces around the variable name.

If it is not a variable, return the original string unchanged

variable(string)

Return the name of a variable. The variable may be specified as a simple string or start with a $ and optionally have braces around it, i.e.

<string> $<string>

or

${<string>}

Module contents

seamm Simulation Environment for Atomistic and Molecular Modeling.