{"id":10279,"library":"tblite","title":"Tblite","description":"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.","status":"active","version":"0.5.0","language":"en","source_language":"en","source_url":"https://github.com/tblite-team/tblite-python","tags":["quantum chemistry","materials science","tight-binding","simulation","molecular modeling"],"install":[{"cmd":"pip install tblite numpy","lang":"bash","label":"Install tblite with core dependencies"}],"dependencies":[{"reason":"Required for array manipulations, particularly for molecular positions.","package":"numpy","optional":false},{"reason":"Used for certain numerical operations within the tight-binding calculations.","package":"scipy","optional":false}],"imports":[{"symbol":"Calculator","correct":"from tblite.interface import Calculator"}],"quickstart":{"code":"import numpy as np\nfrom tblite.interface import Calculator\n\n# Define the molecule\nspecies = [\"H\", \"H\"]\npositions = np.array([[0.0, 0.0, 0.0], [0.0, 0.0, 0.7]])\n\n# Initialize the calculator with a specific method\n# Available methods include GFN1-xTB, GFN2-xTB, GFN-FF, etc.\n# Check official docs for a complete list.\ncalc = Calculator(method=\"GFN2-xTB\")\n\n# Perform the calculation\nresult = calc.calculate(species, positions)\n\n# Access results from the dictionary\nprint(f\"Total energy: {result['energy']} Hartree\")\nprint(f\"Forces (Hartree/Bohr):\\n{result['forces']}\")\n\n# Example with optional charge (default is 0)\ncalc_charged = Calculator(method=\"GFN2-xTB\")\ncharged_result = calc_charged.calculate(species, positions, charge=1)\nprint(f\"Charged system energy: {charged_result['energy']} Hartree\")","lang":"python","description":"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."},"warnings":[{"fix":"Update your code to access results via dictionary keys: `result = calc.calculate(...); energy = result['energy']`. Check the documentation for available keys.","message":"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.","severity":"breaking","affected_versions":">=0.4.0"},{"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'.","message":"The `Calculator` constructor requires a valid `method` string (e.g., 'GFN2-xTB'). Using an unknown or misspelled method name will lead to a `ValueError`.","severity":"gotcha","affected_versions":"all"},{"fix":"Convert your list of positions to a NumPy array before passing it to `calc.calculate`: `positions = np.array([[x1, y1, z1], ...])`.","message":"Molecular positions must be provided as a NumPy array. Passing a standard Python list of lists will result in a `TypeError`.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Access results using dictionary keys: `energy = result['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.","error":"AttributeError: 'dict' object has no attribute 'energy'"},{"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').","cause":"The specified tight-binding method name is incorrect or not supported by tblite.","error":"ValueError: Unknown method 'GFN-xTB'"},{"fix":"Ensure `positions` is a NumPy array: `import numpy as np; positions = np.array([[x1, y1, z1], ...])`.","cause":"The `positions` argument was passed as a Python list of lists instead of a NumPy array.","error":"TypeError: 'list' object cannot be interpreted as a numpy array"}]}