diffpes.certify¶

JAX-native certified forward execution, scientific evidence, provenance, information-flow analysis, policy evaluation, and certificate inspection.

Certify differentiable DiffPES forward-model executions.

Extended Summary¶

The certification package combines static scientific identity and provenance with numerical evidence from the actual JAX forward program. Canonical records and CRC32 checksums provide non-security bookkeeping at the I/O boundary; they do not establish physical validity. Runtime claims, derivative checks, dependency maps, sensitivities, and information spectra are JAX-native numerical carriers.

The package contains these submodules:

canonical
Represent scientific records canonically for certification.
checksums
Compute non-security consistency checksums for scientific records.
checks
Register pure JAX scientific certification checks.
contracts
Define semantic contracts for composable certified transformations.
registry
Register certified models and transformations deterministically.
provenance
Trace artifact lineage and semantic information loss.
dependencies
Trace differentiable information flow through forward models.
evidence
Build differentiable evidence for certified forward models.
resolvers
Resolve certificate artifacts and verify external evidence.
reproduction
Reproduce a certified forward result from resolved artifacts.
policy
Evaluate cumulative scientific-certification policies.
execution
Execute JAX-native certified forward models.
inspect
Render forward-model certificates in a human-readable form.
models
Register built-in certified DiffPES forward models.
waivers
Validate bounded policy-waiver records at the I/O boundary.

Routine Listings¶

achieved_levels(): Return certification level names achieved by a concrete report.
artifact_ref(): Build separate byte, normalized-content, and semantic identities.
build_provenance(): Build a deterministic provenance DAG and propagate information.
canonical_json(): Return deterministic typed JSON bytes for value.
canonical_pytree(): Return canonical bytes for a supported carrier or PyTree.
certify_forward(): Execute a prepared model and produce a certified JAX PyTree.
certify_forward_checked(): Execute certification and return structured hard-domain errors.
checksum_bytes(): Return a non-security consistency checksum for data.
checksum_chunks(): Compute a consistency checksum over consecutive byte chunks.
checksum_file(): Stream exact file bytes into a consistency checksum.
checksum_pytree(): Stream a canonical carrier into a consistency checksum.
compose_transformations(): Compose contracts and raise for unsatisfied requirements.
clear_dependency_cache(): Clear the eager cache for structural dependency analyses.
dependency_cache_info(): Return cache size, hit count, and miss count.
dependency_map(): Trace leaf-level structural and local numerical dependencies.
derivative_evidence(): Compare JAX information flow with batched finite differences.
diff_certificates(): Compare two certificates by scientific meaning and record class.
effective_information(): Return propagated semantics, losses, and invalidations for one node.
evaluate_claim(): Evaluate a numerical claim and preserve residual and margin leaves.
evaluate_domain(): Evaluate a symmetric domain predicate around a reference value.
evaluate_evidence(): Compare measured values with an external numerical reference.
evaluate_policy(): Derive cumulative certification outcomes from numerical claims.
execute_tb_radial(): Execute the radial ARPES model from one certification input PyTree.
explain_claim(): Explain one claim and the numerical evidence supporting it.
freeze_registry(): Prevent later registration and return the final immutable snapshot.
filesystem_artifact_resolver(): Resolve a byte-valued artifact from its local locator.
get_check(): Resolve a registered JAX certification check.
get_model(): Resolve an exact registered model.
get_transformation(): Resolve an exact registered transformation contract.
information_spectrum(): Estimate the leading local information spectrum matrix-free.
invalidated_claims(): Return every claim invalidated at or upstream of one output.
iter_canonical_pytree_chunks(): Yield canonical carrier bytes in bounded chunks.
lineage(): Return the transitive parent-node lineage of one output.
linearized_forward(): Evaluate a forward model and retain its JVP linearization.
list_checks(): List registered checks in deterministic identity order.
list_handshakes(): Return owner handshakes in deterministic identity order.
list_models(): Return model specifications in deterministic identity order.
list_registered_models(): Return an immutable deterministic snapshot including executors.
list_transformations(): Return transformation contracts in deterministic identity order.
parse_checksum(): Parse and validate one checksum string.
packaged_model_card(): Read the packaged generated card for one model identity.
prepare_certification(): Resolve static scientific records before compiled execution.
mapping_artifact_resolver(): Build a deterministic resolver from normalized in-memory values.
register_handshake(): Register declarative requirements from one owning plan.
register_builtin_models(): Register built-in models and information-loss transformations.
register_check(): Register a stable predicate identity and pure JAX callable.
register_model(): Register an exact model identity once.
register_transformation(): Register an exact transformation contract once.
registry_snapshot(): Return one internally consistent immutable registry snapshot.
registry_manifest(): Read the packaged registry manifest.
render_model_card(): Render a model card directly from a model specification.
reproduce_forward(): Re-execute a registered model and compare its recorded result.
require_active_waivers(): Reject malformed, expired, or premature waiver records.
resolve_artifact(): Resolve and validate one referenced artifact.
result_checksum(): Identify a result under a declared numerical configuration.
semantic_checksum(): Identify content together with its declared scientific meaning.
sensitivity_map(): Measure scaled JVP sensitivities for a batch of tangent directions.
summarize_certificate(): Return a deterministic human-readable certificate summary.
tb_radial_model_spec(): Return the stable scientific specification for radial ARPES.
validate_composition(): Validate and conservatively compose transformation semantics.
validate_contract(): Return structural errors for a raw or deserialized contract.
validate_handshake(): Validate one owner handshake against available records.
validate_provenance(): Re-evaluate graph structure and derived state independently.
validate_registry(): Recompute registry structure and consistency checksums.
validate_registry_manifest(): Compare the packaged registry manifest with live entries.
validate_waiver(): Validate one waiver against an explicit absolute UTC time.
validate_waivers(): Validate multiple waivers against one explicit absolute UTC time.
verify_evidence(): Verify referenced artifacts and recorded numerical residuals.
verify_certificate(): Re-evaluate numerical claim and policy consistency without a rerun.

diffpes.certify.canonical_json(value: object) → bytes[source]¶

Return deterministic typed JSON bytes for value.

The record preserves scalar, container, array-dtype, and array-shape identity. It rejects values that have no finite deterministic representation.

See:: TestCanonicalJson

Implementation Logic¶

Bind the documented output:
```
encoded: bytes = CANONICAL_JSON_PREFIX + payload
```
The function validates and transforms the inputs before it binds the documented output.

param value:: JSON-like data. Mapping keys must be strings. The function accepts tuples and distinguishes them from lists.
type value:: object
returns:: encoded – Versioned canonical UTF-8 JSON record.
rtype:: bytes

diffpes.certify.canonical_pytree(tree: object) → bytes[source]¶

Return canonical bytes for a supported carrier or PyTree.

The record preserves scalar, container, array-dtype, and array-shape identity. It rejects values that have no finite deterministic representation.

See:: TestCanonicalPytree
Parameters:: tree (object) – Supported nested scientific content. The record represents Equinox modules through their dataclass fields, including static metadata.
Returns:: encoded – Complete versioned canonical record.
Return type:: bytes

Notes

Use iter_canonical_pytree_chunks() for a streaming checksum of a large array.

diffpes.certify.iter_canonical_pytree_chunks(tree: object, *, chunk_bytes: int = CANONICAL_ARRAY_CHUNK_BYTES) → Iterator[bytes | memoryview][source]¶

Yield canonical carrier bytes in bounded chunks.

The record preserves scalar, container, array-dtype, and array-shape identity. It rejects values that have no finite deterministic representation.

See:: TestIterCanonicalPytreeChunks

Implementation Logic¶

Bind the documented output:
```
yield from _iter_value_chunks(tree, chunk_bytes=chunk_bytes)
```
The function validates and transforms the inputs before it binds the documented output.

