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