basisopt package

Subpackages

Submodules

basisopt.api module

basisopt.api.dummy(path: str)

Sets backend to the DummyWrapper for testing and for when calculations aren’t needed.

basisopt.api.get_backend() → Wrapper

Returns: backend (Wrapper): the Wrapper object for the current backend

basisopt.api.get_tmp_dir() → str

Returns: Path to the current scratch/temp directory

basisopt.api.orca(path: str)

Tests orca import and prepares to be used as calculation backend

basisopt.api.psi4(path: str)

Tests Psi4 import and prepares to be used as calculation backend

basisopt.api.register_backend(func: Callable[[str, str], None]) → Callable[[str, str], None]

Registers a function to set the backend for basisopt

basisopt.api.run_all(evaluate: str = 'energy', mols: list[basisopt.molecule.Molecule] = [], params: dict[Any, Any] = {}, parallel: bool = False) → dict[str, Any]

Runs calculations over a set of molecules, optionally in parallel

Parameters:

  • evaluate (str) – the property to evaluate

  • mols (list) – a list of Molecule objects to run

  • params (dict) – parameters for backend

  • parallel (bool) – if True, will try to run distributed

Returns:

value}

Return type:

a dictionary of the form {molecule name

basisopt.api.run_calculation(evaluate: str = 'energy', mol: Molecule | None = None, params: dict[Any, Any] = {}) → int

Interface to the wrapper used to run a calculation.

Parameters:

  • evaluate (str) – The function to be called for the computation

  • mol (Molecule) – molecule to run the calculation on

  • params (dict) – A dictionary of parameters needed for the computation

Returns:

0 on success, non-zero on failure

Return type:

int

basisopt.api.set_backend(name: str, path: str = '')

Sets the global backend for basisopt calculations

Parameters:

  • name (str) – the name of the program to use

  • path (str) – absolute path to the program executable

basisopt.api.set_logger(level: int = 20, filename: str | None = None)

Initialises Python logging, formatting it nicely, and optionally printing to a file.

basisopt.api.set_parallel(value: bool = True)

Turns parallelism on/off

basisopt.api.set_tmp_dir(path: str)

Sets the working directory for all backend calculations, creating the directory if it doesn’t already exist.

Parameters:

path (str) – path to the scratch directory

basisopt.api.which_backend() → str

Returns: str: The name of the currently registered backend

basisopt.bse_wrapper module

basisopt.bse_wrapper.bse_to_internal(basis: dict[str, Any]) → dict[str, list[basisopt.containers.Shell]]

Converts a BSE basis object into an internal basis dictionary

Parameters:

basis – a BSE basis, must have the following attributes [‘elements’] each of which must then have an [‘electron_shells’] attribute

Returns:

an internal basis dictionary

basisopt.bse_wrapper.fetch_basis(name: str, elements: list[str]) → dict[str, list[basisopt.containers.Shell]]

Fetches a basis set for a set of elements from the BSE

Parameters:

  • name (str) –

  • elements (list) - a list of element symbols (or atomic numbers) –

Returns:

an internal basis dictionary

basisopt.bse_wrapper.fetch_ecp(name: str, elements: list[str]) → dict[str, Any]

Fetches an ECP basis from the BSE, deleting any extraneous non-ECP info

Parameters:

  • name – name of desired basis

  • elements – list of element symbols or atomic numbers

Returns:

a BSE basis dictionary

basisopt.bse_wrapper.internal_basis_converter(basis: dict[str, list[basisopt.containers.Shell]], fmt: str = 'gaussian94') → str

Writes out an internal basis in the desired BSE format

Parameters:

  • basis (dict) – the internal basis dictionary

  • fmt (str) – the desired output format - see the BSE docs for options

Returns:

the basis as a string in the desired format

basisopt.bse_wrapper.internal_to_bse(basis: dict[str, list[basisopt.containers.Shell]]) → dict[str, Any]

Converts an internal basis dictionary into a BSE basis object

Parameters:

basis – an internal basis, which is a dictionary with k, v pairs like: element_symbol: [array of internal Shell objects]

Returns:

a BSE basis of type ‘component’ with ‘gto_spherical’ function types

basisopt.bse_wrapper.make_bse_shell(shell: Shell) → dict[str, Any]

Converts an internal-format basis shell into a BSE-format shell

Parameters:

shell – an internal Shell object

Returns:

a BSE-format gto_spherical shell

basisopt.bse_wrapper.make_internal_shell(shell: dict[str, Any]) → Shell

Converts a BSE-format basis shell into an internal-format shell

Parameters:

shell – a BSE shell, a dictionary that must have these attributes [‘angular_momentum’, ‘exponents’, ‘coefficients’]

Returns:

an internal Shell object

basisopt.containers module

class basisopt.containers.Result(name: str = 'Empty')

Bases: MSONable

Container for storing and archiving all results, e.g. of tests, calculations, and optimizations.

name

identifier for result

Type:

str

depth

a Result object contains children, so a depth of 1 indicates no parents, 2 indicates one parent, etc.

Type:

int

Private attributes:
_data_keys (dict): dictionary with the format

(value_name, number of records)

_data_values (dict): dictionary of values with format

(value_name_with_id, value)

_children (list): references to child Result objects

add_child(child: object)

Adds a child Result to this Result

add_data(name: str, value: Any)

Adds a data point to the result, with archiving

Parameters:

  • name (str) – identifier for the value

  • value – the value, can be basically anything

as_dict() → dict[str, Any]

Converts Result (and all children) to an MSONable dictionary

property depth: int
classmethod from_dict(d: dict[str, Any]) → object

Creates Result from dictionary representation, including recursive creation of children.

get_child(name: str) → object

Returns child Result with given name, if it exists

get_data(name: str, step_back: int = 0) → Any

Retrieve an archived data point

Parameters:

  • name (str) – identifier for the value needed

  • step_back (int) – how many values back to go,

  • added (default will return last point) –

Returns:

the value with the requested name, if it exists

Raises:

DataNotFound if the requested data doesn't exist –

load(filename: str) → object

Loads and returns a Result object from a file pickle

save(filename: str)

Pickles the Result object into a file

search(name: str) → dict[str, Any]

Searches for all data in this and all its children with a given name, returning a dictionary indexed by the name and which child it was found in

statistics()

Tabulates summary statistics for the data in this Result Note: does not recur over children

summary() → str

Creates summaries of the Result and all its children

Returns:

a string with human-readable summary of the results

class basisopt.containers.Shell

Bases: MSONable

Lightweight container for basis set Shells.

l

the angular momentum name of the shell

Type:

char

exps

array of exponents

Type:

numpy array, float

coefs

list of numpy arrays of equal length to exps, corresponding to coefficients for each exponent

Type:

list

as_dict() → dict[str, Any]

Converts Shell to MSONable dictionary

Returns:

dictionary representation of Shell

compute(x: float, y: float, z: float, i: int = 0, m: int = 0) → float

Computes the value of the (spherical) GTO at a given point

Parameters:

  • x (float) – coordinates relative to center of GTO

  • y (float) – coordinates relative to center of GTO

  • z (float) – coordinates relative to center of GTO

  • i (int) – index of GTO in coefs

  • m (int) – azimuthal quantum number in [-l, l]

Returns:

The unnormalised value of the GTO at (x, y, z)

classmethod from_dict(d: dict[str, Any]) → object

Creates Shell object from dictionary representation

Parameters:

d (dict) – dictionary of Shell attributes

Returns:

Shell object

basisopt.containers.basis_to_dict(basis: dict[str, list[basisopt.containers.Shell]]) → dict[str, Any]

Converts an internal basis set of the form {atom: [shells]} to an MSONable dictionary

Parameters:

basis (dict) – internal basis set

Returns:

json-writable dictionary

basisopt.containers.dict_to_basis(d: dict[str, Any]) → dict[str, list[basisopt.containers.Shell]]

Converts an MSON dictionary to an internal basis

Parameters:

d (dict) – dictionary of basis set attributes

Returns:

internal basis set

basisopt.data module

basisopt.data.AM_DICT = {'d': 2, 'f': 3, 'g': 4, 'h': 5, 'i': 6, 'j': 7, 'k': 8, 'l': 9, 'p': 1, 's': 0}

Dictionary converting back from l quantum number to letter value

basisopt.data.INV_AM_DICT = {0: 's', 1: 'p', 2: 'd', 3: 'f', 4: 'g', 5: 'h', 6: 'i', 7: 'j', 8: 'k', 9: 'l'}

Dictionary with pre-optimised even-tempered expansions for atoms

basisopt.data.atomic_number(element: str) → int
basisopt.data.get_even_temper_params(atom: str = 'H', accuracy: float = 1e-05) → list[tuple[float, float, int]]

Searches for the relevant even tempered expansion from _EVEN_TEMPERED_DATA

basisopt.exceptions module

exception basisopt.exceptions.DataNotFound

Bases: Exception

exception basisopt.exceptions.ElementNotSet

Bases: Exception

exception basisopt.exceptions.EmptyBasis

Bases: Exception

exception basisopt.exceptions.EmptyCalculation

Bases: Exception

exception basisopt.exceptions.FailedCalculation

Bases: Exception

exception basisopt.exceptions.InvalidDiatomic

Bases: Exception

exception basisopt.exceptions.InvalidMethodString

Bases: Exception

exception basisopt.exceptions.InvalidResult

Bases: Exception

exception basisopt.exceptions.MethodNotAvailable(estr)

Bases: Exception

exception basisopt.exceptions.PropertyNotAvailable(pstr)

Bases: Exception

basisopt.molecule module

class basisopt.molecule.Molecule(name: str = 'Untitled', charge: int = 0, mult: int = 1)

Bases: MSONable

A very loose definition of a molecule, in that it represents an object with which calculations can be done.

name

identifier

Type:

str

charge

overall net charge

Type:

int

multiplicity

spin multiplicity, i.e. 2S+1

Type:

int

method

name of calculation method, e.g. ‘hf’ or ‘ccsd(t)’

Type:

str

basis

internal basis dictionary, which has (k, v) pairs

Type:

dict

ecps

map of atom types to ecp basis names

Type:

dict

jbasis

internal basis dictionary for Coulomb fitting set

Type:

dict

jkbasis

internal basis dictionary for Coulomb+Exchange fitting set

Type:

dict

of the form (element_symbol

array of Shell objects)

dummy_atoms

list of indices of atoms that should be treated as dummies

Type:

list

Private attributes:

_atom_names (list): atom symbols in order, e.g. [‘H’, ‘H’, ‘O’] _coords (list): x,y,z coords in Angstrom, as numpy arrays, same order as _atom_names _results (dict): dictionary of results calculated for this molecule. NOTE: these results are NOT archived, unlike for a Result object _references (dict): dictionary of reference values for results

add_atom(element: str = 'H', coord: list[float] = [0.0, 0.0, 0.0], dummy: bool = False)

Adds an atom to the molecule

Parameters:

  • element (str) – element name

  • coord (list) – [x,y,z] coords in Ansgtrom

  • dummy (bool) – if True, the atom is marked as a dummy atom

add_reference(name: str, value: Any)

Same as add_result but for reference values

add_result(name: str, value: Any)

Store a result (no archiving)

Parameters:

  • name (str) – identifier for result

  • value (any) – value of result

as_dict() → dict[str, Any]

Converts Molecule to MSONable dictionary

Returns:

dictionary representing the molecule

distance(atom1: int, atom2: int) → float

Computes the Euclidean distance between two atoms. No bounds checking.

Parameters:

  • atom1 (int) – indices of atoms

  • atom2 (int) – indices of atoms

Returns:

the Euclidean separation in Angstrom

classmethod from_dict(d: dict[str, Any]) → object

Creates a Molecule from a dictionary

Parameters:

d (dict) – dictionary with Molecule attributes

Returns:

Molecule

classmethod from_xyz(filename: str, name: str = 'Untitled', charge: int = 0, mult: int = 1) → object

Creates a Molecule from an xyz file

Parameters:

filename (str) – path to xyz file

get_delta(name: str) → Any

Returns: Difference between a result and its reference value

get_line(i: int, atom_prefix: str = '', atom_suffix: str = '') → str

Gets a line of the xyz file representation of the Molecule

Parameters:

  • i (int) – the index of the atom line wanted

  • atom_prefix (str) – optional string to add at start of atom name (for e.g. dummy atoms in psi4)

  • atom_suffix (str) – optional string to add at end of atom name (for e.g. dummy atoms in Orca)

Returns:

a string of form {prefix+element+suffix} {coords}

get_reference(name: str) → Any

Same as get_result but for reference values

get_result(name: str) → Any

Returns: Value of result with given name if it exists, otherwise 0

natoms() → int

Returns number of atoms in Molecule

nelectrons() → int

Returns the number of electrons in the molecule, not accounting for any ECPs

set_dummy_atoms(indices: list[int], overwrite: bool = True)

Sets the list of atoms that should be considered dummies or ghosts

Parameters:

  • indices – list of indices specifying which atoms to dummy-ify

  • overwrite – if True, will overwrite any existing list of dummies, otherwise will append to the existing list

set_ecps(ecp_dict: dict[str, str])

Sets the ECP dictionary.

Parameters:

ecp_dict – a dictionary of atom name to ECP name. The ECP name should be either a name from BSE (for Psi4 backend), or the Orca internal library (for Orca backend, list of names can be found in the manual)

to_xyz() → str

Converts Molecule to xyz file format

Returns:

a string of the Molecule in xyz file format

unique_atoms() → list[str]

Returns a list of all unique atom types in Molecule

basisopt.molecule.build_diatomic(mol_str: str, charge: int = 0, mult: int = 1) → Molecule

Builds a diatomic molecule from a string

Parameters:

  • mol_str (str) – string of diatomic and separation in Angstrom

  • "NO (e.g.) –

  • 1.3" –

  • "H2 –

  • 0.9" –

  • "LiH –

  • etc (1.1") –

  • charge (int) – net molecular charge

  • mult (int) – spin multiplicity

Returns:

Molecule object of diatomic

Raises:

  • IndexError when rval not given in mol_str –

  • InvalidDiatomic when mol_str can't be parsed –

  • error checking not exhaustive –

basisopt.parallelise module

basisopt.parallelise.chunk(x: list[Any], n_chunks: int) → list[list[Any]]

Chunks an array into roughly equal-sized subarrays

Parameters:

  • L (x - array of values of length) –

  • into (n_chunks - number of chunks to split) –

Returns:

a list of n_chunks arrays of length L//n_chunks or (L//n_chunks)+1

basisopt.parallelise.distribute(n_proc: int, func: Callable[[list[Any], dict], Any], x: list[Any], **kwargs) → list[Any]

Distributes a function over a desired no. of procs using the distributed library.

Parameters:

  • start (n_proc - the number of processes to) –

  • call (func - the function to) –

  • signature (with) –

  • over (x - the array of values to distribute) –

  • func (kwargs - the named arguments accepted by) –

Returns:

a list of results ordered by process ID

basisopt.util module

basisopt.util.dict_decode(d: dict[str, Any]) → dict[str, Any]
basisopt.util.fit_poly(x: ndarray, y: ndarray, n: int = 6) → tuple[numpy.poly1d, float, float, list[float]]

Fits a polynomial of order n to the set of (x [Bohr], y [Hartree]) coordinates given, and calculates data necessary for a Dunham analysis.

Parameters:

  • x (numpy array) – atomic separations in Bohr

  • y (numpy array) – energies at each point in Hartree

  • n (int) – order of polynomial to fit

Returns:

poly1d object, reference separation (Bohr), equilibrium separation (Bohr), first (n+1) Taylor series coefficients at eq. sep.

basisopt.util.read_json(filename: str) → MSONable

Reads an MSONable object from file

Parameters:

filename (str) – path to JSON file

Returns:

object

basisopt.util.write_json(filename: str, obj: MSONable)

Writes an MSONable object to file

Parameters:

  • filename (str) – path to JSON file

  • obj (MSONable) – object to be written

basisopt.version module

Module contents