httk.workflow.languages.jobflow¶

Prepare atomate2 jobflow Maker workflows for httk workflow jobs.

Declared workflow parameters are Maker constructor configuration: the runner builds Class(**params) for the maker= form and dataclasses.replace(maker, **params) for the document form, so declared parameters override document Maker fields; language plumbing parameters are reserved-prefixed and never Maker-bound.

Attributes¶

`FILES_DIRECTORY`
`PACKAGE`
`RUNNER`
`DOCUMENT_FILE`
`STAGED_DIRECTORY`
`DEFAULT_DATA_PREFIX`
`OUTPUTS_FILE`
`LANGUAGE`

Exceptions¶

JobflowFormatError

A jobflow Maker document or runner configuration is invalid.

Classes¶

`LanguagePorts`	The named input and output ports of one language document.
`LanguageRequest`	The data supplied when preparing one language workflow.
`LanguageScaffold`	The files, runner, and hooks prepared for one language workflow.
`WorkflowLanguage`	The operations a workflow language exposes to the common layer.

Functions¶

`runner_reference`(package, name)	Return the `runner` member of a `job.json` running one packaged runner.
`payload_relative`(name)	Return where one staged file lands inside a payload.
`collect`(record)	Convert one jobflow runner output document into provenance records.
`document_from_maker`(maker)	Serialize one MSONable Maker using monty.

Package Contents¶

class httk.workflow.languages.jobflow.LanguagePorts[source]¶

The named input and output ports of one language document.

Parameters:

inputs – Names of the document’s input ports.
outputs – Names of the document’s output ports.

inputs: tuple[str, Ellipsis]¶

outputs: tuple[str, Ellipsis]¶

class httk.workflow.languages.jobflow.LanguageRequest[source]¶

The data supplied when preparing one language workflow.

Parameters:

workflow_id – Identify the workflow being prepared.
directory – Locate the workflow package, when it has one.
document – Locate the source workflow document, when it has one.
runner_options – Supply options for the language runner.
inputs – Describe the workflow inputs.
outputs – Describe the requested workflow outputs.
parameters – Describe the declared workflow parameters.
environment – Describe the declared workflow environment.
excluded_members – Package members the realization must not stage.

workflow_id: str¶

directory: pathlib.Path | None¶

document: pathlib.Path | None¶

runner_options: collections.abc.Mapping[str, object]¶

inputs: collections.abc.Mapping[str, collections.abc.Mapping[str, object]]¶

outputs: collections.abc.Mapping[str, collections.abc.Mapping[str, object]]¶

parameters: collections.abc.Mapping[str, collections.abc.Mapping[str, object]]¶

environment: collections.abc.Mapping[str, collections.abc.Mapping[str, object]]¶

excluded_members: tuple[str, Ellipsis] = ()¶

class httk.workflow.languages.jobflow.LanguageScaffold[source]¶

The files, runner, and hooks prepared for one language workflow.

Parameters:

documents – Text or byte documents to write into the payload.
files – Files to stage into the payload.
parameters – Job parameters produced by preparation.
runner – Runner description for the job, when one is supplied.
runner_executor – Select the runner executor.
payload_runner – Name a runner staged in the payload.
workdir_path – Name the workdir below the job payload.
required_capabilities – Require these manager capabilities.
reserved_parameters – Names reserved for per-job realization output.
warnings – Preserve preparation warnings.
instantiate – Supply the per-job hook called after input staging.
finalize – Transform the per-job JobSpec immediately before its payload is prepared.

documents: collections.abc.Mapping[str, str | bytes]¶

files: collections.abc.Mapping[str, pathlib.Path]¶

parameters: collections.abc.Mapping[str, object]¶

runner: collections.abc.Mapping[str, object] | None¶

runner_executor: str = 'path'¶

payload_runner: str | None = None¶

workdir_path: str | None = None¶

required_capabilities: tuple[str, Ellipsis] = ()¶

reserved_parameters: tuple[str, Ellipsis] = ()¶

warnings: tuple[str, Ellipsis] = ()¶

instantiate: collections.abc.Callable[[httk.workflow.scaffold.InstantiateContext], object] | None = None¶

finalize: collections.abc.Callable[[httk.workflow.runtime_builders.JobSpec], httk.workflow.runtime_builders.JobSpec] | None = None¶

