loop_step package

Submodules

loop_step.loop module

Non-graphical part of the Loop step in a SEAMM flowchart

loop_step.loop.APPENDED_VARIABLES = ('_md_runs',)

Workspace variables that steps add records to, one after another, such as _md_runs: a record of each MD run and its data file, which analysis steps read. A parallel loop appends each iteration’s records, in iteration order, as a serial loop leaves them; the records of a skipped iteration, whose directory is removed, are dropped in both.

exception loop_step.loop.BreakLoop(message='break from the loop')

Bases: Exception

Indicates that SEAMM should break from the loop

exception loop_step.loop.ContinueLoop(message='continue with next iteration of loop')

Bases: Exception

Indicates that SEAMM should continue from the loop

class loop_step.loop.Loop(flowchart=None, extension=None)

Bases: Node

property all_options

The complete set of all options.

check_flowchart(preceding)

Check, before the job runs, that a parallel loop’s iterations can merge.

The steps in the body of a parallel loop over one structure must not all write their structure over it: two iterations changing the same configuration cannot be merged. Each such step is reported as a warning – some steps that may write the structure do not change it – with fixes that set its structure handling.

Parameters:

preceding ([seamm.Node]) – The steps that run before this one (not used).

Returns:

The warnings, as seamm.Problem with their fixes; empty if none.

Return type:

[str]

create_parser()

Setup the command-line / config file parser

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.

describe()

Write out information about what this node will do

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.

exit_node()

The next node after the loop, if any

property git_revision

The git version of this module.

property iter_format

loop_node()

The first node in the loop body

run()

Run a Loop step.

safe_filename(filename)

set_id(node_id=())

Sequentially number the loop subnodes

set_subids(node_id=())

Set the ids of the nodes in the loop

property version

The semantic version of this module.

property working_path

loop_step.loop.OVERWRITE = 'Overwrite the current configuration'

The structure handling that writes a step’s structure over the current configuration, which the iterations of a parallel loop over one structure share

exception loop_step.loop.SkipIteration(message='skip iteration of loop')

Bases: Exception

Indicates that SEAMM should skip this iteration of the loop, removing any directories, etc.

loop_step.loop.break_loop()

Break from the loop and continue on.

loop_step.loop.continue_loop()

Continue to the next iteration of the loop

loop_step.loop.iteration_cores(setting, job_cores, n_iterations, at_once=None, job_memory=0, memory=None)

The cores of each iteration of a parallel loop.

Parameters:

• setting (int or str) – “Cores per iteration”: a number, or “automatic” to share the job’s cores among the iterations that run at once.

• job_cores (int) – The job’s cores (its tasks).

• n_iterations (int) – The iterations to run.

• at_once (int or None) – “Iterations at once”, or None for as many as fit.

• job_memory (int) – The job’s memory and each iteration’s, bytes; 0 or None if not known.

• memory (int) – The job’s memory and each iteration’s, bytes; 0 or None if not known.

Returns:

The cores per iteration, and how many iterations share the job’s cores (None when the number was given). A parallel loop gave each iteration one core by default, so 4 replicas ran on 4 of a job’s 64 cores (SEAMM job 5368, 2026-10-22).

Return type:

(int, int or None)

loop_step.loop.skip_iteration()

Entirely skip this iteration, removing any files, etc.

loop_step.loop_parameters module

Control parameters for loops

class loop_step.loop_parameters.LoopParameters(defaults={}, data=None)

Bases: Parameters

The control parameters for loops

