Crate bse

Expand description

§Basis Set Exchange in Rust (bse-rs)

A Rust library and CLI tool for retrieving, manipulating, and converting Gaussian-type orbital (GTO) basis sets for computational chemistry. This is a complete reimplementation of the Python Basis Set Exchange library, providing full API compatibility, with some additional features.

BSE? As a programmer, I don’t understand Bethe-Salpeter Equation very well.

§Overview

bse-rs provides:

Library API: Full Rust API for basis set retrieval, manipulation, and format conversion
CLI Tool: Feature-complete command-line interface with shell completion support
Remote Access: Optional REST API client for fetching basis sets from basissetexchange.org
Format Conversion: 27+ output formats and 18+ input formats for quantum chemistry software
Basis Set Manipulation: Uncontracting, optimization, augmentation, and auxiliary basis generation

This implementation adds several distinct features beyond the Python reference:

Support to REST: REST (Rust-based Electronic Structure Toolkit) format supported for both reading and writing
Seamless Truhlar Calendar Support: Request calendar basis sets (e.g., jul-cc-pVTZ, maug-cc-pVDZ) directly through the standard API and CLI without calling separate functions
Format Auto-detection in Conversion: CLI automatically detects format from file extensions
TOML Configuration: For API usage, basis set arguments can be parsed from TOML configuration files
Support of Directory Read/Write: Read/write basis sets as directories with one file per element, in addition to single-file formats

§Installation

§From Crates.io

cargo install bse

§Library Usage

Add to your Cargo.toml:

[dependencies]
bse = "0.1"

For remote API access:

[dependencies]
bse = { version = "0.1", features = ["remote"] }

§Build from Source

git clone https://github.com/RESTGroup/bse-rs.git
cd bse-rs
cargo build --release

§Quick Start

§Basic CLI Usage

For more details on CLI options, don’t bother bse-rs --help.

# List available basis sets
bse-rs list-basis-sets

# Get basis set in NWChem format
bse-rs get-basis def2-TZVP nwchem --elements "H,C,N,F-Mg,47-55"

# Get basis set with manipulations in Gaussian format
# This specific case is uncontract all segmented contractions and add 1 diffuse function
bse-rs get-basis cc-pVTZ gaussian --unc-seg --aug-diffuse 1

# Get full basis set to directory in REST format (one file per element)
bse-rs get-basis def2-TZVP rest

# Output to directory in Gaussian format (one file per element)
bse-rs get-basis def2-TZVP dir-gaussian94 -o ./basis_dir

# Convert between formats (auto-detects from extension)
bse-rs convert-basis input.nw output.gbs

# Convert between formats (use specific format)
bse-rs convert-basis input.nw basis_dir --out-fmt rest

# Get Truhlar calendar basis set directly
bse-rs get-basis jul-cc-pVTZ nwchem --elements "Zn"

# Generate shell completion
bse-rs completion bash --install

§Download Basis Data

Note that if remote access is allowed, the library will fetch data directly from https://basissetexchange.org. In this case, no local data is required, but will be much slower.

If you have the Python BSE package installed, it will use that data. Be sure the basis_set_exchange Python package is installed and accessible in your environment.

pip install basis_set_exchange

Otherwise, you can specify the data directory using the BSE_DATA_DIR environment variable or the --data-dir CLI option. The original data can be accessable from the Python BSE repository:

export CURRENT_DIR=$(pwd)
git clone https://github.com/MolSSI-BSE/basis_set_exchange.git
export BSE_DATA_DIR="$CURRENT_DIR/basis_set_exchange/basis_set_exchange/data"

§Library API

use bse::prelude::*;

// Get basis set as structured object
let args = BseGetBasisArgsBuilder::default().elements("H, C-O".to_string()).build().unwrap();
let basis = get_basis("cc-pVTZ", args);
println!("Basis: {} ({})", basis.name, basis.family);

// use TOML configuration for arguments
let args_string = r#"
    elements = "H, C-O"
    augment_diffuse = 1
"#;
let basis = get_basis("cc-pVTZ", args_string);
println!("Basis: {} ({})", basis.name, basis.family);

