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 _TaskFileFormatter(string.Formatter):
[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]