xtb-python

https://xtb-python.readthedocs.io/en/latest
Admin
xtb-python is a Python API for the extended tight binding program (xtb) that provides interfaces for...
Tokens:29,202
Snippets:159
Trust Score:8.3
Update:7 months ago
Show doc for...
Tokens:
Raw
### Modify xtb.pc for pkg-config

Source: https://xtb-python.readthedocs.io/en/latest/installation

An example of how to modify the 'xtb.pc' file to correctly point to the xtb installation prefix. This is a manual step to help pkg-config locate the necessary files when automatic detection fails.

```diff
--- a/lib/pkgconfig/xtb.pc
+++ b/lib/pkgconfig/xtb.pc
@@ -1,4 +1,4 @@
-prefix=/
+prefix=/absolute/path/to/xtb
 libdir=${prefix}/lib
 includedir=${prefix}/include/xtb
```

--------------------------------

### Build and Install xtb-python Extension Module

Source: https://xtb-python.readthedocs.io/en/latest/installation

Sets up the build environment using Meson and then builds and installs the CFFI extension module for xtb-python. This process compiles the C code and makes it available to Python.

```bash
meson setup build --prefix=$HOME/.local
ninja -C build install
```

--------------------------------

### Install Build Tools with Pip

Source: https://xtb-python.readthedocs.io/en/latest/installation

Installs necessary build tools like cffi, numpy, meson, and ninja using pip. These tools are required for building the extension module when compiling from source.

```bash
pip install cffi numpy meson ninja
```

--------------------------------

### Check xtb Dependency with pkg-config

Source: https://xtb-python.readthedocs.io/en/latest/installation

Verifies if the 'xtb' dependency can be found by pkg-config, which is used by Meson during the build process. This command helps diagnose issues where Meson cannot locate the xtb installation.

```bash
pkg-config xtb --print-errors
```

--------------------------------

### Perform Single Point Calculation and Get Results (Python)

Source: https://xtb-python.readthedocs.io/en/latest/general-api

Demonstrates how to perform a single-point calculation using the `xtb.interface.Calculator` and retrieve results. It initializes a calculator with GFN2-xTB parameters, sets verbosity, runs the calculation, and then retrieves the energy and gradient. The example also shows how to restart a calculation with existing results.

```python
from xtb.libxtb import VERBOSITY_MINIMAL
from xtb.interface import Calculator, Param
import numpy as np

numbers = np.array([8, 1, 1])
positions = np.array([
 [ 0.00000000000000, 0.00000000000000,-0.73578586109551],
 [ 1.44183152868459, 0.00000000000000, 0.36789293054775],
 [-1.44183152868459, 0.00000000000000, 0.36789293054775]])

calc = Calculator(Param.GFN2xTB, numbers, positions)
calc.set_verbosity(VERBOSITY_MINIMAL)
res = calc.singlepoint()  # energy printed is only the electronic part

print(res.get_energy())
print(res.get_gradient())

res = calc.singlepoint(res)
print(res.get_charges())
```

--------------------------------

### Clone xtb-python Repository

Source: https://xtb-python.readthedocs.io/en/latest/installation

Clones the xtb-python project from GitHub and navigates into the project directory. This is the first step for building the project from source.

```bash
git clone https://github.com/grimme-lab/xtb-python
cd xtb-python
```

--------------------------------

### Install Build Tools with Conda

Source: https://xtb-python.readthedocs.io/en/latest/installation

Installs necessary build tools like cffi, numpy, meson, and ninja using Conda from the conda-forge channel. This method is an alternative to using pip for installing build dependencies.

```bash
conda config --add channels conda-forge
conda install cffi numpy meson ninja
```

--------------------------------

### Install xtb-python with Conda

Source: https://xtb-python.readthedocs.io/en/latest/installation

Installs the xtb-python package and its dependencies using the Conda package manager. It first adds the conda-forge channel and then installs the package. It also shows how to install optional dependencies for ASE and QCArchive integration.

```bash
conda config --add channels conda-forge
conda install xtb-python
conda install qcelemental ase
```

--------------------------------

### Get Orbital Coefficients

Source: https://xtb-python.readthedocs.io/en/latest/_modules/xtb/interface

Retrieves the coefficients for each molecular orbital, forming the basis set expansion.

```APIDOC
## GET /results/orbital_coefficients

### Description
Queries the singlepoint results object for the coefficients of each molecular orbital, which define the linear combination of basis functions.

### Method
GET

### Endpoint
/results/orbital_coefficients

### Parameters
None

### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **orbital_coefficients** (ndarray) - A 2D numpy array where rows represent molecular orbitals and columns represent basis functions, containing the expansion coefficients.

#### Response Example
```json
{
  "orbital_coefficients": [
    [-7.94626768e-01,  6.38378239e-16,  4.52990407e-01, -6.38746369e-16, -8.35495085e-01, -4.44089210e-16],
    [ 2.77555756e-17, -6.97332245e-01,  7.49400542e-16,  1.88136491e-17,  7.21644966e-16, -9.60006511e-01],
    [ 2.17336312e-16, -1.08051945e-16, -1.11598977e-15, -1.00000000e+00,  5.74153329e-17,  3.30330107e-17],
    [-8.67578876e-02, -9.71445147e-16, -8.05763104e-01,  7.71702239e-16, -7.18690020e-01, -4.71844785e-16],
    [-1.84540457e-01, -3.54572323e-01, -2.39090946e-01,  2.87533552e-16,  7.68757806e-01,  9.02845514e-01],
    [-1.84540457e-01,  3.54572323e-01, -2.39090946e-01,  2.01021058e-16,  7.68757806e-01, -9.02845514e-01]
  ]
}
```
```

