settings

Settings for quacc.

QuaccSettings

Bases: BaseSettings

Settings for quacc.

The default way to modify these is to make a ~/.quacc.yaml file. Alternatively, the environment variable QUACC_CONFIG_FILE can be set to point to a custom yaml file with quacc settings. The quacc CLI offers a quacc set <setting> <value> option to do this as well.

The variables can also be modified individually though environment variables by using the "QUACC" prefix. e.g. export QUACC_SCRATCH_DIR=/path/to/scratch.

CHECK_CONVERGENCE class-attribute instance-attribute

CHECK_CONVERGENCE: bool = Field(
    True,
    description="Whether to check for convergence, when implemented by a given recipe.",
)

CONFIG_FILE class-attribute instance-attribute

CONFIG_FILE: Path = Field(
    _DEFAULT_CONFIG_FILE_PATH,
    description="\n            Path to the YAML file to load alternative quacc configuration\n            defaults from.\n            ",
)

CREATE_UNIQUE_DIR class-attribute instance-attribute

CREATE_UNIQUE_DIR: bool = Field(
    True,
    description="\n            Whether to have a unique directory in RESULTS_DIR for each job.\n            Some workflow engines have an option to do this for you already,\n            in which case you should set this to False.\n            ",
)

DEBUG class-attribute instance-attribute

DEBUG: bool = Field(
    False,
    description="\n            Whether to run in debug mode. This will set the logging level to DEBUG,\n            ASE logs (e.g. optimizations, vibrations, thermo) are printed to stdout.\n            ",
)

ESPRESSO_BINARIES class-attribute instance-attribute

ESPRESSO_BINARIES: dict[str, str] = Field(
    {
        "pw": "pw.x",
        "ph": "ph.x",
        "neb": "neb.x",
        "q2r": "q2r.x",
        "dos": "dos.x",
        "matdyn": "matdyn.x",
        "dynmat": "dynmat.x",
        "bands": "bands.x",
        "projwfc": "projwfc.x",
        "pp": "pp.x",
        "wannier90": "wannier90.x",
        "fs": "fs.x",
        "postahc": "postahc.x",
        "dvscf_q2r": "dvscf_q2r.x",
    },
    description="Name for each espresso binary.",
)

ESPRESSO_BIN_DIR class-attribute instance-attribute

ESPRESSO_BIN_DIR: Path = Field(
    Path(),
    description="Base path to the espresso binaries.",
)

ESPRESSO_PRESET_DIR class-attribute instance-attribute

ESPRESSO_PRESET_DIR: Path = Field(
    parent / "calculators" / "espresso" / "presets",
    description="Path to the espresso preset directory",
)

ESPRESSO_PSEUDO class-attribute instance-attribute

ESPRESSO_PSEUDO: Optional[Path] = Field(
    None,
    description="Path to a pseudopotential library for espresso.",
)

GAUSSIAN_CMD class-attribute instance-attribute

GAUSSIAN_CMD: str = Field(
    "g16", description="Path to the Gaussian executable."
)

GULP_CMD class-attribute instance-attribute

GULP_CMD: str = Field(
    "gulp", description="Path to the GULP executable."
)

GULP_LIB class-attribute instance-attribute

GULP_LIB: Optional[Path] = Field(
    None,
    description="Path to the GULP force field library. If not specified, the GULP_LIB environment variable will be used (if present).",
)

GZIP_FILES class-attribute instance-attribute

GZIP_FILES: bool = Field(
    True,
    description="Whether generated files should be gzip'd.",
)

NEWTONNET_CONFIG_PATH class-attribute instance-attribute

NEWTONNET_CONFIG_PATH: Union[Path, list[Path]] = Field(
    "config.yml",
    description="Path to NewtonNet YAML settings file",
)

NEWTONNET_MODEL_PATH class-attribute instance-attribute

NEWTONNET_MODEL_PATH: Union[Path, list[Path]] = Field(
    "best_model_state.tar",
    description="Path to NewtonNet .tar model",
)

ONETEP_CMD class-attribute instance-attribute

ONETEP_CMD: Optional[str] = Field(
    "onetep.arch",
    description="Path to the ONETEP executable.",
)

ONETEP_PARALLEL_CMD class-attribute instance-attribute

