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:

1. Python BSE Package: Auto-detects if basis_set_exchange is installed via pip
2. Environment Variable: Set BSE_DATA_DIR to point to BSE data directory
3. Runtime Specification: Use specify_bse_data_dir() function
4. 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)

Supported Input Formats (Readers)

Basis Set Manipulations

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

Data Structures

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

• MolSSI Basis Set Exchange
• Python BSE Repository
• BSE API Documentation

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.