Main User API

Basis Set Exchange Python library

This package contains utilities for obtaining, reading, writing, and converting basis set information

basis_set_exchange.convert_formatted_basis_file(file_path_in, file_path_out, in_fmt=None, out_fmt=None, encoding='utf-8-sig', make_gen=False)

Convert a formatted basis set file to another format

Parameters:

  • file_path_in (str) – Path to the file to be read

  • file_path_out (str) – Path to the file to be written.

  • in_fmt (str) – The format of the basis to be read. If None, it is detected from the file name

  • out_fmt (str) – The format of the basis to be written. If None, it is detected from the file name

  • encoding (str) – The encoding of the input file

Returns:

The basis set as a str with the new format

Return type:

str

basis_set_exchange.convert_formatted_basis_str(basis_in, in_fmt, out_fmt)

Convert a formatted basis set to another format

Parameters:

  • basis_in (str) – String representing the formatted input basis set input

  • in_fmt (str) – The format of the basis set stored in basis_in

  • out_fmt (str) – The desired output format

Returns:

The basis set as a str with the new format

Return type:

str

basis_set_exchange.create_bundle(outfile, fmt, reffmt, archive_type=None, data_dir=None)

Create a single archive file containing all basis sets in a given format

Parameters:

  • outfile (str) – Path to the file to create. Existing files will be overwritten

  • fmt (str) – Format of the basis set to archive (nwchem, turbomole, …)

  • reffmt (str) – Format of the basis set references to archive (nwchem, turbomole, …)

  • archive_type (str) – Type of archive to create. Can be ‘zip’ or ‘tbz’. Default is None, which will autodetect based on the outfile name

  • data_dir (str) – Data directory with all the basis set information. By default, it is in the ‘data’ subdirectory of this project.

Return type:

None

basis_set_exchange.filter_basis_sets(substr=None, family=None, role=None, elements=None, data_dir=None)

Filter basis sets by some criteria

All parameters are ANDed together and are not case sensitive.

Parameters:

  • substr (str) – Substring to search for in the basis set name

  • family (str) – Family the basis set belongs to

  • role (str) – Role of the basis set

  • elements (str or list) – List of elements that the basis set must include. Elements can be specified by Z-number (int or str) or by symbol (str). If this argument is a str (ie, ‘1-3,7-10’), it is expanded into a list. Z numbers and symbols (case insensitive) can be used interchangeably (see basis_set_exchange.misc.expand_elements())

  • data_dir (str) – Data directory with all the basis set information. By default, it is in the ‘data’ subdirectory of this project.

Returns:

Basis set metadata that matches the search criteria

Return type:

dict

basis_set_exchange.get_all_basis_names(data_dir=None)

Obtain a list of all basis set names

The returned list is the internal representation of the basis set name.

The data is read from the METADATA.json file in the data directory.

Parameters:

data_dir (str) – Data directory with all the basis set information. By default, it is in the ‘data’ subdirectory of this project.

basis_set_exchange.get_archive_types()

Return information related to the types of archives available

basis_set_exchange.get_basis(name, elements=None, version=None, fmt=None, uncontract_general=False, uncontract_spdf=False, uncontract_segmented=False, remove_free_primitives=False, make_general=False, optimize_general=False, augment_diffuse=0, augment_steep=0, get_aux=0, data_dir=None, header=True)

Obtain a basis set

This is the main function for getting basis set information. This function reads in all the basis data and returns it either as a string or as a python dictionary.

Parameters:

  • name (str) – Name of the basis set. This is not case sensitive.

  • elements (str or list) –

    List of elements that you want the basis set for. Elements can be specified by Z-number (int or str) or by symbol (str). If this argument is a str (ie, ‘1-3,7-10’), it is expanded into a list. Z numbers and symbols (case insensitive) can be used interchangeably (see basis_set_exchange.misc.expand_elements())

    If an empty string or list is passed, or if None is passed (the default), all elements for which the basis set is defined are included.

  • version (int or str) – Obtain a specific version of this basis set. By default, the latest version is returned.

  • fmt (str) –

    The desired output format of the basis set. By default, basis set information is returned as a python dictionary. Otherwise, if a format is specified, a string is returned. Use basis_set_exchange.api.get_formats() to programmatically obtain the available formats. The fmt argument is not case sensitive.

    Available formats are

    • bdf

    • gamess_us

    • gaussian94

    • json

    • nwchem

    • psi4

    • turbomole

  • uncontract_general (bool) – If True, remove general contractions by duplicating the set of primitive exponents with each vector of coefficients. Primitives with zero coefficient are removed, as are duplicate shells.

  • uncontract_spdf (bool) – If True, remove general contractions with combined angular momentum (sp, spd, etc) by duplicating the set of primitive exponents with each vector of coefficients. Primitives with zero coefficient are removed, as are duplicate shells.

  • uncontract_segmented (bool) – If True, remove segmented contractions by duplicating each primitive into new shells. Each coefficient is set to 1.0

  • make_general (bool) – If True, make the basis set as generally-contracted as possible. There will be one shell per angular momentum (for each element)

  • optimize_general (bool) – Optimize by removing general contractions that contain uncontracted functions (see basis_set_exchange.manip.optimize_general())

  • augment_diffuse (int) – Add n diffuse functions by even-tempered extrapolation

  • augment_steep (int) – Add n steep functions by even-tempered extrapolation

  • get_aux (int) – Instead of the orbital basis, get an auxiliary basis set. Options 0 (return orbital basis), 1 (return AutoAux basis), 2 (return Auto-ABS Coulomb fitting basis)

  • data_dir (str) – Data directory with all the basis set information. By default, it is in the ‘data’ subdirectory of this project.