--------------------------------

### Get Bond Orders

Source: https://xtb-python.readthedocs.io/en/latest/_modules/xtb/interface

Retrieves the bond order matrix from the singlepoint results object.

```APIDOC
## GET /results/bond_orders

### Description
Queries the singlepoint results object for the bond order matrix.

### Method
GET

### Endpoint
/results/bond_orders

### Parameters
None

### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **bond_orders** (ndarray) - A 2D numpy array representing the bond order matrix between atoms.

#### Response Example
```json
{
  "bond_orders": [
    [0.00000000e+00, 9.20433501e-01, 9.20433501e-01],
    [9.20433501e-01, 0.00000000e+00, 2.74039053e-04],
    [9.20433501e-01, 2.74039053e-04, 0.00000000e+00]
  ]
}
```
```

--------------------------------

### ASE XTB Calculator Usage (Python)

Source: https://xtb-python.readthedocs.io/en/latest/ase-calculator

Demonstrates how to use the XTB calculator within the Atomic Simulation Environment (ASE) for calculating molecular properties. It requires ASE and the xtb package. The example shows initializing a molecule, assigning the XTB calculator with a specific method, and then obtaining the potential energy and forces.

```python
from ase.build import molecule
from xtb.ase.calculator import XTB
atoms = molecule('H2O')
atoms.calc = XTB(method="GFN2-xTB")
print(atoms.get_potential_energy())
print(atoms.get_forces())
```

--------------------------------

### Get Orbital Eigenvalues

Source: https://xtb-python.readthedocs.io/en/latest/_modules/xtb/interface

Retrieves the orbital energies for each basis function, given in Hartree.

```APIDOC
## GET /results/orbital_eigenvalues

### Description
Queries the singlepoint results object for the orbital energies of each basis function, provided in Hartree units.

### Method
GET

### Endpoint
/results/orbital_eigenvalues

### Parameters
None

### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **orbital_eigenvalues** (ndarray) - A numpy array containing the energy of each orbital.

#### Response Example
```json
{
  "orbital_eigenvalues": [-0.68087967, -0.56667693, -0.51373083, -0.44710101, 0.08394016, 0.24142397]
}
```
```

--------------------------------

### Create and Initialize Molecular Structure (Python)

Source: https://xtb-python.readthedocs.io/en/latest/general-api

Shows how to create a Molecule object in Python using atomic numbers and positions. It demonstrates initializing the object and checking its length. An example of an update that fails due to a nuclear fusion check is also included.

```python
from xtb.interface import Molecule
import numpy as np

numbers = np.array([8, 1, 1])
positions = np.array([
[ 0.00000000000000, 0.00000000000000,-0.73578586109551],
[ 1.44183152868459, 0.00000000000000, 0.36789293054775],
[-1.44183152868459, 0.00000000000000, 0.36789293054775]])

mol = Molecule(numbers, positions)
print(len(mol))
```

--------------------------------

### Get Orbital Occupations

Source: https://xtb-python.readthedocs.io/en/latest/_modules/xtb/interface

Retrieves the occupation numbers for each orbital.

```APIDOC
## GET /results/orbital_occupations

### Description
Queries the singlepoint results object for the occupation numbers of each orbital.

### Method
GET

### Endpoint
/results/orbital_occupations

### Parameters
None

### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **orbital_occupations** (ndarray) - A numpy array containing the occupation number for each orbital.

#### Response Example
```json
{
  "orbital_occupations": [2.0, 2.0, 2.0, 2.0, 0.0, 0.0]
}
```
```

--------------------------------

### Get Partial Charges

Source: https://xtb-python.readthedocs.io/en/latest/_modules/xtb/interface

Retrieves the partial charges for each atom from the singlepoint results object. Charges are given in units of electrons (e).

```APIDOC
## GET /results/charges

### Description
Queries the singlepoint results object for the partial charges of each atom, provided in units of electrons (e).

### Method
GET

### Endpoint
/results/charges

### Parameters
None

### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **charges** (ndarray) - A numpy array where each element represents the partial charge of an atom.

#### Response Example
```json
{
  "charges": [-0.56317913, 0.28158957, 0.28158957]
}
```
```

--------------------------------

### Get xtb Solvent Enumerator

Source: https://xtb-python.readthedocs.io/en/latest/_modules/xtb/utils

