pymolpro package

Module contents

class pymolpro.ASEMolpro(name='ASEMolpro', method='hf', basis='cc-pVDZ', project_location=None, **kwargs)

Bases: BaseCalculator

ASE calculator interface to Molpro. Implemented using pysjef and pymolpro, which use project bundles to contain input, output and other files, as described at https://github.com/molpro/sjef and https://github.com/molpro/pymolpro.

__init__(name='ASEMolpro', method='hf', basis='cc-pVDZ', project_location=None, **kwargs)

Parameters:

name (str) – The file name for the Molpro project
method (str) – Molpro input fragment that specifies the method
basis (str) – Basis set specification in the form of arguments to Molpro basis directive
project_location (str) – Directory where the project bundle will be placed. Defaults to a unique temporary directory
kwargs (dict) – Any additional arguments to pass through to pymolpro.Project()

calculate(atoms, properties, system_changes)

calculate_properties(atoms, properties): This method is experimental; currently for internal use.

calculation_required(atoms, properties)

check_state(atoms, tol=1e-15): Check for any system changes since last calculation.

clean(): Remove all Molpro projects from file system

export_properties()

get_charges(atoms=None)

get_dipole_moment(atoms=None)

get_forces(atoms=None)

get_magnetic_moment(atoms=None)

get_magnetic_moments(atoms=None): Calculate magnetic moments projected onto atoms.

get_potential_energies(atoms=None)

get_potential_energy(atoms=None, force_consistent=False)

get_property(name, atoms=None, allow_calculation=True): Get the named property.

get_stress(atoms=None)

get_stresses(atoms=None): the calculator should return intensive stresses, i.e., such that stresses.sum(axis=0) == stress

implemented_properties: list[str] = ['energy', 'forces']: Properties calculator can handle (energy, forces, …)

property name: str

todict() → dict[str, Any]: Obtain a dictionary of parameter information

class pymolpro.Database(molecules: dict[str, str] = None, reactions: dict[str, dict[str, int]] = None, description: str = None, project_directory: str = None)

Bases: object

Database of molecular structures and reactions. The class contains and supports the following data.

Descriptions of molecules: geometry, charge, spin state.
Descriptions of reactions between the molecules: stochiometric factors.
Optionally, computed data: energies of molecules and/or reactions,s the parameters used to obtain them, and references to persistent data that can be used to further query or restart.
Description and external URLs that serve to further define the provenance of the data.
Specification of recommended subsets of the reactions

__init__(molecules: dict[str, str] = None, reactions: dict[str, dict[str, int]] = None, description: str = None, project_directory: str = None)

Parameters:

molecules – Initial molecules to be added with default options to add_molecule().
reactions – Initial reactions to be added with default options to add_reaction().
description – Text describing the database
project_directory – The path of the directory where support files that were generated in calculating energies can be found.

add_molecule(name, geometry, energy=None, description=None, InChI=None, SMILES=None, spin=None, charge=None, preamble=None)

Add a molecule to the database. The minimal information that is stored is the geometry, but information from each of the optional arguments, if given, is also stored in the molecules dictionary.

Parameters:

name (str) – The key for the molecule in molecules.
geometry (str) – The geometry. Any format recognised by Molpro can be used. This includes xyz, with or without the two header lines, or Z matrix, and lines can be separated either with newline or ;. The geometry can be specified either as a string, or a filename or url reference, in which case the contents of the reference are resolved now.
energy (float) – The reference value for the energy of the molecule in Hartree units
description (str) – Descriptive text
InChI (str) – InChI string describing the molecule
SMILES (str) – SMILES string describing the molecule
spin (int) – The spin multiplicity minus one
charge (int) – Electrical charge of molecule
preamble (str) – Additional Molpro input to be added before geometry

Returns:

The added molecule

Return type:

dict

add_reaction(name, stoichiometry, energy=None, description=None)

Add a reaction to the database. The minimal information that is stored is the stoichiometry, which references existing molecules in the database, but information from each of the optional arguments, if given, is also stored in the reactions dictionary.

Parameters:

name – The key for the reaction in reactions.
stoichiometry – A dictionary describing the stoichiometry of the reaction. Each key should be a key in molecules, and the value is an integer giving the number of equivalents of the molecule in the reaction, with the sign convention of positive for products, negative for reactants.
energy – The reference value for the energy change of the reaction in Hartree units. If not given, and if all molecules in the reaction have an energy, it will be computed.
description – Descriptive text

Returns:

The added reaction

Return type:

dict

add_reference(key, url)

add_subset(subset_name, subset)

basis: A string specifying the orbital basis-set used to compute the energies.

calculate_reaction_energies(check=False)

clean(keep_run_directories=1)

Remove run directories from each project in projects.

Parameters:: keep_run_directories – The number of most recent run directories to keep for each project.

copy()

description: Text describing the database

dump(filename=None)

Dump the database in json format.

Parameters:: filename (str) – If specified, the destination of the result
Returns:: If filename is not specified, the json is returned as a string
Return type:: str

failed: Subset of projects corresponding to jobs that did not complete successfully.

input_specification: A string containing JSON describing the Molpro input used to construct the energies

load(source)

Load the database from a json dump in either the library, a file or a string

Parameters:: source (str) – Source of dump
Returns:: The database
Return type:: Database

method: A string specifying the ansatz used to compute the energies.

molecule_energies: A dictionary with molecule keys giving the molecular energy/Hartree reference values associated with the Database. The dictionary could be empty or only partly filled.

molecules: Dictionary of molecules

preamble: any Molpro commands that should be executed before geometry specification. Typically angstrom could be specified if the geometry specification is in Z-matrix format with numerical values that would, by default, be interpreted as Bohr.

project_directory: A string giving the path of the directory where support files generated in calculating energies can be found.

projects: A dictionary with molecule handles pointing to filesystem project bundles for each Molpro job that has been run.

reaction_energies: A dictionary with reaction keys giving the reaction energy/Hartree reference values associated with the Database. The dictionary could be empty or only partly filled. A database might have either, both or none of molecule_energies or reaction_energies.

reactions: Dictionary of reactions involving the molecules together with stoichiometric factors

references: A dictionary of external references to the data. The keys should be a short-form string that you want printed, eg author, year, and the values URLs that lead to the resource.

