Config#

Input data is validated against a Pydantic model, in the NbedConfig class. This is then passed to the NbedDriver.

Example Configuration File#

For the command-line interface to Nbed, you’ll need to provide a path to a config file. This should contain a Json dictionary of input values.

{
"geometry":"1\\n\\nH\\t0.0\\t0.0\\t0.0",
"n_active_atoms":1,
"basis":"sto-3g",
"xc_functional":"b3lyp",
"projector":"mu",
"localization":"spade",
"convergence":1e-6,
"charge":0,
"spin":0,
"unit":"angstrom",
"symmetry":false,
"mu_level_shift":1000000.0,
"run_ccsd_emb":false,
"run_fci_emb":false,
"run_virtual_localization":true,
"run_dft_in_dft":false,
"n_mo_overwrite":[null,null],
"max_ram_memory":4000,
"occupied_threshold":0.95,
"virtual_threshold":0.95,
"max_shells":4,
"init_huzinaga_rhf_with_mu":false,
"max_hf_cycles":50,
"max_dft_cycles":50,
"force_unrestricted":false,
"mm_coords":null,
"mm_charges":null,
"mm_radii":null
}

Config Model#

Custom Types and Enums.

class nbed.config.NbedConfig(*, geometry: Annotated[str, _PydanticGeneralMetadata(pattern='^\\d+\n\\s?\n(?:\\w(?:\\s+\\-?\\d\\.\\d+){3}\n?)*'), BeforeValidator(func=validate_xyz_file, json_schema_input_type=PydanticUndefined)], n_active_atoms: Annotated[int, Gt(gt=0)], basis: str, xc_functional: str, projector: ProjectorTypes = ProjectorTypes.MU, localization: OccupiedLocalizerTypes = OccupiedLocalizerTypes.SPADE, convergence: Annotated[float, Gt(gt=0)] = 1e-06, charge: int = 0, spin: int = 0, unit: str = 'angstrom', symmetry: bool = False, restricted_global: bool = False, restricted_active: bool = False, savefile: Annotated[Path, PathType(path_type=file)] | None = None, run_ccsd_emb: bool = False, run_fci_emb: bool = False, run_dft_in_dft: bool = False, mm_coords: list | None = None, mm_charges: list | None = None, mm_radii: list | None = None, mu_level_shift: Annotated[float, Gt(gt=0)] = 1000000.0, init_huzinaga_rhf_with_mu: bool = False, virtual_localization: VirtualLocalizerTypes = VirtualLocalizerTypes.CONCENTRIC, n_mo_overwrite: tuple[None | Annotated[int, Ge(ge=0)], None | Annotated[int, Ge(ge=0)]] = (None, None), occupied_threshold: Annotated[float, Gt(gt=0), Lt(lt=1)] = 0.95, virtual_threshold: Annotated[float, Gt(gt=0), Lt(lt=1)] = 0.95, max_shells: Annotated[int, Gt(gt=0)] = 4, norm_cutoff: Annotated[float, Gt(gt=0)] = 0.05, overlap_cutoff: Annotated[float, Gt(gt=0)] = 1e-05, force_unrestricted: bool = False, max_ram_memory: Annotated[int, Gt(gt=0)] = 4000, max_hf_cycles: Annotated[int, Gt(gt=0)] = 50, max_dft_cycles: Annotated[int, Gt(gt=0)] = 50, build_hamiltonian: bool = False)[source]#

Bases: BaseModel

Config for Nbed.

Parameters:

  • geometry (XYZGeometry) – Path to .xyz file containing molecular geometry or raw xyz string.

  • n_active_atoms (PositiveInt) – The number of atoms to include in the active region.

  • basis (str) – The name of an atomic orbital basis set to use for chemistry calculations.

  • xc_functional (str) – The name of an Exchange-Correlation functional to be used for DFT.

  • projector (ProjectorTypes) – Projector to screen out environment orbitals, One of ‘mu’ or ‘huzinaga’.

  • localization (OccupiedLocalizerTypes) – Orbital localization method to use. One of ‘spade’, ‘pipek-mezey’, ‘boys’ or ‘ibo’.

  • convergence (Annotated[float, Gt(gt=0), Lt(lt=1)]) – The convergence tolerance for energy calculations.

  • charge (PositiveInt) – Charge of molecular species

  • mu_level_shift (PositiveFloat) – Level shift parameter to use for mu-projector.

  • run_ccsd_emb (bool) – Whether or not to find the CCSD energy of embbeded system for reference.

  • run_fci_emb (bool) – Whether or not to find the FCI energy of embbeded system for reference.

  • run_virtual_localization (bool) – Whether or not to localize virtual orbitals.

  • n_mo_overwrite (tuple[None| PositiveInt, None | PositiveInt]) – Optional overwrite values for occupied localizers.

  • max_ram_memory (PositiveInt) – Amount of RAM memery in MB available for PySCF calculation

  • unit (str) – molecular geometry unit ‘Angstrom’ or ‘Bohr’

  • max_hf_cycles (PositiveInt) – max number of Hartree-Fock iterations allowed (for global and local HFock)

  • max_dft_cycles (PositiveInt) – max number of DFT iterations allowed in scf calc

  • init_huzinaga_rhf_with_mu (bool) – Hidden flag to seed huzinaga RHF with mu shift result (for developers only)

  • savefile (FilePath) – Location of file to save output to.