param tree:: A supported scientific carrier or nested PyTree-like value.
type tree:: object
param chunk_bytes:: Maximum payload bytes yielded for each numerical-array chunk.
type chunk_bytes:: int, default: CANONICAL_ARRAY_CHUNK_BYTES
Yields:: chunk (bytes | memoryview) – Consecutive chunks of the canonical representation.
raises ValueError:: If chunk_bytes is not positive. This error also occurs if the tree contains an unsupported or nonfinite value.

diffpes.certify.get_check(check_id: str) → CheckFunction[source]¶

Resolve a registered JAX certification check.

The process-local registry selects pure JAX predicates by stable scientific identity. Registered functions retain continuous margins in compiled execution.

See:: TestGetCheck

Implementation Logic¶

Bind the documented output:
```
check: CheckFunction = _check_registry()[check_id]
```
The function validates and transforms the inputs before it binds the documented output.

param check_id:: Exact predicate identifier (static – a compile-time selection).
type check_id:: str
returns:: check – Registered pure JAX predicate implementation.
rtype:: Callable[[PyTree], DomainResult]
raises KeyError:: If no check has the requested identity.

diffpes.certify.list_checks() → tuple[str, ...][source]¶

List registered checks in deterministic identity order.

The process-local registry selects pure JAX predicates by stable scientific identity. Registered functions retain continuous margins in compiled execution.

See:: TestListChecks

Implementation Logic¶

Bind the documented output:
```
checks: tuple[str, ...] = tuple(sorted(_check_registry()))
```
The function validates and transforms the inputs before it binds the documented output.

returns:: checks – Sorted stable predicate identifiers.
rtype:: tuple[str, ...]

diffpes.certify.register_check(check_id: str, check_fn: CheckFunction) → None[source]¶

The process-local registry selects pure JAX predicates by stable scientific identity. Registered functions retain continuous margins in compiled execution.

See:

TestRegisterCheck

Parameters:

check_id (str) – Stable predicate identifier (static – a compile-time selection).
check_fn (Callable[[PyTree], DomainResult]) – Pure JAX predicate implementation (static – a compiled program).

Raises:

ValueError – If the identity is unstable or already registered.

Return type:

None

Notes

Registration occurs at the eager application boundary. The registered callable itself remains pure and traceable inside certification kernels.

diffpes.certify.artifact_ref(path: str | Path, normalized: object, *, role: str, media_type: str = 'application/octet-stream', semantics: object | None = None, artifact_id: str | None = None) → ArtifactRef[source]¶

Build separate byte, normalized-content, and semantic identities.

The CRC32 value detects accidental disagreement in canonical scientific records. It is bookkeeping evidence, not cryptographic authentication.

See:: TestArtifactRef

Implementation Logic¶

Bind the documented output:

reference: ArtifactRef = make_artifact_ref(
        artifact_id=resolved_id,
        media_type=media_type,
        byte_checksum=byte_value,
        content_checksum=content_value,
        semantic_checksum=semantic_value,
        locator=str(source),
        role=role,
    )

The function validates and transforms the inputs before it binds the documented output.

param path:: Source artifact with a record of its exact bytes.
type path:: str | Path
param normalized:: Parsed, normalized scientific carrier derived from the source.
type normalized:: object
param role:: Scientific role of this artifact in the execution.
type role:: str
param media_type:: Declared media type of the source bytes.
type media_type:: str, default: "application/octet-stream"
param semantics:: Meaning-bearing declarations. By default, the role and normalized carrier type form the minimal semantic descriptor.
type semantics:: object | None, default: None
param artifact_id:: Stable caller-owned identity. By default, the function derives a local identity from the byte checksum value.
type artifact_id:: str | None, default: None
returns:: reference – Immutable certification carrier with three deliberately separate consistency checksums.
rtype:: ArtifactRef

diffpes.certify.checksum_bytes(data: bytes, *, record_kind: str) → str[source]¶

Return a non-security consistency checksum for data.

The CRC32 value detects accidental disagreement in canonical scientific records. It is bookkeeping evidence, not cryptographic authentication.

See:: TestChecksumBytes

Implementation Logic¶

Bind the documented output:
```
checksum: str = checksum_chunks((data,), record_kind=record_kind)
```
The function validates and transforms the inputs before it binds the documented output.

param data:: Exact record bytes.
type data:: bytes
param record_kind:: Stable kind distinguishing otherwise equal byte payloads.
type record_kind:: str
returns:: checksum – Typed CRC32 bookkeeping value.
rtype:: str

diffpes.certify.checksum_chunks(chunks: Iterable[bytes | memoryview], *, record_kind: str) → str[source]¶

Compute a consistency checksum over consecutive byte chunks.

The CRC32 value detects accidental disagreement in canonical scientific records. It is bookkeeping evidence, not cryptographic authentication.

See:: TestChecksumChunks

Implementation Logic¶

Bind the documented output:
```
checksum: str = _format_checksum(value, record_kind=record_kind)
```
The function validates and transforms the inputs before it binds the documented output.

param chunks:: Consecutive byte-like pieces of one record.
type chunks:: Iterable[bytes | memoryview]
param record_kind:: Stable description, such as "normalized-content" or "result".
type record_kind:: str
returns:: checksum – Versioned, typed CRC32 consistency checksum.
rtype:: str

diffpes.certify.checksum_file(path: str | Path, *, record_kind: str) → str[source]¶

Stream exact file bytes into a consistency checksum.

The CRC32 value detects accidental disagreement in canonical scientific records. It is bookkeeping evidence, not cryptographic authentication.

See:: TestChecksumFile

Implementation Logic¶

Bind the documented output:
```
checksum: str = checksum_chunks(chunks(), record_kind=record_kind)
```
The function validates and transforms the inputs before it binds the documented output.

param path:: Existing regular file.
type path:: str | Path
param record_kind:: Stable record-kind label.
type record_kind:: str
returns:: checksum – Typed CRC32 bookkeeping value.
rtype:: str

diffpes.certify.checksum_pytree(tree: object, *, record_kind: str) → str[source]¶

Stream a canonical carrier into a consistency checksum.

The CRC32 value detects accidental disagreement in canonical scientific records. It is bookkeeping evidence, not cryptographic authentication.

See:: TestChecksumPytree

Implementation Logic¶

Bind the documented output:
```
checksum: str = checksum_chunks(chunks, record_kind=record_kind)
```
The function validates and transforms the inputs before it binds the documented output.

param tree:: Supported carrier or nested scientific PyTree.
type tree:: object
param record_kind:: Stable record-kind label.
type record_kind:: str
returns:: checksum – Typed CRC32 bookkeeping value.
rtype:: str

diffpes.certify.parse_checksum(checksum: str) → tuple[str, str, str, str][source]¶

Parse and validate one checksum string.

The CRC32 value detects accidental disagreement in canonical scientific records. It is bookkeeping evidence, not cryptographic authentication.

See:: TestParseChecksum

Implementation Logic¶

Bind the documented output:

parsed: tuple[str, str, str, str] = (
        CHECKSUM_ALGORITHM,
        match.group("canonical"),
        match.group("kind"),
        match.group("value"),
    )

The function validates and transforms the inputs before it binds the documented output.

param checksum:: Value produced by this module.
type checksum:: str
returns:: parsed – Algorithm, canonicalization version, record kind, and hexadecimal value.
rtype:: tuple[str, str, str, str]
raises ValueError:: If checksum is not in the current explicit format.

diffpes.certify.result_checksum(value: object, numerical: object) → str[source]¶

Identify a result under a declared numerical configuration.

The CRC32 value detects accidental disagreement in canonical scientific records. It is bookkeeping evidence, not cryptographic authentication.

See:: TestResultChecksum

Implementation Logic¶

Bind the documented output:
```
checksum: str = checksum_pytree(payload, record_kind="result")
```
The function validates and transforms the inputs before it binds the documented output.

param value:: Result carrier.
type value:: object
param numerical:: Precision, backend-independent tolerance semantics, and any other numerical configuration that defines result identity.
type numerical:: object
returns:: checksum – Non-security result consistency checksum.
rtype:: str

diffpes.certify.semantic_checksum(value: object, semantics: object) → str[source]¶

