Source code for ase2sprkkr.configuration

"""ASE2SPRKKR user configuration."""

import os
import warnings
from collections.abc import Mapping

from ruamel.yaml.error import YAMLError
from .common.grammar_types import CustomMixed, AlwaysQString, Array, Bool, Keyword, Integer
from .common.container_definitions import SectionDefinition, ConfigurationRootDefinition
from .common.configuration_containers import RootConfigurationContainer, Section as ConfigurationSection
from .common.value_definitions import ValueDefinition
from .common.generated_configuration_definitions import GeneratedValueDefinition
from .common.options import Option
from .profiles import ProfilesConfigurationContainer
import platformdirs


[docs] class Section(SectionDefinition): info_in_data_description = True dir_common_attributes = False
[docs] class ExecutionProfile(ConfigurationSection): """Mutable named execution profile stored in ASE2SPRKKR configuration.""" read_only = False
[docs] class ProfilesSection(Section): """Definition of the dict-like named execution-profile section.""" result_class = ExecutionProfile repeated_class = ProfilesConfigurationContainer
[docs] def _get_suffix(*_): return os.environ.get("SPRKKR_EXECUTABLE_SUFFIX", "")
[docs] def _legacy_value(section, name, default=None): return section._container.profiles.legacy_value(name, default)
[docs] def _set_legacy_value(section, value, name): section._container.profiles._set_legacy_value(name, value)
[docs] def _legacy_mpi(section): return _legacy_value(section, "mpi", "auto")
[docs] def _set_legacy_mpi(section, value): _set_legacy_value(section, value, "mpi")
[docs] def _legacy_mpi_warning(section): return _legacy_value(section, "mpi_warning", True)
[docs] def _set_legacy_mpi_warning(section, value): _set_legacy_value(section, value, "mpi_warning")
[docs] def _legacy_executable_dir(section): return _legacy_value(section, "executable_dir")
[docs] def _set_legacy_executable_dir(section, value): _set_legacy_value(section, value, "executable_dir")
[docs] def _legacy_executable_suffix(section): return _legacy_value(section, "executable_suffix", _get_suffix)
[docs] def _set_legacy_executable_suffix(section, value): _set_legacy_value(section, value, "executable_suffix")
[docs] def user_preferences_directory(): """Return the ASE2SPRKKR user configuration directory.""" return platformdirs.user_config_dir("ase2sprkkr", "ase2sprkkr")
[docs] def user_preferences_file(): """Return the preferred YAML user configuration filename.""" return os.path.join(user_preferences_directory(), "config.yaml")
[docs] def legacy_user_preferences_file(): """Return the optional Python user-configuration hook filename.""" return os.path.join(user_preferences_directory(), "__init__.py")
[docs] def _load_legacy_user_preferences(file): import types import importlib.machinery loader = importlib.machinery.SourceFileLoader("ase2sprkkr.personal", file) mod = types.ModuleType(loader.name) loader.exec_module(mod)
[docs] def _profile_overlay_values(yaml_file): """Return profile values from the Python hook not overridden by YAML.""" from .configuration_yaml import load_yaml_document python_profiles = { name: profile.as_dict(only_changed="explicit", generated=False) or {} for name, profile in config.profiles._raw_items() } if not python_profiles: return {} document = load_yaml_document(yaml_file) yaml_profiles = document.get("profiles", {}) if not isinstance(yaml_profiles, Mapping): return {} overlay = {} for name, values in python_profiles.items(): if name not in yaml_profiles: overlay[name] = values continue yaml_values = yaml_profiles[name] if not isinstance(yaml_values, Mapping): continue missing = {key: value for key, value in values.items() if key not in yaml_values} if missing: overlay[name] = missing return overlay
[docs] def load_user_preferences(): """Load the Python hook and then overlay ``config.yaml`` if present. Invalid YAML values are recovered individually. An unreadable YAML *document* cannot be recovered, so its values are skipped with a warning and the original file is kept unchanged. Unexpected loader and Python-hook exceptions still propagate. """ from .configuration_yaml import ( InvalidYamlDocumentError, YamlConfigurationWarning, load_configuration_yaml, ) yaml_file = user_preferences_file() legacy_file = legacy_user_preferences_file() if os.path.isfile(legacy_file): _load_legacy_user_preferences(legacy_file) if os.path.isfile(yaml_file): try: overlay = _profile_overlay_values(yaml_file) load_configuration_yaml(config, yaml_file) except (YAMLError, InvalidYamlDocumentError) as exc: # A syntax error makes the whole YAML document unusable. Do not # hide programming errors from the loader or mutate the bad file. warnings.warn( f"Cannot parse ASE2SPRKKR configuration '{yaml_file}':\n" f"{exc}\nThe file was not changed and its YAML values were not loaded.", YamlConfigurationWarning, stacklevel=2, ) return if overlay: with config.profiles._mutation("set") as (transaction, _policy): config.profiles._stage_persisted( transaction, overlay, unknown="fail", merge=True, )
[docs] class Configuration(RootConfigurationContainer):
[docs] def _generic_info(self): return "ASE2SPRKKR Configuration"
[docs] def save_user_preferences(self, *, system=False): """Persist staged ASE profile values and explicit YAML configuration. ASE-owned settings are written into ASE config.ini, not copied to ASE2SPRKKR YAML. System-wide writes require system=True. """ from .configuration_yaml import load_yaml_document, save_configuration_yaml # Do not save YAML if persisting the ASE profile fails. self.profiles.save_ase_changes(system=system) file = user_preferences_file() document = load_yaml_document(file) if os.path.isfile(file) else None save_configuration_yaml(self, file, document)
[docs] class ConfigurationOption(Option):
[docs] def set_permanent(self, value, doc=None, doc_regex=False, *, system=False): """Set and persist configuration; allow system ASE writes if requested.""" self.set(value) self.store_permanent(system=system)
[docs] def store_permanent(self, doc=None, doc_regex=False, *, system=False): """Persist staged configuration to its owning files.""" self._get_root_container().save_user_preferences(system=system)
[docs] class GeneratedConfigurationOption(ConfigurationOption): """Configuration option whose value is backed by another config object."""
[docs] class ConfigValueDefinition(ValueDefinition): result_class = ConfigurationOption
[docs] class GeneratedConfigValueDefinition(GeneratedValueDefinition): result_class = GeneratedConfigurationOption
[docs] class ConfigFileDefinition(ConfigurationRootDefinition): dir_common_attributes = False result_class = Configuration
V = ConfigValueDefinition G = GeneratedConfigValueDefinition MPI = CustomMixed( (Bool.I, Integer.I, Array(AlwaysQString.I), AlwaysQString.I), string_type=AlwaysQString.I, ) SYNC_POLICY = Keyword( { "changed": "Transfer files only when their content differs.", "always": "Always transfer files.", "missing": "Transfer files only when the destination is missing.", "never": "Never transfer files.", }, transform='lower', ) EXECUTOR = Keyword( { "local": "Run directly on this machine.", "ssh": "Run on a machine reached by SSH.", "psij": "Submit through local PSI/J (legacy location shorthand).", }, transform='lower', ) """ The definition of ASE2SPRKKR configuration """ definition = ConfigFileDefinition( "config", [ V( "default_profile", AlwaysQString.I, is_optional=True, info="Explicit default execution profile. If unset, ASE and legacy profiles may be used as fallbacks.", ), ProfilesSection( "profiles", [ V( "mpi", MPI, default_value="auto", is_optional=True, info='MPI runner for this profile. Defaults to "auto" and accepts the same values as the legacy running.mpi option.', ), V( "mpi_warning", True, info="Whether missing MPI support should be reported for this profile.", ), V( "executable_dir", AlwaysQString.I, is_optional=True, info="Directory containing SPR-KKR executables for this profile.", ), V( "executable_suffix", AlwaysQString.I, is_optional=True, info="Suffix appended to SPR-KKR executable names for this profile.", ), V( "executor", EXECUTOR, is_optional=True, info="Execution location: local, ssh or legacy psij. Use backend to select direct, kkrunner or psij.", ), V( "backend", Keyword({ "direct": "Run without an installed supervisor (limited reattachment).", "kkrunner": "Supervised process with durable completion information.", "psij": "PSI/J scheduler.", }, transform='lower'), is_optional=True, info="KKRunner backend, independent of local/SSH transport.", ), V( "host", AlwaysQString.I, is_optional=True, info="SSH destination for an ssh executor, for example user@cluster.", ), V( "local_root", AlwaysQString.I, is_optional=True, info="Local root mapped into the remote workspace by an ssh executor.", ), V( "remote_root", AlwaysQString.I, is_optional=True, info="Remote root used for persistent workspaces by an ssh executor.", ), V( "ssh_options", Array(AlwaysQString.I), is_optional=True, info="Additional arguments passed to ssh, such as ['-p', '2222'].", ), V( "filesystem_id", AlwaysQString.I, is_optional=True, info="Shared target filesystem identity for SSH aliases or shared mounts.", ), V( "ssh_zstd", False, info="Use tar --zstd for batch SSH file transfers (requires zstd on both ends).", ), V( "remote_command", Array(AlwaysQString.I), is_optional=True, info="Deprecated remote service command. Use remote_python for the Python RPC transport.", ), V( "remote_python", Array(AlwaysQString.I), is_optional=True, info="Python command on the SSH host, e.g. ['python3'].", ), V( "input_sync", SYNC_POLICY, is_optional=True, info="Input-file synchronization policy for an ssh executor.", ), V( "output_sync", SYNC_POLICY, is_optional=True, info="Output-file synchronization policy for an ssh executor.", ), V( "psij_backend", AlwaysQString.I, is_optional=True, info="PSI/J executor backend, for example slurm or pbs.", ), V( "psij_url", AlwaysQString.I, is_optional=True, info="Optional PSI/J executor URL.", ), ], is_repeated="DICT_SECTION", is_optional=True, info="Named SPR-KKR execution profiles. Reserved 'default' selects the active profile; 'ase' is a virtual editable view of ASE config.ini; 'legacy' is persisted but read-only through the profiles API.", ), Section( "running", [ V( "empty_spheres", Keyword( { True: "Always do empty spheres finding.", False: "Newer do empty spheres finding.", "auto": "Do empty spheres finding for unconverged potential not containing any vaccuum atom.", }, transform=None, quote='"', ), default_value="auto", info="Run empty spheres finding before calculation? Default value ``auto`` means only for SCF calculations not containing any vacuum atom.", ), V( "print_output", CustomMixed( (Bool.I, Array(AlwaysQString.I, as_list=tuple), AlwaysQString.I), string_type=AlwaysQString.I, ), default_value=("info","ERROR"), info="Print all (True), no output (False), short SCF summary ('info'), regex-matching lines, or combine modes in a tuple.", ), G( "mpi", _legacy_mpi, _set_legacy_mpi, is_optional=True, info='Deprecated compatibility option backed by profiles["legacy"].', ), G( "mpi_warning", _legacy_mpi_warning, _set_legacy_mpi_warning, is_optional=True, info='Deprecated compatibility option backed by profiles["legacy"].', ), ], info="Default values for SPRKKR calculator parameters.", ), Section( "executables", [ G( "suffix", _legacy_executable_suffix, _set_legacy_executable_suffix, is_optional=True, info='Deprecated compatibility option backed by profiles["legacy"].', ), G( "dir", _legacy_executable_dir, _set_legacy_executable_dir, is_optional=True, info='Deprecated compatibility option backed by profiles["legacy"].', ), ], info="Deprecated compatibility view of the legacy execution profile.", ), Section("nomad", [V("token", AlwaysQString.I, info="Token for NOMAD upload", is_optional=True)]), ], ) config = definition.create_object()