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            ",
)

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_PARALLEL_CMD class-attribute instance-attribute

ESPRESSO_PARALLEL_CMD: Union[str, tuple[str, str]] = Field(
    "",
    description='\n            Parallelization flags to run Espresso. The 0th index of the tuple\n            contains any commands that come before the binary, and the 1st index\n            contains any commands that come after the binary.\n\n            For example: ["mpirun -np 4", "-nk 2"] would be the same as running\n            Espresso via `"mpirun -np 4 {binary} -nk 2"` where {binary} is the\n            binary that is automatically determined based on the job type,\n            `ESPRESSO_BIN_DIR` and `ESPRESSO_BINARIES`.\n\n            If only a `str` is provided, no post-binary commands will be used.\n            ',
)

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.",
)

LOG_FILENAME class-attribute instance-attribute

LOG_FILENAME: Optional[Path] = Field(
    None, description="Path to store the log file."
)

LOG_LEVEL class-attribute instance-attribute

LOG_LEVEL: Optional[
    Literal["CRITICAL", "ERROR", "WARNING", "INFO", "DEBUG"]
] = Field("INFO", description="Logger level.")

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: str = Field(
    "onetep.arch",
    description="Full ONETEP command, including parallelization flags.",
)

ONETEP_PP_PATH class-attribute instance-attribute

ONETEP_PP_PATH: Path = Field(
    Path(), 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.",
)

PREFECT_RESOLVE_FLOW_RESULTS class-attribute instance-attribute

PREFECT_RESOLVE_FLOW_RESULTS: bool = Field(
    True,
    description="Whether to resolve all futures in flow results to data and fail if not possible",
)

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(
    cwd(),
    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(cls._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

validate_espresso_parallel_cmd classmethod

validate_espresso_parallel_cmd(
    v: Union[str, tuple[str, str]]
) -> tuple[str, str]

Clean up Espresso parallel command.

Source code in quacc/settings.py

@field_validator("ESPRESSO_PARALLEL_CMD")
@classmethod
def validate_espresso_parallel_cmd(
    cls, v: Union[str, tuple[str, str]]
) -> tuple[str, str]:
    """Clean up Espresso parallel command."""

    if isinstance(v, str):
        v = (v, "")

    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 _internally_set_settings, get_settings

    if "WORKFLOW_ENGINE" in changes:
        raise ValueError(
            "Cannot change the workflow engine in a context manager. Please use environment variables, e.g. `export QUACC_WORKFLOW_ENGINE=jobflow`, if you need to dynamically change the workflow engine."
        )

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

    _internally_set_settings(changes=changes)

    try:
        yield
    finally:
        _internally_set_settings(changes=original_values)

change_settings_wrap

change_settings_wrap(
    func: Callable, changes: dict[str, Any]
) -> Callable

Wraps a function with the change_settings context manager if not already wrapped.

Parameters:

• func (Callable) –

  The function to wrap.

• changes (dict[str, Any]) –

  The settings to apply within the context manager.

Returns:

• Callable –

  The wrapped function.

Source code in quacc/settings.py

def change_settings_wrap(func: Callable, changes: dict[str, Any]) -> Callable:
    """
    Wraps a function with the change_settings context manager if not already wrapped.

    Parameters
    ----------
    func
        The function to wrap.
    changes
        The settings to apply within the context manager.

    Returns
    -------
    Callable
        The wrapped function.
    """
    original_func = func._original_func if getattr(func, "_changed", False) else func

    @wraps(original_func)
    def wrapper(*args, **kwargs):
        with change_settings(changes):
            return original_func(*args, **kwargs)

    wrapper._changed = True
    wrapper._original_func = original_func
    return wrapper