Identify content together with its declared scientific meaning.

The CRC32 value detects accidental disagreement in canonical scientific records. It is bookkeeping evidence, not cryptographic authentication.

See:: TestSemanticChecksum

Implementation Logic¶

Bind the documented output:
```
checksum: str = checksum_pytree(payload, record_kind="semantic")
```
The function validates and transforms the inputs before it binds the documented output.

param value:: Normalized scientific content.
type value:: object
param semantics:: Units, axes, frames, conventions, schema, and other meaning-bearing declarations.
type semantics:: object
returns:: checksum – Non-security semantic consistency checksum.
rtype:: str

diffpes.certify.compose_transformations(contracts: Sequence[TransformationContract], *, initial_semantics: Iterable[str] = ()) → CompositionReport[source]¶

Compose contracts and raise for unsatisfied requirements.

The operation propagates declared semantics and information loss conservatively. It never infers that an undeclared scientific property survives.

See:: TestComposeTransformations

Implementation Logic¶

Bind the documented output:
```
msg: str = "; ".join(report.errors)
```
The function validates and transforms the inputs before it binds the documented output.

param contracts:: Ordered transformation pipeline.
type contracts:: Sequence[TransformationContract]
param initial_semantics:: Properties present before the first step.
type initial_semantics:: Iterable[str], default: ()
returns:: report – Valid composition report.
rtype:: CompositionReport
raises ValueError:: If any registered semantic requirement is missing.

diffpes.certify.validate_composition(contracts: Sequence[TransformationContract], *, initial_semantics: Iterable[str] = ()) → CompositionReport[source]¶

Validate and conservatively compose transformation semantics.

The operation propagates declared semantics and information loss conservatively. It never infers that an undeclared scientific property survives.

See:

TestValidateComposition

Parameters:

contracts (Sequence[TransformationContract]) – Ordered transformation pipeline.
initial_semantics (Iterable[str], default: ()) – Properties available on the pipeline inputs.

Returns:

report – Deterministic semantics, information-loss, and claim-invalidation summary. The report contains invalid composition instead of raising an exception.

Return type:

CompositionReport

Notes

The operation treats a property as lost when preserves does not name it at that step. This rule prevents an undeclared transformation from retaining a scientific claim.

diffpes.certify.validate_contract(contract: TransformationContract) → tuple[str, ...][source]¶

Return structural errors for a raw or deserialized contract.

The operation propagates declared semantics and information loss conservatively. It never infers that an undeclared scientific property survives.

See:: TestValidateContract

Implementation Logic¶

Bind the documented output:
```
result: tuple[str, ...] = tuple(errors)
```
The function validates and transforms the inputs before it binds the documented output.

param contract:: Semantic and information-loss declaration to validate.
type contract:: TransformationContract
returns:: result – Deterministic structural error messages, empty when valid.
rtype:: tuple[str, ...]

diffpes.certify.clear_dependency_cache() → None[source]¶

Clear the eager cache for structural dependency analyses.

The function resets process-local orchestration state between evaluations.

See:: TestClearDependencyCache

Notes

The function changes orchestration state only. It does not run in a JAX numerical kernel.

Return type:: None

diffpes.certify.dependency_cache_info() → tuple[int, int, int][source]¶

Return cache size, hit count, and miss count.

The tuple gives deterministic counters for structural cache tests.

See:: TestDependencyCacheInfo
Returns:: info – Entry count, hit count, and miss count.
Return type:: tuple[int, int, int]

Notes

The counters measure eager structural analysis. They do not measure a JAX compilation cache.

diffpes.certify.dependency_map(model_id: str, forward_fn: Callable[[PyTree], PyTree], inputs: PyTree, *, threshold: float = 1e-12) → DependencyMap[source]¶

Trace leaf-level structural and local numerical dependencies.

Structural dependencies come from typed JAXPR variable flow. traced records whether an all-ones tangent produces a local response above threshold. A false entry is local evidence, not global independence.

See:: TestDependencyMap

Implementation Logic¶

Bind the documented output:

result: DependencyMap = make_dependency_map(
        model_id=model_id,
        input_paths=_path_names(inputs),
        output_paths=_path_names(abstract_output),
        structural=structural,
        traced=traced,
    )

The function validates and transforms the inputs before it binds the documented output.

param model_id:: Permanent scientific model identity (static).
type model_id:: str
param forward_fn:: Pure differentiable forward model.
type forward_fn:: Callable[[PyTree], PyTree]
param inputs:: Numerical model inputs in their declared physical units.
type inputs:: PyTree
param threshold:: Positive local-response threshold. Default 1e-12.
type threshold:: float, default: 1e-12
returns:: result – Structural and local numerical dependency matrices.
rtype:: DependencyMap

Notes

The traced matrix is differentiable only through its continuous JVP source. Thresholded Boolean entries do not carry useful gradients.

diffpes.certify.information_spectrum(forward_fn: Callable[[PyTree], PyTree], inputs: PyTree, *, input_paths: tuple[str, ...] | None = None, output_weights: Float[Array, 'n_output'] | None = None, rank: int = 8, iterations: int = 8, threshold: float = 1e-10) → InformationSpectrum[source]¶

Estimate the leading local information spectrum matrix-free.

The function computes leading eigenpairs of J.T @ W @ J through JVP and VJP maps. It never materializes the dense Jacobian. Singular values are square roots of the nonnegative information eigenvalues.

See:: TestInformationSpectrum

Implementation Logic¶

Bind the documented output:

result: InformationSpectrum = make_information_spectrum(
        input_paths=paths,
        singular_values=singular_values,
        right_singular_vectors=right_vectors,
        effective_rank=effective_rank,
        condition_estimate=condition,
        threshold=threshold,
    )

The function validates and transforms the inputs before it binds the documented output.

param forward_fn:: Pure differentiable forward model.
type forward_fn:: Callable[[PyTree], PyTree]
param inputs:: Numerical model inputs in their declared physical units.
type inputs:: PyTree
param input_paths:: Names for flattened real input coordinates (static). Default None.
type input_paths:: Optional[tuple[str, ...]], default: None
param output_weights:: Nonnegative metric weights for flattened outputs. Default None.
type output_weights:: Optional[Float[Array, 'n_output']], default: None
param rank:: Requested leading spectrum rank (static). Default 8.
type rank:: int, default: 8
param iterations:: Number of subspace iterations (static). Default 8.
type iterations:: int, default: 8
param threshold:: Singular-value activity threshold. Default 1e-10.
type threshold:: float, default: 1e-10
returns:: result – Leading singular values, right vectors, rank, and condition estimate.
rtype:: InformationSpectrum

Notes

The subspace iteration and eigendecomposition remain JAX differentiable. Degenerate eigenvalues can make individual singular vectors non-unique.

diffpes.certify.linearized_forward(forward_fn: Callable[[PyTree], PyTree], inputs: PyTree) → tuple[PyTree, Callable[[PyTree], PyTree]][source]¶

Evaluate a forward model and retain its JVP linearization.

The operation exposes local information flow with JAX linearization and PyTree coordinates. Numerical leaves remain differentiable.

See:: TestLinearizedForward

Implementation Logic¶

Bind the documented output:
```
linearized = jax.linearize(forward_fn, inputs)
```
The function validates and transforms the inputs before it binds the documented output.

param forward_fn:

Pure JAX forward function accepting one input PyTree.

type forward_fn:

Callable[[PyTree], PyTree]

param inputs:

Evaluation point for the forward model.

type inputs:

PyTree

rtype:

tuple[PyTree, Callable[[PyTree], PyTree]]

returns:

output (PyTree) – Forward-model value at inputs.
pushforward (Callable[[PyTree], PyTree]) – Reusable linear map from input tangents to output tangents.

diffpes.certify.sensitivity_map(input_paths: tuple[str, ...], output_projection_ids: tuple[str, ...], forward_fn: Callable[[PyTree], Array], inputs: PyTree, directions: PyTree, scales: Float[Array, 'n_input'], *, threshold: float = 1e-12) → SensitivityMap[source]¶

