Settings

Configure calculations and select method defaults.

Settings `pydantic-model`

Bases: Base

Settings for (base) computational chemistry calculations.

Attributes:

Name	Type	Description
`mode`	`Mode`	calculation mode (affects thresholds for optimizations, etc.)
`tasks`	`UniqueList[Task]`	tasks to perform (deprecated, specify in workflows or calculations instead)
`method`	`Method`	computational method
`basis_set`	`BasisSet \| None`	basis set to use (autopopulated for 3c methods)
`engine`	`Engine`	computational engine to use (auto-selected if None)
`corrections`	`UniqueList[Correction]`	list of corrections to apply (e.g. D3BJ, D4)
`solvent_settings`	`SolventSettings \| None`	solvent model settings (if any)
`omega`	`OmegaTuning \| PositiveFloat \| None`	range-separation parameter or tuning method (parameter in Bohr⁻¹)
`excited_state_settings`	`ExcitedStateSettingsUnion \| None`	settings for excited-state calculations (if any)
`pbc_dft_settings`	`PBCDFTSettings \| None`	settings specific to DFT calculations on periodic systems
`scf_settings`	`SCFSettings`	SCF settings
`opt_settings`	`OptimizationSettings`	geometry optimization settings
`thermochem_settings`	`ThermochemistrySettings`	thermochemistry settings
`compute_settings`	`ComputeSettings`	hardware settings

Show JSON schema:

