Levels of Theory

A level of theory specifies which computational method, basis set, and solvation model to use for a calculation.

Predefined Levels

The easiest way to get started is with a predefined constant:

from atomiverse.levels import (
    AIMNET2,
    AIMNET2_NSE,
    AIMNET2_PD,
    B97_3C,
    GFN2_XTB,
    GFN_FF,
    GXTB,
    R2SCAN_3C,
    WB97M_V_DEF2_QZVPD,
    WB97M_V_DEF2_SVP,
    WB97M_V_DEF2_TZVPPD,
    WB97X_3C,
    # r²SCAN SMD-solvated (faster alternative to wB97M-V for gsolv):
    R2SCAN_DEF2_SVP_SMD_WATER,
    R2SCAN_DEF2_TZVPPD_SMD_WATER,
    R2SCAN_DEF2_QZVPD_SMD_WATER,
)

GFN2_XTB, GFN_FF, and GXTB are standalone xTB-family methods with no basis set. The AIMNet presets are standalone machine-learned potentials with no basis set. B97_3C, R2SCAN_3C, and WB97X_3C are basisless composite methods. All are available in gas phase and with CPCM implicit solvation for a fixed set of solvent names. WB97M_V_DEF2_SVP, WB97M_V_DEF2_TZVPPD, and WB97M_V_DEF2_QZVPD use the wb97m-v/def2-SVP, wb97m-v/def2-TZVPPD, and wb97m-v/def2-QZVPD combinations and also support the same CPCM solvent list.

Constant	Solvation
AIMNET2	ALPB with the supported solvent list below
AIMNET2_NSE	ALPB with the supported solvent list below
AIMNET2_PD	—
B97_3C	CPCM with the supported solvent list below
GFN2_XTB	—
GFN_FF	—
GXTB	ALPB with the supported solvent list below
R2SCAN_3C	CPCM with the supported solvent list below
R2SCAN_DEF2_SVP	SMD with the supported solvent list below
R2SCAN_DEF2_TZVPPD	SMD with the supported solvent list below
R2SCAN_DEF2_QZVPD	SMD with the supported solvent list below
WB97M_V_DEF2_QZVPD	CPCM with the supported solvent list below
WB97M_V_DEF2_SVP	CPCM with the supported solvent list below
WB97M_V_DEF2_TZVPPD	CPCM with the supported solvent list below
WB97X_3C	CPCM with the supported solvent list below

AIMNet Variants

Atomiverse currently exposes these published AIMNet models:

Constant	Method	Notes
AIMNET2	aimnet2	Default AIMNet2 model
AIMNET2_NSE	aimnet2-nse	Open-shell / radical variant
AIMNET2_PD	aimnet2-pd	Palladium-specialized variant; gas phase only

AIMNET2 and AIMNET2_NSE are available in gas phase and with ALPB implicit solvation using the supported solvent list below.

Building a Custom Level

Use LevelOfTheory directly when you need a combination not covered above:

from atomiverse import LevelOfTheory

lot = LevelOfTheory(
    method="gfn2-xtb",
)

For AIMNet, pass the method name directly:

from atomiverse import LevelOfTheory

lot = LevelOfTheory(method="aimnet2")

For basisless composite methods such as b97-3c, r2scan-3c, and wb97x-3c, omit the basis set:

from atomiverse import LevelOfTheory

lot = LevelOfTheory(method="r2scan-3c")

lot = LevelOfTheory(method="b97-3c")

from atomiverse.levels import B97_3C

lot = LevelOfTheory(method="wb97x-3c")

Or use the predefined constant:

from atomiverse.levels import B97_3C, R2SCAN_3C, WB97X_3C

For wb97m-v/def2-QZVPD, include the basis set explicitly:

from atomiverse import LevelOfTheory

lot = LevelOfTheory(
    method="wb97m-v",
    basis_set="def2-QZVPD",
)

Or use the predefined constant:

from atomiverse.levels import WB97M_V_DEF2_QZVPD

For wb97m-v/def2-SVP, include the basis set explicitly:

from atomiverse import LevelOfTheory

lot = LevelOfTheory(
    method="wb97m-v",
    basis_set="def2-SVP",
)

Or use the predefined constant:

from atomiverse.levels import WB97M_V_DEF2_SVP

For wb97m-v/def2-TZVPPD, include the basis set explicitly:

from atomiverse import LevelOfTheory

lot = LevelOfTheory(
    method="wb97m-v",
    basis_set="def2-TZVPPD",
)

Or use the predefined constant:

from atomiverse.levels import WB97M_V_DEF2_TZVPPD