Measure scaled JVP sensitivities for a batch of tangent directions.

directions has the same tree structure as inputs and a leading probe axis on every leaf. The flattened output must correspond to output_projection_ids.

See:: TestSensitivityMap

Implementation Logic¶

Bind the documented output:

result: SensitivityMap = make_sensitivity_map(
        input_paths=input_paths,
        output_projection_ids=output_projection_ids,
        scales=scales,
        sensitivities=scaled,
        threshold=threshold,
        active=active,
    )

The function validates and transforms the inputs before it binds the documented output.

param input_paths:: Stable input-coordinate names (static).
type input_paths:: tuple[str, ...]
param output_projection_ids:: Stable output-projection names (static).
type output_projection_ids:: tuple[str, ...]
param forward_fn:: Pure differentiable forward model.
type forward_fn:: Callable[[PyTree], Array]
param inputs:: Numerical model inputs in their declared physical units.
type inputs:: PyTree
param directions:: Batched tangent directions with a leading probe axis.
type directions:: PyTree
param scales:: Positive physical scale for each input direction.
type scales:: Float[Array, 'n_input']
param threshold:: Absolute activity threshold. Default 1e-12.
type threshold:: float, default: 1e-12
returns:: result – Scaled output-by-input sensitivities and activity indicators.
rtype:: SensitivityMap

Notes

The sensitivity values carry gradients through jax.linearize. The thresholded activity matrix is a derived diagnostic.

diffpes.certify.derivative_evidence(forward_fn: Callable[[PyTree], Float[Array, 'n_output']], inputs: PyTree, directions: PyTree, cotangents: Float[Array, 'n_cotangent n_output'], *, input_paths: tuple[str, ...], output_projection_ids: tuple[str, ...], scales: Float[Array, 'n_probe'], step: float = 6e-6, spectrum_rank: int = 8) → DerivativeEvidence[source]¶

Compare JAX information flow with batched finite differences.

The tangent tree has a leading probe axis on every leaf. The function reuses one jax.linearize result for all JVP probes. It applies jax.vmap to the central differences and the retained VJP. The result also contains a matrix-free local information spectrum.

See:: TestDerivativeEvidence

Implementation Logic¶

Compute the derivative residuals:
```
residuals: Array = jvp_values - reference
```
The residual retains the difference between JAX linearization and the finite-difference reference before construction of the evidence.

param forward_fn:: Pure differentiable forward model.
type forward_fn:: Callable[[PyTree], Float[Array, 'n_output']]
param inputs:: Numerical model inputs in their declared physical units.
type inputs:: PyTree
param directions:: Tangent probes with one leading probe axis on each numerical leaf.
type directions:: PyTree
param cotangents:: Output-space probes in the units reciprocal to the forward output.
type cotangents:: Float[Array, 'n_cotangent n_output']
param input_paths:: Stable names for the probed input coordinates (static).
type input_paths:: tuple[str, ...]
param output_projection_ids:: Stable names for the output projections (static).
type output_projection_ids:: tuple[str, ...]
param scales:: Positive physical scale for each tangent probe.
type scales:: Float[Array, 'n_probe']
param step:: Relative central-difference step. Default 6e-6.
type step:: float, default: 6e-6
param spectrum_rank:: Requested information-spectrum rank (static). Default 8.
type spectrum_rank:: int, default: 8
returns:: evidence – JVP, VJP, finite-difference, and local information-spectrum evidence.
rtype:: DerivativeEvidence

Notes

JVP, VJP, residual, and spectrum leaves remain differentiable. The function derives Boolean evidence fields after it retains the continuous values.

diffpes.certify.evaluate_claim(claim_id: str, subject_id: str, predicate_id: str, measured: Array, reference: Array, tolerance: Array, *, evidence_ids: tuple[str, ...] = (), checked: bool = True, in_domain: bool = True, severity_code: int = 1) → CertificationClaim[source]¶

Evaluate a numerical claim and preserve residual and margin leaves.

The operation retains continuous residuals and margins before it derives Boolean certification outcomes. These leaves remain available to JAX transformations.

See:

TestEvaluateClaim

Parameters:

claim_id (str) – Stable claim identifier (static – changing it retraces).
subject_id (str) – Scientific subject identifier (static – changing it retraces).
predicate_id (str) – Predicate identity (static – changing it retraces).
measured (Array) – Computed numerical values in the predicate units.
reference (Array) – Reference values in the same units.
tolerance (Array) – Nonnegative component tolerances in the same units.
evidence_ids (tuple[str, ...], default: ()) – Supporting evidence identifiers (static – changing them retraces).
checked (bool, default: True) – Whether evaluation occurred (static – changing it retraces).
in_domain (bool, default: True) – Whether the subject lies in the validity domain (static).
severity_code (int, default: 1) – Numerical severity code (static – changing it retraces).

Returns:

claim – Claim with continuous residual and signed minimum margin leaves.

Return type:

CertificationClaim

Raises:

ValueError – If measured and reference shapes differ.

Notes

The margin is differentiable almost everywhere with respect to measured values. The function derives the Boolean outcome after it retains that margin.

diffpes.certify.evaluate_domain(predicate_id: str, measured: Array, reference: Array, tolerance: Array, *, checked: bool = True, severity_code: int = 1) → DomainResult[source]¶

Evaluate a symmetric domain predicate around a reference value.

The operation retains continuous residuals and margins before it derives Boolean certification outcomes. These leaves remain available to JAX transformations.

See:

TestEvaluateDomain

Parameters:

predicate_id (str) – Stable domain-predicate identity (static – changing it retraces).
measured (Array) – Measured physical quantity in the predicate units.
reference (Array) – Domain-center value in the same units.
tolerance (Array) – Symmetric half-width in the same units.
checked (bool, default: True) – Whether evaluation occurred (static – changing it retraces).
severity_code (int, default: 1) – Numerical severity code (static – changing it retraces).

Returns:

result – Traced outcome retaining residual and signed boundary margin.

Return type:

DomainResult

Notes

The signed margin remains differentiable away from the absolute-value cusp. Optimization can use it directly without differentiating a Boolean.

diffpes.certify.evaluate_evidence(evidence_id: str, method_id: str, measured: Array, reference: Array, tolerance: Array, *, artifact_refs: tuple[str, ...] = (), source_type: str = 'external_reference', independent: bool = True) → EvidenceRef[source]¶

Compare measured values with an external numerical reference.

The operation retains continuous residuals and margins before it derives Boolean certification outcomes. These leaves remain available to JAX transformations.

See:

TestEvaluateEvidence

Parameters:

evidence_id (str) – Stable evidence identifier (static – changing it retraces).
method_id (str) – Stable comparison-method identifier (static – a change retraces).
measured (Array) – Computed numerical values in the declared observable units.
reference (Array) – Independent reference values in the same units.
tolerance (Array) – Nonnegative component tolerances in the same units.
artifact_refs (tuple[str, ...], default: ()) – Source artifact identifiers (static – changing them retraces).
source_type (str, default: "external_reference") – Evidence-source category (static – changing it retraces).
independent (bool, default: True) – Whether the source is independent (static – changing it retraces).

Returns:

evidence – Vector evidence retaining measured, reference, residual, and tolerance.

Return type:

EvidenceRef

Raises:

ValueError – If measured and reference shapes differ.

Notes

Residuals remain JAX leaves, so losses may differentiate through the comparison before any Boolean policy reduction.

diffpes.certify.certify_forward(context: CertificationContext, inputs: PyTree, *, directions: PyTree | None = None, scales: Float[Array, 'n_probe'] | None = None, spectrum_rank: int = 8) → CertifiedResult[source]¶

Execute a prepared model and produce a certified JAX PyTree.

The operation binds a registered forward model to explicit evidence and policy records. Numerical outputs and assurance leaves remain differentiable.

See:

TestCertifyForward

Parameters:

context (CertificationContext) – Prepared model, policy, evidence, and domain-check selections.
inputs (PyTree) – Numerical model inputs in the model’s declared physical units.
directions (Optional[PyTree], default: None) – Batched tangent probes. By default, the function builds one probe per real input coordinate.
scales (Optional[Float[Array, 'n_probe']], default: None) – Positive physical scale for every tangent probe.
spectrum_rank (int, default: 8) – Requested information-spectrum rank (static – a change retraces).

Returns:

result – Forward value paired with differentiable evidence and policy outcome.

Return type:

CertifiedResult

Notes

The result value, residuals, margins, sensitivities, and information spectrum remain differentiable with respect to numerical input leaves.

diffpes.certify.certify_forward_checked(context: CertificationContext, inputs: PyTree, *, directions: PyTree | None = None, scales: Float[Array, 'n_probe'] | None = None, spectrum_rank: int = 8) → tuple[Any, CertifiedResult][source]¶

Execute certification and return structured hard-domain errors.

The function returns a checkify.Error with the certified result. The caller controls when the structured error becomes an exception.

See:

TestCertifyForwardChecked

Parameters:

context (CertificationContext) – Prepared model, policy, evidence, and domain-check selections.
inputs (PyTree) – Numerical model inputs in the declared physical units.
directions (Optional[PyTree], default: None) – Batched tangent probes. Default None creates one probe per coordinate.
scales (Optional[Float[Array, 'n_probe']], default: None) – Positive physical scale for every tangent probe. Default None.
spectrum_rank (int, default: 8) – Requested information-spectrum rank (static). Default 8.

Returns:

checked – Structured checkify error and complete certified result.

Return type:

tuple[Any, CertifiedResult]

Notes

The structured error remains compatible with JIT and VMAP. Call error.throw() only at an eager boundary.

diffpes.certify.prepare_certification(model_id: str, model_version: str, manifest: ExecutionManifest, *, policy_id: str = 'org.diffpes.policy.research.v1', artifacts: tuple[ArtifactRef, ...] = (), transformations: tuple[TransformationRecord, ...] = (), evidence: tuple[EvidenceRef, ...] = (), check_ids: tuple[str, ...] = (), input_checksums: tuple[str, ...] = (), waivers: tuple[WaiverRecord, ...] = ()) → CertificationContext[source]¶

Resolve static scientific records before compiled execution.

The operation binds a registered forward model to explicit evidence and policy records. Numerical outputs and assurance leaves remain differentiable.

See:: TestPrepareCertification

Implementation Logic¶

Resolve the registered model:
```
registered: RegisteredModel = get_model(model_id, model_version)
```
Exact lookup binds the context to one stable scientific model identity before the function collects evidence and domain checks.

param model_id:: Permanent model identifier (static – changing it retraces).
type model_id:: str
param model_version:: Exact semantic model version (static – changing it retraces).
type model_version:: str
param manifest:: Prepared execution identity and numerical environment.
type manifest:: ExecutionManifest
param policy_id:: Certification policy identity (static – changing it retraces).
type policy_id:: str, default: "org.diffpes.policy.research.v1"
param artifacts:: Input and derived artifact references.
type artifacts:: tuple[ArtifactRef, ...], default: ()
param transformations:: Ordered information-flow records.
type transformations:: tuple[TransformationRecord, ...], default: ()
param evidence:: Independent numerical evidence records.
type evidence:: tuple[EvidenceRef, ...], default: ()
param check_ids:: Domain checks to run (static – changing them retraces).
type check_ids:: tuple[str, ...], default: ()
param input_checksums:: Bookkeeping identities for inputs (static – a change retraces).
type input_checksums:: tuple[str, ...], default: ()
param waivers:: Policy-waiver records. Default is an empty tuple.
type waivers:: tuple[WaiverRecord, ...], default: ()
returns:: context – Cross-validated static selections for compiled execution.
rtype:: CertificationContext
raises ValueError:: If a waiver does not match the selected policy or active UTC interval.

diffpes.certify.verify_certificate(certificate: ForwardCertificate, *, resolver: ArtifactResolver | None = None) → VerificationReport[source]¶

Re-evaluate numerical claim and policy consistency without a rerun.

The operation binds a registered forward model to explicit evidence and policy records. Numerical outputs and assurance leaves remain differentiable.

See:

TestVerifyCertificate

Parameters:

certificate (ForwardCertificate) – Concrete certificate. The function checks its internal numerical relations.
resolver (Optional[Callable[[ArtifactRef], tuple[Any, Optional[bytes]]]], default: None) – Artifact resolver for external evidence. Default None checks only internal consistency and does not make a resolution claim.

Returns:

report – Structural and policy consistency outcome.

Return type:

VerificationReport

Notes

Verification recomputes recorded relations only. It does not rerun the forward model or convert bookkeeping checksums into scientific evidence.

diffpes.certify.diff_certificates(left: ForwardCertificate, right: ForwardCertificate) → CertificateDiff[source]¶

Compare two certificates by scientific meaning and record class.

The inspection result answers a bounded scientific question without loading the associated result arrays. It excludes private source locators.

See:: TestDiffCertificates

Implementation Logic¶

Bind the documented output:

difference: CertificateDiff = make_certificate_diff(
        scientific=tuple(scientific),
        numerical=_field_differences(left, right, numerical_names),
        environment=_field_differences(
            left.manifest,
            right.manifest,
            environment_names,
        ),
        audit=tuple(audit),
    )

The function validates and transforms the inputs before it binds the documented output.

param left:: Reference certificate.
type left:: ForwardCertificate
param right:: Candidate certificate.
type right:: ForwardCertificate
returns:: difference – Stable field-name differences grouped into scientific, numerical, environment, and audit categories.
rtype:: CertificateDiff

diffpes.certify.explain_claim(certificate: ForwardCertificate, claim_id: str) → str[source]¶

Explain one claim and the numerical evidence supporting it.

The inspection result answers a bounded scientific question without loading the associated result arrays. It excludes private source locators.

See:: TestExplainClaim

Implementation Logic¶

Bind the documented output:
```
explanation: str = "\n".join(lines)
```
The function validates and transforms the inputs before it binds the documented output.

param certificate:: Certificate containing the claim.
type certificate:: ForwardCertificate
param claim_id:: Stable claim identifier to explain.
type claim_id:: str
returns:: explanation – Multiline explanation with status, margin, and evidence arrays.
rtype:: str
raises KeyError:: If the certificate does not contain claim_id.

diffpes.certify.summarize_certificate(certificate: ForwardCertificate) → str[source]¶

Return a deterministic human-readable certificate summary.

The inspection result answers a bounded scientific question without loading the associated result arrays. It excludes private source locators.

See:: TestSummarizeCertificate

Implementation Logic¶

Bind the documented output:
```
summary: str = "\n".join(lines)
```
The function validates and transforms the inputs before it binds the documented output.

param certificate:: Certificate to summarize. The function does not need or load the associated result arrays.
type certificate:: ForwardCertificate
returns:: summary – Compact multiline summary of identity, semantics, provenance, claim status, and derivative diagnostics.
rtype:: str

diffpes.certify.execute_tb_radial(inputs: tuple[Any, ...]) → ArpesSpectrum[source]¶

Execute the radial ARPES model from one certification input PyTree.

The tuple order is (bands, radial, simulation, polarization, work_function, self_energy, radial_grid, momentum_width). Optional entries use None and therefore become empty JAX subtrees.

See:: TestExecuteTbRadial

Implementation Logic¶

Bind the documented output:

spectrum: ArpesSpectrum = simulate_tb_radial(
        bands,
        radial,
        simulation,
        polarization,
        work_function=work_function,
        self_energy=self_energy,
        r_grid=grid,
        dk=dk,
    )

The function validates and transforms the inputs before it binds the documented output.

param inputs:: Eight-position radial-model input PyTree. Its tuple structure is static; a change to the structure triggers retracing.
type inputs:: tuple[Any, ...]
returns:: spectrum – Simulated ARPES intensity and axes in their declared physical units.
rtype:: ArpesSpectrum
raises ValueError:: If inputs does not contain exactly eight entries.