ONETEP_PARALLEL_CMD: Optional[dict] = Field(
    None,
    description="Parallelization commands to run ONETEP that are prepended to the executable.",
)

ONETEP_PP_PATH class-attribute instance-attribute

ONETEP_PP_PATH: Optional[Path] = Field(
    None, description="Path to pseudopotentials."
)

ORCA_CMD class-attribute instance-attribute

ORCA_CMD: str = Field(
    which("orca") or "orca",
    description="\n            Path to the ORCA executable. This must be the full, absolute path\n            for parallel calculations to work.\n            ",
)

PREFECT_AUTO_SUBMIT class-attribute instance-attribute

PREFECT_AUTO_SUBMIT: bool = Field(
    True,
    description="Whether to auto-submit tasks to the task runner.",
)

QCHEM_CMD class-attribute instance-attribute

QCHEM_CMD: str = Field(
    "qchem",
    description="Command to run the standard version of Q-Chem.",
)

QCHEM_CUSTODIAN_MAX_ERRORS class-attribute instance-attribute

QCHEM_CUSTODIAN_MAX_ERRORS: int = Field(
    5, description="Maximum errors for Q-Chem Custodian."
)

QCHEM_LOCAL_SCRATCH class-attribute instance-attribute

QCHEM_LOCAL_SCRATCH: Path = Field(
    Path("/tmp") if exists() else cwd() / ".qchem_scratch",
    description="Compute-node local scratch directory in which Q-Chem should perform IO.",
)

QCHEM_NBO_EXE class-attribute instance-attribute

QCHEM_NBO_EXE: Optional[Path] = Field(
    None, description="Full path to the NBO executable."
)

QCHEM_NUM_CORES class-attribute instance-attribute

QCHEM_NUM_CORES: int = Field(
    cpu_count(logical=False),
    description="Number of cores to use for the Q-Chem calculation.",
)

QCHEM_USE_ERROR_HANDLERS class-attribute instance-attribute

QCHEM_USE_ERROR_HANDLERS: bool = Field(
    True,
    description="Whether Custodian's error handlers should be employed for Q-Chem.",
)

RESULTS_DIR class-attribute instance-attribute

RESULTS_DIR: Path = Field(
    Path(),
    description="\n            Directory to permanently store I/O-based calculation results in.\n            Note that this behavior may be modified by the chosen workflow engine.\n            ",
)

SCRATCH_DIR class-attribute instance-attribute

SCRATCH_DIR: Optional[Path] = Field(
    None,
    description="\n            The base directory where calculations are run. If set to None, calculations will be run in a\n            temporary directory within `RESULTS_DIR`. If a `Path` is supplied, calculations will\n            be run in a temporary directory within `SCRATCH_DIR`. Files are always moved back\n            to `RESULTS_DIR` after the calculation is complete, and the temporary directory\n            in `SCRATCH_DIR` is removed.\n            ",
)

STORE class-attribute instance-attribute

STORE: Optional[Union[dict[str, dict], Store]] = Field(
    None,
    description="\n            The desired Maggma data store where calculation results will be stored. All data stores listed in\n            `maggma.stores.__init__.py` are supported. If a dictionary is provided, the first key must be set\n            to the desired store type. The sub-parameters are the keyword arguments accepted by the Store.\n            An example is shown below:\n\n            ```yaml\n            STORE:\n              MongoStore:\n                database: my_db\n                collection_name: my_collection\n                username: my_username\n                password: my_password\n                host: localhost\n                port: 27017\n            ```\n            ",
)

VASP_BADER class-attribute instance-attribute

VASP_BADER: bool = Field(
    bool(which("bader")),
    description='"\n            Whether to run a Bader analysis when summarizing VASP results.\n            Requires bader to be in PATH.\n            ',
)

VASP_CHARGEMOL class-attribute instance-attribute

VASP_CHARGEMOL: bool = Field(
    bool(get("DDEC6_ATOMIC_DENSITIES_DIR")),
    description="\n            Whether to run a Chargemol (i.e. DDEC6, CM5) analysis when summarizing VASP results.\n            Requires the Chargemol executable to be in PATH and the DDEC6_ATOMIC_DENSITIES_DIR environment variable.\n            ",
)