Retrieves the correct solvent enumerator for a given solvent string. It supports common solvent names and their abbreviations, performing case-insensitive matching.

```python
# This file is part of xtb.
#
# Copyright (C) 2020 Sebastian Ehlert
#
# xtb is free software: you can redistribute it and/or modify it under
# the terms of the GNU Lesser General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# xtb is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU Lesser General Public License for more details.
#
# You should have received a copy of the GNU Lesser General Public License
# along with xtb.  If not, see <https://www.gnu.org/licenses/>.
"""Helper functions to deal with xtb API objects"""

from typing import Optional
from .interface import Solvent, Param


_solvents = {
    "acetone": Solvent.acetone,
    "acetonitrile": Solvent.acetonitrile,
    "benzene": Solvent.benzene,
    "ch2cl2": Solvent.ch2cl2,
    "chcl3": Solvent.chcl3,
    "chloroform": Solvent.chcl3,
    "cs2": Solvent.cs2,
    "dmf": Solvent.dmf,
    "dmso": Solvent.dmso,
    "ether": Solvent.ether,
    "h2o": Solvent.h2o,
    "water": Solvent.h2o,
    "methanol": Solvent.methanol,
    "nhexane": Solvent.nhexane,
    "n-hexane": Solvent.nhexane,
    "thf": Solvent.thf,
    "toluene": Solvent.toluene,
}


def get_solvent(solvent: str) -> Optional[Solvent]:
    """Return the correct solvent enumerator for a string input."""

    return _solvents.get(solvent.lower())

```

--------------------------------

### Get xtb Method Parameter

Source: https://xtb-python.readthedocs.io/en/latest/_modules/xtb/utils

Retrieves the correct parameter enumerator for a given xtb method string. It handles various string formats and returns an optional Param object. Case-insensitive matching is performed.

```python
# This file is part of xtb.
#
# Copyright (C) 2020 Sebastian Ehlert
#
# xtb is free software: you can redistribute it and/or modify it under
# the terms of the GNU Lesser General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# xtb is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU Lesser General Public License for more details.
#
# You should have received a copy of the GNU Lesser General Public License
# along with xtb.  If not, see <https://www.gnu.org/licenses/>.
"""Helper functions to deal with xtb API objects"""

from typing import Optional
from .interface import Solvent, Param


_methods = {
    "gfn2-xtb": Param.GFN2xTB,
    "gfn2xtb": Param.GFN2xTB,
    "gfn1-xtb": Param.GFN1xTB,
    "gfn1xtb": Param.GFN1xTB,
    "ipea-xtb": Param.IPEAxTB,
    "ipeaxtb": Param.IPEAxTB,
    "gfn0-xtb": Param.GFN0xTB,
    "gfn0xtb": Param.GFN0xTB,
    "gfn-ff": Param.GFNFF,
    "gfnff": Param.GFNFF,
}


def get_method(method: str) -> Optional[Param]:
    """Return the correct parameter enumerator for a string input.

    Example
    -------
    >>> get_method('GFN2-xTB')
    <Param.GFN2xTB: 1>
    >>> get_method('gfn2xtb')
    <Param.GFN2xTB: 1>
    >>> get_method('GFN-xTB') is None
    True
    >>> get_method('GFN1-xTB') is None
    False
    """

    return _methods.get(method.lower())

```

--------------------------------

### Perform XTB Single-Point Calculation and Get Energy (Python)

Source: https://xtb-python.readthedocs.io/en/latest/_modules/xtb/interface

Performs a single-point energy calculation using the XTB library and retrieves the calculated energy. It initializes a Calculator object, sets verbosity, runs the calculation, and then extracts the energy value. The energy is returned in Hartrees. Raises XTBException if the calculation fails.

```python
from xtb.libxtb import VERBOSITY_MINIMAL
from xtb.interface import Calculator, Param
import numpy as np

numbers = np.array([8, 1, 1])
positions = np.array([
    [ 0.00000000000000, 0.00000000000000,-0.73578586109551],
    [ 1.44183152868459, 0.00000000000000, 0.36789293054775],
    [-1.44183152868459, 0.00000000000000, 0.36789293054775]])

calc = Calculator(Param.GFN2xTB, numbers, positions)
calc.set_verbosity(VERBOSITY_MINIMAL)
res = calc.singlepoint()  # energy printed is only the electronic part

# To get the energy value:
# res.get_energy()
# -5.070451354836705
```

--------------------------------

### Initialize and Configure Calculation Environment (Python)

Source: https://xtb-python.readthedocs.io/en/latest/general-api

Demonstrates how to initialize an Environment object, set output file, and verbosity level. It also shows how to check the environment status and display error messages if any occur. This is a foundational step for most XTB calculations.

```python
from xtb.libxtb import VERBOSITY_FULL
from xtb.interface import Environment

env = Environment()
env.set_output("error.log")
env.set_verbosity(VERBOSITY_FULL)
if env.check != 0:
    env.show("Error message")

env.release_output()
```

