Source code for ase2sprkkr.input_parameters.task_definition

"""Task-level metadata and registries for SPR-KKR calculations."""

from __future__ import annotations

from dataclasses import dataclass, replace
import os
import string
from typing import Callable, Iterable, Optional, Tuple, Union

from .definitions._filenames import dataset_adsi
from ..common.doc import process_input_parameters_definition
from ..common.module_registry import (
    ModuleRegistry,
    RegistryDefinitionError,
    RegistryEntryNotFound,
)


_FilePath = Union[str, os.PathLike[str]]
_FileTemplate = Union[_FilePath, Callable[[object], Optional[_FilePath]]]


[docs] def _normalize_identifier(value: str, field: str) -> str: if not isinstance(value, str): raise TypeError(f"{field} must be a string") value = value.strip() if not value: raise ValueError(f"{field} must not be empty") return value.upper()
[docs] def _validate_executable(value: str) -> str: if not isinstance(value, str): raise TypeError("executable must be a string") if not value.strip(): raise ValueError("executable must not be empty") return value
from kkrunner import TaskFile
[docs] class _MissingTaskFileValue(ValueError): """Optional filename template field is unset."""
[docs] class _TaskFileFormatter(string.Formatter):
[docs] def __init__(self, parameters): self.parameters = parameters
[docs] def get_field(self, field_name, args, kwargs): if field_name in ("DATASET", "dataset"): value = self.parameters.CONTROL.DATASET() elif field_name == "DATASET_ADSI": value = dataset_adsi(self.parameters) else: value = self.parameters for key in field_name.split("."): value = value[key] if callable(value): value = value() if value is None: raise _MissingTaskFileValue(field_name) if value == "": raise ValueError(f"TaskFile template field {field_name!r} must not be empty") return value, field_name
[docs] def _normalize_task_files(files: Iterable[_FileTemplate], field: str) -> Tuple[TaskFile, ...]: if isinstance(files, (str, bytes, os.PathLike)) or callable(files): raise TypeError(f"{field} must be an iterable of path-like strings or TaskFile declarations") try: iterator = iter(files) except TypeError: raise TypeError(f"{field} must be an iterable of path-like strings or TaskFile declarations") from None normalized = [] for index, item in enumerate(iterator): try: normalized.append(item if isinstance(item, TaskFile) else TaskFile(item)) except (TypeError, ValueError) as exc: raise type(exc)(f"{field}[{index}]: {exc}") from None return tuple(normalized)
[docs] @dataclass(frozen=True, init=False) class TaskDefinition: """Immutable declarative metadata identifying one SPR-KKR task. Convenience methods delegate task-bound operations to their owning service registries; resolution and parsing policy does not live in this value object. """ input_parameters_definition_name: str name: str executable: str mpi: bool experimental: bool output_reader_name: Optional[str] input_files: Tuple[TaskFile, ...] output_files: Tuple[TaskFile, ...] cache_files: Tuple[TaskFile, ...]
[docs] def __init__( self, input_parameters_definition_name: str, *, name: Optional[str] = None, executable: str = "kkrscf", mpi: bool = True, experimental: bool = False, output_reader_name: Optional[str] = None, output_reader: Optional[str] = None, input_files: Iterable[_FileTemplate] = (), output_files: Iterable[_FileTemplate] = (), cache_files: Iterable[_FileTemplate] = (), ) -> None: schema_name = _normalize_identifier( input_parameters_definition_name, "input_parameters_definition_name" ) task_name = ( schema_name if name is None else _normalize_identifier(name, "name") ) executable = _validate_executable(executable) if type(mpi) is not bool: raise TypeError("mpi must be a bool") if type(experimental) is not bool: raise TypeError("experimental must be a bool") if output_reader_name is not None and output_reader is not None: raise TypeError( "Specify only one of output_reader_name and output_reader" ) if output_reader_name is None: output_reader_name = output_reader if output_reader_name is not None: if not isinstance(output_reader_name, str): raise TypeError("output_reader must be a string or None") output_reader_name = _normalize_identifier( output_reader_name, "output_reader" ) object.__setattr__(self, "input_parameters_definition_name", schema_name) object.__setattr__(self, "name", task_name) object.__setattr__(self, "executable", executable) object.__setattr__(self, "mpi", mpi) object.__setattr__(self, "experimental", experimental) object.__setattr__(self, "output_reader_name", output_reader_name) for kind, values in ( ("input", input_files), ("output", output_files), ("cache", cache_files), ): object.__setattr__( self, f"{kind}_files", _normalize_task_files(values, f"{kind}_files"), )
[docs] def output_reader( self, input_parameters=None, calculator=None, print_info=False, directory=None, ): """Create this task's output reader through the reader registry.""" from ..outputs.reader_registry import reader_registry return reader_registry.reader_for_task( self, input_parameters=input_parameters, calculator=calculator, print_info=print_info, directory=directory, )
[docs] def read_output_from_file( self, filename, *, input_parameters=None, calculator=None, directory=None, ): """Read a completed output file through the task's registered reader.""" from ..outputs.reader_registry import reader_registry return reader_registry.read_for_task( self, filename, input_parameters=input_parameters, calculator=calculator, directory=directory, )
[docs] class TaskMismatchError(ValueError): """Parsed input values represent a different task than expected.""" def __init__(self, expected_task_name, task_name): self.expected_task_name = expected_task_name self.task_name = task_name super().__init__( f"Input file read for task {expected_task_name!r} represents " f"task {task_name!r}" )
[docs] class InputParametersRegistry(ModuleRegistry): """Registry and factory service for input-parameter schemas and values."""
[docs] def __init__(self, package): super().__init__( package, "input_parameters_definition", factory=True, include=lambda name: not name.startswith("_") and name != "sections", )
[docs] def prepare_value(self, name, module, value): from .input_parameters_definitions import InputParametersDefinition if not isinstance(value, InputParametersDefinition): raise RegistryDefinitionError( f"{module.__name__}.input_parameters_definition must produce " f"InputParametersDefinition, got {type(value).__name__}" ) # A differently named registry entry is a preset of its original IPD, # not another canonical schema or task. user_defined = self.is_user_defined(module) canonical = str(value.name).upper() == name task = value._task_definition if task is not None: if not isinstance(task, TaskDefinition): raise RegistryDefinitionError( f"{module.__name__}._task_definition must be TaskDefinition, " f"got {type(task).__name__}" ) if not user_defined: if task.name != name: raise RegistryDefinitionError( f"Canonical task {task.name} does not match input schema {name}" ) if task.input_parameters_definition_name != name: raise RegistryDefinitionError( f"Canonical task {task.name} references input schema " f"{task.input_parameters_definition_name} instead of {name}" ) if user_defined and value.name in self: value.name = name if task is not None and task.experimental: value.experimental = True value.is_user_defined = user_defined process_input_parameters_definition(module, value) return value
[docs] def iter_canonical_values(self, *, name_contains=None): """Yield canonical IPDs, excluding named copies used as presets.""" yield from self.iter_valid_values(include_aliases=False, name_contains=name_contains, condition=lambda d: not d.is_derived_definition())
[docs] def definition_for_task(self, task): """Return the schema identified by declarative task metadata.""" if not isinstance(task, TaskDefinition): raise TypeError("task must be a TaskDefinition") definition = self[task.input_parameters_definition_name] return definition
[docs] def create_for_task( self, task, *, inputfile=None, outputfile=False, ): """Create InputParameters for a resolved TaskDefinition.""" from .input_parameters import InputParameters definition = self.definition_for_task(task) return InputParameters( definition=definition, requested_task_name=task.name, inputfile=inputfile, outputfile=outputfile, )
[docs] def read_for_task( self, task, file, *, input_definition=None, allow_dangerous=False, allow_incomplete=False, report_invalid=None, ): """Read input with an exact schema and require it to represent *task*. ``input_definition`` is primarily for historical reconstruction: when omitted, the task's current declared schema is used. Passing a schema name or definition selects that exact schema. An explicit definition object may intentionally be unregistered, which supports experimental or custom parsers while retaining the task-identity check. In strict mode the expected task is not supplied as parsing context. In incomplete mode it is available to callable defaults, but any explicit selector in the file must still agree with the expected task. This allows recovery of a partial file without silently overriding a conflicting task identity. """ from .input_parameters_definitions import InputParametersDefinition if input_definition is None: definition = self.definition_for_task(task) elif isinstance(input_definition, str): definition = self[input_definition] elif isinstance(input_definition, InputParametersDefinition): definition = input_definition else: raise TypeError( "input_definition must be an InputParametersDefinition, string, or None" ) out = definition.read_from_file( file, allow_dangerous=allow_dangerous, allow_incomplete=allow_incomplete, inputfile=file, **({"requested_task_name": task.name} if allow_incomplete else {}), **({"report_invalid": report_invalid} if report_invalid is not None else {}), ) task_name = out.task_name if task_name != task.name: raise TaskMismatchError(task.name, task_name) out._requested_task_name = task.name return out
[docs] def create_from_result(self, task, result): """Create InputParameters for *task* using snapshot defaults from *result*.""" definition = self.definition_for_task(task) out = self.create_for_task(task) definition.initialize_from_result(out, result) return out
[docs] @staticmethod def _resolve_file_templates(parameters, directory, templates): """Resolve templates to concrete TaskFile values without losing metadata.""" formatter = _TaskFileFormatter(parameters) files = [] for value in templates: declaration = value if isinstance(value, TaskFile) else TaskFile(value) pathname = declaration.pathname if callable(pathname): pathname = pathname(parameters) if pathname is None: continue if isinstance(pathname, TaskFile): declaration = pathname pathname = declaration.pathname path = os.fspath(pathname) if not isinstance(path, str): raise TypeError("File callback must return a string/path or None") if not path: raise ValueError("TaskFile pathname must not be empty") try: path = formatter.format(path) except _MissingTaskFileValue as exc: if declaration.optional: continue raise ValueError( f"Required TaskFile template {path!r} has unset field {exc}" ) from exc resolved = path if os.path.isabs(path) else os.path.join(directory, path) files.append(replace(declaration, pathname=resolved)) return tuple(files)
[docs] def files_for_task(self, task, parameters, directory, kind): """Combine declarative task templates with schema-specific file rules.""" definition = self.definition_for_task(task) declared = self._resolve_file_templates( parameters, directory, getattr(task, f"{kind}_files") ) schema_files = getattr(definition, f"{kind}_files")(parameters, directory) # Keep schema extension hooks; shared resolution lives in this registry. # A TaskFile retains metadata, while plain paths remain valid shorthands. schema_files = tuple( value if isinstance(value, TaskFile) else TaskFile(value) for value in schema_files ) return (*declared, *schema_files)
[docs] class _ExtraTaskRegistry(ModuleRegistry): """Validate explicit task declarations at materialization time."""
[docs] def __init__(self, package, input_parameters_registry): super().__init__(package, "task_definition", factory=True) self.input_parameters_registry = input_parameters_registry
[docs] def prepare_value(self, name, module, task): if not isinstance(task, TaskDefinition): raise RegistryDefinitionError( f"Extra task {name} must be TaskDefinition, got {type(task).__name__}" ) if task.name != name: raise RegistryDefinitionError( f"Extra task {task.name} is registered as {name}" ) try: self.input_parameters_registry.definition_for_task(task) except RegistryEntryNotFound: raise RegistryDefinitionError( f"Task {task.name} references unknown input schema " f"{task.input_parameters_definition_name}" ) from None return task
[docs] class TaskRegistry: """Authoritative namespace and resolver for SPR-KKR task identities. Task declarations intentionally have two sources. A schema with exactly one canonical task may co-locate its :class:`TaskDefinition` on the ``InputParametersDefinition`` as ``_task_definition``; this keeps the common one-schema/one-task case simple and declarative. Tasks sharing one input schema are declared separately in the extra task package and refer to that schema by name. The registry owns the task namespace and resolution rules, not necessarily the physical location of each declaration. Consumers should resolve task identities through this registry rather than reading ``_task_definition`` directly. """ normalize_name = staticmethod(ModuleRegistry.normalize_name)
[docs] def __init__(self, input_parameters_registry, extra_tasks_package): self.input_parameters_registry = input_parameters_registry self.extra_tasks = _ExtraTaskRegistry( extra_tasks_package, input_parameters_registry )
[docs] def _input_task(self, name): """ Tasks, defined by the input_parameters """ try: definition = self.input_parameters_registry[name] except RegistryEntryNotFound: return None task = definition._task_definition """ Maybe, the definition just use task from another "canonical" definition """ if task and task.name == name: return task else: return None
[docs] def _extra_task(self, name): """ Tasks, defined separatelly, to be shared by more tasks """ try: return self.extra_tasks[name] except RegistryEntryNotFound: return None
def __getitem__(self, name): name = self.normalize_name(name) input_task = self._input_task(name) extra_task = self._extra_task(name) if input_task is not None and extra_task is not None: raise RegistryDefinitionError( f"Task {name} is defined both by an input schema and explicitly" ) if extra_task is not None: return extra_task if input_task is not None: return input_task raise RegistryEntryNotFound(name) def __contains__(self, name): try: self[name] except RegistryEntryNotFound: return False return True
[docs] def names(self, *, name_contains=None): """Enumerate valid tasks; broken unrelated definitions are skipped.""" names = {task.name for task in self.extra_tasks.iter_valid_values(name_contains=name_contains)} for schema in self.input_parameters_registry.iter_canonical_values(name_contains=name_contains): task = schema._task_definition if task is None: continue name = task.name if name in names: raise RegistryDefinitionError( f"Task {name} is defined both by an input schema and explicitly" ) names.add(name) return tuple(sorted(names))
[docs] def values(self, *, name_contains=None): return tuple(self[name] for name in self.names(name_contains=name_contains))
[docs] def task_for_parameters(self, parameters): """Resolve the task represented by concrete parameter values.""" name = parameters.task_name return None if name is None else self[name]