VASP_CMD class-attribute instance-attribute

VASP_CMD: str = Field(
    "vasp_std",
    description="Command to run the standard version of VASP.",
)

VASP_COPY_MAGMOMS class-attribute instance-attribute

VASP_COPY_MAGMOMS: bool = Field(
    True,
    description="\n            If True, any pre-existing atoms.get_magnetic_moments() will be set\n            in atoms.set_initial_magnetic_moments().\n            ",
)

VASP_CUSTODIAN_HANDLERS class-attribute instance-attribute

VASP_CUSTODIAN_HANDLERS: list[str] = Field(
    [
        "VaspErrorHandler",
        "MeshSymmetryErrorHandler",
        "UnconvergedErrorHandler",
        "NonConvergingErrorHandler",
        "PotimErrorHandler",
        "PositiveEnergyErrorHandler",
        "FrozenJobErrorHandler",
        "StdErrHandler",
        "LargeSigmaHandler",
        "IncorrectSmearingHandler",
    ],
    description="Handlers for Custodian",
)

VASP_CUSTODIAN_MAX_ERRORS class-attribute instance-attribute

VASP_CUSTODIAN_MAX_ERRORS: int = Field(
    5, description="Maximum errors for Custodian"
)

VASP_CUSTODIAN_VALIDATORS class-attribute instance-attribute

VASP_CUSTODIAN_VALIDATORS: list[str] = Field(
    ["VasprunXMLValidator", "VaspFilesValidator"],
    description="Validators for Custodian",
)

VASP_CUSTODIAN_VTST class-attribute instance-attribute

VASP_CUSTODIAN_VTST: bool = Field(
    False,
    description="\n            If VTST-related input swaps should be used when running Custodian.\n            Requires VASP to be compiled with VTST\n            ",
)

VASP_CUSTODIAN_WALL_TIME class-attribute instance-attribute

VASP_CUSTODIAN_WALL_TIME: Optional[int] = Field(
    None,
    description="\n            After this many seconds, Custodian will stop running\n            and ensure that VASP writes a STOPCAR\n            ",
)

VASP_GAMMA_CMD class-attribute instance-attribute

VASP_GAMMA_CMD: str = Field(
    "vasp_gam",
    description="Command to run the gamma-point only version of VASP.",
)

VASP_INCAR_COPILOT class-attribute instance-attribute

VASP_INCAR_COPILOT: Literal["off", "on", "aggressive"] = (
    Field(
        "on",
        description="\n            Controls VASP co-pilot mode for automated INCAR parameter handling.\n            off: Do not use co-pilot mode. INCAR parameters will be unmodified.\n            on: Use co-pilot mode. This will only modify INCAR flags not already set by the user.\n            aggressive: Use co-pilot mode in aggressive mode. This will modify INCAR flags even if they are already set by the user.\n            ",
    )
)

VASP_MAG_CUTOFF class-attribute instance-attribute

VASP_MAG_CUTOFF: float = Field(
    0.02,
    description="\n            If the absolute value of all magnetic moments are below this value,\n            they will be set to 0 such that a spin-unpolarized calculation will be performed.\n            ",
)

VASP_PARALLEL_CMD class-attribute instance-attribute

VASP_PARALLEL_CMD: str = Field(
    "",
    description='\n            Parallel command to run VASP with Custodian.\n            For example: `"srun -N 2 --ntasks-per-node 48"`.\n            Note that this does not include the executable name.\n            ',
)

VASP_PP_PATH class-attribute instance-attribute

VASP_PP_PATH: Optional[Path] = Field(
    None,
    description="Path to the VASP pseudopotential library. Must contain the directories `potpaw_PBE` and `potpaw` for PBE and LDA pseudopotentials, respectively.",
)

VASP_PRESET_DIR class-attribute instance-attribute

VASP_PRESET_DIR: Path = Field(
    parent / "calculators" / "vasp" / "presets",
    description="Path to the VASP preset directory",
)

VASP_PRESET_MAG_DEFAULT class-attribute instance-attribute

VASP_PRESET_MAG_DEFAULT: float = Field(
    1.0,
    description="\n            Default initial magmom to use for a given element if a preset\n            with magmoms is provided but an element is missing from the list.\n            ",
)