--------------------------------

### Initialize Calculator and Perform Singlepoint Calculation (Python)

Source: https://xtb-python.readthedocs.io/en/latest/_modules/xtb/interface

Demonstrates how to initialize a Calculator object with GFN2xTB parameters, set verbosity, and perform a singlepoint calculation. It also shows how to retrieve the calculated energy and gradient. Requires numpy and xtb.libxtb.

```python
from xtb.libxtb import VERBOSITY_MINIMAL
from xtb.interface import Calculator, Param
import numpy as np

numbers = np.array([8, 1, 1])
positions = np.array([
 [ 0.00000000000000, 0.00000000000000,-0.73578586109551],
 [ 1.44183152868459, 0.00000000000000, 0.36789293054775],
 [-1.44183152868459, 0.00000000000000, 0.36789293054775]])

calc = Calculator(Param.GFN2xTB, numbers, positions)
calc.set_verbosity(VERBOSITY_MINIMAL)
res = calc.singlepoint()
print(res.get_energy())
print(res.get_gradient())
```

--------------------------------

### Calculator Initialization and Single Point Calculation

Source: https://xtb-python.readthedocs.io/en/latest/general-api

Demonstrates how to initialize the Calculator object with parameters, numbers, and positions, and then perform a single-point energy calculation.

```APIDOC
## Calculator Class

### Description
This calculator represents a calculator object in the `xtb` API and provides access to all methods implemented with a unified interface. The API object must be loaded with a parametrisation before it can be used in any other API request.

### Method
Initialization

### Parameters
- **param** (xtb.interface.Param) - The parametrization to use for the calculator.
- **numbers** (List[int]) - A list of atomic numbers for the system.
- **positions** (List[float]) - A list of atomic coordinates for the system.
- **charge** (Optional[float]) - The total charge of the system.
- **uhf** (Optional[int]) - The number of unpaired electrons.
- **lattice** (Optional[List[float]]) - The lattice vectors for periodic calculations.
- **periodic** (Optional[List[bool]]) - A list indicating whether each dimension is periodic.

### Request Example
```python
from xtb.libxtb import VERBOSITY_MINIMAL
from xtb.interface import Calculator, Param
import numpy as np

numbers = np.array([8, 1, 1])
positions = np.array([
    [ 0.00000000000000, 0.00000000000000,-0.73578586109551],
    [ 1.44183152868459, 0.00000000000000, 0.36789293054775],
    [-1.44183152868459, 0.00000000000000, 0.36789293054775]])

calc = Calculator(Param.GFN2xTB, numbers, positions)
calc.set_verbosity(VERBOSITY_MINIMAL)
res = calc.singlepoint() 
```

### Response
#### Success Response (200)
- **xtb.interface.Results** - An object containing the results of the calculation.

#### Response Example
```python
print(res.get_energy())
# Output: -5.070451354836705

print(res.get_gradient())
# Output: [[ 6.24500451e-17 -3.47909735e-17 -5.07156941e-03]
#          [-1.24839222e-03  2.43536791e-17  2.53578470e-03]
#          [ 1.24839222e-03  1.04372944e-17  2.53578470e-03]]
```

## POST /singlepoint

### Description
Performs a single-point energy calculation for the current system configuration. The results of a previous calculation can be optionally passed to potentially speed up convergence.

### Method
POST

### Endpoint
/singlepoint

### Parameters
#### Query Parameters
- **res** (Optional[xtb.interface.Results]) - An optional previous results object to use for warm-starting the calculation.
- **copy** (bool) - If True, a copy of the previous results object is made before updating it. Defaults to False.

### Request Example
```python
# Assuming 'calc' is an initialized Calculator object
res = calc.singlepoint()
# Or using a previous result for warm-starting
new_res = calc.singlepoint(res, copy=True)
```

### Response
#### Success Response (200)
- **xtb.interface.Results** - An object containing the results of the single-point calculation.

#### Response Example
```python
# Assuming 'res' is the result from calc.singlepoint()
print(res.get_energy())
```
```

--------------------------------

### run_qcschema

Source: https://xtb-python.readthedocs.io/en/latest/qcarchive

Perform a calculation based on an atomic input model using QCSchema.