// Get formatted output for quantum chemistry software
let args = BseGetBasisArgsBuilder::default().elements("H, O".to_string()).header(true).build().unwrap();
let output = get_formatted_basis("sto-3g", "nwchem", args);
println!("{}", output);

// Apply manipulations
let args = BseGetBasisArgsBuilder::default().uncontract_general(true).augment_diffuse(2).build().unwrap();
let basis = get_basis("def2-SVP", args);
println!("Basis: {} ({})", basis.name, basis.family);

// Get Truhlar calendar basis directly (seamless integration)
let basis = get_basis("jul-cc-pVTZ", BseGetBasisArgs::default());
println!("Basis: {} ({})", basis.name, basis.family);
let basis = get_basis("maug-cc-pVDZ", BseGetBasisArgs::default()); // Auto-selects jun for DZ
println!("Basis: {} ({})", basis.name, basis.family);

// Read basis from file
// assumes basis.nw exists and is in NWChem format
let content = std::fs::read_to_string("basis.nw").unwrap();
let basis_minimal = read_formatted_basis_str(&content, "nwchem");
println!("Basis: {}", basis_minimal.name);

§Features and Configuration

§Data Source Configuration

The library supports multiple data sources with automatic detection:

Python BSE Package: Auto-detects if basis_set_exchange is installed via pip
Environment Variable: Set BSE_DATA_DIR to point to BSE data directory
Runtime Specification: Use specify_bse_data_dir() function
Remote API: Fetch directly from basissetexchange.org (requires remote feature)

§BSE_DATA_DIR - Local Data Directory

# Environment variable method
export BSE_DATA_DIR=/path/to/basis_set_exchange/basis_set_exchange/data

§BSE_REMOTE - Default Data Source

The BSE_REMOTE environment variable controls the default data source behavior:

# Use local data directory only
export BSE_REMOTE=local

# Use remote REST API only (requires remote feature)
export BSE_REMOTE=remote

# Try local first, fallback to remote if local fails (default)
export BSE_REMOTE=auto

Supported values:

local, 0, false, no: Use local data directory only
remote, 1, true, yes: Use remote REST API only
auto: Try local first, fallback to remote (default)

§BSE_TIMEOUT - Request Timeout

Timeout in seconds for remote API requests (default: 10). Only applies when using remote or auto source with the remote feature enabled.

export BSE_TIMEOUT=30  # 30 second timeout

§BSE_WARN_LOCAL_NOTFOUND - Fallback Warning

Control warning message when falling back from local to remote in auto mode (default: true/warning enabled).

export BSE_WARN_LOCAL_NOTFOUND=0  # Suppress fallback warning

§CLI Source Override

The --source option overrides the BSE_REMOTE environment variable:

# Override to use remote
bse-rs --source remote get-basis cc-pVTZ nwchem

# Override to use auto (tries local, then remote)
bse-rs --source auto get-basis cc-pVTZ nwchem

§Supported Output Formats (Writers)

Name	Extension	Aliases	Display
acesii	.acesii		ACES II
bdf	.bdf		BDF
bsedebug	.bse		BSE Debug
cfour	.c4bas	c4bas	CFOUR
cp2k	.cp2k		CP2K
crystal	.crystal		Crystal
dalton	.dalton		Dalton
demon2k	.d2k	d2k	deMon2K
fhiaims	.fhiaims		FHI-aims
gamess_uk	.bas		GAMESS UK
gamess_us	.bas		GAMESS US
gaussian94	.gbs	g94, gaussian, gau	Gaussian
gaussian94lib	.gbs	g94lib	Gaussian, system library
jaguar	.jaguar		Jaguar
json	.json	bsejson	JSON
libmol	.libmol		Molpro system library
molcas	.molcas		Molcas
molcas_library	.molcas		Molcas basis library
molpro	.mpro	mpro	Molpro
nwchem	.nw	nw	NWChem
orca	.orca		ORCA
pqs	.pqs		PQS
psi4	.gbs		Psi4
qchem	.qchem		Q-Chem
qcschema	.json		QCSchema
rest	.json		REST (directory only format)
ricdwrap	.ricdwrap		Wrapper for generating acCD auxiliary basis sets with OpenMolcas
turbomole	.tm	tm	Turbomole
veloxchem	.vlx	vlx	VeloxChem
xtron	.gbs		xTron

