seamm_util package

Submodules

seamm_util.argument_parser module

A configuration and argument parser tailored to SEAMM.

The goal of this is to allow options to be specified both on the command line and in ini files, with command line having precedence. This is tailored to SEAMM flowcharts so that options for each type of step (plug-in) is in its own section on the command line or in the ini file, labeled by the type of section.

class seamm_util.argument_parser.ArgumentParser(*args, ini_files=['/home/runner/.seamm.d/seamm.ini', 'seamm.ini'], interpolation=<configparser.ExtendedInterpolation object>, **kwargs)

Bases: object

Replacement and extension for argparse.ArgumentParser that adds support for .ini files plus something like the subcommands in argparse but with multiple ones active at the same time.

This is accomplished by separating sections with ‘<section name>’ on the commandline, and using ‘[<section name>] in the .ini files. e.g.

test.flow lammps-step –log-level debug psi4-step –np 32

add_argument(section, *args, **kwargs)

add_argument_group(section, title, description=None)

add_parser(section, prog=None, usage=None, description=None, epilog=None, parents=[], formatter_class=<class 'argparse.HelpFormatter'>, prefix_chars='-', fromfile_prefix_chars=None, argument_default=None, conflict_handler='error', add_help=True, allow_abbrev=True)

Capture the information needed to create a subparser.

Parameters:

• section (str) – The name of this section of the parsing.

• prog (str = sys.argv[0]) – The name of the program

• usage (str = None) – A usage message (default: auto-generated from arguments)

• description (str = None) – A description of what the program does

• epilog (str = None) – Text following the argument descriptions

• parents ([argparse.ArgumentParser] = []) – Parsers whose arguments should be copied into this one

• formatter_class (argparse.HelpFormatter) – HelpFormatter class for printing help messages

• prefix_chars (str = '-') – Characters that prefix optional arguments

• fromfile_prefix_chars (str = None) – Characters that prefix files containing additional arguments

• argument_default (str = None) – The default value for all arguments

• conflict_handler (str = 'error') – String indicating how to handle conflicts

• add_help (bool = True) – Add a -h/-help option

• allow_abbrev (bool = True) – Allow long options to be abbreviated unambiguously

exists(name)

format_help(args=None)

Prepare the help message.

Parameters:

args ([str] = sys.argv[1:]) – The arguments to pass the parsers, defaults to sys.argv[1:]

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

Get an option value for a given section.

If `vars’ is provided, it must be a dictionary. The option is looked up in `vars’ (if provided), `section’, and in `DEFAULTSECT’ in that order. If the key is not found and `fallback’ is provided, it is used as a fallback value. `None’ can be provided as a `fallback’ value.

If interpolation is enabled and the optional argument `raw’ is False, all interpolations are expanded in the return values.