```APIDOC
## POST /run_qcschema

### Description
Performs a calculation based on an atomic input model and returns the results in a QCSchema compatible format.

### Method
POST

### Endpoint
/run_qcschema

### Parameters
#### Request Body
- **input_data** (dict or qcelemental.models.results.AtomicInput) - Required - The input data for the calculation, which can be a dictionary or an AtomicInput object.
  - **molecule** (qcelemental.models.Molecule) - Required - Represents the molecular structure and properties.
    - **symbols** (list[str]) - Required - List of chemical symbols for each atom.
    - **geometry** (list[float]) - Required - List of atomic coordinates.
  - **driver** (str) - Required - The type of calculation to perform (e.g., "energy", "gradient").
  - **model** (dict) - Required - Specifies the computational model.
    - **method** (str) - Required - The calculation method (e.g., "GFN2-xTB").
  - **keywords** (dict) - Optional - Keywords to control the calculation parameters.
    - **accuracy** (float) - Optional - Numerical accuracy of the calculation. Defaults to 1.0.
    - **electronic_temperature** (float) - Optional - Electronic temperature for TB methods. Defaults to 300.0.
    - **max_iterations** (int) - Optional - Maximum iterations for self-consistent evaluation. Defaults to 250.
    - **solvent** (str) - Optional - GBSA implicit solvent model. Defaults to "none".

### Request Example
```json
{
  "input_data": {
    "molecule": {
      "symbols": ["O", "H", "H"],
      "geometry": [
        0.00000000000000,  0.00000000000000, -0.73578586109551,
        1.44183152868459,  0.00000000000000,  0.36789293054775,
       -1.44183152868459,  0.00000000000000,  0.36789293054775
    ]
    },
    "driver": "energy",
    "model": {
      "method": "GFN2-xTB"
    },
    "keywords": {
      "accuracy": 1.0,
      "max_iterations": 50
    }
  }
}
```

### Response
#### Success Response (200)
- **return_result** (float) - The result of the calculation.

#### Response Example
```json
{
  "return_result": -5.070451354848316
}
```
```

--------------------------------

### Calculator Initialization and Singlepoint Calculation

Source: https://xtb-python.readthedocs.io/en/latest/_modules/xtb/interface

This section details the initialization of the Calculator object with specific parameters and demonstrates how to perform a singlepoint calculation.

```APIDOC
## POST /calculator

### Description
Initializes a calculator object with a specified parametrisation, atomic numbers, and positions, then performs a singlepoint calculation.

### Method
POST

### Endpoint
/calculator

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **param** (Param) - Required - The parametrisation to use (e.g., GFN2xTB, GFN1xTB).
- **numbers** (List[int]) - Required - A list of atomic numbers for the molecule.
- **positions** (List[float]) - Required - A list of Cartesian coordinates for the atoms.
- **charge** (Optional[float]) - Optional - The total charge of the molecule.
- **uhf** (Optional[int]) - Optional - The number of unpaired electrons.
- **lattice** (Optional[List[float]]) - Optional - The lattice vectors for periodic calculations.
- **periodic** (Optional[List[bool]]) - Optional - Flags indicating periodic boundary conditions.

### Request Example
```json
{
  "param": "GFN2xTB",
  "numbers": [8, 1, 1],
  "positions": [
    0.00000000000000, 0.00000000000000, -0.73578586109551,
    1.44183152868459, 0.00000000000000, 0.36789293054775,
    -1.44183152868459, 0.00000000000000, 0.36789293054775
  ],
  "charge": 0,
  "uhf": 0
}
```

### Response
#### Success Response (200)
- **energy** (float) - The calculated electronic energy.
- **gradient** (List[List[float]]) - The calculated forces on the atoms.

#### Response Example
```json
{
  "energy": -5.070451354836705,
  "gradient": [
    [ 6.24500451e-17, -3.47909735e-17, -5.07156941e-03],
    [-1.24839222e-03,  2.43536791e-17,  2.53578470e-03],
    [ 1.24839222e-03,  1.04372944e-17,  2.53578470e-03]
  ]
}
```

### Errors
- **XTBException**: If errors are encountered during parametrisation loading or calculation.
```

--------------------------------

### Get Virial Tensor

Source: https://xtb-python.readthedocs.io/en/latest/_modules/xtb/interface

Retrieves the virial tensor from the singlepoint results object. The virial is given in Hartree.

```APIDOC
## GET /results/virial

### Description
Queries the singlepoint results object for the virial tensor, provided in Hartree units.

### Method
GET

### Endpoint
/results/virial

### Parameters
None

### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **virial** (ndarray) - A 3x3 numpy array representing the virial tensor.

#### Response Example
```json
{
  "virial": [
    [1.43012837e-02, 3.43893209e-17, -1.86809511e-16],
    [0.00000000e+00, 0.00000000e+00, 0.00000000e+00],
    [1.02348685e-16, 1.46994821e-17, 3.82414977e-02]
  ]
}
```
```

--------------------------------

### Run QCSchema Calculation with xtb

Source: https://xtb-python.readthedocs.io/en/latest/_modules/xtb/qcschema/harness

Performs a single-point energy calculation using the xtb package based on a QCSchema AtomicInput object. It handles input parsing, method and keyword validation, and calculation execution, returning results in a QCSchema AtomicResult format. Dependencies include qcelemental and xtb's internal modules.