Notes

Gradients pass through every numerical input accepted by simulate_tb_radial().

diffpes.certify.register_builtin_models() → None[source]¶

The operation uses the built-in radial ARPES adapter and its declared conventions. It preserves JAX differentiation through numerical model inputs.

See:: TestRegisterBuiltinModels

Notes

Registration is explicit and idempotent at the eager application boundary. Numerical model execution and domain predicates remain pure JAX programs.

Return type:: None

diffpes.certify.tb_radial_model_spec() → ForwardModelSpec[source]¶

Return the stable scientific specification for radial ARPES.

The operation uses the built-in radial ARPES adapter and its declared conventions. It preserves JAX differentiation through numerical model inputs.

See:: TestTbRadialModelSpec
Returns:: spec – Versioned assumptions, conventions, domain, and differentiable paths.
Return type:: ForwardModelSpec

Notes

The specification identifies the current tight-binding plus radial dipole model. It does not itself evaluate or certify a numerical result.

diffpes.certify.achieved_levels(report: PolicyReport) → tuple[str, ...][source]¶

Return certification level names achieved by a concrete report.

The cumulative policy derives named levels from explicit claims. It retains the claim truth table as JAX arrays.

See:: TestAchievedLevels
Parameters:: report (PolicyReport) – Concrete policy report inspected at the eager boundary.
Returns:: levels – Achieved level identities in cumulative policy order.
Return type:: tuple[str, ...]

Notes

This eager inspection helper converts the traced Boolean vector to a Python tuple. Do not call the helper inside a compiled kernel.

diffpes.certify.evaluate_policy(claims: Iterable[CertificationClaim], policy_id: str = 'org.diffpes.policy.research.v1', *, waivers: tuple[WaiverRecord, ...] = ()) → PolicyReport[source]¶

Derive cumulative certification outcomes from numerical claims.

The cumulative policy derives named levels from explicit claims. It retains the claim truth table as JAX arrays.

See:

TestEvaluatePolicy

Parameters:

claims (Iterable[CertificationClaim]) – Numerical claims evaluated for one forward execution.
policy_id (str, default: "org.diffpes.policy.research.v1") – Built-in cumulative policy identity (static – a change retraces).
waivers (tuple[WaiverRecord, ...], default: ()) – Valid active waiver records. Default is an empty tuple.

Returns:

report – Traced truth table and cumulative achieved-level vector.

Return type:

PolicyReport

Raises:

ValueError – If policy_id is not a registered built-in policy.

Notes

Required claim selections are static. Boolean outcomes are JAX leaves, so the policy computation remains compatible with jit and vmap. A waiver never changes a claim outcome. Publication and parity policies do not achieve their final level when a waiver exists.

diffpes.certify.build_provenance(records: Sequence[TransformationRecord], *, external_inputs: Mapping[str, Iterable[str]] | Iterable[str] = (), strict: bool = True) → ProvenanceGraph[source]¶

Build a deterministic provenance DAG and propagate information.

The operation propagates semantic state, information loss, and claim invalidation through a directed artifact graph. It reports contradictions explicitly.

See:: TestBuildProvenance

Implementation Logic¶

Bind the documented output:

graph: ProvenanceGraph = make_provenance_graph(
        records=normalized_records,
        external_inputs=input_ids,
        initial_semantics=semantic_pairs,
        topological_order=analysis.topological_order,
        information=analysis.information,
        validation_errors=analysis.errors,
        graph_checksum=checksum,
    )

The function validates and transforms the inputs before it binds the documented output.

param records:: Transformation executions linking parent and output artifact IDs.
type records:: Sequence[TransformationRecord]
param external_inputs:: Known source-node IDs. A mapping additionally declares the semantic properties initially available on each source.
type external_inputs:: Mapping[str, Iterable[str]] | Iterable[str], default: ()
param strict:: Raise ValueError for any invalid graph. False is useful to construct an inspectable rejected graph.
type strict:: bool, default: True
returns:: graph – Immutable graph with propagated per-node semantic state.
rtype:: ProvenanceGraph
raises ValueError:: If strict validation detects a cycle or an invalid node. This error also identifies an unused input or contradictory information.

diffpes.certify.effective_information(graph: ProvenanceGraph, output_id: str) → InformationState[source]¶

Return propagated semantics, losses, and invalidations for one node.

The operation propagates semantic state, information loss, and claim invalidation through a directed artifact graph. It reports contradictions explicitly.

See:: TestEffectiveInformation

Implementation Logic¶

Bind the documented output:
```
msg: str = f"unknown provenance node: {output_id}"
```
The function validates and transforms the inputs before it binds the documented output.

param graph:: Validated provenance graph to inspect.
type graph:: ProvenanceGraph
param output_id:: Artifact or result node identifier.
type output_id:: str
returns:: information – Propagated semantic state at the requested node.
rtype:: InformationState
raises KeyError:: If output_id is absent from the graph.

diffpes.certify.invalidated_claims(graph: ProvenanceGraph, output_id: str) → tuple[str, ...][source]¶

Return every claim invalidated at or upstream of one output.

The operation propagates semantic state, information loss, and claim invalidation through a directed artifact graph. It reports contradictions explicitly.

See:: TestInvalidatedClaims

Implementation Logic¶

Bind the documented output:

claims: tuple[str, ...] = effective_information(
        graph,
        output_id,
    ).invalidated_claims

The function validates and transforms the inputs before it binds the documented output.

param graph:: Validated provenance graph to inspect.
type graph:: ProvenanceGraph
param output_id:: Artifact or result node identifier.
type output_id:: str
returns:: claims – Sorted claim identifiers invalidated along the upstream lineage.
rtype:: tuple[str, ...]

diffpes.certify.lineage(graph: ProvenanceGraph, output_id: str) → tuple[str, ...][source]¶

Return the transitive parent-node lineage of one output.

The operation propagates semantic state, information loss, and claim invalidation through a directed artifact graph. It reports contradictions explicitly.

See:: TestLineage

Implementation Logic¶

Bind the documented output:
```
result: tuple[str, ...] = tuple(sorted(ancestors))
```
The function validates and transforms the inputs before it binds the documented output.

param graph:: Validated provenance graph to inspect.
type graph:: ProvenanceGraph
param output_id:: Artifact or result node identifier.
type output_id:: str
returns:: result – Sorted transitive ancestor identifiers.
rtype:: tuple[str, ...]
raises KeyError:: If output_id is absent from the graph.

diffpes.certify.validate_provenance(graph: ProvenanceGraph) → ProvenanceReport[source]¶

Re-evaluate graph structure and derived state independently.

The operation propagates semantic state, information loss, and claim invalidation through a directed artifact graph. It reports contradictions explicitly.

See:: TestValidateProvenance

Implementation Logic¶

Bind the documented output:

report: ProvenanceReport = make_provenance_report(
        valid=not errors,
        errors=tuple(errors),
        roots=analysis.roots,
        terminal_outputs=analysis.terminal_outputs,
        orphaned_inputs=analysis.orphaned_inputs,
        topological_order=analysis.topological_order,
        graph_checksum=expected_checksum,
    )

The function validates and transforms the inputs before it binds the documented output.

param graph:: Graph returned by build_provenance() or read from storage.
type graph:: ProvenanceGraph
returns:: report – Complete deterministic validation result.
rtype:: ProvenanceReport

diffpes.certify.freeze_registry() → RegistrySnapshot[source]¶

Prevent later registration and return the final immutable snapshot.

The process-local registry uses exact scientific identities and deterministic ordering. Freezing prevents later mutation of the selected programs.

See:: TestFreezeRegistry
Returns:: snapshot – Final immutable contents after the function disables mutation.
Return type:: RegistrySnapshot

Notes

Freezing is process-local eager registry control and is never invoked from a traced numerical kernel.

diffpes.certify.get_model(model_id: str, model_version: str) → RegisteredModel[source]¶

Resolve an exact registered model.