basis: str#
build_hamiltonian: bool#
charge: int#
convergence: Annotated[float, Gt(gt=0)]#
force_unrestricted: bool#
geometry: Annotated[str, FieldInfo(annotation=NoneType, required=True, metadata=[_PydanticGeneralMetadata(pattern='^\\d+\n\\s?\n(?:\\w(?:\\s+\\-?\\d\\.\\d+){3}\n?)*')]), BeforeValidator(func=validate_xyz_file, json_schema_input_type=PydanticUndefined)]#
init_huzinaga_rhf_with_mu: bool#
localization: OccupiedLocalizerTypes#
max_dft_cycles: Annotated[int, Gt(gt=0)]#
max_hf_cycles: Annotated[int, Gt(gt=0)]#
max_ram_memory: Annotated[int, Gt(gt=0)]#
max_shells: Annotated[int, Gt(gt=0)]#
mm_charges: list | None#
mm_coords: list | None#
mm_radii: list | None#
model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

mu_level_shift: Annotated[float, Gt(gt=0)]#
n_active_atoms: Annotated[int, Gt(gt=0)]#
n_mo_overwrite: tuple[None | Annotated[int, Ge(ge=0)], None | Annotated[int, Ge(ge=0)]]#
norm_cutoff: Annotated[float, Gt(gt=0)]#
occupied_threshold: float#
overlap_cutoff: Annotated[float, Gt(gt=0)]#
projector: ProjectorTypes#
restricted_active: bool#
restricted_global: bool#
run_ccsd_emb: bool#
run_dft_in_dft: bool#
run_fci_emb: bool#
savefile: Annotated[Path, PathType(path_type=file)] | None#
spin: int#
symmetry: bool#
unit: str#
virtual_localization: VirtualLocalizerTypes#
virtual_threshold: float#
xc_functional: str#
class nbed.config.OccupiedLocalizerTypes(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]#

Bases: Enum

Implemented Occupied Localizers.

BOYS = 'boys'#
IBO = 'ibo'#
PM = 'pm'#
SPADE = 'spade'#
class nbed.config.ProjectorTypes(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]#

Bases: Enum

Implemented Projectors.

BOTH = 'both'#
HUZ = 'huzinaga'#
MU = 'mu'#
class nbed.config.VirtualLocalizerTypes(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]#

Bases: Enum

Implemented Virtual Localizers.

CONCENTRIC = 'cl'#
DISABLE = 'disable'#
PROJECTED_AO = 'pao'#
nbed.config.overwrite_config_kwargs(config: NbedConfig, **config_kwargs) → NbedConfig[source]#

Overwrites config values with key-words and revalidates.

Parameters:

  • config (NbedConfig) – A config model.

  • config_kwargs (dict) – Any possible key-word arguments.

Returns:

A validated config model.

Return type:

NbedConfig

Raises:

ValidationError – If key-word arguments provided are not part of model.

nbed.config.parse_config(config: NbedConfig | str | None = None, **config_kwargs)[source]#

Parse the various config options and return a valid model.

Parameters:

  • config (NbedConfig) – A validated config model or path to a ‘.json’ config file.

  • **config_kwargs – Allows arbitrary keyword arguments for manual configuration.

Returns:

A valid config model.

Return type:

NbedConfig

nbed.config.validate_xyz_file(maybe_xyz: Any) → str[source]#

Validates the the filepath given leads to a valid XYZ formatted file.

Parameters:

maybe_xyz (Any) – A path to an existing file.

Returns:

an XYZ geometry string.

Return type:

str