```python
from typing import Union
from tempfile import NamedTemporaryFile
from ..libxtb import VERBOSITY_MUTED, get_api_version
from ..interface import Calculator, XTBException
from ..utils import get_method, get_solvent
import qcelemental as qcel


_keywords = [
    "accuracy",
    "electronic_temperature",
    "max_iterations",
    "solvent",
    "verbosity"
]



def run_qcschema(
    input_data: Union[dict, qcel.models.AtomicInput]
) -> qcel.models.AtomicResult:
    """Perform a calculation based on an atomic input model.

    Example
    -------
    >>> from xtb.qcschema.harness import run_qcschema
    >>> import qcelemental as qcel
    >>> atomic_input = qcel.models.AtomicInput(
    ...     molecule = qcel.models.Molecule(
    ...         symbols = ["O", "H", "H"],
    ...         geometry = [
    ...             0.00000000000000,  0.00000000000000, -0.73578586109551,
    ...             1.44183152868459,  0.00000000000000,  0.36789293054775,
    ...            -1.44183152868459,  0.00000000000000,  0.36789293054775
    ...         ],
    ...     ),
    ...     driver = "energy",
    ...     model = {
    ...         "method": "GFN2-xTB",
    ...     },
    ...     keywords = {
    ...         "accuracy": 1.0,
    ...         "max_iterations": 50,
    ...     },
    ... )
    ... 
    >>> atomic_result = run_qcschema(atomic_input)
    >>> atomic_result.return_result
    -5.070451354848316
    """

    if not isinstance(input_data, qcel.models.AtomicInput):
        atomic_input = qcel.models.AtomicInput(**input_data)
    else:
        atomic_input = input_data
    ret_data = atomic_input.dict()

    provenance = {
        "creator": "xtb",
        "version": get_api_version(),
        "routine": "xtb.qcschema.run_qcschema",
    }

    _method = get_method(atomic_input.model.method)
    if _method is None:
        ret_data.update(
            success=False,
            return_result=0.0,
            provenance=provenance,
            properties={},
            error=qcel.models.ComputeError(
                error_type="input_error",
                error_message="Invalid method {} provided in model".format(
                    atomic_input.model.method
                ),
            ),
        )

        return qcel.models.AtomicResult(**ret_data)

    verbosity = atomic_input.keywords.get("verbosity", "full")
    fd = None
    output = None
    success = True
    try:
        calc = Calculator(
            _method,
            atomic_input.molecule.atomic_numbers,
            atomic_input.molecule.geometry,
            atomic_input.molecule.molecular_charge,
            atomic_input.molecule.molecular_multiplicity - 1,
        )

        if "solvent" in atomic_input.keywords:
            calc.set_solvent(get_solvent(atomic_input.keywords["solvent"]))

        if "accuracy" in atomic_input.keywords:
            calc.set_accuracy(atomic_input.keywords["accuracy"])

        if "max_iterations" in atomic_input.keywords:
            calc.set_max_iterations(atomic_input.keywords["max_iterations"])

        if "electronic_temperature" in atomic_input.keywords:
            calc.set_electronic_temperature(
                atomic_input.keywords["electronic_temperature"]
            )

        # Work out how verbose the printing from xtb should be
        verbosity = calc.set_verbosity(verbosity)
        if verbosity > VERBOSITY_MUTED:
            fd = NamedTemporaryFile()
            calc.set_output(fd.name)

        # Perform actual calculation
        res = calc.singlepoint()

        calc.release_output()

        # Check if the calculation has generated a wavefunction
        _wfn = res.get_number_of_orbitals() > 0

        # First we access properties that should be always available
        properties = {
            "return_energy": res.get_energy(),
            "scf_dipole_moment": res.get_dipole(),
        }

```

--------------------------------

### Run QCSchema Calculation with Atomic Input

Source: https://xtb-python.readthedocs.io/en/latest/qcarchive

Performs a quantum chemistry calculation using QCSchema or QCElemental Atomic Input. It translates the input into a format understandable by the `xtb` API and returns the results in a QCSchema compatible format. Dependencies include `qcelemental` and `xtb`. The input can be a dictionary or a `qcelemental.models.results.AtomicInput` object, and the output is a `qcelemental.models.results.AtomicResult` object.

```python
from xtb.qcschema.harness import run_qcschema
import qcelemental as qcel

atomic_input = qcel.models.AtomicInput(
    molecule = qcel.models.Molecule(
        symbols = ["O", "H", "H"],
        geometry = [
            0.00000000000000,  0.00000000000000, -0.73578586109551,
            1.44183152868459,  0.00000000000000,  0.36789293054775,
           -1.44183152868459,  0.00000000000000,  0.36789293054775
        ],
    ),
    driver = "energy",
    model = {
        "method": "GFN2-xTB",
    },
    keywords = {
        "accuracy": 1.0,
        "max_iterations": 50,
    },
)

atomic_result = run_qcschema(atomic_input)
print(atomic_result.return_result)

```

--------------------------------

### Get Dipole Moment

Source: https://xtb-python.readthedocs.io/en/latest/_modules/xtb/interface

Retrieves the dipole moment vector from the singlepoint results object. The dipole is given in electron Bohr (e·Bohr).