VASP_USE_CUSTODIAN class-attribute instance-attribute

VASP_USE_CUSTODIAN: bool = Field(
    True,
    description="Whether Custodian should be used to run VASP",
)

VASP_VDW class-attribute instance-attribute

VASP_VDW: Optional[Path] = Field(
    None,
    description="Path to the vdw_kernel.bindat file for VASP vdW functionals.",
)

WORKFLOW_ENGINE class-attribute instance-attribute

WORKFLOW_ENGINE: Optional[
    Literal[
        "covalent",
        "dask",
        "parsl",
        "prefect",
        "redun",
        "jobflow",
    ]
] = Field(
    None, description="The workflow manager to use, if any."
)

model_config class-attribute instance-attribute

model_config = SettingsConfigDict(
    env_prefix="quacc_",
    env_nested_delimiter="__",
    env_parse_none_str="None",
    extra="forbid",
    validate_assignment=True,
)

expand_paths classmethod

expand_paths(v: Optional[Path]) -> Optional[Path]

Expand ~/ and $ENV_VARS in paths.

Source code in quacc/settings.py

@field_validator(
    "RESULTS_DIR",
    "SCRATCH_DIR",
    "ESPRESSO_PRESET_DIR",
    "ESPRESSO_PSEUDO",
    "GULP_LIB",
    "QCHEM_LOCAL_SCRATCH",
    "NEWTONNET_MODEL_PATH",
    "VASP_PRESET_DIR",
    "VASP_PP_PATH",
    "VASP_VDW",
)
@classmethod
def expand_paths(cls, v: Optional[Path]) -> Optional[Path]:
    """Expand ~/ and $ENV_VARS in paths."""
    if v:
        v = Path(os.path.expandvars(v)).expanduser()
    return v

generate_store classmethod

generate_store(
    v: Union[dict[str, dict[str, Any]], Store]
) -> Store

Generate the Maggma store.

Source code in quacc/settings.py

@field_validator("STORE")
@classmethod
def generate_store(cls, v: Union[dict[str, dict[str, Any]], Store]) -> Store:
    """Generate the Maggma store."""
    from maggma import stores

    if isinstance(v, dict):
        store_name = next(iter(v.keys()))
        store = getattr(stores, store_name)

        return store(**v[store_name])
    else:
        return v

load_user_settings classmethod

load_user_settings(
    settings: dict[str, Any]
) -> dict[str, Any]

Loads settings from a root file if available and uses that as defaults in place of built in defaults. Will also convert common strings to their proper types.

Parameters:

• settings (dict[str, Any]) –

  Settings to load.

Returns:

• dict –

  Loaded settings.

Source code in quacc/settings.py

@model_validator(mode="before")
@classmethod
def load_user_settings(cls, settings: dict[str, Any]) -> dict[str, Any]:
    """
    Loads settings from a root file if available and uses that as defaults in place
    of built in defaults. Will also convert common strings to their proper types.

    Parameters
    ----------
    settings
        Settings to load.

    Returns
    -------
    dict
        Loaded settings.
    """
    return _type_handler(_use_custom_config_settings(settings))

make_directories classmethod

make_directories(v: Optional[Path]) -> Optional[Path]

Make directories.

Source code in quacc/settings.py

@field_validator("RESULTS_DIR", "SCRATCH_DIR")
@classmethod
def make_directories(cls, v: Optional[Path]) -> Optional[Path]:
    """Make directories."""
    if v:
        v.mkdir(exist_ok=True, parents=True)
    return v

change_settings

change_settings(changes: dict[str, Any])

Temporarily change an attribute of an object.

Parameters:

• changes (dict[str, Any]) –

  Dictionary of changes to make formatted as attribute: value.

Source code in quacc/settings.py

@contextmanager
def change_settings(changes: dict[str, Any]):
    """
    Temporarily change an attribute of an object.

    Parameters
    ----------
    changes
        Dictionary of changes to make formatted as attribute: value.
    """
    from quacc import SETTINGS

    original_values = {attr: getattr(SETTINGS, attr) for attr in changes}

    for attr, new_value in changes.items():
        setattr(SETTINGS, attr, new_value)

    try:
        yield
    finally:
        for attr, original_value in original_values.items():
            setattr(SETTINGS, attr, original_value)