subset(subset=None, open_shell=True, max_atoms=None, max_electrons=None)

Extract a subset of this database as a new database

Parameters:

subset – Either a key in the subsets or a list of keys in reactions. If not given, all the reactions in the database
open_shell – Whether to include reactions involving open-shell molecules, or prune to closed-shell only
max_atoms – Exclude reactions with one or more molecules with more than this number of atoms
max_electrons – Exclude reactions with one or more molecules with more than this number of electrons

Returns:

The subset

Return type:

Database

subsets: A dictionary defining named subsets of the database reactions

class pymolpro.Orbital(node, directory=None)

Bases: object

Container for an orbital (usually molecular).

property ID

__init__(node, directory=None)

Initialise from a node on a Molpro output xml tree

Parameters:

node – lxml.etree.Element holding a single orbital
directory – the directory in which the xml file, and its sidecar, live

property atoms

attribute(key)

property axes

The coordinate system for the orbital. The $z$ axis is the normalised vector $\vec e_{z}$ that is the eigenvector of the second-moment tensor of largest eigenvalue, similarly for $\vec e_y, \vec e_x$. The phase of each axis is chosen such that the largest of the coefficients specifying the axis in the global coordinate system is positive.

Returns:: The axes, with the first index labelling the component in the base coordinate system, and the second index specifying which orbital axis.
Return type:: np.array(3,3)

centroid: Centroid of the orbital

cube_data(resolution: float = 0.2, border=4.25, bounds=None, threshold=None) → CubeData

Generates a 3D data cube representation of the molecular system.

The method computes a 3D data grid based on the atomic coordinates in the molecular system. The grid is defined by a specified resolution and includes an additional border around the atomic region. The computed grid points are evaluated for property values to create the data cube.

Parameters:

resolution: float: The spacing between grid points in Bohr.
border: float: The distance to extend the grid beyond the minimum and maximum atomic coordinates in all dimensions, in Bohr.
bounds: list[list[float]]: Limit edges of the grid to specified values, in Bohr. The shape of bounds should be (3,2), with the first index labelling the cartesian coordinate, and the second corresponding to minimum and maximum extents.
threshold: float: Trim the sampled region to exclude feasible regions with occupation below this threshold.

Returns:

CubeData: An object containing details about the generated data cube, including atomic information, grid properties, and evaluated data.

energy: energy of the orbital

evaluate(points, values=False)

Evaluate orbital on a grid of points

Parameters:

points – List of geometries specified as 3-list of values in bohr
values

Returns:

array of dictionaries giving the occupation and values on the grid, or if ID is specified, a single dictionary, or if values==True, a numpy array

grid(npt, method='erfinv', scale=1.0, grid_parameters=[], spherical_average=False, resolution=None, orbital_cutoff=0.001)

Generate a grid centred on the orbital.

Parameters:

npt – Number of desired points in each coordinate.
method – Algorithm for grid generation.
scale – Scale the grid by this factor.
resolution – Resolution of the grid in Bohr, for the uniform grid method.

Returns:

points and weights (numpy array [npt,4])

property kinetic_energy: Kinetic energy expectation value for the orbital.

property local_second_moments

occupation: Occupation of the orbital

second_moment_eigenvalues: Eigenvalues of the orbital second-moment tensor (origin at centre of charge) in ascending order

class pymolpro.Pair(node)

Bases: Tuple

Container for a pair of orbitals

__init__(node): Initialise from a node on a Molpro output xml tree

property axes

The coordinate system for the pair of orbitals. The $z$ axis is the vector $\vec e_{z,10}=(\vec r_1-\vec r_0)/|\vec r_1-\vec r_0|$ from orbital 0 to orbital 1. The $x$ axis is the along the vector $\vec e_{x,10} = \vec e_{z,10} \times \vec e_z$ (or $\vec e_y$ if necessary), normalised. Then $\vec e_{y,10}=\vec e_{z,10}\times\vec e_{x,10}$. If $|\vec r_1-\vec r_0|$ is small, the global coordinate axes are adopted.

Returns:: The axes, with the first index labelling the component in the base coordinate system, and the second index specifying which pair axis.
Return type:: np.array(3,3)

energy: Correlation energy contribution from a Single or Pair

property local_orbital_axes

The coordinate axes of the orbitals expressed in the basis of the pair coordinate system.

Returns:
Return type:: list(np.array(3,3))

orbitals: Orbital objects forming the tuple

spins: 1(alpha) or -1(beta) for each orbital

Bases: Project

A Project holds all the data associated with a single Molpro job. This includes input, output, any auxiliary files, and information about the state of the job. Project acts as a reference to a sjef Project with some added functionality. All of the data is stored in the project bundle on the file system, with the consequence that it is safe to construct and recreate multiple Project objects all mapping the same underlying project.

The underlying functionality of sjef includes job submission and monitoring on local or remote machines, and structured searching of Molpro’s xml output stream. This class provides additional convenience operations:

Preparation of simple Molpro input from provided geometry, method, basis set and other options.
Molpro-specific error checking.
Computed properties, energies and geometries.
Computed orbitals, including their evaluation on a grid.
Values of Molpro variables.

Parameters:

name – The base filename of the filesystem bundle carrying the project. If the bundle does not yet exist, it is created.
input – General specification of the input. If it looks like JSON or is a dictionary, it is treated as if it had been passed as the specification parameter. If it has the form method/basis or method/basis//geometry_method/geometry_basis, it is treated as if it had been passed as the ansatz parameter. Otherwise, it is treated as the desired contents of the Molpro input file. If input is specified, all other arguments are ignored.
specification – Either a dictionary or a JSON string conforming to the JSON schema https://www.molpro.net/schema/molpro_input.json
ansatz – A string of the form method/basis//geometry_method/geometry_basis or method/basis which is parsed to give the same effect as the method and basis parameters. If geometry_method/geometry_basis is specified, the calculation will be preceded by a geometry optimisation at that level of theory.
files – External files to be copied into the project directory. If one of these is a molpro-output xml file, or a plain-text Molpro output file, it is used to construct the input file.
kwargs – Any of the top-level keywords in the JSON schema https://www.molpro.net/schema/molpro_input.json, or any of the arguments accepted by the parent sjef.Project class constructor.

property ansatz

backend_get(backend, key)

Obtain the value of a field in the backend

Parameters:

backend
key

Returns:

backend_names(): Get the names of all the backend objects associated with the object.

backend_parameter_default(backend, param)

Returns default value for backend parameter

Parameters:

backend – name of the backend
param – name of parameter

backend_parameter_delete(backend, param)

Delete backend parameter from property file.

Parameters:

backend – name of the backend
param – name of parameter

backend_parameter_documentation(backend, param)

Returns documentation for backend parameter

Parameters:

backend – name of the backend
param – name of parameter

backend_parameter_get(backend, param)

Gets backend parameter from property file.

Parameters:

backend – name of the backend
param – name of parameter

backend_parameter_set(backend, param, value)

Sets backend parameter in property file. The parameter will be used by the backend when interacting with the current jobs.

Parameters:

backend – name of the backend
param – name of parameter
value – parameter value to set

backend_parameters(backend, doc=False)

Get all of the parameters referenced in the run_command of a backend

Parameters:

backend – The name of the backend
doc – Whether to return documentation instead of default values

Returns:

A dictionary where the keys are the parameter names, and the values the defaults.

basis_registry()

Get the basis registry from the Molpro pointed to in the local backend

Returns:
Return type:: dict

builtins = <module 'builtins' (built-in)>

child(*attributes, nodename='', **kwargs_and_callables)

Utility wrapper over select routine to do a 1 level search of children and select a single one. If more than one child is selected, RuntimeError is thrown.

Arguments are translated into selectors by attribute name ( see select). Key word arguements are translated into selectors by attribute name ( see select).

Example:

out = p.select(‘container[location, name=directory, exists(location)]’,: exists=os.path.exists)

is equivalent to

out = p.child(‘location’, nodename=’container’, name=’directory’, ‘exists(location)’,: exists=os.path.exists)

Parameters:

nodename – selector for name of the node class
attributes – list of attributes for defining selectors by name, [attribute] and callable selectors [func(attr1, attr2)] ( see select)
kwargs_and_callables – dictionary of other kwargs defining attribute selectors key = value and callable functions for callable selectors func = function_name

Returns:

clean(keep_run_directories=1): Remove run directories from the project

commandify_method(method)

completed()

Returns:: True if status is completed

copy(name, location=None, force=False, keep_hash=False, keep_run_directories=1000000)

Make a copy of the project and its directory to a new path.

Parameters:

name – name of the new project
location – path to the parent of the project, by default parent directory stays the same
force – whether to first remove anything already existing at the new location
keep_hash – whether to clone the project_hash, or allow a fresh one to be generated
keep_run_directories – how many run directories to retain in the copy

Returns:

copied project

copy_node(): Returns a copy of itself

energies(*args, **kwargs)

Wrapper for properties() that restricts to energy values

Parameters:

args
kwargs

Returns:

energy(*args, **kwargs)

Wrapper for energies() that returns a single value as a scalar. An exception is thrown if more than one value is found.

Parameters:

args
kwargs

Returns:

erase(path=None)

Delete the project under path with its directory and all files.

Parameters:: path – path to the project, defaults to current project
Todo:: what should happend to attributes and children?

errors(ignore_warning=True)

Return all error nodes

Returns:: list of error nodes
Return type:: lxml.etree

evaluateOrbitals(points, instance=-1, minocc=1e-10, ID=None, values=False)

Evaluate molecular orbitals on a grid of points

Parameters:

points – List of geometries specified as 3-list of values in bohr, or numpy [:,3] array
instance – Which set of orbitals
minocc – Only orbitals with at least this occupation will be returned
ID – Only the orbital whose ID attribute matches this will be selected
values

Returns:

array of dictionaries giving the occupation and values on the grid, or if ID is specified, a single dictionary, or if values==True, a numpy array

export_file(filename, location, overwrite)

Export one or more files from the project.

Parameters:

filename – name of the file in the project
location – The relative or absolute path to the destination directory
overwrite – Whether to overwrite an existing file.

filename(suffix='', name='', run=0)

Get the file name of the bundle, or a primary file of particular type, or a general file in the bundle

Parameters:

suffix – If present without name, look for a primary file with that type. If absent, the file name of the bundle is instead selected
name – If present, look for a file of this name, appended with .suffix if that is non-blank
run –
- 0: the currently focussed run directory
- other: the specified run directory

Returns:

the fully-qualified name of the file

findall(search_pattern)

geometries(preamble='//', parent_node=None)

Obtain all geometries from the job output

Parameters:: preamble – Prepend this to the xpath search expression to locate the geometry
Returns:: list of dictionaries holding the geometry. Coordinates are in bohr

geometry(preamble='//', instance=-1)

Obtain the geometry from the job output

Parameters:

preamble – Prepend this to the xpath search expression to locate the geometry
instance – In the case of multiple geometries in the output stream, which occurence

Returns:

dictionary holding the geometry. Coordinates are in bohr

gradient(instance=-1)

import_file(location, overwrite=True)

Import file at path location into the project.

Parameters:

location – path to file
overwrite – if corresponding file already exists in the project, flags that it should be overwritten

import_input(fpath)

Copy file into the project as input file, or write string to input file

Parameters:: fpath – path to input file

initialize_from_files(files: str | list[str] | None)

input(input: str | dict = None, specification: str | dict = None, ansatz: str = None, **kwargs)

Defines the input for running Molpro.

:param input:General specification of the input. If it looks like JSON or is a dictionary, it is treated as if it had been passed as the specification parameter. If it has the form method/basis or method/basis//geometry_method/geometry_basis, it is treated as if it had been passed as the ansatz parameter. Otherwise, it is treated as the desired contents of the Molpro input file. If input is specified, all other arguments are ignored. :param specification: Either a dictionary or a JSON string conforming to the JSON schema https://www.molpro.net/schema/molpro_input.json :param ansatz: A string of the form method/basis//geometry_method/geometry_basis or method/basis which is parsed to give the same effect as the method and basis parameters. If geometry_method/geometry_basis is specified, the calculation will be preceded by a geometry optimisation at that level of theory. :param kwargs: Any of the top-level keywords in the JSON schema https://www.molpro.net/schema/molpro_input.json

property input_file_path

input_from_out() → list[str]

Return a list of all defined input in the text output stream

Returns:

input_from_run(run: int, action: bool = True) → bool

Copies the input file and any referenced files from a run directory into the main directory.