parameters = {'as variables': {'default': 'yes', 'default_units': '', 'description': 'Values as variables:', 'enumeration': ('yes', 'no'), 'format_string': '', 'help_text': 'Whether to put the values for the row as seperate variables.', 'kind': 'boolean'}, 'cores per iteration': {'default': 'automatic', 'default_units': '', 'description': 'Cores per iteration:', 'enumeration': ('automatic',), 'format_string': '', 'former defaults': ('1',), 'help_text': "The cores each iteration uses for its calculations. 'automatic' shares the job's cores among the iterations that run at once, e.g. 16 each for 4 iterations in a 64-core job.", 'kind': 'integer', 'resource': True}, 'directory name': {'default': 'loop iteration', 'default_units': '', 'description': 'Directory names:', 'enumeration': ('loop iteration', 'system name', 'configuration name'), 'format_string': 's', 'help_text': 'The directory name for the loop iteration.', 'kind': 'string'}, 'end': {'default': '10', 'default_units': '', 'description': 'to', 'enumeration': (), 'format_string': '', 'help_text': 'The ending value of the loop.', 'kind': 'float'}, 'errors': {'default': 'continue to next iteration', 'default_units': '', 'description': 'On errors', 'enumeration': ('continue to next iteration', 'exit the loop', 'stop the job'), 'format_string': 's', 'help_text': 'How to handle errors', 'kind': 'string'}, 'iterations at once': {'default': 'as many as fit', 'default_units': '', 'description': 'Iterations at once:', 'enumeration': ('as many as fit',), 'format_string': '', 'help_text': 'How many iterations run at the same time on this machine. By default as many as the cores and memory allow, given the cores and memory per iteration.', 'kind': 'integer', 'resource': True}, 'memory per iteration': {'default': 2.0, 'default_units': 'GB', 'description': 'Memory per iteration:', 'enumeration': (), 'format_string': '.1f', 'help_text': 'The memory each iteration needs at most.', 'kind': 'float', 'resource': True}, 'parallel': {'default': 'no', 'default_units': '', 'description': 'Run iterations in parallel:', 'enumeration': ('no', 'yes'), 'format_string': '', 'help_text': 'Run the iterations at the same time, each in its own evaluator. They must be independent: each sees the job as it was when the loop started, and variables set in the body are not visible after the loop, except the record of MD runs that analysis steps read. Tables, properties, structures, files and MD runs come back, merged in iteration order.', 'kind': 'boolean'}, 'placement': {'default': 'inline', 'default_units': '', 'description': 'Calculations run:', 'enumeration': ('inline', 'separate tasks'), 'format_string': 's', 'help_text': "Where each iteration's calculations run: inline, in the iteration's own share of the machine, or as separate tasks on the job's target.", 'kind': 'enumeration', 'resource': True}, 'query-column': {'default': '', 'default_units': '', 'description': '', 'enumeration': (), 'format_string': 's', 'help_text': 'The column to test', 'kind': 'string'}, 'query-op': {'default': '==', 'default_units': '', 'description': '', 'enumeration': ('==', '!=', '>', '>=', '<', '<=', 'between', 'contains', 'does not contain', 'contains regexp', 'does not contain regexp', 'is empty', 'is not empty'), 'format_string': 's', 'help_text': 'The column to test', 'kind': 'string'}, 'query-value': {'default': '', 'default_units': '', 'description': '', 'enumeration': (), 'format_string': 's', 'help_text': 'Value to use in the test', 'kind': 'string'}, 'query-value2': {'default': '', 'default_units': '', 'description': '', 'enumeration': (), 'format_string': 's', 'help_text': 'The second value to use in the test', 'kind': 'string'}, 'same-cell writes': {'default': 'are an error', 'default_units': '', 'description': 'Two iterations writing one table cell:', 'enumeration': ('are an error', 'the later iteration wins'), 'format_string': 's', 'help_text': 'What to do when two iterations write the same cell of a table row that existed before the loop: stop with an error, or keep the value from the later iteration, with a warning.', 'kind': 'enumeration'}, 'snapshot': {'default': 'selected structures', 'default_units': '', 'description': 'Each iteration gets:', 'enumeration': ('selected structures', 'whole database'), 'format_string': 's', 'help_text': "What of the job's database each iteration starts with: the structure it works on (and the current one) with all the tables, or a copy of the whole database.", 'kind': 'enumeration'}, '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': 'last', 'default_units': '', 'description': 'using configuration:', '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': 'all', 'default_units': '', 'description': 'For 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'}, 'start': {'default': '1', 'default_units': '', 'description': 'from', 'enumeration': (), 'format_string': '', 'help_text': 'The starting value of the loop.', 'kind': 'float'}, 'step': {'default': '1', 'default_units': '', 'description': 'by', 'enumeration': (), 'format_string': '', 'help_text': 'The step or increment of the loop value.', 'kind': 'float'}, 'table': {'default': 'table1', 'default_units': '', 'description': '', 'enumeration': (), 'format_string': 's', 'help_text': 'The table to iterate over.', 'kind': 'string'}, 'time per iteration': {'default': 'not given', 'default_units': 'h', 'description': 'Time per iteration:', 'enumeration': ('not given',), 'format_string': '.2f', 'help_text': 'An estimate of the time each iteration takes, used to bundle iterations into queue jobs.', 'kind': 'float', 'resource': True}, 'type': {'default': 'For', 'default_units': '', 'description': '', 'enumeration': ('For', 'Foreach', 'For rows in table', 'For systems in the database'), 'format_string': 's', 'help_text': 'The type of loop used.', 'kind': 'enumeration'}, 'values': {'default': '', 'default_units': '', 'description': 'value in', 'enumeration': (), 'format_string': 's', 'help_text': 'The list of values for the loop.', 'kind': 'string'}, 'variable': {'default': 'i', 'default_units': '', 'description': 'loop variable', 'enumeration': (), 'format_string': '', 'help_text': 'The name of the loop variable.', 'kind': 'string'}, 'where': {'default': 'Use all rows', 'default_units': '', 'description': '', 'enumeration': ('Use all rows', 'Select rows where column'), 'format_string': 's', 'help_text': 'The filter for rows, defaults to all rows.', 'kind': 'string'}}

update(data)

Update from a dictionary, translating the legacy system-selection keys (‘where system name’, ‘system name’, ‘default configuration’, ‘configuration name’) and their values from flowcharts saved before 2026.9.18 to the standard structure-selection parameters.

loop_step.loop_step 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 loop_step.loop_step.LoopStep(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 Loop', 'group': 'Control', 'name': 'Loop'}

loop_step.tk_loop module

The graphical part of a Loop step

class loop_step.tk_loop.TkLoop(tk_flowchart=None, node=None, canvas=None, x=120, y=20, w=200, h=50, my_logger=<Logger loop_step.tk_loop (WARNING)>)

Bases: TkNode

The node_class is the class of the ‘real’ node that this class is the Tk graphics partner for

create_dialog()

Create the dialog!

criteria_callback(widget, criterion, event, what)

Handle changes in the search criteria widget.

Parameters:

• widget (Tk widget) – The widget.

• criterion (sw.Criterion) – The row – Criterion widget – in the table.

• event (tk.Event) – The event causing the callback.

• what (str) – The item that changed: ‘inclusion’, ‘field’, ‘operator’, ‘self.two_values’, ‘clear’, ‘set’, ‘add row’, ‘remove row’

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.

next_anchor()

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

node_class

alias of Loop

reset_dialog(widget=None)

Lay out the edit dialog according to the type of loop.

right_click(event)

Probably need to add our dialog…

Module contents

loop_step A step for loops in the SEAMM flowcharts