These levels also support CPCM:

from atomiverse import LevelOfTheory, ImplicitSolvation, SolvationMethod

lot = LevelOfTheory(
    method="wb97m-v",
    basis_set="def2-TZVPPD",
    solvation=ImplicitSolvation(
        method=SolvationMethod.CPCM,
        solvent="Water",
    ),
)

Adding Solvation

Implicit solvation models the effect of a surrounding solvent without explicit solvent molecules:

from atomiverse import LevelOfTheory, ImplicitSolvation, SolvationMethod

lot = LevelOfTheory(
    method="pbe",
    basis_set="def2-tzvp",
    solvation=ImplicitSolvation(
        method=SolvationMethod.CPCM,
        solvent="water",
    ),
)

Method	Description
SolvationMethod.CPCM	Conductor-like PCM. Widely available and a solid default.
SolvationMethod.ALPB	Fast, native to xTB.
SolvationMethod.SMD	Solvation Model based on Density. Used with wB97M-V and r²SCAN DFT functionals for accurate solvation free energies.

For the xTB-family methods currently exposed by Atomiverse, implicit solvation is available through ALPB for gfn2-xtb, gfn-ff, and gxtb. For the composite and DFT levels currently exposed by Atomiverse, implicit solvation is available through CPCM for b97-3c, r2scan-3c, wb97x-3c, and wb97m-v/def2-QZVPD, wb97m-v/def2-SVP, and wb97m-v/def2-TZVPPD. For AIMNet, ALPB is available for aimnet2 and aimnet2-nse.

SMD solvation (Solvation Model based on Density) is available for wb97m-v and r2scan with def2-SVP, def2-TZVPPD, and def2-QZVPD basis sets. r²SCAN is a pure meta-GGA functional that is significantly faster than wB97M-V (range-separated hybrid) while still providing good accuracy for solvation free energies. Use r²SCAN for rapid screening and wB97M-V for production-quality results.

Supported CPCM solvent names for b97-3c, r2scan-3c, wb97x-3c, and wb97m-v/def2-QZVPD, wb97m-v/def2-SVP, and wb97m-v/def2-TZVPPD are: Water, Dimethylsulfoxide, Nitromethane, Acetonitrile, Methanol, Ethanol, Acetone, 1,2-Dichloroethane, Methylenechloride, Tetrahydrofurane, Aniline, Chlorobenzene, Chloroform, Toluene, 1,4-Dioxane, Benzene, Carbon Tetrachloride, Cyclohexane, and N-heptane.

Supported SMD solvent names for r2scan and wb97m-v (with def2-SVP, def2-TZVPPD, or def2-QZVPD) are the same as above: Water, Dimethylsulfoxide, Nitromethane, Acetonitrile, Methanol, Ethanol, Acetone, 1,2-Dichloroethane, Methylenechloride, Tetrahydrofurane, Aniline, Chlorobenzene, Chloroform, Toluene, 1,4-Dioxane, Benzene, Carbon Tetrachloride, Cyclohexane, and N-heptane.

Example SMD-solvated levels:

from atomiverse import LevelOfTheory, ImplicitSolvation, SolvationMethod

# r²SCAN (fast pure meta-GGA) with SMD solvation
lot = LevelOfTheory(
    method="r2scan",
    basis_set="def2-SVP",
    solvation=ImplicitSolvation(
        method=SolvationMethod.SMD,
        solvent="Water",
    ),
)

# Or use predefined constants:
from atomiverse.levels import (
    R2SCAN_DEF2_SVP_SMD_WATER,
    WB97M_V_DEF2_TZVPPD_SMD_ACETONITRILE,
)

Supported ALPB solvent names are: acetone, acetonitrile, aniline, benzaldehyde, benzene, ch2cl2, chcl3, cs2, dioxane, dmf, dmso, ethanol, ether, ethylacetate, furane, hexadecane, hexane, methanol, nitromethane, octanol, octanol-wet, phenol, thf, toluene, and water.

from atomiverse import LevelOfTheory, ImplicitSolvation, SolvationMethod

lot = LevelOfTheory(
    method="gfn-ff",
    solvation=ImplicitSolvation(
        method=SolvationMethod.ALPB,
        solvent="water",
    ),
)

Checking Availability

Not every combination is supported. Use validate_lot to check before submitting:

from atomiverse import validate_lot

error = validate_lot(lot)
if error:
    print(f"Not supported: {error}")

validate_lot returns an empty string when the level is valid, or an error message when it is not.

You can also list all supported levels programmatically:

from atomiverse import supported_lots

for lot in supported_lots():
    print(lot)