Selecting structures in a plug-in#

Many steps operate on existing structures: writing them to a file, extracting clusters from them, looping over them. Rather than each plug-in inventing its own way of saying which structures, SEAMM provides a standard parameter block and a single implementation of the selection.

The parameters#

Include seamm.standard_parameters.structure_selection_parameters in the step’s parameters:

parameters = {
    **seamm.standard_parameters.structure_selection_parameters,
    "my option": {...},
}

It contributes four parameters:

source systems: current (the default), all, or name is / name matches / name regexp together with source system name. A variable, e.g. $frames, holding a list of configurations or of systems may also be given.
source system name: The name, shell-wildcard pattern or regular expression for the systems.
source configurations: Which configurations of each selected system: current (the default), all, last, first, or name is / name matches / name regexp together with source configuration name.
source configuration name: The name, pattern or regular expression for the configurations.

The defaults select exactly the current configuration of the current system, so adding the block to an existing step does not change its behaviour until the user asks for more.

Using the selection#

In run(), after dereferencing the parameters:

P = self.parameters.current_values_to_dict(context=seamm.flowchart_variables._data)
configurations = self.select_configurations(P)
for configuration in configurations:
    ...

Node.select_configurations returns the configurations in system order and then configuration order, and raises a ValueError naming the selection if nothing matched (pass errors=False to get an empty list instead). The underlying function, seamm.standard_parameters.select_configurations(system_db, P), can be used and tested without a node.

For the step’s description, structure_selection_description(P) returns a sentence such as “All configurations of the systems matching ‘H2O’ will be used.”*

The dialog#

In the Tk node, create the widgets in create_dialog and grid them in reset_dialog:

def create_dialog(self):
    frame = super().create_dialog(title="My Step")
    self.create_structure_selection_widgets(frame)
    ...

def reset_dialog(self, widget=None):
    ...
    row, widgets = self.layout_structure_selection(row=row)
    sw.align_labels(widgets, sticky=tk.E)

create_structure_selection_widgets binds the two choice comboboxes to reset_dialog; layout_structure_selection grids the choices and shows a name field beside a choice only when that choice needs one, so the user cannot build a selection that is missing its name.

Semantics shared with existing steps#

The vocabulary is the Loop step’s (name is / name matches / name regexp, all / last / first) and the current choices of Write Structure, so flowcharts read consistently across steps. Those steps, and the Dimer Builder’s private equivalent, are being converted to this block.