§Supported Input Formats (Readers)

Name	Extension	Aliases	Display
cfour	.c4bas		CFOUR
cp2k	.cp2k		CP2K
crystal	.crystal		Crystal
dalton	.mol	mol	Dalton
demon2k	.d2k	d2k	deMon2k
gamess_us	.bas		GAMESS US
gaussian94	.gbs	gaussian, g94, gbs, gau	Gaussian94
gbasis	.gbasis		GBasis
genbas	.genbas		Genbas
json	.json	bsejson	JSON
libmol	.libmol		Molpro system library
molcas	.molcas		Molcas
molcas_library	.molcas		Molcas basis library
molpro	.mpro	mpro	Molpro
nwchem	.nw	nw	NWChem
rest	.json		REST (directory only format)
ricdlib	.ricdlib	ricd	MolCAS RICDlib
turbomole	.tm	tm	Turbomole
veloxchem	.vlx	vlx	VeloxChem

§Basis Set Manipulations

Option	Description
`uncontract_general`	Remove general contractions by duplicating primitives
`uncontract_spdf`	Split combined shells (sp, spd, spdf) into separate shells
`uncontract_segmented`	Fully uncontract (each primitive becomes separate shell)
`make_general`	Make basis set as generally-contracted as possible
`optimize_general`	Optimize general contractions by removing redundant functions
`remove_free_primitives`	Remove uncontracted (free) primitives
`augment_diffuse`	Add n diffuse functions via even-tempered extrapolation
`augment_steep`	Add n steep functions via even-tempered extrapolation
`get_aux`	Generate auxiliary basis: 0=orbital, 1=AutoAux, 2=AutoABS

§Truhlar Calendar Basis Sets

Request calendar basis sets directly through the standard API:

// All month prefixes supported
get_basis("jul-cc-pVTZ", args);  // July - all diffuse
get_basis("jun-cc-pVTZ", args);  // June - s,p diffuse
get_basis("may-cc-pVTZ", args);  // May - s diffuse
get_basis("apr-cc-pVTZ", args);  // April - no diffuse

// maug automatically selects based on zeta level
get_basis("maug-cc-pVDZ", args); // -> jun-cc-pVDZ
get_basis("maug-cc-pVTZ", args); // -> may-cc-pVTZ
get_basis("maug-cc-pVQZ", args); // -> apr-cc-pVQZ

§Reference/Citation Formats

# Get BibTeX references
bse-rs get-refs cc-pVTZ bib --elements "H,C"

# Available formats: bib, txt, ris, endnote, json

§Metadata Queries

# List basis sets with filters
bse-rs list-basis-sets --family dunning --substr aug
bse-rs list-basis-sets --role jkfit --elements "H-C"

# Get basis set info
bse-rs get-info cc-pVTZ

# Lookup auxiliary basis by role
bse-rs lookup-by-role cc-pVTZ jkfit

§API Documentation

Full API documentation is available at docs.rs/bse.

§Key Functions

Function	Description
`get_basis`	Retrieve basis set by name
`get_formatted_basis`	Get formatted output for specific software
`read_formatted_basis_str`	Parse basis set from formatted string
`write_formatted_basis_str`	Convert basis set to specific format
`get_metadata`	Get all basis set metadata
`filter_basis_sets`	Filter basis sets by family, role, elements
`get_references`	Get citations for a basis set
`get_family_notes`	Get notes for a basis set family
`lookup_basis_by_role`	Find auxiliary basis by role

§Data Structures

Struct	Description
`BseBasis`	Complete basis set with all metadata
`BseBasisElement`	Per-element basis data (shells, ECPs)
`BseElectronShell`	Individual shell (angular momentum, exponents, coefficients)
`BseGetBasisArgs`	Arguments for basis set retrieval and manipulation
`BseFilterArgs`	Arguments for filtering basis sets

§CLI Reference

Usage: bse-rs [OPTIONS] <COMMAND>