Returns:

The basis set in the desired format. If fmt is None, this will be a python dictionary. Otherwise, it will be a string.

Return type:

str or dict

basis_set_exchange.get_basis_family(basis_name, data_dir=None)

Lookup a family by a basis set name

basis_set_exchange.get_data_dir()

Get the default data directory of this installation

basis_set_exchange.get_formats(function_types=None)

Return information about the basis set formats available

The returned data is a map of format to display name. The format can be passed as the fmt argument to get_basis()

If a list is specified for function_types, only those formats supporting the given function types will be returned.

basis_set_exchange.get_reader_formats()

Returns the basis set formats that can be read by this library.

This is returned as an ordered dictionary of key to display name.

basis_set_exchange.get_reference_formats()

Return information about the reference/citation formats available

The returned data is a map of format to display name. The format can be passed as the fmt argument to get_references()

basis_set_exchange.get_references(basis_name, elements=None, version=None, fmt=None, data_dir=None)

Get the references/citations for a basis set

Parameters:

  • basis_name (str) – Name of the basis set. This is not case sensitive.

  • elements (list) – List of element numbers that you want the basis set for. By default, all elements for which the basis set is defined are included.

  • version (int) – Obtain a specific version of this basis set. By default, the latest version is returned.

  • fmt (str) –

    The desired output format of the basis set references. By default, basis set information is returned as a list of dictionaries. Use get_reference_formats() to programmatically obtain the available formats. The fmt argument is not case sensitive.

    Available reference formats are

    • bib

    • txt

    • json

  • data_dir (str) – Data directory with all the basis set information. By default, it is in the ‘data’ subdirectory of this project.

Returns:

The references for the given basis set in the desired format. If fmt is None, this will be a python dictionary. Otherwise, it will be a string.

Return type:

str or dict

basis_set_exchange.get_roles()

Return information about the available basis set roles available

The returned data is a map of role to display name. The format can be passed as the role argument to fmt argument to lookup_basis_by_role()

basis_set_exchange.get_writer_formats(function_types=None)

Return information about the basis set formats available for writing

The returned data is a map of format to display name. The format can be passed as the fmt argument to write_formatted_basis_str() or write_formatted_basis_file()

If a list is specified for function_types, only those formats supporting the given function types will be returned.

basis_set_exchange.lookup_basis_by_role(primary_basis, role, data_dir=None)

Lookup the name of an auxiliary basis set given a primary basis set and role

Parameters:

  • primary_basis (str) – The primary (orbital) basis set that we want the auxiliary basis set for. This is not case sensitive.

  • role (str) –

    Desired role/type of auxiliary basis set. Use get_roles() to programmatically obtain the available roles. The role argument is not case sensitive.

    Available roles are

    • jfit

    • jkfit

    • rifit

    • optri

    • admmfit

    • dftxfit

    • dftjfit

    • guess

  • data_dir (str) – Data directory with all the basis set information. By default, it is in the ‘data’ subdirectory of this project.

Returns:

The name of the auxiliary basis set for the given primary basis and role.

Return type:

str

basis_set_exchange.validate_data(file_type, bs_data)

Validates json basis set data against a schema

Parameters:

  • file_type (str) – Type of the data to validate. May be ‘component’, ‘element’, ‘table’, ‘complete’, ‘minimal’, or ‘references’

  • bs_data – Data to be validated

Raises:

  • RuntimeError – If the file_type is not valid (and/or a schema doesn’t exist)

  • ValidationError – If the given file does not pass validation

  • FileNotFoundError – If the file given by file_path doesn’t exist

basis_set_exchange.validate_file(file_type, file_path)

Validates a file against a schema

Parameters:

  • file_type (str) – Type of file to read. May be ‘component’, ‘element’, ‘table’, ‘complete’, ‘minimal’, or ‘references’

  • file_path – Full path to the file to be validated

Raises:

  • RuntimeError – If the file_type is not valid (and/or a schema doesn’t exist)

  • ValidationError – If the given file does not pass validation

  • FileNotFoundError – If the file given by file_path doesn’t exist

basis_set_exchange.version(distribution_name)

Get the version string for the named package.

Parameters:

distribution_name – The name of the distribution package to query.

Returns:

The version string for the package as defined in the package’s “Version” metadata key.

basis_set_exchange.write_formatted_basis_str(basis_dict, fmt, header=None)

Returns the basis set data as a string representing the data in the specified output format