Arguments `raw’, `vars’, and `fallback’ are keyword only.

The section DEFAULT is special.

get_ini_files()

Return a list of the .ini files actually used.

Returns:

The list of .ini files found

Return type:

[str]

get_options(section=None)

Return the options for the given section.

Parameters:

section (str = None) – Return the options for the given section, or all sections

Returns:

{str – The dictionary of options for the section, or all sections.

Return type:

int, float, str or bool}

get_origins(section=None)

Return the origins of the options for the given section.

Parameters:

section (str = None) – Return the origins for the given section, or all sections

Returns:

{str – The dictionary of origins for the section, or all sections.

Return type:

str}

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

Return a list of (name, value) tuples for each option in a section.

All % interpolations are expanded in the return values, based on the defaults passed into the constructor, unless the optional argument `raw’ is true. Additional substitutions may be provided using the `vars’ argument, which must be a dictionary whose contents overrides any pre-existing defaults.

The section DEFAULT is special.

optionxform(optionstr)

parse_args(args=None)

Parse the .ini file and command-line arguments.

There are three distinct steps to the process:

1. Process the command-line arguments, breaking them into sections corresponding to the subparsers.

2. Read the .ini files, if any.

3. Create the actual parsers from the saved information, replacing or adding defaults for any values found in the .ini files.

4. Parse each section of the command-line with the correct parser.

Parameters:

args ([str] = sys.argv[1:]) – The arguments to parse. Defaults to the command-line arguments.

print_help(args=None, fd=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

split_args(args=None)

Break the argument line into sections for each plug-in.

Parameters:

args ([str] = sys.argv[1:])

Returns:

dict[str – A dictionary with entries of an array of strings for all plug-ins plus ‘SEAMM’

Return type:

[str]]

seamm_util.argument_parser.getParser(name='SEAMM', **kwargs)

Get the named command-line argument parser.

Returns:

The seamm.ArgumentParser for handling commandline and config-file parsing.

Return type:

ArgumentParser

seamm_util.argument_parser.seamm_parser(name='SEAMM')

Setup the command-line argument parser for SEAMM.

Returns:

The seamm.ArgumentParser for handling commandline and config-file parsing.

Return type:

ArgumentParser

seamm_util.check_executable module

Functions for handling executables

seamm_util.check_executable.check_executable(executable)

Check that an executable exists.

Check that an executable exists and is executable. If no path is given, but just the executable name, then the current path is checked. If the executable is missing or not actually executable this function raises a useful error with a message letting the user know where the path came from – a command line option, an environment variable, configuration file, or default.

Parameters:

of (executable -- required positional parameter giving the name) – the executable as a string. It can be a simple name or contain a path to the executable.

Returns:

The string for the path to the executable. If it was found on the path, the full path is returned, otherwise the return is the same as the executable string passed in.

Errors:

FileNotFoundError if the executable is not found or is not executable.

The message contains information about where the option came from, either the command-line, an environment variable, configuration file or the default.

seamm_util.compact_json_encoder module

From a gist by Jannis Mainczyk https://gist.github.com/jannismain/e96666ca4f059c3e5bc28abb711b5c92

class seamm_util.compact_json_encoder.CompactJSONEncoder(*args, **kwargs)

Bases: JSONEncoder

A JSON Encoder that puts small containers on single lines.

CONTAINER_TYPES = (<class 'list'>, <class 'tuple'>, <class 'dict'>)

Container datatypes include primitives or other containers.

MAX_ITEMS = 6

Maximum number of items in container that might be put on single line.

MAX_WIDTH = 80

Maximum width of a container that might be put on a single line.

encode(o)

Encode JSON object o with respect to single line lists.

property indent_str: str

iterencode(o, **kwargs)

Required to also work with json.dump.

seamm_util.configuration module

A class for reading, updating and writing the configuration file.

This class handles the configuration (.ini) file as text, so that comments in the file are preserved.

class seamm_util.configuration.Configuration(path=None)

Bases: object

add_prolog(text='', force=False)

Add the prolog to the configuration.

Parameters:

• text (str = '') – The body of the prolog, which should be just comments.

• force (bool = True) – Whether to overwrite an existing prolog.

add_section(name, text='', force=False)

Add a new section to the configuration.

Parameters:

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

• text (str = '') – The body of the section, which must be properly formatted.

• force (bool = True) – Whether to overwrite an existing section of the same name.

file_exists()

Whether the configuration file exists.

from_string(text)

Replace the contents of the configuration with those from text.

Parameters:

text (str) – The configuration data as text.

get_prolog()

Return the prolog of the file, if any.

Returns:

The prolog of the configuration.

Return type:

str

get_values(section)

Return the values in a section as a dictionary.

Returns an empty dictionary if the section does not exist, or if it does not contain any keyword definitions. Use section_exists to differentiate.

Parameters:

section (str) – The name of the section to retrieve.

Returns:

A dictionary of keyword-value pairs, as strings.

Return type:

dict

property path

The path to the configuration file.

save()

Save the current configuration to disk.

section_exists(section)

Return whether a section exits in the configuration.

Parameters:

section (str) – The name of the section.

Returns:

True if the section exists; False otherwise.

Return type:

bool

sections()

Return a list of sections in the configuration.

Returns:

The list of sections.

Return type:

[str]

set_value(section, key, value, strict=False)

Set the key in a section.

Parameters:

• section (str) – The section to work with.

• key (str) – The key to set in the section.

• value (str) – The value to set the key to.

• strict (bool = False) – Raise an error is the key does not already exist.

to_string(section=None)

Create the text of a section.

Parameters:

section (str) – The name of the section. Defaults to the entire file.

seamm_util.dictionary module

Provides a Dictionary, identical to a dict, but which can be subclassed safely.

class seamm_util.dictionary.Dictionary(*args, ordered=False, **kwargs)

Bases: MutableMapping

Class that acts like a dictionary, but can safely be subclassed.

The Dictionary class implements a dictionary-like class that other classes can inherit from. In addition, __init__ accepts a keyword ‘ordered’ specifying the use of an ordered dictionary.

copy()

Return a shallow copy.

classmethod fromkeys(iterable, value=None)

Create a new Dictionary with keys from iterable and values set to value.

seamm_util.elemental_data module

Tabulated data about the elements.

seamm_util.include_open module

Context manager for extending file reading to handle include’s

class seamm_util.include_open.Open(path, mode='r', logger=<Logger seamm_util.include_open (WARNING)>, include='#include', history=10, uri_handler=None)

Bases: object

property depth

The depth of the current line stack

property lineno

THe line number in the current file.

property path

The path of the current working file

property paths

The paths of all the opened files.

push(n=1)

Push the n last lines back onto the device (virtually)

stack()

Provide the traceback of the included files

property total_lines

property visited

The set of files used

seamm_util.include_open.default_uri_handler(path)

Do nothing! Just return the path

seamm_util.include_open.splitext(path)

Get the extension of a file, ignoring .gz or .bz2 on the end

Parameters:

path (str or pathlib.Path) – The name or path of the file

seamm_util.list_definition module

Tools for handling the shorthand definitions of lists in SEAMM.

seamm_util.list_definition.parse_list(input, duplicates=True, sort=False, **kwargs)

Parse a SEAMM-style list of values, including ranges.

Parameters:

• input (str) – The list definition (see below).

• duplicates (bool = True) – Allows duplicate values in the list by default.

• sort (bool = False) – If False, the list is not sorted. True or “ascending” sorts into ascending order while “descending” into reverse order. Only the first letter is tested, so any abbreviation works.

• kwargs ({str: any}) – Optional dictionary of values of variables used in the list.

Returns:

• list ([int or float]) – The expanded list of values

• The input list definition consists of any number of individual values or ranges,

• separated by commas (‘,’). Ranges are similar to those in Python *except that the*

• ’stop’ value is included in the list if stop = start + n*step. Ranges are defined as

• start (stop[:step]. If step is ommitted, it defaults to 1.)

Examples

A simple, commma delimited list is transformed into a python list:

>>> parse_list("1, 2, 4, 5")
[1, 2, 4, 5]

If any of the values is a float, the result is also a float

>>> parse_list("1, 2.0, 4, 5")
[1, 2.0, 4, 5]

This is a simple range:

>>> parse_list("1:6")
[1, 2, 3, 4, 5, 6]

Note that the stop value is include in the result. This is different than a python range where the termination is <, not <=. This is more natural for users of SEAMM. For example, scanning a dihedral angle from 0 to 180 degrees, most people will expect 180 to be in the list.

Now using a step of 2:

>>> parse_list("1:6:2")
[1, 3, 5]

Note that the stop value is not included in the output in this case.

The step can be negative as long as stop < start:

>>> parse_list("6:1:-2")
[6, 4, 2]

Now we can put it all together:

>>> parse_list("1, 2.0, 4, 5, 1:6, 1:6:2")
[1, 2.0, 4, 5, 1, 2, 3, 4, 5, 6, 1, 3, 5]

Note that a value can appear multiple times in a simple list. This can be controlled by setting duplicates = False:

>>> parse_list("1, 2.0, 4, 5, 1:6, 1:6:2", duplicates=False)
[1, 2.0, 4, 5, 3, 6]

You can also sort the results into ascending or descending order:

>>> parse_list("1, 2.0, 4, 5, 1:6, 1:6:2", sort="ascending")
[1, 1, 1, 2.0, 2, 3, 3, 4, 4, 5, 5, 5, 6]

and if you want to remove the duplicates too:

>>> parse_list("1, 2.0, 4, 5, 1:6, 1:6:2", duplicates=False, sort="descending")
[6, 5, 4, 3, 2.0, 1]

Where do variable fit? Any of the values in the input string can be variables as as long as values are are given as keyword arguments:

>>> parse_list("first:last:incr", first=1, last=6, incr=0.5)
[1, 1.5, 2.0, 2.5, 3.0, 3.5, 4.0, 4.5, 5.0, 5.5, 6.0]

It is often convenient if the variables are in a dictionary:

>>> values = {"first": 6, "last": 1, "incr":-0.5}
>>> parse_list("first:last:incr", **values)
[6, 5.5, 5.0, 4.5, 4.0, 3.5, 3.0, 2.5, 2.0, 1.5]

seamm_util.md_statistics module

Helpful routine using the underlying Python functions in ‘statistics’ and ‘statsmodels’ to handle common needs in molecular modeling

seamm_util.md_statistics.analyze_autocorrelation(y, interval=1, nlags=64, method='zr', use_confidence=False)

Find the statistical inefficiency, correlation time and other useful parameters given the time sequence of values ‘y’.

This function implements two approaches, ‘zr’ and ‘cspsd’ corresponding to the two papers (using the initials as the method name):

zr: Zięba, A.; Ramza, P. Standard Deviation of the Mean of Autocorrelated Observations Estimated with the Use of the Autocorrelation Function Estimated From the Data. Metrology and Measurement Systems 2011, 18 (4), 3–14.

cspsd: Chodera, J. D.; Swope, W. C.; Pitera, J. W.; Seok, C.; Dill, K. A. Use of the Weighted Histogram Analysis Method for the Analysis of Simulated and Parallel Tempering Simulations. J. Chem. Theory Comput. 2006, 3 (1), 26–41.

Parameters:

• y ([float]) – the time sequence to analyze

• interval (float) – the time interval between values, defaults to 1

• nlags (int) – the number of lags to start with

• method (str) – the approach to use, ‘zr’ or ‘cspsd’. Defaults to ‘zr’

Returns:

dict(

‘n’: (int) number of values in y ‘n_effective’: (int) effective number of uncorrelated values ‘n_c’: (int) the first zero crossing in the ACF ‘n_tau’: (int) number of intervals in the correlation time ‘tau’: (float) the correlation time if <interval> is correct ‘inefficiency’: (float) the statistical inefficiency ‘acf’: ([float]) the autocorrelation function ‘confidence_interval’: [(float, float)] the 95% confidence interval

The input parameter <nlags> is solely for performance. Since calculating the ACF is expensive (O(N^2)) and often the correlation time is short, at least if the trajectory is sampled reasonably, this function starts with a small number of lags, and doubles the number repeatedly if it does not find the zero crossing it expects.

seamm_util.md_statistics.ar1(n=1000, a=10.0, b=0.2, sigma=0.5, seed=None)

Generate an AR(1) series of length n

seamm_util.output module

A class for wrapping output from the MolSSI Framework and plugins. Initially it is a thin wrapper around a dictionary to store the output, using JSON to serialize and deserialize the data.

It presents the dict api with the addition of methods to serialize and deserialize the contents.

class seamm_util.output.Output(filename=None, **kwargs)

Bases: MutableMapping

copy()

Return a shallow copy of the dictionary

property filename

The filename for the serialized data

seamm_util.plotting module

A package for handling plotly plots in SEAMM.

A figure comprises one or more plots (or graphs) laid out in a grid. The datasets within a plot are represetned by traces, lines, scatter plots, pie chart elements, etc.

This package consists of a Figure class which is a container, a Plot class that handles the actual plotting, and a Trace class for the individual datasets and their graphical representations. The figure class uses a grid similar to the Tk grid to control the layout of the plots.

This package does not directly interact with plotly. Rather, it uses templates and Jinja to create the JSON, HTML or other representation of a plotly figure. The various containers in this package contain dictionaries of Jinja keys and the associated values. The keys needed are defined by the template used.

class seamm_util.plotting.Axis(direction, *args, anchor=None, start=0.0, stop=1.0, **kwargs)

Bases: Dictionary

Class to represent an axis in a plotly plot.

The Axis class defines an axis and the associated graphical control for how to display them. The class is a dict-like object where the elements of the dictionary are the control parameters for the axis.

to_dict()

Return a dictionary representing the axis.

Returns:

A dictionary of the axis data, suitable for Jinja.

Return type:

dict

class seamm_util.plotting.Figure(*args, jinja_env=None, template=None, **kwargs)

Bases: Dictionary

Holds one or more subplots and controls the layout.

add_plot(name, **kwargs)

Create a new plot and return it.

Parameters:

name (str) – The name of the plot, which must be unique.

Return type:

The plot object.

dump(filename)

Write the filled in template to disk as <filename>.

Parameters:

filename (str or filepath) – The name or path to the file to write.

Return type:

nothing

dumps()

Return the filled in template document as a string.

Merge the layout data and the traces into the template document and return a string version of the document.

Returns:

The resulting document.

Return type:

str

get_plot(name)

Return the named plot.

Parameters:

name (str) – The name of the plot, which must exist.

Return type:

The plot object.

grid_plots(*args, padx=0.02, pady=0.02)

Define the layout of the plots.

When there is more than one plot, they need to be laid out in a grid. This method is called to define the layout, and will follow closely the approach used in Tk grid.

Parameters:

• *args –

  Positional arguments specifying the layout of one or more rows. each row is given as a string composed of the following:

  <plot> :

  is the name of a plot.

  x :

  leaves an empty column between the plot on the left and the plot on the right.

  ^ :

  extends the row span of the plot above the ^’s in the grid. The number of ^’s in a row must match the number of columns spanned by the plot above it.

  • :

    increases the column span of the plot to the left. Several -‘s in a row will successively increase the number of columns spanned. A - may not follow a ^ or a x, nor may it be the first plot argument to grid configure.

• **kwargs –

  Keyword arguments for options for the given rows:

  padxfloat, optional

  The fraction of space to leave between plots in a row. Defaults to 0.02.

  padyfloat, optional

  The fraction of space to leave between rows. Defaults to 0.02.

property template

The template to use for this figure.

class seamm_util.plotting.Plot(left=0, right=1, top=1, bottom=0, row=0, column=0, column_span=1, row_span=1)

Bases: Dictionary

Class to represent a plotly plot.

The Plot class contains Axes and Traces, which represent the datasets being plotted. This class is a dict-like object where the elements of the dictionary are the traces.

add_axis(direction, anchor=None, **kwargs)

Create a new axis and return it.

Parameters:

direction (str (one of 'x', 'y', or 'z')) – The direction of this axis.

Return type:

The axis object.

add_trace(name, x_axis=None, y_axis=None, z_axis=None, **kwargs)

Create a new trace and return it.

Parameters:

name (str) – The name of the trace, which must be unique.

Return type:

The trace object.

property axes

The list of axes for this plot.

class seamm_util.plotting.Trace(x_axis=None, y_axis=None, z_axis=None, **kwargs)

Bases: Dictionary

Class to represent a trace in a plotly plot.

The Trace class contains the datasets and associated graphical control for how to display them. The class is a dict-like object where the elements of the dictionary are the traces.

to_dict()

Return a dictionary representing the trace.

Returns:

A dictionary of the trace data, suitable for Jinja.

Return type:

dict

seamm_util.printing module

The Printer class provides control over printing output, based on the Python logging module. The levels a translated to more reasonable names for output, rather than debugging:

Level Logger Level Numeric value ——– ———— ————- JOB CRITICAL 50 IMPORTANT ERROR 40 TERSE WARNING 30 NORMAL INFO 20 VERBOSE DEBUG 10 ALL ALL 0

By default, JOB level output is mirrored in the main log for the job as well as the local log for the stage. All output from the cutoff level up, which is NORMAL by default, is placed in the local stage log. Optionally, output from a cutoff level and up is also written to the standard output.

class seamm_util.printing.FormattedText(text, dedent=True, indent='', indent_initial=True, indent_all=False, wrap=True, line_length=80, *args, **kwargs)

Bases: object

Class for wrapping, formatting and indenting text to make textual output from the MolSSI Framework and its plugins easier

The __str__ method returns the formatted text, so e.g. print(<object>) formats the text and prints it as expected.

Example:

ft = FormattedText(‘’’ This is the first line. And the second. And a very, very, very, very, very, very, very, very, very, very, very, very long line. And i = ‘{i}’ and j = ‘{j}’ followed by a line break

Ending with the last line. Which can of course also be wrapped if we want it to be.

What about a list: 1

With a second item: 2

Does that work?’’’, i=1, j=2, indent=’—>’, line_length=70)

print(ft)

—>This is the first line. And the second. And a very, very, very, —>very, very, very, very, very, very, very, very, very long line. —>And i = ‘1’ and j = ‘2’ followed by a line break

—>Ending with the last line. Which can of course also be wrapped if —>we want it to be.

—> What about a list: 1

—> With a second item: 2

—>Does that work?

where the start of each arrow is aligned to the left (not indented as in this string).

class seamm_util.printing.Manager(print_root)

Bases: object

There is [under normal circumstances] just one Manager instance, which holds the hierarchy of printers.

getPrinter(name)

Get a printer with the specified name (channel name), creating it if it doesn’t yet exist. If a PlaceHolder existed for the specified name [i.e. the printer didn’t exist but a child of it did], replace it with the created printer and fix up the parent/child references which pointed to the placeholder to now point to the printer.

class seamm_util.printing.PlaceHolder(aprinter)

Bases: object

PlaceHolder instances are used in the Manager printer hierarchy to take the place of nodes for which no printers have been defined [FIXME add example].

append(aprinter)

Add the specified printer as a child of this placeholder.

class seamm_util.printing.Printer(name, level=0)

Bases: Filterer

Provide controlled printing for plugins for the MolSSI Framework.

addHandler(hdlr)

Add the specified handler to this printer.

callHandlers(record)

Loop through all handlers for this printer and its parents in the printer hierarchy. If no handler was found, output a one-off error message to sys.stderr. Stop searching up the hierarchy whenever a printer with the “propagate” attribute set to zero is found - that will be the last printer whose handlers are called.

property disabled

findCaller()

Find the stack frame of the caller so that we can note the source file name and line number.

getEffectiveLevel()

Loop through this printer and its parents in the printer hierarchy, looking for a non-zero logging level. Return the first one found.

handle(record)

Call the handlers for the specified record. This method is used for unpickled records received from a socket, as well as those created locally. Logger-level filtering is applied.

property handlers

important(msg, *args, **kwargs)

Logs a message with level IMPORTANT on this printer. The msg is the message format string, and the args are the arguments which are merged into msg using the string formatting operator. (Note that this means that you can use keywords in the format string, together with a single dictionary argument.)

isEnabledFor(lvl)

Is this printer enabled for level lvl?

job(msg, *args, **kwargs)

Logs a message with level JOB on this printer. The msg is the message format string, and the args are the arguments which are merged into msg using the string formatting operator. (Note that this means that you can use keywords in the format string, together with a single dictionary argument.)

property level

makeRecord(name, lvl, fn, lno, msg, args, exc_info)

A factory method which can be overridden in subclasses to create specialized LogRecords.

manager = <seamm_util.printing.Manager object>

property name

normal(msg, *args, **kwargs)

Logs a message with level NORMAL on this printer. The msg is the message format string, and the args are the arguments which are merged into msg using the string formatting operator. (Note that this means that you can use keywords in the format string, together with a single dictionary argument.)

property parent

print(lvl, msg, *args, **kwargs)

Prints a message with integer level lvl on this logger. The other arguments are interpreted as for verbose().

print_root = <seamm_util.printing.RootPrinter object>

property propagate

removeHandler(hdlr)

Remove the specified handler from this printer.

setLevel(lvl)

Set the printing level of this printer.

terse(msg, *args, **kwargs)

Logs a message with level TERSE on this printer. The msg is the message format string, and the args are the arguments which are merged into msg using the string formatting operator. (Note that this means that you can use keywords in the format string, together with a single dictionary argument.)

verbose(msg, *args, **kwargs)

Logs a message with level VERBOSE on this printer. The msg is the message format string, and the args are the arguments which are merged into msg using the string formatting operator. (Note that this means that you can use keywords in the format string, together with a single dictionary argument.)

class seamm_util.printing.RootPrinter(lvl)

Bases: Printer

A root printer is not that different to any other printer, except that it must have a printing level and there is only one instance of it in the hierarchy.

seamm_util.printing.addLevelName(lvl, levelName)

Associate ‘levelName’ with ‘lvl’. This is used when converting levels to text during message formatting.

seamm_util.printing.basicConfig()

Do basic configuration for the printing system by creating a StreamHandler with a default Formatter and adding it to the root logger.

seamm_util.printing.disable(level)

Disable all printing calls less severe than ‘level’.

seamm_util.printing.fileConfig(fname)

Read the printing configuration from a ConfigParser-format file. This can be called several times from an application, allowing an end user the ability to select from various pre-canned configurations (if the developer provides a mechanism to present the choices and load the chosen configuration). In versions of ConfigParser which have the readfp method [typically shipped in 2.x versions of Python], you can pass in a file-like object rather than a filename, in which case the file-like object will be read using readfp.

seamm_util.printing.getLevelName(lvl)

Return the textual representation of printing level ‘lvl’. If the level is one of the predefined levels (JOB, IMPORTANT, TERSE, NORMAL, VERBOSE) then you get the corresponding string. If you have associated levels with names using addLevelName then the name you have associated with ‘lvl’ is returned. Otherwise, the string “Level %s” % lvl is returned.

seamm_util.printing.getPrinter(name=None)

Return a printer with the specified name, creating it if necessary. If no name is specified, return the root printer.

seamm_util.printing.important(msg, *args, **kwargs)

Log a message with severity ‘IMPORTANT’ on the root printer.

seamm_util.printing.job(msg, *args, **kwargs)

Log a message with severity ‘JOB’ on the root printer.

seamm_util.printing.normal(msg, *args, **kwargs)

Log a message with severity ‘NORMAL’ on the root printer.

seamm_util.printing.setPrinterClass(klass)

Set the class to be used when instantiating a printer. The class should define __init__() such that only a name argument is required, and the __init__() should call Printer.__init__()

seamm_util.printing.shutdown()

Perform any cleanup actions in the printing system (e.g. flushing buffers). Should be called at application exit.

seamm_util.printing.terse(msg, *args, **kwargs)

Log a message with severity ‘TERSE’ on the root printer.

seamm_util.printing.verbose(msg, *args, **kwargs)

Log a message with severity ‘VERBOSE’ on the root printer.

seamm_util.seamm_file module

A class for wrapping output from the MolSSI Framework and plugins. Initially it is a thin wrapper around a dictionary to store the output, using JSON to serialize and deserialize the data.

It presents the dict api with the addition of methods to serialize and deserialize the contents.

class seamm_util.seamm_file.File(filename, mode, compression=None, organization='MolSSI', filetype=None, version=None)

Bases: object

read_header()

seamm_util.seamm_json module

Extend JSON encoding/decoding to handle pint Quantities, as well as datetimes and timedeltas

To encode:

import seamm_util dump = json.dumps(<variable>, cls=seamm_util.JSONEncoder)

and to decode:

import seamm_util decoder = seamm_util.JSONDecoder() <variable> = decoder.decode(dump)

Adapted from http://taketwoprogramming.blogspot.com/2009/06/subclassing-jsonencoder-and-jsondecode

class seamm_util.seamm_json.JSONDecoder

Bases: JSONDecoder

Decodes a json string, where pint Quantities, datetime and timedelta objects were converted into objects using the seamm_util.JSONEncoder, back into a python object.

dict_to_object(d)

class seamm_util.seamm_json.JSONEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)

Bases: JSONEncoder

Encodes a python object, where pint Quantities, datetime and timedelta objects are converted into objects that can be decoded using the seamm_util.JSONDecoder.

Adapted from http://taketwoprogramming.blogspot.com/2009/06/subclassing-jsonencoder-and-jsondecoder.html # noqa: E501

default(obj)

Implement this method in a subclass such that it returns a serializable object for o, or calls the base implementation (to raise a TypeError).

For example, to support arbitrary iterators, you could implement default like this:

def default(self, o):
    try:
        iterable = iter(o)
    except TypeError:
        pass
    else:
        return list(iterable)
    # Let the base class default method raise the TypeError
    return super().default(o)

seamm_util.seamm_util module

Main module.

seamm_util.units module

Localize the unit handling.

seamm_util.units.default_units(units_or_dimensions)

Return the default units.

Parameters:

units_or_dimensions (str) – The units or dimensionality.

Returns:

The list of unit strings.

Return type:

[str]

seamm_util.units.sort_dimensions(dimensions)

Sort the dimensions.

Parameters:

dimensions (str) – The dimensions.

Returns:

The sorted dimensions.

Return type:

str

seamm_util.variable_names module

Utility routines to help with variable names for scripts

seamm_util.variable_names.clean(raw_name)

Fix up an input string so that it is a valid variable name

seamm_util.variable_names.is_valid(name)

Check if a variable name is valid and is not a keyword

seamm_util.variable_names.iskeyword()

x.__contains__(y) <==> y in x.

seamm_util.water_models module

Various water models.

class seamm_util.water_models.SPC

Bases: Water

atom_types()

The atom types for this model.

Returns:

types – 3-vector of atom types

Return type:

str[3]

class seamm_util.water_models.SPC_E

Bases: Water

atom_types()

The atom types for this model.

Returns:

types – 3-vector of atom types

Return type:

str[3]

reference()

class seamm_util.water_models.TIP3P

Bases: Water

atom_types()

The atom types for this model.

Returns:

types – 3-vector of atom types

Return type:

str[3]

class seamm_util.water_models.Water(r0, theta0, qO=None, qH=None, lj_a=None, lj_b=None)

Bases: object

Generic water model

coordinates()

A standard set of coordinates in Angstrom

The oxygen is at the origin, with the hydrogens in the x-z plane. Z is the two-fold axis of symmetry.

Return type:

Tuple of three tuples with (x, y z)

static create_model(model_name)

Static method to simplify constructing models for string names.

static find_waters(system)

Find the water molecules in the given system.

At the moment, the atoms are 0-based, but the bonds are given using 1-based atom numbers!

Parameters:

system (System object)

property mass

pdb()

The contents of a PDB file for this model.

Returns:

pdb – The contents of a PDB file for this model.

Return type:

str

system()

Return the model as a SEAMM system.

Returns:

system

Return type:

SEAMM system

seamm_util.zenodo module

Interact with Zenodo via its REST API

class seamm_util.zenodo.Record(data, token)

Bases: Mapping

A class for handling uploading a record to Zenodo.

data

The record data from Zenodo. See https://developers.zenodo.org/#depositions

Type:

dict()

token

The Zenodo access token for the user.

Type:

str

metadata

The metadata for updating the record.

Type:

dict()

add_creator(name, affiliation=None, orcid=None, ignore_duplicates=False)

Add a creator (author) to the record.

Parameters:

• name (str) – The creators name as “family name, other names”

• affiliation (str, optional) – The creators affiliation (University, company,…)

• orcid (str, optional) – The ORCID id of the creator.

• ignore_duplicates (bool = False) – Silently ignore duplicate records.

add_file(path, contents=None, binary=False)

Add the given file to the record.

Parameters:

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

• binary (bool = False) – Whether to open as a binary file.

add_keyword(keyword)

Add a keyword to the record.

Parameters:

keyword (str) – The keyword

property authors

Synonym for creators

property conceptdoi

The generic concept DOI.

property creators

The creators for the record.

property description

The description for the record.

property doi

The (prereserved) DOI.

download_file(filename, path)

Download a file to a local copy.

Parameters:

• filename (str) – The name of the file.

• path (pathlib.Path) – The path to download the file to. Can be a directory in which case the filename is used in that directory.

Returns:

The path to the downloaded file.

Return type:

pathlib.Path

files()

List of the files deposited.

Return type:

[str]

get_file(filename)

Get the contents of a file.

Parameters:

filename (str) – The name of the file.

Return type:

str or byte

property in_progress

Whether the deposition is still in progress, i.e. editable.

Return type:

bool

property keywords

The keywords for the record.

publish()

Publish the record on Zenodo.

This registers the DOI, and after this the files cannot be changed. Any new metadata is uploaded before publishing.

remove_file(filename)

Remove a file.

Parameters:

filename (str) – The name of the file.

remove_keyword(keyword)

Remove a keyword from the record.

Parameters:

keyword (str) – The keyword

property submitted

Whether the record has been submitted.

If so the files can’t be changed, but it may be possible to edit the metadata.

Return type:

bool

property title

The title for the record.

update_metadata()

Update the metadata for the record in Zenodo.

property upload_type

The type of record in Zenodo.

class seamm_util.zenodo.Zenodo(token=None, configfile='~/.seamm.d/seammrc', use_sandbox=False)

Bases: object

add_version(_id)

Create a new record object for uploading a new version to Zenodo.

create_record()

Create a new record object for uploading to Zenodo.

get_deposit_record(_id)

Get an existing deposit record object from Zenodo.

get_record(_id)

Get an existing record object from Zenodo.

search(authors=None, query='', communities=None, keywords=None, title=None, description=None, all_versions=False, size=25, page=1)

Search for records in Zenodo.

property token

The appropriate token for Zenodo.

Module contents

seamm_util Utility functions for the SEAMM environment.