{
  "$defs": {
    "BasisSet": {
      "description": "Atomic orbital basis set.\n\nAttributes:\n    name: basis set name (e.g., def2-SVP, cc-pVDZ)\n    overrides: element or atom-specific basis set overrides\n    cutoff_threshold: basis function screening threshold",
      "properties": {
        "name": {
          "title": "Name",
          "type": "string"
        },
        "overrides": {
          "anyOf": [
            {
              "items": {
                "$ref": "#/$defs/BasisSetOverride"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": [],
          "title": "Overrides"
        },
        "cutoff_threshold": {
          "default": 1e-10,
          "exclusiveMinimum": 0,
          "title": "Cutoff Threshold",
          "type": "number"
        }
      },
      "required": [
        "name"
      ],
      "title": "BasisSet",
      "type": "object"
    },
    "BasisSetOverride": {
      "description": "Basis set override for specific atoms or elements.\n\nAttributes:\n    name: basis set name for override\n    atomic_numbers: atomic numbers to override (mutually exclusive with atoms)\n    atoms: 1-indexed atom indices to override (mutually exclusive with atomic_numbers)",
      "properties": {
        "name": {
          "title": "Name",
          "type": "string"
        },
        "atomic_numbers": {
          "anyOf": [
            {
              "items": {
                "exclusiveMinimum": 0,
                "type": "integer"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Atomic Numbers"
        },
        "atoms": {
          "anyOf": [
            {
              "items": {
                "exclusiveMinimum": 0,
                "type": "integer"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Atoms"
        }
      },
      "required": [
        "name"
      ],
      "title": "BasisSetOverride",
      "type": "object"
    },
    "ComputeSettings": {
      "description": "Hardware compute settings.\n\nAttributes:\n    requested_compute_type: requested hardware type\n    compute_type_used: actual hardware type used (set after execution)",
      "properties": {
        "requested_compute_type": {
          "$ref": "#/$defs/ComputeType",
          "default": "cpu"
        },
        "compute_type_used": {
          "anyOf": [
            {
              "$ref": "#/$defs/ComputeType"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        }
      },
      "title": "ComputeSettings",
      "type": "object"
    },
    "ComputeType": {
      "description": "Hardware compute type.",
      "enum": [
        "cpu",
        "gpu",
        "auto"
      ],
      "title": "ComputeType",
      "type": "string"
    },
    "Constraint": {
      "description": "Represents a single (absolute) constraint.\n\nAttributes:\n    constraint_type: which type\n    atoms: atoms in question (1-indexed)\n    value: value to constrain to; leaving blank sets current value",
      "properties": {
        "constraint_type": {
          "$ref": "#/$defs/ConstraintType"
        },
        "atoms": {
          "items": {
            "exclusiveMinimum": 0,
            "type": "integer"
          },
          "title": "Atoms",
          "type": "array"
        },
        "value": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Value"
        }
      },
      "required": [
        "constraint_type",
        "atoms"
      ],
      "title": "Constraint",
      "type": "object"
    },
    "ConstraintType": {
      "description": "Different sorts of constraints.",
      "enum": [
        "bond",
        "angle",
        "dihedral",
        "freeze_atoms"
      ],
      "title": "ConstraintType",
      "type": "string"
    },
    "Correction": {
      "description": "Various post hoc corrections.",
      "enum": [
        "d3bj",
        "d3",
        "d4",
        "gcp"
      ],
      "title": "Correction",
      "type": "string"
    },
    "Engine": {
      "description": "Computational chemistry engine.",
      "enum": [
        "aimnet2",
        "egret",
        "gpu4pyscf",
        "mace",
        "mopac",
        "openff",
        "omol25",
        "orb",
        "psi4",
        "pyscf",
        "quantum_espresso",
        "tblite",
        "terachem",
        "xtb"
      ],
      "title": "Engine",
      "type": "string"
    },
    "Method": {
      "description": "Computational chemistry method.",
      "enum": [
        "hf",
        "hf_3c",
        "pbe",
        "bp86",
        "b97_3c",
        "b97_d3bj",
        "r2scan",
        "r2scan_3c",
        "tpss",
        "m06l",
        "pbe0",
        "b3lyp",
        "tpssh",
        "m06",
        "m062x",
        "camb3lyp",
        "wb97x_d3",
        "wb97x_v",
        "wb97x_3c",
        "wb97m_v",
        "wb97m_d3bj",
        "dsd_blyp_d3bj",
        "skala",
        "aimnet2_wb97md3",
        "mace_mp_0",
        "mace_mp_0b2_l",
        "omol25_conserving_s",
        "uma_s_omol",
        "uma_s_1_2_omol",
        "uma_m_omol",
        "uma_s_omat",
        "uma_s_1_2_omat",
        "uma_m_omat",
        "uma_s_omc",
        "uma_s_1_2_omc",
        "uma_m_omc",
        "orb_v3_conservative_inf_omat",
        "orb_v3_conservative_omol",
        "egret_1",
        "egret_1e",
        "egret_1t",
        "gfn_ff",
        "gfn0_xtb",
        "gfn1_xtb",
        "gfn2_xtb",
        "g_xtb",
        "pm6",
        "pm6_d3h4x",
        "pm6_org",
        "pm7",
        "off_sage_2_0_0",
        "off_sage_2_2_1",
        "off_sage_2_3_0",
        "mango_1_0_0",
        "smirnoff_2_0_0_amber_am1bcc",
        "smirnoff_2_2_1_amber_am1bcc"
      ],
      "title": "Method",
      "type": "string"
    },
    "Mode": {
      "description": "Calculation accuracy mode.",
      "enum": [
        "auto",
        "reckless",
        "rapid",
        "careful",
        "meticulous",
        "debug",
        "manual"
      ],
      "title": "Mode",
      "type": "string"
    },
    "OmegaTuning": {
      "description": "Select a strategy for tuning the range-separation parameter omega.",
      "enum": [
        "koopmans",
        "generalized_koopmans",
        "half"
      ],
      "title": "OmegaTuning",
      "type": "string"
    },
    "OptimizationSettings": {
      "description": "Geometry optimization settings.\n\nAttributes:\n    max_steps: maximum number of optimization steps\n    transition_state: perform transition state optimization\n    recalc_hess_every: recalculate Hessian every n steps (0 = never)\n    max_gradient_threshold: convergence threshold for max gradient, in Hartree/\u00c5\n    rms_gradient_threshold: convergence threshold for RMS gradient, in Hartree/\u00c5\n    max_displacement_threshold: convergence threshold for step displacement, in \u00c5\n    rms_displacement_threshold: convergence threshold for step displacement, in \u00c5\n    energy_threshold: convergence threshold for energy change, in Hartree\n    optimize_cell: optimize unit cell (periodic systems only)\n    constraints: geometric constraints to apply\n    save_intermediate_steps: save intermediate geometries",
      "properties": {
        "max_steps": {
          "default": 250,
          "exclusiveMinimum": 0,
          "title": "Max Steps",
          "type": "integer"
        },
        "transition_state": {
          "default": false,
          "title": "Transition State",
          "type": "boolean"
        },
        "recalc_hess_every": {
          "default": 0,
          "title": "Recalc Hess Every",
          "type": "integer"
        },
        "max_gradient_threshold": {
          "default": 0.0005,
          "exclusiveMinimum": 0,
          "title": "Max Gradient Threshold",
          "type": "number"
        },
        "rms_gradient_threshold": {
          "default": 0.0003,
          "exclusiveMinimum": 0,
          "title": "Rms Gradient Threshold",
          "type": "number"
        },
        "max_displacement_threshold": {
          "default": 0.002,
          "exclusiveMinimum": 0,
          "title": "Max Displacement Threshold",
          "type": "number"
        },
        "rms_displacement_threshold": {
          "default": 0.001,
          "exclusiveMinimum": 0,
          "title": "Rms Displacement Threshold",
          "type": "number"
        },
        "energy_threshold": {
          "default": 1e-06,
          "exclusiveMinimum": 0,
          "title": "Energy Threshold",
          "type": "number"
        },
        "optimize_cell": {
          "default": false,
          "title": "Optimize Cell",
          "type": "boolean"
        },
        "constraints": {
          "default": [],
          "items": {
            "$ref": "#/$defs/Constraint"
          },
          "title": "Constraints",
          "type": "array"
        },
        "save_intermediate_steps": {
          "default": true,
          "title": "Save Intermediate Steps",
          "type": "boolean"
        }
      },
      "title": "OptimizationSettings",
      "type": "object"
    },
    "PBCDFTSettings": {
      "description": "PBC DFT settings.\n\nAttributes:\n    plane_wave_cutoff: plane-wave kinetic-energy cutoff (Hartree);\n        None = use highest cutoff from pseudopotential metadata of elements in structure\n\n    charge_density_cutoff: charge-density plane-wave cutoff (Hartree);\n        None = use highest cutoff from pseudopotential metadata of elements in structure\n\n    kpoints: Monkhorst\u2013Pack k-point-grid dimensions; (None -> \u00c5\u207b\u00b9 = .3)\n    smearing_type: occupations smearing type\n    smearing_width: smearing width, if relevant (Hartree)\n    hubbard_u: DFT+U on-site Coulomb repulsion per element symbol (Hartree)\n        None = no DFT+U; \"auto\" = automatic U values from MP database",
      "properties": {
        "plane_wave_cutoff": {
          "anyOf": [
            {
              "exclusiveMinimum": 0,
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Plane Wave Cutoff"
        },
        "charge_density_cutoff": {
          "anyOf": [
            {
              "exclusiveMinimum": 0,
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Charge Density Cutoff"
        },
        "kpoints": {
          "anyOf": [
            {
              "maxItems": 3,
              "minItems": 3,
              "prefixItems": [
                {
                  "exclusiveMinimum": 0,
                  "type": "integer"
                },
                {
                  "exclusiveMinimum": 0,
                  "type": "integer"
                },
                {
                  "exclusiveMinimum": 0,
                  "type": "integer"
                }
              ],
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Kpoints"
        },
        "smearing_type": {
          "anyOf": [
            {
              "$ref": "#/$defs/PBCDFTSmearing"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "smearing_width": {
          "default": 0.005,
          "exclusiveMinimum": 0,
          "title": "Smearing Width",
          "type": "number"
        },
        "hubbard_u": {
          "anyOf": [
            {
              "additionalProperties": {
                "exclusiveMinimum": 0,
                "type": "number"
              },
              "type": "object"
            },
            {
              "const": "auto",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Hubbard U"
        }
      },
      "title": "PBCDFTSettings",
      "type": "object"
    },
    "PBCDFTSmearing": {
      "description": "Smearing types for occupations in PBC DFT calculations.",
      "enum": [
        "marzari_vanderbilt",
        "methfessel_paxton",
        "fermi_dirac",
        "gaussian"
      ],
      "title": "PBCDFTSmearing",
      "type": "string"
    },
    "SCFSettings": {
      "description": "Settings for SCF convergence.\n\nAttributes:\n    max_iters: maximum number of SCF iterations to permit\n    soscf: use SOSCF (second-order SCF) when true.",
      "properties": {
        "max_iters": {
          "default": 250,
          "title": "Max Iters",
          "type": "integer"
        },
        "soscf": {
          "$ref": "#/$defs/UseSOSCF",
          "default": "upon_failure"
        }
      },
      "title": "SCFSettings",
      "type": "object"
    },
    "Solvent": {
      "description": "Implicit solvent.",
      "enum": [
        "water",
        "nitromethane",
        "nitrobenzene",
        "toluene",
        "benzene",
        "chlorobenzene",
        "carbontetrachloride",
        "dichloroethane",
        "dichloromethane",
        "chloroform",
        "diethylether",
        "diisopropylether",
        "dimethylsulfoxide",
        "tetrahydrofuran",
        "cyclohexane",
        "aceticacid",
        "hexane",
        "octane",
        "decane",
        "ethylacetate",
        "acetone",
        "acetonitrile",
        "methanol",
        "ethanol",
        "isopropanol",
        "octanol",
        "dimethylacetamide",
        "dimethylformamide",
        "n_methylpyrrolidone",
        "ethylene_glycol"
      ],
      "title": "Solvent",
      "type": "string"
    },
    "SolventModel": {
      "description": "Implicit solvation model.",
      "enum": [
        "pcm",
        "cpcm",
        "alpb",
        "cosmo",
        "cosmo2",
        "cosmors",
        "gbsa",
        "cpcmx",
        "smd",
        "anysolv"
      ],
      "title": "SolventModel",
      "type": "string"
    },
    "SolventSettings": {
      "description": "Implicit solvation settings.\n\nAttributes:\n    solvent: solvent to use\n    model: solvation model",
      "properties": {
        "solvent": {
          "$ref": "#/$defs/Solvent"
        },
        "model": {
          "$ref": "#/$defs/SolventModel"
        }
      },
      "required": [
        "solvent",
        "model"
      ],
      "title": "SolventSettings",
      "type": "object"
    },
    "TDDFTSettings": {
      "description": "Settings for TDDFT calculations.\n\nAttributes:\n    tda: use Tamm-Dancoff approximation\n    num_excitations: positive number of excitations to calculate\n    target_root: positive root to target (for gradient/optimization); must not exceed `num_excitations` when set\n    settings_type: excited-state settings discriminator, fixed to `tddft_settings`",
      "properties": {
        "tda": {
          "default": true,
          "title": "Tda",
          "type": "boolean"
        },
        "num_excitations": {
          "default": 5,
          "exclusiveMinimum": 0,
          "title": "Num Excitations",
          "type": "integer"
        },
        "target_root": {
          "anyOf": [
            {
              "exclusiveMinimum": 0,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Target Root"
        },
        "settings_type": {
          "const": "tddft_settings",
          "default": "tddft_settings",
          "title": "Settings Type",
          "type": "string"
        }
      },
      "title": "TDDFTSettings",
      "type": "object"
    },
    "Task": {
      "description": "Calculation task type.",
      "enum": [
        "energy",
        "gradient",
        "optimize",
        "optimize_ts",
        "charge",
        "spin_density",
        "dipole",
        "hessian",
        "frequencies",
        "stress",
        "band_structure",
        "elastic_tensor"
      ],
      "title": "Task",
      "type": "string"
    },
    "ThermochemistrySettings": {
      "description": "Thermochemistry calculation settings.\n\nAttributes:\n    cutoff_frequency: Cramer/Truhlar quasi-harmonic cutoff, in cm^-1\n    temperature: temperature for thermochemistry, in K\n    scaling_factor: frequency scaling factor\n    concentration: concentration, in M (defaults to 1 atm)",
      "properties": {
        "cutoff_frequency": {
          "default": 100,
          "minimum": 0,
          "title": "Cutoff Frequency",
          "type": "number"
        },
        "temperature": {
          "default": 298,
          "minimum": 0,
          "title": "Temperature",
          "type": "number"
        },
        "scaling_factor": {
          "default": 1.0,
          "minimum": 0,
          "title": "Scaling Factor",
          "type": "number"
        },
        "concentration": {
          "default": 0.0408740470708,
          "minimum": 0,
          "title": "Concentration",
          "type": "number"
        }
      },
      "title": "ThermochemistrySettings",
      "type": "object"
    },
    "UseSOSCF": {
      "description": "Select when to use second-order SCF convergence.",
      "enum": [
        "always",
        "upon_failure",
        "never"
      ],
      "title": "UseSOSCF",
      "type": "string"
    }
  },
  "description": "Settings for (base) computational chemistry calculations.\n\nAttributes:\n    mode: calculation mode (affects thresholds for optimizations, etc.)\n    tasks: tasks to perform (deprecated, specify in workflows or calculations instead)\n    method: computational method\n    basis_set: basis set to use (autopopulated for 3c methods)\n    engine: computational engine to use (auto-selected if None)\n    corrections: list of corrections to apply (e.g. D3BJ, D4)\n    solvent_settings: solvent model settings (if any)\n    omega: range-separation parameter or tuning method (parameter in Bohr\u207b\u00b9)\n    excited_state_settings: settings for excited-state calculations (if any)\n    pbc_dft_settings: settings specific to DFT calculations on periodic systems\n    scf_settings: SCF settings\n    opt_settings: geometry optimization settings\n    thermochem_settings: thermochemistry settings\n    compute_settings: hardware settings",
  "properties": {
    "mode": {
      "$ref": "#/$defs/Mode",
      "default": "auto"
    },
    "tasks": {
      "default": [
        "energy",
        "charge",
        "dipole"
      ],
      "items": {
        "$ref": "#/$defs/Task"
      },
      "title": "Tasks",
      "type": "array"
    },
    "method": {
      "$ref": "#/$defs/Method",
      "default": "hf"
    },
    "basis_set": {
      "anyOf": [
        {
          "$ref": "#/$defs/BasisSet"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "engine": {
      "$ref": "#/$defs/Engine",
      "default": null
    },
    "corrections": {
      "default": [],
      "items": {
        "$ref": "#/$defs/Correction"
      },
      "title": "Corrections",
      "type": "array"
    },
    "solvent_settings": {
      "anyOf": [
        {
          "$ref": "#/$defs/SolventSettings"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "omega": {
      "anyOf": [
        {
          "$ref": "#/$defs/OmegaTuning"
        },
        {
          "exclusiveMinimum": 0,
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Omega"
    },
    "excited_state_settings": {
      "anyOf": [
        {
          "discriminator": {
            "mapping": {
              "tddft_settings": "#/$defs/TDDFTSettings"
            },
            "propertyName": "settings_type"
          },
          "oneOf": [
            {
              "$ref": "#/$defs/TDDFTSettings"
            }
          ]
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Excited State Settings"
    },
    "pbc_dft_settings": {
      "anyOf": [
        {
          "$ref": "#/$defs/PBCDFTSettings"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "scf_settings": {
      "$ref": "#/$defs/SCFSettings",
      "default": {
        "max_iters": 250,
        "soscf": "upon_failure"
      }
    },
    "opt_settings": {
      "$ref": "#/$defs/OptimizationSettings",
      "default": {
        "max_steps": 250,
        "transition_state": false,
        "recalc_hess_every": 0,
        "max_gradient_threshold": 0.0005,
        "rms_gradient_threshold": 0.0003,
        "max_displacement_threshold": 0.002,
        "rms_displacement_threshold": 0.001,
        "energy_threshold": 1e-06,
        "optimize_cell": false,
        "constraints": [],
        "save_intermediate_steps": true
      }
    },
    "thermochem_settings": {
      "$ref": "#/$defs/ThermochemistrySettings",
      "default": {
        "cutoff_frequency": 100.0,
        "temperature": 298.0,
        "scaling_factor": 1.0,
        "concentration": 0.0408740470708
      }
    },
    "compute_settings": {
      "$ref": "#/$defs/ComputeSettings",
      "default": {
        "requested_compute_type": "cpu",
        "compute_type_used": null
      }
    }
  },
  "title": "Settings",
  "type": "object"
}

Fields:

mode (Mode)
tasks (UniqueList[Task])
method (Method)
basis_set (BasisSet | None)
engine (Engine)
corrections (UniqueList[Correction])
solvent_settings (SolventSettings | None)
omega (OmegaTuning | PositiveFloat | None)
excited_state_settings (ExcitedStateSettingsUnion | None)
pbc_dft_settings (PBCDFTSettings | None)
scf_settings (SCFSettings)
opt_settings (OptimizationSettings)
thermochem_settings (ThermochemistrySettings)
compute_settings (ComputeSettings)

Validators:

_force_cosmors_recipe
set_defaults
set_mode_auto → mode
validate_and_build
parse_basis_set → basis_set
remove_empty_string → corrections

level_of_theory `property`

level_of_theory: str

Describe the selected method, corrections, and basis set.

Returns:

Type	Description
`str`	level-of-theory label

set_defaults `pydantic-validator`

set_defaults() -> Self

Set the calculation engine and any dependent defaults.

set_mode_auto `pydantic-validator`

set_mode_auto(mode: Mode) -> Mode

Set the mode to RAPID if AUTO is selected.

Parameters:

Name	Type	Description	Default
`mode`	`Mode`	effort mode to apply	required

validate_and_build `pydantic-validator`

validate_and_build() -> Self

Apply mode-dependent defaults and validate calculation settings.

Returns:

Type	Description
`Self`	settings with resolved defaults

model_post_init

model_post_init(__context: Any) -> None

Normalize transition-state tasks and composite-method basis sets.

parse_basis_set `pydantic-validator`

parse_basis_set(v: Any) -> BasisSet | dict[str, Any] | None

Normalize a basis set name or supplied definition.

Parameters:

Name	Type	Description	Default
`v`	`Any`	basis set name, definition, or existing basis set	required

remove_empty_string `pydantic-validator`

remove_empty_string(v: list[_T]) -> list[_T]

Filter empty correction values.

Parameters:

Name	Type	Description	Default
`v`	`list[_T]`	input correction values to filter	required

Basis sets

Pass a basis set name as a string for ordinary calculations. Use rowan.BasisSet when configuring atom- or element-specific overrides.

Define basis set selections and overrides.

BasisSetOverride `pydantic-model`

Bases: Base

Basis set override for specific atoms or elements.

Attributes:

Name	Type	Description
`name`	`str`	basis set name for override
`atomic_numbers`	`list[PositiveInt] \| None`	atomic numbers to override (mutually exclusive with atoms)
`atoms`	`list[PositiveInt] \| None`	1-indexed atom indices to override (mutually exclusive with atomic_numbers)

Show JSON schema:

{
  "description": "Basis set override for specific atoms or elements.\n\nAttributes:\n    name: basis set name for override\n    atomic_numbers: atomic numbers to override (mutually exclusive with atoms)\n    atoms: 1-indexed atom indices to override (mutually exclusive with atomic_numbers)",
  "properties": {
    "name": {
      "title": "Name",
      "type": "string"
    },
    "atomic_numbers": {
      "anyOf": [
        {
          "items": {
            "exclusiveMinimum": 0,
            "type": "integer"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Atomic Numbers"
    },
    "atoms": {
      "anyOf": [
        {
          "items": {
            "exclusiveMinimum": 0,
            "type": "integer"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Atoms"
    }
  },
  "required": [
    "name"
  ],
  "title": "BasisSetOverride",
  "type": "object"
}

Fields:

name (str)
atomic_numbers (list[PositiveInt] | None)
atoms (list[PositiveInt] | None)

Validators:

check_override

check_override `pydantic-validator`

check_override() -> Self

Require exactly one atom selection method.

Returns:

Type	Description
`Self`	validated override

Raises:

Type	Description
`AssertionError`	both or neither atom selections are provided

BasisSet `pydantic-model`

Bases: Base

Atomic orbital basis set.

Attributes:

Name	Type	Description
`name`	`str`	basis set name (e.g., def2-SVP, cc-pVDZ)
`overrides`	`list[BasisSetOverride] \| None`	element or atom-specific basis set overrides
`cutoff_threshold`	`PositiveFloat`	basis function screening threshold

Show JSON schema:

{
  "$defs": {
    "BasisSetOverride": {
      "description": "Basis set override for specific atoms or elements.\n\nAttributes:\n    name: basis set name for override\n    atomic_numbers: atomic numbers to override (mutually exclusive with atoms)\n    atoms: 1-indexed atom indices to override (mutually exclusive with atomic_numbers)",
      "properties": {
        "name": {
          "title": "Name",
          "type": "string"
        },
        "atomic_numbers": {
          "anyOf": [
            {
              "items": {
                "exclusiveMinimum": 0,
                "type": "integer"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Atomic Numbers"
        },
        "atoms": {
          "anyOf": [
            {
              "items": {
                "exclusiveMinimum": 0,
                "type": "integer"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Atoms"
        }
      },
      "required": [
        "name"
      ],
      "title": "BasisSetOverride",
      "type": "object"
    }
  },
  "description": "Atomic orbital basis set.\n\nAttributes:\n    name: basis set name (e.g., def2-SVP, cc-pVDZ)\n    overrides: element or atom-specific basis set overrides\n    cutoff_threshold: basis function screening threshold",
  "properties": {
    "name": {
      "title": "Name",
      "type": "string"
    },
    "overrides": {
      "anyOf": [
        {
          "items": {
            "$ref": "#/$defs/BasisSetOverride"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": [],
      "title": "Overrides"
    },
    "cutoff_threshold": {
      "default": 1e-10,
      "exclusiveMinimum": 0,
      "title": "Cutoff Threshold",
      "type": "number"
    }
  },
  "required": [
    "name"
  ],
  "title": "BasisSet",
  "type": "object"
}

Fields:

name (str)
overrides (list[BasisSetOverride] | None)
cutoff_threshold (PositiveFloat)

Define geometry optimization settings.

OptimizationSettings `pydantic-model`

Bases: Base

Geometry optimization settings.

Attributes:

Name	Type	Description
`max_steps`	`PositiveInt`	maximum number of optimization steps
`transition_state`	`bool`	perform transition state optimization
`recalc_hess_every`	`int`	recalculate Hessian every n steps (0 = never)
`max_gradient_threshold`	`PositiveFloat`	convergence threshold for max gradient, in Hartree/Å
`rms_gradient_threshold`	`PositiveFloat`	convergence threshold for RMS gradient, in Hartree/Å
`max_displacement_threshold`	`PositiveFloat`	convergence threshold for step displacement, in Å
`rms_displacement_threshold`	`PositiveFloat`	convergence threshold for step displacement, in Å
`energy_threshold`	`PositiveFloat`	convergence threshold for energy change, in Hartree
`optimize_cell`	`bool`	optimize unit cell (periodic systems only)
`constraints`	`Sequence[Constraint]`	geometric constraints to apply
`save_intermediate_steps`	`bool`	save intermediate geometries

Show JSON schema:

{
  "$defs": {
    "Constraint": {
      "description": "Represents a single (absolute) constraint.\n\nAttributes:\n    constraint_type: which type\n    atoms: atoms in question (1-indexed)\n    value: value to constrain to; leaving blank sets current value",
      "properties": {
        "constraint_type": {
          "$ref": "#/$defs/ConstraintType"
        },
        "atoms": {
          "items": {
            "exclusiveMinimum": 0,
            "type": "integer"
          },
          "title": "Atoms",
          "type": "array"
        },
        "value": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Value"
        }
      },
      "required": [
        "constraint_type",
        "atoms"
      ],
      "title": "Constraint",
      "type": "object"
    },
    "ConstraintType": {
      "description": "Different sorts of constraints.",
      "enum": [
        "bond",
        "angle",
        "dihedral",
        "freeze_atoms"
      ],
      "title": "ConstraintType",
      "type": "string"
    }
  },
  "description": "Geometry optimization settings.\n\nAttributes:\n    max_steps: maximum number of optimization steps\n    transition_state: perform transition state optimization\n    recalc_hess_every: recalculate Hessian every n steps (0 = never)\n    max_gradient_threshold: convergence threshold for max gradient, in Hartree/\u00c5\n    rms_gradient_threshold: convergence threshold for RMS gradient, in Hartree/\u00c5\n    max_displacement_threshold: convergence threshold for step displacement, in \u00c5\n    rms_displacement_threshold: convergence threshold for step displacement, in \u00c5\n    energy_threshold: convergence threshold for energy change, in Hartree\n    optimize_cell: optimize unit cell (periodic systems only)\n    constraints: geometric constraints to apply\n    save_intermediate_steps: save intermediate geometries",
  "properties": {
    "max_steps": {
      "default": 250,
      "exclusiveMinimum": 0,
      "title": "Max Steps",
      "type": "integer"
    },
    "transition_state": {
      "default": false,
      "title": "Transition State",
      "type": "boolean"
    },
    "recalc_hess_every": {
      "default": 0,
      "title": "Recalc Hess Every",
      "type": "integer"
    },
    "max_gradient_threshold": {
      "default": 0.0005,
      "exclusiveMinimum": 0,
      "title": "Max Gradient Threshold",
      "type": "number"
    },
    "rms_gradient_threshold": {
      "default": 0.0003,
      "exclusiveMinimum": 0,
      "title": "Rms Gradient Threshold",
      "type": "number"
    },
    "max_displacement_threshold": {
      "default": 0.002,
      "exclusiveMinimum": 0,
      "title": "Max Displacement Threshold",
      "type": "number"
    },
    "rms_displacement_threshold": {
      "default": 0.001,
      "exclusiveMinimum": 0,
      "title": "Rms Displacement Threshold",
      "type": "number"
    },
    "energy_threshold": {
      "default": 1e-06,
      "exclusiveMinimum": 0,
      "title": "Energy Threshold",
      "type": "number"
    },
    "optimize_cell": {
      "default": false,
      "title": "Optimize Cell",
      "type": "boolean"
    },
    "constraints": {
      "default": [],
      "items": {
        "$ref": "#/$defs/Constraint"
      },
      "title": "Constraints",
      "type": "array"
    },
    "save_intermediate_steps": {
      "default": true,
      "title": "Save Intermediate Steps",
      "type": "boolean"
    }
  },
  "title": "OptimizationSettings",
  "type": "object"
}

Fields:

max_steps (PositiveInt)
transition_state (bool)
recalc_hess_every (int)
max_gradient_threshold (PositiveFloat)
rms_gradient_threshold (PositiveFloat)
max_displacement_threshold (PositiveFloat)
rms_displacement_threshold (PositiveFloat)
energy_threshold (PositiveFloat)
optimize_cell (bool)
constraints (Sequence[Constraint])
save_intermediate_steps (bool)

loose `classmethod`

loose(**kwargs: Any) -> Self

Return optimization settings with loose convergence thresholds.

Parameters:

Name	Type	Description	Default
`kwargs`	`Any`	additional settings fields	`{}`

tight `classmethod`

tight(**kwargs: Any) -> Self

Return optimization settings with tight convergence thresholds.

Parameters:

Name	Type	Description	Default
`kwargs`	`Any`	additional settings fields	`{}`

Define periodic density functional theory settings.

PBCDFTSmearing

Bases: LowercaseStrEnum

Smearing types for occupations in PBC DFT calculations.

PBCDFTSettings `pydantic-model`

Bases: BaseModel

PBC DFT settings.

Attributes:

Name	Type	Description
`plane_wave_cutoff`	`PositiveFloat \| None`	plane-wave kinetic-energy cutoff (Hartree); None = use highest cutoff from pseudopotential metadata of elements in structure
`charge_density_cutoff`	`PositiveFloat \| None`	charge-density plane-wave cutoff (Hartree); None = use highest cutoff from pseudopotential metadata of elements in structure
`kpoints`	`tuple[PositiveInt, PositiveInt, PositiveInt] \| None`	Monkhorst–Pack k-point-grid dimensions; (None -> Å⁻¹ = .3)
`smearing_type`	`PBCDFTSmearing \| None`	occupations smearing type
`smearing_width`	`PositiveFloat`	smearing width, if relevant (Hartree)
`hubbard_u`	`dict[str, PositiveFloat] \| Literal['auto'] \| None`	DFT+U on-site Coulomb repulsion per element symbol (Hartree) None = no DFT+U; "auto" = automatic U values from MP database

Show JSON schema:

{
  "$defs": {
    "PBCDFTSmearing": {
      "description": "Smearing types for occupations in PBC DFT calculations.",
      "enum": [
        "marzari_vanderbilt",
        "methfessel_paxton",
        "fermi_dirac",
        "gaussian"
      ],
      "title": "PBCDFTSmearing",
      "type": "string"
    }
  },
  "description": "PBC DFT settings.\n\nAttributes:\n    plane_wave_cutoff: plane-wave kinetic-energy cutoff (Hartree);\n        None = use highest cutoff from pseudopotential metadata of elements in structure\n\n    charge_density_cutoff: charge-density plane-wave cutoff (Hartree);\n        None = use highest cutoff from pseudopotential metadata of elements in structure\n\n    kpoints: Monkhorst\u2013Pack k-point-grid dimensions; (None -> \u00c5\u207b\u00b9 = .3)\n    smearing_type: occupations smearing type\n    smearing_width: smearing width, if relevant (Hartree)\n    hubbard_u: DFT+U on-site Coulomb repulsion per element symbol (Hartree)\n        None = no DFT+U; \"auto\" = automatic U values from MP database",
  "properties": {
    "plane_wave_cutoff": {
      "anyOf": [
        {
          "exclusiveMinimum": 0,
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Plane Wave Cutoff"
    },
    "charge_density_cutoff": {
      "anyOf": [
        {
          "exclusiveMinimum": 0,
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Charge Density Cutoff"
    },
    "kpoints": {
      "anyOf": [
        {
          "maxItems": 3,
          "minItems": 3,
          "prefixItems": [
            {
              "exclusiveMinimum": 0,
              "type": "integer"
            },
            {
              "exclusiveMinimum": 0,
              "type": "integer"
            },
            {
              "exclusiveMinimum": 0,
              "type": "integer"
            }
          ],
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Kpoints"
    },
    "smearing_type": {
      "anyOf": [
        {
          "$ref": "#/$defs/PBCDFTSmearing"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "smearing_width": {
      "default": 0.005,
      "exclusiveMinimum": 0,
      "title": "Smearing Width",
      "type": "number"
    },
    "hubbard_u": {
      "anyOf": [
        {
          "additionalProperties": {
            "exclusiveMinimum": 0,
            "type": "number"
          },
          "type": "object"
        },
        {
          "const": "auto",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Hubbard U"
    }
  },
  "title": "PBCDFTSettings",
  "type": "object"
}

Fields:

plane_wave_cutoff (PositiveFloat | None)
charge_density_cutoff (PositiveFloat | None)
kpoints (tuple[PositiveInt, PositiveInt, PositiveInt] | None)
smearing_type (PBCDFTSmearing | None)
smearing_width (PositiveFloat)
hubbard_u (dict[str, PositiveFloat] | Literal['auto'] | None)

Define excited state calculation settings.

ExcitedStateSettings `pydantic-model`

Bases: BaseModel, ABC

Settings for excited state calculations.

Show JSON schema:

{
  "description": "Settings for excited state calculations.",
  "properties": {},
  "title": "ExcitedStateSettings",
  "type": "object"
}

TDDFTSettings `pydantic-model`

Bases: ExcitedStateSettings

Settings for TDDFT calculations.

Attributes:

Name	Type	Description
`tda`	`bool`	use Tamm-Dancoff approximation
`num_excitations`	`PositiveInt`	positive number of excitations to calculate
`target_root`	`PositiveInt \| None`	positive root to target (for gradient/optimization); must not exceed `num_excitations` when set
`settings_type`	`Literal['tddft_settings']`	excited-state settings discriminator, fixed to `tddft_settings`

Show JSON schema:

{
  "description": "Settings for TDDFT calculations.\n\nAttributes:\n    tda: use Tamm-Dancoff approximation\n    num_excitations: positive number of excitations to calculate\n    target_root: positive root to target (for gradient/optimization); must not exceed `num_excitations` when set\n    settings_type: excited-state settings discriminator, fixed to `tddft_settings`",
  "properties": {
    "tda": {
      "default": true,
      "title": "Tda",
      "type": "boolean"
    },
    "num_excitations": {
      "default": 5,
      "exclusiveMinimum": 0,
      "title": "Num Excitations",
      "type": "integer"
    },
    "target_root": {
      "anyOf": [
        {
          "exclusiveMinimum": 0,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Target Root"
    },
    "settings_type": {
      "const": "tddft_settings",
      "default": "tddft_settings",
      "title": "Settings Type",
      "type": "string"
    }
  },
  "title": "TDDFTSettings",
  "type": "object"
}

Fields:

tda (bool)
num_excitations (PositiveInt)
target_root (PositiveInt | None)
settings_type (Literal['tddft_settings'])

Validators:

validate_setup

validate_setup `pydantic-validator`

validate_setup() -> Self

Check that the target root is among requested excitations.

Returns:

Type	Description
`Self`	validated settings

Raises:

Type	Description
`ValueError`	target root exceeds the excitation count

Settings

Settings pydantic-model

level_of_theory property

set_defaults pydantic-validator

set_mode_auto pydantic-validator

validate_and_build pydantic-validator

model_post_init

parse_basis_set pydantic-validator

remove_empty_string pydantic-validator

Basis sets

BasisSetOverride pydantic-model

check_override pydantic-validator

BasisSet pydantic-model

OptimizationSettings pydantic-model

loose classmethod

tight classmethod

PBCDFTSmearing

PBCDFTSettings pydantic-model

ExcitedStateSettings pydantic-model

TDDFTSettings pydantic-model

validate_setup pydantic-validator

Settings `pydantic-model`

level_of_theory `property`

set_defaults `pydantic-validator`

set_mode_auto `pydantic-validator`

validate_and_build `pydantic-validator`

parse_basis_set `pydantic-validator`

remove_empty_string `pydantic-validator`

BasisSetOverride `pydantic-model`

check_override `pydantic-validator`

BasisSet `pydantic-model`

OptimizationSettings `pydantic-model`

loose `classmethod`

tight `classmethod`

PBCDFTSettings `pydantic-model`

ExcitedStateSettings `pydantic-model`

TDDFTSettings `pydantic-model`

validate_setup `pydantic-validator`