The process-local registry uses exact scientific identities and deterministic ordering. Freezing prevents later mutation of the selected programs.

See:: TestGetModel

Implementation Logic¶

Bind the documented output:
```
msg: str = f"unknown model identity: {model_id}@{model_version}"
```
The function validates and transforms the inputs before it binds the documented output.

param model_id:: Permanent scientific model identifier.
type model_id:: str
param model_version:: Exact semantic model version.
type model_version:: str
returns:: model – Immutable registered model binding.
rtype:: RegisteredModel
raises KeyError:: If the exact ID and semantic version are absent.

diffpes.certify.get_transformation(transformation_id: str, transformation_version: str) → RegisteredTransformation[source]¶

Resolve an exact registered transformation contract.

The process-local registry uses exact scientific identities and deterministic ordering. Freezing prevents later mutation of the selected programs.

See:: TestGetTransformation

Implementation Logic¶

Bind the documented output:

msg: str = (
        "unknown transformation identity: "
        f"{transformation_id}@{transformation_version}"
    )

The function validates and transforms the inputs before it binds the documented output.

param transformation_id:: Permanent transformation identifier.
type transformation_id:: str
param transformation_version:: Exact semantic transformation version.
type transformation_version:: str
returns:: transformation – Immutable registered transformation binding.
rtype:: RegisteredTransformation
raises KeyError:: If the exact ID and semantic version are absent.

diffpes.certify.list_handshakes() → tuple[RegistrationHandshake, ...][source]¶

Return owner handshakes in deterministic identity order.

The process-local registry returns one immutable tuple.

See:: TestListHandshakes
Returns:: handshakes – Immutable sorted handshake declarations.
Return type:: tuple[RegistrationHandshake, ...]

Notes

The function reads the tuple while the registry lock is active.

diffpes.certify.list_models() → tuple[ForwardModelSpec, ...][source]¶

Return model specifications in deterministic identity order.

The process-local registry uses exact scientific identities and deterministic ordering. Freezing prevents later mutation of the selected programs.

See:: TestListModels

Implementation Logic¶

Bind the documented output:

models: tuple[ForwardModelSpec, ...] = tuple(
            entry.spec for entry in state.models
        )

The function validates and transforms the inputs before it binds the documented output.

returns:: models – Immutable sorted model specifications without executor callables.
rtype:: tuple[ForwardModelSpec, ...]

diffpes.certify.list_registered_models() → tuple[RegisteredModel, ...][source]¶

Return an immutable deterministic snapshot including executors.

The process-local registry uses exact scientific identities and deterministic ordering. Freezing prevents later mutation of the selected programs.

See:: TestListRegisteredModels

Implementation Logic¶

Bind the documented output:
```
models: tuple[RegisteredModel, ...] = state.models
```
The function validates and transforms the inputs before it binds the documented output.

returns:: models – Immutable sorted model bindings including static executor callables.
rtype:: tuple[RegisteredModel, ...]

diffpes.certify.list_transformations() → tuple[TransformationContract, ...][source]¶

Return transformation contracts in deterministic identity order.

The process-local registry uses exact scientific identities and deterministic ordering. Freezing prevents later mutation of the selected programs.

See:: TestListTransformations

Implementation Logic¶

Bind the documented output:

transformations: tuple[TransformationContract, ...] = tuple(
            entry.contract for entry in state.transformations
        )

The function validates and transforms the inputs before it binds the documented output.

returns:: transformations – Immutable sorted semantic and information-loss contracts.
rtype:: tuple[TransformationContract, ...]

diffpes.certify.packaged_model_card(model_id: str, model_version: str) → str[source]¶

Read the packaged generated card for one model identity.

The filename combines the permanent model ID with its semantic version.

See:: TestPackagedModelCard

Implementation Logic¶

Read the generated resource:
```
filename = f"{model_id}@{model_version}.md"
```
The package resource contains the canonical generated Markdown view.

param model_id:: Exact permanent model ID.
type model_id:: str
param model_version:: Exact semantic model version.
type model_version:: str
returns:: card – Packaged Markdown model card.
rtype:: str

diffpes.certify.register_handshake(handshake: RegistrationHandshake) → None[source]¶

The registry stores requirements before or after the owner registers them.

See:: TestRegisterHandshake
Return type:: None

Implementation Logic¶

Store the sorted declaration:

state.handshakes = tuple(
    sorted((*state.handshakes, handshake), key=_handshake_key)
)

Stable owner ordering removes import-order effects.

param handshake:: Exact model, transformation, convention, and evidence references.
type handshake:: RegistrationHandshake
raises ValueError:: If the owner has a handshake or the registry has a frozen state.

diffpes.certify.register_model(spec: ForwardModelSpec, executor: Callable[[...], Any]) → None[source]¶

The process-local registry uses exact scientific identities and deterministic ordering. Freezing prevents later mutation of the selected programs.

See:: TestRegisterModel
Return type:: None

Implementation Logic¶

Bind the documented output:
```
state.models = tuple(sorted((*state.models, entry), key=_model_key))
```
The function validates and transforms the inputs before it binds the documented output.

param spec:: Immutable scientific model specification.
type spec:: ForwardModelSpec
param executor:: Pure model implementation. Certification later verifies its JAX behavior. Registration only requires a callable.
type executor:: Callable[..., Any]
raises ValueError:: If the identity is invalid or already exists. The function also raises when the registry no longer accepts changes.

diffpes.certify.register_transformation(contract: TransformationContract) → None[source]¶

The process-local registry uses exact scientific identities and deterministic ordering. Freezing prevents later mutation of the selected programs.

See:: TestRegisterTransformation
Return type:: None

Implementation Logic¶

Bind the documented output:

state.transformations = tuple(
            sorted(
                (*state.transformations, entry),
                key=_transformation_key,
            )
        )

The function validates and transforms the inputs before it binds the documented output.

param contract:: Validated semantic and information-loss declaration.
type contract:: TransformationContract
raises ValueError:: If the contract is invalid or duplicated. The function also raises when the registry no longer accepts changes.

diffpes.certify.registry_manifest() → dict[str, Any][source]¶

Read the packaged registry manifest.

The manifest records generated model and transformation identities.

See:: TestRegistryManifest

Implementation Logic¶

Parse the package resource:
```
decoded = json.loads(text)
```
The function rejects a root that is not a JSON object.

returns:: manifest – Parsed manifest with generated model and transformation identities.
rtype:: dict[str, Any]
raises ValueError:: If the manifest root is not a JSON object.

diffpes.certify.registry_snapshot() → RegistrySnapshot[source]¶

Return one internally consistent immutable registry snapshot.

The process-local registry uses exact scientific identities and deterministic ordering. Freezing prevents later mutation of the selected programs.

See:: TestRegistrySnapshot

Implementation Logic¶

Bind the documented output:

snapshot: RegistrySnapshot = make_registry_snapshot(
        models=models,
        transformations=transformations,
        checksum=checksum,
    )

The function validates and transforms the inputs before it binds the documented output.

returns:: snapshot – Models, transformations, and their non-security consistency checksum.
rtype:: RegistrySnapshot

diffpes.certify.render_model_card(spec: ForwardModelSpec) → str[source]¶

Render a model card directly from a model specification.

The generated Markdown contains no separately maintained scientific data.

See:: TestRenderModelCard

Implementation Logic¶

Render registry fields:
```
card = f"# {spec.model_id}\\n\\nVersion: `{spec.model_version}`."
```
The complete output also lists assumptions, conventions, and domains.

param spec:: Registered scientific model specification.
type spec:: ForwardModelSpec
returns:: card – Deterministic Markdown generated only from registry truth.
rtype:: str

diffpes.certify.validate_handshake(handshake: RegistrationHandshake, *, evidence_ids: tuple[str, ...] = ()) → HandshakeReport[source]¶

Validate one owner handshake against available records.

The report names each exact reference that has no available binding.

See:: TestValidateHandshake

Implementation Logic¶

Collect missing references:

missing = tuple(
    reference
    for required, available in available_groups
    for reference in required
    if reference not in available
)