```APIDOC
## GET /results/dipole

### Description
Queries the singlepoint results object for the dipole moment vector, provided in units of electron Bohr (e·Bohr).

### Method
GET

### Endpoint
/results/dipole

### Parameters
None

### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **dipole** (ndarray) - A 3-element numpy array representing the dipole moment vector.

#### Response Example
```json
{
  "dipole": [-4.44089210e-16, 1.44419023e-16, 8.89047667e-01]
}
```
```

--------------------------------

### Perform Singlepoint Calculation with xtb.interface.Calculator

Source: https://xtb-python.readthedocs.io/en/latest/general-api

Demonstrates how to initialize a Calculator object, set parameters, perform a singlepoint calculation, and retrieve the energy and gradient. This method requires the 'xtb.interface.Param' for parametrisation and 'numpy' for numerical arrays.

```python
from xtb.libxtb import VERBOSITY_MINIMAL
from xtb.interface import Calculator, Param
import numpy as np

numbers = np.array([8, 1, 1])
positions = np.array([
 [ 0.00000000000000, 0.00000000000000,-0.73578586109551],
 [ 1.44183152868459, 0.00000000000000, 0.36789293054775],
 [-1.44183152868459, 0.00000000000000, 0.36789293054775]])

calc = Calculator(Param.GFN2xTB, numbers, positions)
calc.set_verbosity(VERBOSITY_MINIMAL)
res = calc.singlepoint()  # energy printed is only the electronic part
print(res.get_energy())
print(res.get_gradient())

```

--------------------------------

### Get Orbital Eigenvalues from Calculation Results (Python)

Source: https://xtb-python.readthedocs.io/en/latest/general-api

Retrieves the orbital energies (eigenvalues) in Hartrees. These values correspond to the energy levels of the electrons in the molecule.

```python
res.get_orbital_eigenvalues()
# Expected output: array([-0.68087967, -0.56667693, -0.51373083, -0.44710101,  0.08394016,
#         0.24142397])
```

--------------------------------

### Get Energy from Calculation Results (Python)

Source: https://xtb-python.readthedocs.io/en/latest/general-api

Fetches the total electronic energy of the system in Hartrees from the calculation results. This is a fundamental output of any quantum chemistry calculation.

```python
res.get_energy()
# Expected output: -5.070451354836705
```

--------------------------------

### Get Dipole Moment from Calculation Results (Python)

Source: https://xtb-python.readthedocs.io/en/latest/general-api

Retrieves the calculated dipole moment of the molecule in units of electron-Bohr. This property is important for understanding the polarity of the molecule.

```python
res.get_dipole()
# Expected output: [-4.44089210e-16  1.44419023e-16  8.89047667e-01]
```

--------------------------------

### Set Solvent Model for Calculator (Python)

Source: https://xtb-python.readthedocs.io/en/latest/_modules/xtb/interface

Shows how to set a solvation model for the calculator using predefined solvents or by searching for a solvent string. It also demonstrates how to remove the solvent model. Requires xtb.utils.

```python
from xtb.utils import get_solvent, Solvent

# Assuming 'calc' is an initialized Calculator object
calc.set_solvent(Solvent.h2o)  # Set solvent to water with enumerator
calc.set_solvent()  # Release solvent again
calc.set_solvent(get_solvent("CHCl3"))  # Find correct enumerator
```

--------------------------------

### Create xtb Calculation Environment

Source: https://xtb-python.readthedocs.io/en/latest/_modules/xtb/interface

Initializes a new calculation environment for xtb. This environment object wraps the C-API's TEnvironment, managing IO configuration and error logs. It's a prerequisite for all subsequent API calls.

```python
class Environment:
    """
    .. Calculation environment

    Wraps an API object representing a TEnvironment class in ``xtb``.
    The API object is constructed automatically and deconstructed on garbage
    collection, it stores the IO configuration and the error log of the API.

    All API calls require an environment object, usually this is done
    automatically as all other classes inherent from the calculation
    environment.

    Example
    -------
    >>> from xtb.libxtb import VERBOSITY_FULL
    >>> from xtb.interface import Environment
    >>> env = Environment()
    >>> env.set_output("error.log")
    >>> env.set_verbosity(VERBOSITY_FULL)
    >>> if env.check != 0:
    ...     env.show("Error message")
    ...
    >>> env.release_output()
    """

    _env = _ffi.NULL

    def __init__(self):
        """Create new xtb calculation environment object"""
        self._env = new_environment()


    def check(self) -> int:
        """Check current status of calculation environment

        Example
        -------
        """

```

--------------------------------

### Get Orbital Coefficients from Calculation Results (Python)

Source: https://xtb-python.readthedocs.io/en/latest/general-api

Retrieves the coefficients of the molecular orbitals. These coefficients define the linear combination of atomic orbitals that form the molecular orbitals.