Parameters: run: int

The run identifier used to locate specific input files.

action: bool, optional: If False, only compare source and destination files, otherwise copy them if there are differences.

Returns: bool

True if there were differences between the source files and their corresponding targets, False otherwise.

input_from_xml(instance=-1)

Return a list of all defined input in the xml output stream

Parameters:: instance – index of occurence of input node in output
Returns:

kill(): Kill the job started by run()

list_files(): Return a list of files in the project directory

property local_molpro_root

Get the directory of the Molpro installation in the local backend

Returns:: directory
Return type:: pathlib.Path

property location: Local path to the project directory

molecule(instance=-1)

Obtain a molecule in the job output

Parameters:: instance – Which molecule object to get
Returns:: a dictionary containing all the information available

move(name=None, location=None, force=False)

Move the project bundle to a new location

Parameters:

name – new name of the project
location – path to the directory where project should be moved. Defaults to same directory as current project.
force – whether to first remove anything already existing at the new location

property name: Name of the project

orbitals(instance=-1, minocc=1.0, ID=None, orbital_instance=-1)

Obtain some or all of the orbitals in the job output

Parameters:

instance – Which molecule object to get orbitals for
minocc – Only orbitals with at least this occupation will be returned
ID – Only the orbital whose ID attribute matches this will be selected
orbital_instance – Which set of orbitals

Returns:

a list of Orbital objects

orbitals_old(instance=-1, minocc=1.0, ID=None, orbital_instance=-1)

Obtain some or all of the orbitals in the job output

Parameters:

instance – Which molecule object to get orbitals for
minocc – Only orbitals with at least this occupation will be returned
ID – Only the orbital whose ID attribute matches this will be selected
orbital_instance – Which set of orbitals

Returns:

a list of Orbital objects

orbitals_to_molden(filename=None, instance=-1, minocc=1.0, ID=None)

orbitals_to_trexio(filename=None, instance=-1, overwrite=True)

Create a TrexIO dump containing the geometry and orbitals.

Parameters:

filename (str) – Name of the Trexio file to be placed in the run directory
instance (int) – Which instance of the molecule node in the xml file
overwrite (bool) – Overwrite existing TrexIO file

Returns:

file, label

Return type:

str, str

property out

property output

Returns:: node with Molpro’s output

property output_file_path

pairs(instance=-1)

Obtain some or all of the correlation pairs in the job output

Parameters:: instance – Which set of pairs
Returns:: a list of Pair objects

parse(force=False, **options)

Parse the output file and save resultant node as a child

Parameters:: force – reparse the output

parse_ansatz(ansatz)

procedures_registry()

Get the procedures registry from the Molpro pointed to in the local backend

Returns:
Return type:: dict

properties(*args, **kwargs)

Obtain selected properties from the job output

Parameters:

args – any trailing XPath qualifier, for example '[@StateSymmetry = "1" or @StateSymmetry = "4"]'. For restrictions that should be combined with and, it’s simpler to instead use a kwarg argument, eg StateSymmetry=1
kwargs – any attribute selectors for the select function, including the following
name – name of property
principal – restrict to principal property
preamble – XPath expression to prepend the search for the property node
command – restrict to properties contained in a jobstep with this command
dict – return property value, scalar float or list of floats as appropriate, if False or omitted. Otherwise, a dictionary containing all the data in the property node is returned

Returns:

list of properties

properties_old(name='Energy', principal=True, *, value=False, **kwargs)

Obtain selected properties from the job output

Parameters:

name – name of property
principal – principal property
value – return by value
kwargs – any other attribute selectors for the select function

Returns:

list of properties