class httk.workflow.languages.jobflow.WorkflowLanguage[source]¶

The operations a workflow language exposes to the common layer.

Parameters:

name – Name the language.
steps – Declare the runner’s steps.
initial_step – Select the runner’s initial step.
matches – Identify documents belonging to the language.
ports – Read the input and output ports of a document.
validate_runner – Validate runner options for a document.
prepare – Prepare a language request for execution.
collect – Convert a completed job record into language outputs.
document_policy – State whether package manifests require, allow, or forbid a source document.
open_ports – Skip manifest port validation when document ports cannot be enumerated statically.
has_default_collector – Provide a default collector path.
allows_modes – Permit manifest data and workdir mode overrides.
environment – Declare language-provided environment metadata.
required_modules – Name the importable modules a job of this language needs at run time.

name: str¶

steps: tuple[str, Ellipsis]¶

initial_step: str¶

matches: collections.abc.Callable[[pathlib.Path], bool]¶

ports: collections.abc.Callable[[pathlib.Path], LanguagePorts]¶

validate_runner: collections.abc.Callable[[collections.abc.Mapping[str, object], pathlib.Path], None]¶

prepare: collections.abc.Callable[[LanguageRequest], LanguageScaffold]¶

collect: collections.abc.Callable[[httk.workflow.collecting.JobRecord], collections.abc.Mapping[str, object]]¶

document_policy: DocumentPolicy = 'required'¶

open_ports: bool = False¶

has_default_collector: bool = True¶

allows_modes: bool = True¶

environment: collections.abc.Mapping[str, collections.abc.Mapping[str, object]]¶

required_modules: tuple[str, Ellipsis] = ()¶

httk.workflow.languages.jobflow.runner_reference(package, name)[source]¶

Return the runner member of a job.json running one packaged runner.

The reserved pkg: form names the runner inside its own consumer package, and the digest is taken from the installed bytes, which is exactly what the manager verifies before it stages and executes them.

httk.workflow.languages.jobflow.FILES_DIRECTORY = 'files'[source]¶

httk.workflow.languages.jobflow.payload_relative(name)[source]¶

Return where one staged file lands inside a payload.

A bare name lands in FILES_DIRECTORY, so POSCAR becomes files/POSCAR — where the packaged runners read it — and a name that carries a directory of its own is used exactly as it is written.

Parameters:

name (str) – Name the staged file within the payload.

Returns:

The validated payload-relative destination.

Raises:

httk.workflow.errors.FormatError – If the name uses a reserved payload member.
ValueError – If the name is empty or absolute.

Return type:

pathlib.PurePosixPath

httk.workflow.languages.jobflow.PACKAGE = 'httk.workflow.languages.jobflow'[source]¶

httk.workflow.languages.jobflow.RUNNER = 'jobflow_runner.py'[source]¶

httk.workflow.languages.jobflow.DOCUMENT_FILE = 'files/maker.json'[source]¶

httk.workflow.languages.jobflow.STAGED_DIRECTORY = 'files/inputs'[source]¶

httk.workflow.languages.jobflow.DEFAULT_DATA_PREFIX = 'jobflow'[source]¶

httk.workflow.languages.jobflow.OUTPUTS_FILE = 'jobflow-outputs.json'[source]¶

exception httk.workflow.languages.jobflow.JobflowFormatError[source]¶

Bases: ValueError

A jobflow Maker document or runner configuration is invalid.

httk.workflow.languages.jobflow.collect(record)[source]¶

Convert one jobflow runner output document into provenance records.

Parameters:: record (httk.workflow.collecting.JobRecord) – The completed job record containing runner outputs.
Returns:: Output records keyed by their declared workflow roles.
Return type:: collections.abc.Mapping[str, object]

httk.workflow.languages.jobflow.document_from_maker(maker)[source]¶

Serialize one MSONable Maker using monty.

Parameters:: maker (object) – A Maker object exposing as_dict().
Returns:: A sorted, indented JSON Maker document.
Raises:: JobflowFormatError – If maker has no usable MSONable document.
Return type:: str

Monty must be installed when this helper is called.

httk.workflow.languages.jobflow.LANGUAGE[source]¶