Commands:
  list-writer-formats  Output a list of basis set formats that can be written
  list-reader-formats  Output a list of basis set formats that can be read
  list-ref-formats     Output a list of all available reference formats and descriptions
  list-roles           Output a list of all available roles and descriptions
  get-data-dir         Output the default data directory of this package
  list-basis-sets      Output a list of all available basis sets and descriptions
  list-families        Output a list of all available basis set families
  lookup-by-role       Lookup a companion/auxiliary basis by primary basis and role
  get-basis            Output a formatted basis set
  get-refs             Output references for a basis set
  get-info             Output general info and metadata for a basis set
  get-notes            Output the notes for a basis set
  get-family           Output the family of a basis set
  get-versions         Output a list of all available versions of a basis set
  get-family-notes     Get the notes of a family of basis sets
  convert-basis        Convert basis set files from one format to another
  autoaux-basis        Form AutoAux auxiliary basis
  autoabs-basis        Form AutoABS auxiliary basis
  completion           Generate or install shell completion scripts
  help                 Print this message or the help of the given subcommand(s)

Options:
  -d, --data-dir <PATH>  Override which data directory to use
      --source <SOURCE>  Data source: 'local', 'remote' (requires remote feature), or 'auto'. Default is from BSE_REMOTE env var, or 'local' if unset
  -o, --output <PATH>    Output to given file rather than stdout
  -h, --help             Print help
  -V, --version          Print version

§References

§License

Apache License 2.0. See LICENSE for details.

§Acknowledgments

This project is a Rust reimplementation of the Python Basis Set Exchange library by MolSSI. Current implementation should comply v0.12 of python’s original.

Note that this is not officially affiliated with the MolSSI BSE project, but is an independent implementation in current status.

This project is supported by REST (Rust-based Electronic Structure Toolkit).

AI assistance is applied in code generation, documentation, and testing. Acknowledges to Claude Code and GLM-5. Deepseek is also used for early prototyping and development.

§Contributing

Contributions are welcome! Please feel free to submit pull requests or open issues on the GitHub repository.

Re-exports§

pub use error::BseError;
pub use prelude::*;

Modules§

api: Main interface to Basis Set Exchange internal basis sets.
cli
client: Client for fetching basis set data from the BSE REST API.
compose: Functions for composing basis sets from individual components.
dir_reader: Directory-based basis set reader.
dir_writer: Directory-based basis set writer.
error: Error types for the bse crate.
fields: Data structures for basis set information.
ints: One-center integrals for Gaussian-type and Slater-type orbitals.
lut: Functions for looking up element names, numbers, and symbols and for converting between angular momentum conventions.
lut_data
manip: Common basis set manipulations.
misc: Miscellaneous helper functions and constants.
notes: Helper functions for handling basis set and family notes.
prelude: Common imports for users and developers of the bse crate.
printing: Helper functions for formatting basis set output.
readers: Functions for reading formatted basis set files.
refconverters: Reference/citation format converters.
references: Helper functions for handling basis set references/citations.
sort: Sorting utilities for basis set data.
writers: Conversion of basis sets to various formats.

Macros§

bse_raise: Raise a BseError with trace information.
bse_trace: Create a trace string with file, line, and column information.

Crate bse

Crate bse Copy item path

§Basis Set Exchange in Rust (bse-rs)

§Overview

§Installation

§From Crates.io

§Library Usage

§Build from Source

§Quick Start

§Basic CLI Usage

§Download Basis Data

§Library API

§Features and Configuration

§Data Source Configuration

§BSE_DATA_DIR - Local Data Directory

§BSE_REMOTE - Default Data Source

§BSE_TIMEOUT - Request Timeout

§BSE_WARN_LOCAL_NOTFOUND - Fallback Warning

§CLI Source Override

§Supported Output Formats (Writers)

§Supported Input Formats (Readers)

§Basis Set Manipulations

§Truhlar Calendar Basis Sets

§Reference/Citation Formats

§Metadata Queries

§API Documentation

§Key Functions

§Data Structures

§CLI Reference

§References

§License

§Acknowledgments

§Contributing

Re-exports§

Modules§

Macros§

Crate bse