Shorthand for p.select(‘//properties[name= {}, principal ={}, … ]’)

property(*args, **kwargs)

Wrapper for properties() that returns a single value as a scalar. An exception is thrown if more than one value is found.

Parameters:

args
kwargs

Returns:

property_delete(*properties): Delete properties

property_get(*properties): Return a dictionary of property, value pairs

property_names(): Return names of all assigned properties

property_set(properties): Set the value of a project property

recent_find(location)

refresh_backends()

Reload the backends from the configuration file

Returns:

registry(set=None)

Access the registry belonging to Molpro in the local backend.

Parameters:: set – If present, obtain as a dictionary the specified registry set. If absent, obtain a list of all sets
Returns:

run(backend=None, verbosity=0, force=False, wait=False, options='', backend_parameters=None)

Start a sjef job

Parameters:

backend – name of the backend
verbosity – If >0, show underlying processing
force – whether to force submission of job even if run_needed() reports that it’s unnecessary
wait – whether to wait until the job completes instead of returning after launchin it
options – command-line options
backend_parameters – if given, a dictionary of backend parameter name/value pairs to use for this run only. Any backend parameters already set are restored once the job has been launched, so the override does not persist beyond this call.

run_delete(run): Remove a specific run directory from the project

run_directory_new()

Check whether the job has changed since the previous run and needs to be rerun

Returns:: True/False

run_local_molpro(options: list)

run_needed(verbosity=0)

Check weather the job has changed since the previous run and needs to be rerun

Returns:: True/False

select(selection_string, **options_and_callables)

Specialization of pysjef.select() which applies selection to the parsed output

Returns:: list of nodes that pass selection criteria

singles(instance=-1)

Obtain some or all of the correlation singles in the job output

Parameters:: instance – Which set of singles
Returns:: a list of Single objects

property status: String status of the project. Can be one of: unknown, running, waiting, completed, unevaluated, killed, or failed.

trash(): Move the project bundle to the trash

tree_view(**options): Build tree view from this node

variable(name, instance=-1, list=False, dict=False)

Return the value of a variable in the output xml stream

Parameters:

name – The name of the variable
instance – index of occurence in output
list – Whether to force returning a list. If true, a list is always returned; otherwise if the result is a scalar, a scalar is returned, and if no match is found, None is returned
dict – return property value, scalar float or list of floats as appropriate, if False or omitted. Otherwise, a dictionary containing all the data in the property node is returned

Returns:

variables(instance=-1)

Return a list of all defined variables

Parameters:: instance – index of occurence of variables node in output
Returns:

property vibrations

Give information on normal vibrational modes

Parameters:: instance (int)
Returns:: Mass-weighted normal coordinates, vibrational wavenumbers, atomic masses, force constant matrix
Return type:: dict

view_input(): Opens the input file in editor as specified by ‘$EDITOR’ environment variable. Should by called from an interactive session

view_output(): Opens the input file in editor as specified by ‘$EDITOR’ environment variable. Should by called from an interactive session

wait(max_epoch=0.005)

Wait unconditionally for status() to return neither ‘waiting’ nor ‘running’

Parameters:: max_epoch – maximum time to wait between checking status (seconds)

write_file(filename, content, overwrite=True)

Creates a file in the project with specified content

Parameters:

filename – name of the file to create in the project
content – string content to write in the file
overwrite – if corresponding file already exists in the project, flags that it should be overwritten

Returns:

True if file was created or overwritten, otherwise False

write_input(content)

Create an input file with content specified as a string

Parameters:: content – string with content for the input file

property xml

xml_run(run: int)

xpath(query, element=None): Specialization of pysjef.project.Project.xpath() that caches the parsed XML tree per project instance instead of re-reading and re-parsing the output file from disk on every call. Callers like no_errors() and variable() each query this multiple times per project; the cache is keyed on the output file’s mtime, so it’s used only while nothing about the output has changed since it was built.

xpath_search(xpath_query, attribute='', run=0)

Simple XPath search on the xml document. For each matching node found, return a string that contains the value of a specified attribute, or if the attribute is omitted, the node contents.

Parameters:

xpath_query
attribute
run

xyz(preamble='//', instance=-1, title='')

Obtain a geometry in xyz file format

Parameters:

instance – In the case of multiple geometries in the output stream, which occurence
preamble – Prepend this to the xpath search expression to locate the geometry
title – A title to be injected into the second line

Returns:

A string containing the xyz representation of the geometry

xyzs(preamble='//', title='')

Obtain a set of geometries in xyz file format

Parameters:

preamble – Prepend this to the xpath search expression to locate the geometry
title – A title to be injected into the second line

Returns:

A list of strings containing the xyz representation of the geometry

class pymolpro.Single(node)

Bases: Tuple

Container for a single orbital

__init__(node): Initialise from a node on a Molpro output xml tree

energy: Correlation energy contribution from a Single or Pair

orbitals: Orbital objects forming the tuple

spins: 1(alpha) or -1(beta) for each orbital

class pymolpro.Tuple(node)

Bases: object

Container for a tuple of orbitals

Parameters:: node (lxml.etree.Element) – Node holding a correlation single or pair descriptor

__init__(node): Initialise from a node on a Molpro output xml tree

energy: Correlation energy contribution from a Single or Pair

orbitals: Orbital objects forming the tuple

spins: 1(alpha) or -1(beta) for each orbital

pymolpro.element_to_dict(node, attributes=True)

Convert an lxml.etree node tree into a dict.

Parameters:

node (lxml.etree.ElementTree) – A node in an lxml tree
attributes (bool, optional) – whether to include attributes in the result

Returns:

A dictionary representing the tree

Return type:

dict

pymolpro.no_errors(projects, ignore_warning=True)

Checks that none of the projects have any errors. Projects can by running.

Parameters:

projects – list of projects to check for errors
ignore_warning – Whether to count warnings as well as errors.

Returns:

True/False whether any projects have errors

pymolpro.xyz_to_zmat(xyz: str, algorithm='chemcoord')

Converts from xyz to z-matrix coordinates.

Parameters:

xyz – xyz-file
algorithm – algorithm to choose, default is the chemcoord algorithm

Returns:

The Z matrix as a string, or None in case of unknown algorithm,

Return type:

str

Submodules

pymolpro.molpro_input module

class pymolpro.molpro_input.InputSpecification(input: str = None, allowed_methods=None, debug: bool = False, specification: dict = None, directory: str = None)

Bases: UserDict

A declarative specification of a Molpro input. Almost any simple input - no loops or logic - that requests a single quantum-mechanical method, possibly with geometry optimisation using a different method, can be represented. The class can be instantiated from a procedural Molpro input, or from a JSON string or dictionary. If both an input and a specification are provided, the specification is ignored.

The class is a dictionary with some extra methods, with all the data contained in the dictionary, which is constrained to conform with the molpro_input JSON schema, https://www.molpro.net/schema/molpro_input.json .

__init__(input: str = None, allowed_methods=None, debug: bool = False, specification: dict = None, directory: str = None)

Parameters:

input – Either a text string or a file name containing Molpro procedural input.
allowed_methods – A list of allowed methods to be appended to the defaults.
specification – Initial data to be included in the specification.
directory – The directory where any auxiliary files are located. If not specified, the current working directory will be used.

property ansatz: str: A string of the form method/basis, or method/basis//geometry_method/geometry_basis summarising the ansatz where possible, otherwise an empty string.

property basis_hamiltonian: str: The hamiltonian for which the orbital basis set is designed

property basis_quality: int: The cardinal number of the basis set used in the job. If not a correlation-consistent basis set, returns 0.

clear() → None. Remove all items from D.

copy()

classmethod default_instance() → InputSpecification: Factory method for creating a default instance generated from the schema.

property density_functional: str: For a Kohn-Sham calculation, the name of the density functional used

classmethod fromkeys(iterable, value=None)

get(k[, d]) → D[k] if k in D, else d. d defaults to None.

items() → a set-like object providing a view on D's items

property job_steps: list[JobStep]: Returns the job steps in this input

keys() → a set-like object providing a view on D's keys

property method: str: The single method implemented by the job, represented as the Molpro input command name that implements it.

property method_options: str: The options for a single-method job

molpro_input() → str: Create the procedural Molpro input from the declarative specification

property open_shell_electrons: int: The number of open-shell electrons in the molecule’s normal state. This will typically be 0 or 1, but for some special cases (eg atoms) might be higher.

parse(input: str, debug=False) → InputSpecification

Take a procedural molpro input, and logically parse it. If it is impossible to do so, an empty specification is returned.

Parameters:: input – Either text that is the input, or a file name containing it.

polish(): Ensure that the job specification is valid and complete

pop(k[, d]) → v, remove specified key and return the corresponding: value. If key is not found, d is returned if given, otherwise KeyError is raised.

popitem() → (k, v), remove and return some (key, value) pair: as a 2-tuple; but raise KeyError if D is empty.

set_job_step(job_step: JobStep, index: int)

set_job_type(new_job_type)

setdefault(k[, d]) → D.get(k,d), also set D[k]=d if k not in D

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.keys(): 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

validate(): Validate the specification according to the schema.

values() → an object providing a view on D's values

property with_defaults: InputSpecification: A copy of this specification with all defaults filled in from the schema.

property without_defaults: InputSpecification: A copy of this specification with any values equal to the schema default removed.

class pymolpro.molpro_input.JobStep(card: 'str')

Bases: object

__init__(card: str)

command: str

directives: list

dump(braces=True)

load(card: str)

options: list

pymolpro.molpro_input.canonicalise(input)

pymolpro.molpro_input.equivalent(input1, input2, debug=False)

pymolpro.molpro_input.hamiltonians() → dict[str, dict[str, str]]: Returns a dictionary containing the supported hamiltonians.

pymolpro.molpro_input.job_types() → dict: Return the supported job types.

pymolpro.molpro_input.local_orbital_types() → dict[str, dict[str, str]]: Return a dictionary containing the supported local orbital types.

pymolpro.molpro_input.orientation_options()

pymolpro.molpro_input.procedures_registry() → dict: Returns a dictionary with procedure names as keys and procedures as values.

pymolpro.molpro_input.supported_methods(): Returns a list of supported methods.

pymolpro.molpro_input.symmetry_commands()

pymolpro.database module

class pymolpro.database.Database(molecules: dict[str, str] = None, reactions: dict[str, dict[str, int]] = None, description: str = None, project_directory: str = None)

Bases: object

Database of molecular structures and reactions. The class contains and supports the following data.

Descriptions of molecules: geometry, charge, spin state.
Descriptions of reactions between the molecules: stochiometric factors.
Optionally, computed data: energies of molecules and/or reactions,s the parameters used to obtain them, and references to persistent data that can be used to further query or restart.
Description and external URLs that serve to further define the provenance of the data.
Specification of recommended subsets of the reactions

__init__(molecules: dict[str, str] = None, reactions: dict[str, dict[str, int]] = None, description: str = None, project_directory: str = None)

Parameters:

molecules – Initial molecules to be added with default options to add_molecule().
reactions – Initial reactions to be added with default options to add_reaction().
description – Text describing the database
project_directory – The path of the directory where support files that were generated in calculating energies can be found.

add_molecule(name, geometry, energy=None, description=None, InChI=None, SMILES=None, spin=None, charge=None, preamble=None)

Add a molecule to the database. The minimal information that is stored is the geometry, but information from each of the optional arguments, if given, is also stored in the molecules dictionary.

Parameters:

name (str) – The key for the molecule in molecules.
geometry (str) – The geometry. Any format recognised by Molpro can be used. This includes xyz, with or without the two header lines, or Z matrix, and lines can be separated either with newline or ;. The geometry can be specified either as a string, or a filename or url reference, in which case the contents of the reference are resolved now.
energy (float) – The reference value for the energy of the molecule in Hartree units
description (str) – Descriptive text
InChI (str) –
InChI string describing the molecule
SMILES (str) –
SMILES string describing the molecule
spin (int) – The spin multiplicity minus one
charge (int) – Electrical charge of molecule
preamble (str) – Additional Molpro input to be added before geometry

Returns:

The added molecule

Return type:

dict

add_reaction(name, stoichiometry, energy=None, description=None)

Add a reaction to the database. The minimal information that is stored is the stoichiometry, which references existing molecules in the database, but information from each of the optional arguments, if given, is also stored in the reactions dictionary.

Parameters:

name – The key for the reaction in reactions.
stoichiometry – A dictionary describing the stoichiometry of the reaction. Each key should be a key in molecules, and the value is an integer giving the number of equivalents of the molecule in the reaction, with the sign convention of positive for products, negative for reactants.
energy – The reference value for the energy change of the reaction in Hartree units. If not given, and if all molecules in the reaction have an energy, it will be computed.
description – Descriptive text

Returns:

The added reaction

Return type:

dict

add_reference(key, url)

add_subset(subset_name, subset)

basis: A string specifying the orbital basis-set used to compute the energies.

calculate_reaction_energies(check=False)

clean(keep_run_directories=1)

Remove run directories from each project in projects.

Parameters:: keep_run_directories – The number of most recent run directories to keep for each project.

copy()

description: Text describing the database

dump(filename=None)

Dump the database in json format.

Parameters:: filename (str) – If specified, the destination of the result
Returns:: If filename is not specified, the json is returned as a string
Return type:: str

failed: Subset of projects corresponding to jobs that did not complete successfully.

input_specification: A string containing JSON describing the Molpro input used to construct the energies

load(source)

Load the database from a json dump in either the library, a file or a string

Parameters:: source (str) – Source of dump
Returns:: The database
Return type:: Database

method: A string specifying the ansatz used to compute the energies.

molecule_energies: A dictionary with molecule keys giving the molecular energy/Hartree reference values associated with the Database. The dictionary could be empty or only partly filled.

molecules: Dictionary of molecules

preamble: any Molpro commands that should be executed before geometry specification. Typically angstrom could be specified if the geometry specification is in Z-matrix format with numerical values that would, by default, be interpreted as Bohr.

project_directory: A string giving the path of the directory where support files generated in calculating energies can be found.

projects: A dictionary with molecule handles pointing to filesystem project bundles for each Molpro job that has been run.

reaction_energies: A dictionary with reaction keys giving the reaction energy/Hartree reference values associated with the Database. The dictionary could be empty or only partly filled. A database might have either, both or none of molecule_energies or reaction_energies.

reactions: Dictionary of reactions involving the molecules together with stoichiometric factors

references: A dictionary of external references to the data. The keys should be a short-form string that you want printed, eg author, year, and the values URLs that lead to the resource.

subset(subset=None, open_shell=True, max_atoms=None, max_electrons=None)

Extract a subset of this database as a new database

Parameters:

subset – Either a key in the subsets or a list of keys in reactions. If not given, all the reactions in the database
open_shell – Whether to include reactions involving open-shell molecules, or prune to closed-shell only
max_atoms – Exclude reactions with one or more molecules with more than this number of atoms
max_electrons – Exclude reactions with one or more molecules with more than this number of electrons

Returns:

The subset

Return type:

Database

subsets: A dictionary defining named subsets of the database reactions

pymolpro.database.analyse(databases, reference_database=None, unit=None, **kwargs)

Analyse and format the results in one or more databases

Parameters:

databases (list(Database)|Database)
reference_database (Database)
unit – Either a string or a float specifying desired units for the output. In the case of a string, it should match (case insensitive) one of the keys of units; if an explicit value is given, it should be the value of the desired units in atomic units, ie the results will be divided by the value.

Returns:

A dictionary with keys, where possible,

molecule energies
molecule energy deviations
molecule statistics
molecule violin
reaction energies
reaction energy deviations
reaction statistics
reaction violin

The energy deviations are, for each molecule or reaction, the difference between the energies in each element of databases and the value in reference_database. The values are pandas Dataframe objects, whose columns correspond to the elements of databases. In the case of the molecule or reaction energies or energy deviations, the rows correspond to the individual molecule or reaction. In the case of statistics, the rows are

MSD: the mean of the deviations

STDEVD: the standard deviation of the deviations

MAD: the mean of the absolute value of the deviations

MAXD: the maximum absolute value of the deviations

RMSD: the root mean square deviation

Return type:: dict

pymolpro.database.basis_extrapolate(results, hf_results, x=None)

pymolpro.database.load(source)

Construct a Database from a json dump in either the library, a file or a string

Parameters:: source (str) – Source of dump
Returns:: The database
Return type:: Database

pymolpro.database.run(db, ansatz=None, specification=None, location='.', parallel=None, backend='local', clean=False, check=False, check_energy=True, molecule_inputs=None, retries=3, retry_delay=5, backend_parameters=None, **kwargs)

Construct and run a Molpro job for each molecule in a Database, and compute reaction energies.

Parameters:

db (Database) – The database that defines molecules and reactions.
method (str) – The computational method for constructed input. Anything accepted as Molpro input, including parameters and directives, can be given. If the method needs a preceding Hartree-Fock calculation, this is prepended automatically.
basis (str) – The orbital basis set for constructed input. Anything that can appear after basis= in Molpro input is accepted.
ansatz (str) – String of the form method/basis//geometry_method/geometry_basis or method/basis which is parsed to give the same effect as the method and basis parameters. If geometry_method/geometry_basis is specified, the calculation will be preceded by a geometry optimisation at that level of theory.
specification – A JSON string, or a dict, giving the method used to compute the energies in the database, conforming to the JSON schema https://www.molpro.net/schema/molpro_input.json.
func (str) –
This should be one of
- energy for a single geometry
- opt for a geometry optimisation
extrapolate (str) – If specified, carry out basis-set extrapolation. Anything that can appear after extrapolate,basis= in Molpro input is accepted.
location (str) – The filesystem directory in which projects will be constructed.
parallel (int) – The number of simultaneous jobs to be launched. The default is the number of cores on the local machine.
backend (str) – The sjef backend to be used for running jobs.
clean (bool) – Whether to destroy the project bundles on successful completion. This should not normally be done, since later invocations of run() will use cached results when possible. If there are errors, this parameter is ignored.
check (bool) – Whether to check for status of jobs instead of running them.
check_energy (bool) – Whether to throw an exception if any job did not set the Molpro ENERGY variable
molecule_inputs (dict) – A dictionary keyed by molecule name (matching keys in db.molecules), each value being a dictionary of keyword arguments to pass to project.Project() for that molecule only. These are merged with kwargs, with molecule_inputs taking precedence on any clash; the database’s own per-molecule spin/charge/preamble still take precedence over molecule_inputs. Every key of molecule_inputs must match a key in db.molecules.
retries (int) – How many times to attempt launching each job before giving up, to ride out transient remote connection failures (most relevant for a remote backend). 1 disables retrying.
retry_delay (float) – Seconds to wait before the first retry of a failed launch; doubles on each subsequent attempt.
backend_parameters (dict) – If given, a dictionary of backend parameter name/value pairs to pass through to project.Project.run() for this run only.
kwargs – Any other options to pass to project.Project(), including any top-level keywords from the JSON schema https://www.molpro.net/schema/molpro_input.json.

Returns:

A new database which is a copy of db but with the new results overwriting any old ones

Return type:

Database

pymolpro.database.units = <pymolpro.database.Units object>: A dictionary of units, giving their values in atomic units.

pymolpro.grid module

pymolpro.grid.construct_primitives(alpha, cartesianAngularQuantumNumbers, lqbase, ncompc, normfac, points, primitivesc, relative_points_powers, spherical_values)

pymolpro.grid.cubical_grid(points1d, weights1d)

Take a one-dimensional grid, and construct a 3-dimensional outer-product cubical grid

Parameters:

points1d
weights1d

Returns:

points and weights (numpy array [npt,4])

pymolpro.grid.cuboidal_grid(points1d, weights1d=None)

Take a one-dimensional grid, and construct a 3-dimensional outer-product cubical grid

Parameters:

points1d
weights1d

Returns:

points and weights (numpy array [npt,4])

pymolpro.grid.evaluateBasis(molecule, points)

Evaluate the orbital basis set on a grid

Parameters:

molecule – lxml.etree.Element holding the molecule
points – numpy :,3 array

Returns:

numpy :,: array, first index basis function, second index brid point

pymolpro.grid.evaluateOrbitals(molecule, points, minocc=1e-10, ID=None, values=False, directory=None)

Evaluate the molecular orbitals on a grid

Parameters:

molecule – lxml.etree.Element holding the molecule
points – numpy :,3 array
minocc – Only orbitals with at least this occupation will be returned
ID – Only the orbital whose ID attribute matches this will be selected
values

Returns:

array of dictionaries giving the occupation and values on the grid, or if ID is specified, a single dictionary, or if values==True, a numpy array

pymolpro.grid.spherical_grid(radial_points, radial_weights, l: int)

Take a one-dimensional grid, and use it for radial integration, together with a Lebedev grid of specified order, to generate a 3-dimensional grid (cartesian coordinates, weights) for quadrature.

Parameters:

radial_points
radial_weights
l – Largest rank of spherical harmonic for which exact quadrature is wanted.

Returns:

points and weights (numpy array [npt,4])

pymolpro.node_xml module

class pymolpro.node_xml.AxesXml(filename=None, xml=None, parent=None, suffix=None, **options)

Bases: RootXml

molpro-output:axes Children: [list of doubles]

class pymolpro.node_xml.BasisSetXml(filename=None, xml=None, parent=None, suffix=None, **options)

Bases: RootXml

molpro-output:basisSet - Container for a basis set Children: basisGroup, association Attributes: str id, str type, str angular, int groups, str primitives, int length, int cartesianLength

class pymolpro.node_xml.CmlAtomXml(filename=None, xml=None, parent=None, suffix=None, **options)

Bases: RootXml

cml:atom - Output about a single atom

class pymolpro.node_xml.CmlMoleculeXml(filename=None, xml=None, parent=None, suffix=None, **options)

Bases: RootXml

cml:molecule - Output about a single molecule Children: cml:atomarry, cml:symmetry

class pymolpro.node_xml.CubeXml(filename=None, xml=None, parent=None, suffix=None, **options)

Bases: RootXml

molpro-output:cube - Metadata for a cube dataset Children: field, dimensions, origin, axes, step Attributes: str method

class pymolpro.node_xml.DateXml(filename=None, xml=None, parent=None, suffix=None, **options)

Bases: RootXml

molpro-output:date - The time of the calculation. Children: [string datetime] Attributes: int year, int month, int day, int hour, int minute, int second

class pymolpro.node_xml.DiagnosticsXml(filename=None, xml=None, parent=None, suffix=None, **options)

Bases: RootXml

molpro-output:diagnostics - Diagnostic info from the job Attributes: int warnings

class pymolpro.node_xml.DimensionsXml(filename=None, xml=None, parent=None, suffix=None, **options)

Bases: RootXml

molpro-output:dimensions Children: [list of doubles]

class pymolpro.node_xml.FieldXml(filename=None, xml=None, parent=None, suffix=None, **options)

Bases: RootXml

molpro-output:field Attributes: str quantity, str type, str number, str symmetry, double occupancy, double energy, str file

class pymolpro.node_xml.InputXml(filename=None, xml=None, parent=None, suffix=None, **options)

Bases: RootXml

molpro-output:input - Molpro input dataset Children: p, include

class pymolpro.node_xml.JobstepXml(filename=None, xml=None, parent=None, suffix=None, **options)

Bases: RootXml

molpro-output:jobstep - Output from a single job step Children: error, gradient, opt, property, cube, time, storage, vibrations, jobstep, cml:molecule, variables, instanton Attributes: str command, str commandset, bool displaced

class pymolpro.node_xml.LicenceXml(filename=None, xml=None, parent=None, suffix=None, **options)

Bases: RootXml

molpro-output:licence Attributes: str id

class pymolpro.node_xml.MachineXml(filename=None, xml=None, parent=None, suffix=None, **options)

Bases: RootXml

molpro-output:machine Attributes: str hostname

class pymolpro.node_xml.MoleculeXml(filename=None, xml=None, parent=None, suffix=None, **options)

Bases: RootXml

molpro-output:molecule - Summary output about the job Children: cml:molecule, basisSet, vibrations, orbitals, stm:metadataList, platform Attributes: str id, str index, str InChI, str InChIKey, str SMILES, str title, str method, str basis, str geometryMethod, str geometryBasis, double energy

class pymolpro.node_xml.NormalCoordinateXml(filename=None, xml=None, parent=None, suffix=None, **options)

Bases: RootXml

molpro-output:normalCoordinate - A normal vibrational coordinate Children: [list of doubles] Attributes: double wavenumber, str units, double IRintensity, str IRintensityunits, str symmetry, str real_zero_imag

class pymolpro.node_xml.OrbitalXml(filename=None, xml=None, parent=None, suffix=None, **options)

Bases: RootXml

molpro-output:orbital - A Molpro molecular orbital Children: [string] Attributes: str symmetryID, double energy, double occupation

class pymolpro.node_xml.OrbitalsXml(filename=None, xml=None, parent=None, suffix=None, **options)

Bases: RootXml

molpro-output:orbitals - Container for Molpro internal orbitals Children: orbital Attributes: str basis, str angular, str spin, str method

class pymolpro.node_xml.OriginXml(filename=None, xml=None, parent=None, suffix=None, **options)

Bases: RootXml

molpro-output:origin Children: [list of doubles]

class pymolpro.node_xml.ParallelXml(filename=None, xml=None, parent=None, suffix=None, **options)

Bases: RootXml

molpro-output:parallel Attributes: int processes, int nodes, int all_processes, int openmp

class pymolpro.node_xml.PlatformXml(filename=None, xml=None, parent=None, suffix=None, **options)

Bases: RootXml

molpro-output:platform - Container for metadata about the platform Children: version, licence, parallel, machine, dimensions

class pymolpro.node_xml.PlotXml(filename=None, xml=None, parent=None, suffix=None, **options)

Bases: RootXml

molpro-output:plot - Metadata for plot from a Molpro table Attributes: str table, str plot, str type Also attributes from http://www.w3.org/1999/xlink

class pymolpro.node_xml.PropertyXml(filename=None, xml=None, parent=None, suffix=None, **options)

Bases: RootXml

molpro-output:property - Output about a single property of a single molecule Attributes: str name, any value

class pymolpro.node_xml.StepXml(filename=None, xml=None, parent=None, suffix=None, **options)

Bases: RootXml

molpro-output:step Children: [list of doubles]

class pymolpro.node_xml.VariableXml(filename=None, xml=None, parent=None, suffix=None, **options)

Bases: RootXml

TODO Doc

class pymolpro.node_xml.VariablesXml(filename=None, xml=None, parent=None, suffix=None, **options)

Bases: RootXml

molpro-output:variables - Container for Molpro internal variables Children: variable

class pymolpro.node_xml.VersionXml(filename=None, xml=None, parent=None, suffix=None, **options)

Bases: RootXml

molpro-output:version Children: [string], date Attributes: int major, int minor, str SHA, int integer_bits, str parallelism

class pymolpro.node_xml.VibrationsXml(filename=None, xml=None, parent=None, suffix=None, **options)

Bases: RootXml

molpro-output:vibrations - Container for info on molecular vibrations Children: normalCoordinate Attributes: str name, str type, str units, int length

pymolpro.node_xml.tag_to_name(tag): Takes XML tag with namespace, outputs raw node name.