```python
res.get_orbital_coefficients()
# Expected output: array([[-7.94626768e-01,  6.38378239e-16,  4.52990407e-01,
        -6.38746369e-16, -8.35495085e-01, -4.44089210e-16],
       [ 2.77555756e-17, -6.97332245e-01,  7.49400542e-16,
         1.88136491e-17,  7.21644966e-16, -9.60006511e-01],
       [ 2.17336312e-16, -1.08051945e-16, -1.11598977e-15,
        -1.00000000e+00,  5.74153329e-17,  3.30330107e-17],
       [-8.67578876e-02, -9.71445147e-16, -8.05763104e-01,
         7.71702239e-16, -7.18690020e-01, -4.71844785e-16],
       [-1.84540457e-01, -3.54572323e-01, -2.39090946e-01,
         2.87533552e-16,  7.68757806e-01,  9.02845514e-01],
       [-1.84540457e-01,  3.54572323e-01, -2.39090946e-01,
         2.01021058e-16,  7.68757806e-01, -9.02845514e-01]])
```

--------------------------------

### Calculation Settings API

Source: https://xtb-python.readthedocs.io/en/latest/_modules/xtb/interface

APIs for configuring numerical accuracy, maximum iterations, and electronic temperature for XTB calculations.

```APIDOC
## PUT /accuracy

### Description
Sets the numerical accuracy for the calculation. The accuracy value should range from 1000 to 0.0001. Values outside this range will be clipped, and a warning will be logged.

### Method
PUT

### Endpoint
/accuracy

### Parameters
#### Query Parameters
- **accuracy** (float) - Required - The desired numerical accuracy (e.g., 1.0).

### Response
#### Success Response (200)
- **status** (string) - Indicates success.

#### Response Example
```json
{
  "status": "Accuracy set successfully"
}
```

## PUT /max_iterations

### Description
Sets the maximum number of iterations for self-consistent charge methods. Values less than one are ignored. Convergence failure within the specified iterations is not always reported as an error.

### Method
PUT

### Endpoint
/max_iterations

### Parameters
#### Query Parameters
- **maxiter** (int) - Required - The maximum number of iterations (e.g., 100).

### Response
#### Success Response (200)
- **status** (string) - Indicates success.

#### Response Example
```json
{
  "status": "Maximum iterations set successfully"
}
```

## PUT /electronic_temperature

### Description
Sets the electronic temperature in Kelvin for tight-binding Hamiltonians. Values less than or equal to zero are ignored.

### Method
PUT

### Endpoint
/electronic_temperature

### Parameters
#### Query Parameters
- **etemp** (int) - Required - The electronic temperature in Kelvin (e.g., 300).

### Response
#### Success Response (200)
- **status** (string) - Indicates success.

#### Response Example
```json
{
  "status": "Electronic temperature set successfully"
}
```
```

--------------------------------

### Get Number of Orbitals from Calculation Results (Python)

Source: https://xtb-python.readthedocs.io/en/latest/general-api

Returns the total number of basis functions (orbitals) used in the calculation. This is a basic structural property of the electronic configuration.

```python
res.get_number_of_orbitals()
# Expected output: 6
```

--------------------------------

### Get Gradient from Calculation Results (Python)

Source: https://xtb-python.readthedocs.io/en/latest/general-api

Retrieves the gradient of the energy with respect to atomic positions, in units of Hartree/Bohr. This is crucial for geometry optimization and understanding forces on atoms.

```python
res.get_gradient()
# Expected output: [[ 6.24500451e-17 -3.47909735e-17 -5.07156941e-03]
#  [-1.24839222e-03  2.43536791e-17  2.53578470e-03]
#  [ 1.24839222e-03  1.04372944e-17  2.53578470e-03]]
```

--------------------------------

### Get Orbital Occupations using Python

Source: https://xtb-python.readthedocs.io/en/latest/general-api

Retrieves the occupation numbers from a singlepoint results object. This function returns a numpy array containing the occupation numbers for each orbital. It is part of the xtb-python library.

```python
>>> res.get_orbital_occupations()
array([2., 2., 2., 2., 0., 0.])
```

--------------------------------

### Get Bond Orders from Calculation Results (Python)

Source: https://xtb-python.readthedocs.io/en/latest/general-api

Retrieves the bond order matrix from a single-point calculation's results object. This method is useful for analyzing the bonding in the molecule after a calculation has been performed.

```python
res.get_bond_orders()
# Expected output: [[0.00000000e+00 9.20433501e-01 9.20433501e-01]
#  [9.20433501e-01 0.00000000e+00 2.74039053e-04]
#  [9.20433501e-01 2.74039053e-04 0.00000000e+00]]
```

--------------------------------

### Initialize XTB Results Object (Python)

Source: https://xtb-python.readthedocs.io/en/latest/_modules/xtb/interface

Initializes a new XTB `Results` object. The constructor can either create a new, empty results object or copy an existing one. It ensures that the new results object is connected to its own independent environment. The number of atoms is also stored.

```python
def __init__(self, res: Union[Molecule, "Results"]):
    Environment.__init__(self)
    if isinstance(res, Results):
        self._res = copy_results(res._res)
    else:
        self._res = new_results()
    self._natoms = len(res)

def __len__(self):
    return self._natoms
```
Tokens:
Raw