The comparison uses exact versioned identities from each registry.

param handshake:: Declarative requirements supplied by the owning plan.
type handshake:: RegistrationHandshake
param evidence_ids:: Available evidence record IDs. Default is an empty tuple.
type evidence_ids:: tuple[str, ...], default: ()
returns:: report – Completion state and sorted missing exact references.
rtype:: HandshakeReport

diffpes.certify.validate_registry() → RegistryReport[source]¶

Recompute registry structure and consistency checksums.

The process-local registry uses exact scientific identities and deterministic ordering. Freezing prevents later mutation of the selected programs.

See:: TestValidateRegistry

Implementation Logic¶

Bind the documented output:

report: RegistryReport = make_registry_report(
        valid=not errors,
        errors=tuple(errors),
        model_count=len(models),
        transformation_count=len(transformations),
        checksum=checksum,
        frozen=frozen,
    )

The function validates and transforms the inputs before it binds the documented output.

returns:: report – Validation errors, entry counts, deterministic checksum, and frozen state. The checksum has bookkeeping meaning only.
rtype:: RegistryReport

diffpes.certify.validate_registry_manifest() → tuple[str, ...][source]¶

Compare the packaged registry manifest with live entries.

The comparison detects missing entries and generated model-card drift.

See:: TestValidateRegistryManifest

Implementation Logic¶

Compare packaged entries:
```
manifest = registry_manifest()
```
The function compares each manifest identity with the live registry.

returns:: errors – Sorted missing-entry and generated-card drift messages.
rtype:: tuple[str, ...]

diffpes.certify.reproduce_forward(certificate: ForwardCertificate, *, resolver: ArtifactResolver, tolerance: float = 1e-10) → ReproductionReport[source]¶

Re-execute a registered model and compare its recorded result.

The runner resolves one normalized input and one separately stored result.

See:: TestReproduceForward

Implementation Logic¶

Resolve and re-execute:
```
reproduced_value = registered.executor(inputs)
```
Exact registry lookup binds the rerun to the certificate model.
Compare numerical leaves:
```
absolute = jnp.abs(actual_flat - expected_flat)
```
The report stores maximum absolute and relative errors.

param certificate:: Certificate with one normalized-input and one result artifact.
type certificate:: ForwardCertificate
param resolver:: Eager resolver for both normalized artifacts.
type resolver:: Callable[[ArtifactRef], tuple[Any, Optional[bytes]]]
param tolerance:: Nonnegative absolute and relative comparison tolerance. Default 1e-10.
type tolerance:: float, default: 1e-10
returns:: report – Numerical comparison and reproduced result identity.
rtype:: ReproductionReport
raises ValueError:: If required artifact roles or result tree structure are inconsistent.

Notes

The comparison uses tolerance for both the absolute and relative terms. Each leaf must satisfy absolute <= tolerance * (1 + abs(expected)).

diffpes.certify.filesystem_artifact_resolver(reference: ArtifactRef) → tuple[bytes, bytes][source]¶

Resolve a byte-valued artifact from its local locator.

The resolver returns normalized bytes and exact source bytes separately.

See:: TestFilesystemArtifactResolver

Implementation Logic¶

Read the local artifact:
```
data = Path(reference.locator).read_bytes()
```
The calling validator checks both returned byte identities.

param reference:: Artifact with a local filesystem locator.
type reference:: ArtifactRef
returns:: resolved – Normalized byte value and the same exact source bytes.
rtype:: tuple[bytes, bytes]
raises ValueError:: If the artifact has no local locator.

diffpes.certify.mapping_artifact_resolver(artifacts: Mapping[str, Any]) → ArtifactResolver[source]¶

Build a deterministic resolver from normalized in-memory values.

The resolver uses exact artifact IDs and an immutable mapping copy.

See:: TestMappingArtifactResolver

Implementation Logic¶

Freeze the supplied mapping:
```
frozen = dict(artifacts)
```
The resolver reads this copy for each exact artifact ID.

param artifacts:: Normalized values keyed by exact artifact ID.
type artifacts:: Mapping[str, Any]
returns:: resolver – Resolver that returns normalized values without source bytes.
rtype:: Callable[[ArtifactRef], tuple[Any, Optional[bytes]]]

diffpes.certify.resolve_artifact(reference: ArtifactRef, resolver: ArtifactResolver) → Any[source]¶

Resolve and validate one referenced artifact.

The function checks normalized content and any available exact bytes.

See:: TestResolveArtifact

Implementation Logic¶

Check normalized content:
```
content_checksum = checksum_pytree(
    value, record_kind="normalized-content"
)
```
The function rejects content that differs from the artifact reference.

param reference:: Expected byte, normalized-content, and semantic identities.
type reference:: ArtifactRef
param resolver:: Eager resolver for the artifact location or backing store.
type resolver:: Callable[[ArtifactRef], tuple[Any, Optional[bytes]]]
returns:: value – Validated normalized scientific content.
rtype:: Any
raises ValueError:: If a returned byte or content identity does not match.

diffpes.certify.verify_evidence(reference: EvidenceRef, artifacts: tuple[ArtifactRef, ...], resolver: ArtifactResolver) → EvidenceReport[source]¶

Verify referenced artifacts and recorded numerical residuals.

The report keeps resolution, compatibility, and tolerance outcomes distinct.

See:: TestVerifyEvidence

Implementation Logic¶

Resolve each evidence artifact:
```
resolve_artifact(artifact, resolver)
```
The final outcome also requires every numerical residual to fit.

param reference:: Numerical evidence and the artifact IDs that support it.
type reference:: EvidenceRef
param artifacts:: Available artifact records.
type artifacts:: tuple[ArtifactRef, ...]
param resolver:: Eager resolver for normalized artifact content.
type resolver:: Callable[[ArtifactRef], tuple[Any, Optional[bytes]]]
returns:: report – Resolution, compatibility, and numerical tolerance outcome.
rtype:: EvidenceReport

diffpes.certify.require_active_waivers(waivers: tuple[WaiverRecord, ...], *, as_of_utc: str) → None[source]¶

Reject malformed, expired, or premature waiver records.

The eager boundary rejects every record without active temporal scope.

See:

TestRequireActiveWaivers

Parameters:

waivers (tuple[WaiverRecord, ...]) – Static waiver declarations.
as_of_utc (str) – Absolute UTC evaluation time ending in Z.

Raises:

ValueError – If one waiver lacks valid and active temporal scope.

Return type:

None

Notes

Successful validation records the waiver only. It does not change any failed, unchecked, or out-of-domain claim.

diffpes.certify.validate_waiver(waiver: WaiverRecord, *, as_of_utc: str) → WaiverReport[source]¶

Validate one waiver against an explicit absolute UTC time.

The report distinguishes malformed records from records outside their active interval.

See:

TestValidateWaiver

Parameters:

waiver (WaiverRecord) – Static waiver declaration.
as_of_utc (str) – Absolute UTC evaluation time ending in Z.

Returns:

report – Structural validity, temporal activity, and validation errors.

Return type:

WaiverReport

Notes

The function performs static I/O-boundary validation. It does not run in a compiled certification kernel.

diffpes.certify.validate_waivers(waivers: tuple[WaiverRecord, ...], *, as_of_utc: str) → tuple[WaiverReport, ...][source]¶

Validate multiple waivers against one explicit absolute UTC time.

The function rejects duplicate identities. It then validates each interval.

See:: TestValidateWaivers

Implementation Logic¶

Validate each waiver:

reports = tuple(
    validate_waiver(waiver, as_of_utc=as_of_utc)
    for waiver in waivers
)

Input ordering remains stable in the returned report tuple.

param waivers:: Static waiver declarations.
type waivers:: tuple[WaiverRecord, ...]
param as_of_utc:: Absolute UTC evaluation time ending in Z.
type as_of_utc:: str
returns:: reports – Validation reports in input order.
rtype:: tuple[WaiverReport, ...]
raises ValueError:: If waiver identities contain duplicates.