Tblite

0.5.0 · active · verified Fri Apr 17

Tblite is a lightweight Python interface to the tblite C++ library, providing fast and efficient tight-binding calculations for quantum chemistry and materials science. It allows users to perform energy, force, and other property calculations for molecular systems. The current version is 0.5.0, and it maintains a regular release cadence, with API changes detailed in release notes.

Common errors

```
AttributeError: 'dict' object has no attribute 'energy'
```
cause Attempting to access results using attribute notation (e.g., `result.energy`) instead of dictionary key access after the v0.4.0 API change.

fix Access results using dictionary keys: `energy = result['energy']`.
```
ValueError: Unknown method 'GFN-xTB'
```
cause The specified tight-binding method name is incorrect or not supported by tblite.

fix Double-check the method name for typos or refer to the tblite documentation for a list of valid methods (e.g., 'GFN2-xTB' or 'GFN1-xTB').
```
TypeError: 'list' object cannot be interpreted as a numpy array
```
cause The `positions` argument was passed as a Python list of lists instead of a NumPy array.

fix Ensure `positions` is a NumPy array: `import numpy as np; positions = np.array([[x1, y1, z1], ...])`.

Warnings

breaking The `calculate` method's return type changed from a tuple to a dictionary in v0.4.0. Direct unpacking or attribute access (e.g., `result.energy`) will fail.
Fix: Update your code to access results via dictionary keys: `result = calc.calculate(...); energy = result['energy']`. Check the documentation for available keys.
gotcha The `Calculator` constructor requires a valid `method` string (e.g., 'GFN2-xTB'). Using an unknown or misspelled method name will lead to a `ValueError`.
Fix: Ensure the `method` string exactly matches one of the supported methods listed in the tblite documentation. Common methods include 'GFN1-xTB', 'GFN2-xTB', 'GFN-FF'.
gotcha Molecular positions must be provided as a NumPy array. Passing a standard Python list of lists will result in a `TypeError`.
Fix: Convert your list of positions to a NumPy array before passing it to `calc.calculate`: `positions = np.array([[x1, y1, z1], ...])`.

Install

pip install tblite numpy Install tblite with core dependencies

Imports

Calculator
```
from tblite.interface import Calculator
```

Quickstart

Initializes a `Calculator` for a specified tight-binding method, defines a simple H2 molecule, and performs an energy and force calculation, accessing results from the returned dictionary. Also shows an example with an explicit charge.

import numpy as np
from tblite.interface import Calculator

# Define the molecule
species = ["H", "H"]
positions = np.array([[0.0, 0.0, 0.0], [0.0, 0.0, 0.7]])

# Initialize the calculator with a specific method
# Available methods include GFN1-xTB, GFN2-xTB, GFN-FF, etc.
# Check official docs for a complete list.
calc = Calculator(method="GFN2-xTB")

# Perform the calculation
result = calc.calculate(species, positions)

# Access results from the dictionary
print(f"Total energy: {result['energy']} Hartree")
print(f"Forces (Hartree/Bohr):\n{result['forces']}")

# Example with optional charge (default is 0)
calc_charged = Calculator(method="GFN2-xTB")
charged_result = calc_charged.calculate(species, positions, charge=1)
print(f"Charged system energy: {charged_result['energy']} Hartree")

view raw JSON →