snnlab.sim.conformance

Complete declared API of the conformance module, with signatures, data fields, validation and source.

Fail-closed comparison of complete named tensor layers under declared exact or numerical policies. Reports include coverage, shape, dtype and error bounds. This comparison framework does not itself establish scientific acceptance thresholds.

The signatures, defaults, fields, docstrings and implementation excerpts below are generated from the Python source. Annotations are shown as declared; unannotated means the source supplies no type annotation. These pages document callable surfaces, including legacy support utilities, without promising backend support for every declaration.

Symbol	Kind
ComparisonPolicy	class
TensorComparison	class
ConformanceReport	class
canonical_json_tensor	function
remap_named_tensors	function
compare_conformance_layers	function
write_conformance_report	function

ComparisonPolicy

View source

Comparison mode and explicit absolute/relative error tolerances. Exact policies require exact tensor equality; numeric policies use declared bounds.

Class decorators: dataclass(frozen=True).

Dataclass constructor parameters. Factory defaults are shown as field declarations; omit these arguments to create fresh values per instance:

ComparisonPolicy(mode: ComparisonMode = 'exact', atol: float = 0.0, rtol: float = 0.0, equal_nan: bool = False)

Declared fields, including fields inherited from local data classes:

Field	Annotation	Default	Meaning
`mode`	`ComparisonMode`	`'exact'`	Stored member of this data contract; see the class docstring and serialization methods.
`atol`	`float`	`0.0`	Stored member of this data contract; see the class docstring and serialization methods.
`rtol`	`float`	`0.0`	Stored member of this data contract; see the class docstring and serialization methods.
`equal_nan`	`bool`	`False`	Stored member of this data contract; see the class docstring and serialization methods.

Constructor/initialization exception expressions:

Explicit exception expression
`ValueError(f'unsupported conformance comparison mode {self.mode}')`
`ValueError('conformance tolerances must be non-negative')`
`ValueError('exact conformance policy cannot declare tolerances')`

Complete class implementation

class ComparisonPolicy:
    mode: ComparisonMode = "exact"
    atol: float = 0.0
    rtol: float = 0.0
    equal_nan: bool = False

    def __post_init__(self):
        if self.mode not in {"exact", "numeric"}:
            raise ValueError(f"unsupported conformance comparison mode {self.mode}")
        if self.atol < 0 or self.rtol < 0:
            raise ValueError("conformance tolerances must be non-negative")
        if self.mode == "exact" and (self.atol or self.rtol):
            raise ValueError("exact conformance policy cannot declare tolerances")

TensorComparison

View source

One named-field comparison result, including shape/dtype agreement and measured error bounds.

Class decorators: dataclass(frozen=True).

Dataclass constructor parameters. Factory defaults are shown as field declarations; omit these arguments to create fresh values per instance:

TensorComparison(layer: str, field: str, passed: bool, reason: str | None, reference_shape: list[int] | None, candidate_shape: list[int] | None, reference_dtype: str | None, candidate_dtype: str | None, policy: ComparisonPolicy, max_abs_error: float | None = None, max_rel_error: float | None = None)

Declared fields, including fields inherited from local data classes:

Field	Annotation	Default	Meaning
`layer`	`str`	required	Stored member of this data contract; see the class docstring and serialization methods.
`field`	`str`	required	Stored member of this data contract; see the class docstring and serialization methods.
`passed`	`bool`	required	Stored member of this data contract; see the class docstring and serialization methods.
`reason`	`str \| None`	required	Stored member of this data contract; see the class docstring and serialization methods.
`reference_shape`	`list[int] \| None`	required	Stored member of this data contract; see the class docstring and serialization methods.
`candidate_shape`	`list[int] \| None`	required	Stored member of this data contract; see the class docstring and serialization methods.
`reference_dtype`	`str \| None`	required	Stored member of this data contract; see the class docstring and serialization methods.
`candidate_dtype`	`str \| None`	required	Stored member of this data contract; see the class docstring and serialization methods.
`policy`	`ComparisonPolicy`	required	Stored member of this data contract; see the class docstring and serialization methods.
`max_abs_error`	`float \| None`	`None`	Stored member of this data contract; see the class docstring and serialization methods.
`max_rel_error`	`float \| None`	`None`	Stored member of this data contract; see the class docstring and serialization methods.

Complete class implementation

class TensorComparison:
    layer: str
    field: str
    passed: bool
    reason: str | None
    reference_shape: list[int] | None
    candidate_shape: list[int] | None
    reference_dtype: str | None
    candidate_dtype: str | None
    policy: ComparisonPolicy
    max_abs_error: float | None = None
    max_rel_error: float | None = None

ConformanceReport

View source

Collection of comparison results, failures and metadata that can be serialized as a versioned report.

Class decorators: dataclass(frozen=True).

Dataclass constructor parameters. Factory defaults are shown as field declarations; omit these arguments to create fresh values per instance:

ConformanceReport(case_id: str, comparisons: tuple[TensorComparison, ...], schema: str = CONFORMANCE_REPORT_SCHEMA)

Declared fields, including fields inherited from local data classes:

Field	Annotation	Default	Meaning
`case_id`	`str`	required	Stored member of this data contract; see the class docstring and serialization methods.
`comparisons`	`tuple[TensorComparison, ...]`	required	Stored member of this data contract; see the class docstring and serialization methods.
`schema`	`str`	`CONFORMANCE_REPORT_SCHEMA`	Stored member of this data contract; see the class docstring and serialization methods.

ConformanceReport.passed

View source

Decorators: property.

def ConformanceReport.passed(self) -> bool

Return annotation: bool.

Return expressions (branch-dependent; names refer to the linked implementation):

all((row.passed for row in self.comparisons))

Implementation

def passed(self) -> bool:
        return all(row.passed for row in self.comparisons)

ConformanceReport.to_dict

View source

def ConformanceReport.to_dict(self) -> dict[str, Any]

Return annotation: dict[str, Any].

Return expressions (branch-dependent; names refer to the linked implementation):

{'schema': self.schema, 'case_id': self.case_id, 'passed': self.passed, 'summary': {'comparisons': len(self.comparisons), 'passed': sum((row.passed for row in self.comparisons)), 'failed': sum((not row.passed for row in self.comparisons))}, 'comparisons': [asdict(row) for row in self.comparisons]}

Implementation

def to_dict(self) -> dict[str, Any]:
        return {
            "schema": self.schema,
            "case_id": self.case_id,
            "passed": self.passed,
            "summary": {
                "comparisons": len(self.comparisons),
                "passed": sum(row.passed for row in self.comparisons),
                "failed": sum(not row.passed for row in self.comparisons),
            },
            "comparisons": [asdict(row) for row in self.comparisons],
        }

ConformanceReport.require_passed

View source

def ConformanceReport.require_passed(self) -> None

Return annotation: None.

Explicit exceptions in this implementation; called helpers may raise additional errors:

Explicit exception expression
`AssertionError('conformance failed: ' + '; '.join(failures))`

Implementation

def require_passed(self) -> None:
        failures = [
            f"{row.layer}.{row.field}: {row.reason}"
            for row in self.comparisons
            if not row.passed
        ]
        if failures:
            raise AssertionError("conformance failed: " + "; ".join(failures))

Complete class implementation

class ConformanceReport:
    case_id: str
    comparisons: tuple[TensorComparison, ...]
    schema: str = CONFORMANCE_REPORT_SCHEMA

    @property
    def passed(self) -> bool:
        return all(row.passed for row in self.comparisons)

    def to_dict(self) -> dict[str, Any]:
        return {
            "schema": self.schema,
            "case_id": self.case_id,
            "passed": self.passed,
            "summary": {
                "comparisons": len(self.comparisons),
                "passed": sum(row.passed for row in self.comparisons),
                "failed": sum(not row.passed for row in self.comparisons),
            },
            "comparisons": [asdict(row) for row in self.comparisons],
        }

    def require_passed(self) -> None:
        failures = [
            f"{row.layer}.{row.field}: {row.reason}"
            for row in self.comparisons
            if not row.passed
        ]
        if failures:
            raise AssertionError("conformance failed: " + "; ".join(failures))

canonical_json_tensor

View source

def canonical_json_tensor(value: Any) -> torch.Tensor

Source docstring:

Encode JSON-compatible structure for exact named conformance comparison.

Parameter	Annotation	Default	Meaning
`value`	`Any`	required	Defined by the source contract and implementation below.

Return annotation: torch.Tensor.

Return expressions (branch-dependent; names refer to the linked implementation):

torch.tensor(list(encoded), dtype=torch.uint8)

Implementation

def canonical_json_tensor(value: Any) -> torch.Tensor:
    """Encode JSON-compatible structure for exact named conformance comparison."""
    encoded = json.dumps(
        value, sort_keys=True, separators=(",", ":"), ensure_ascii=False
    ).encode()
    return torch.tensor(list(encoded), dtype=torch.uint8)

remap_named_tensors

View source

def remap_named_tensors(values: Mapping[str, torch.Tensor], mapping: Mapping[str, str]) -> dict[str, torch.Tensor]

Source docstring:

Apply an explicit complete name map without positional or partial fallback.

Parameter	Annotation	Default	Meaning
`values`	`Mapping[str, torch.Tensor]`	required	Defined by the source contract and implementation below.
`mapping`	`Mapping[str, str]`	required	Defined by the source contract and implementation below.

Return annotation: dict[str, torch.Tensor].

Return expressions (branch-dependent; names refer to the linked implementation):

{mapping[name]: values[name] for name in sorted(values)}

Explicit exceptions in this implementation; called helpers may raise additional errors:

Explicit exception expression
`ValueError(f'conformance name map must be complete; missing={sorted(set(values) - set(mapping))}, extra={sorted(set(mapping) - set(values))}')`
`ValueError('conformance name map contains duplicate destination names')`

Implementation

def remap_named_tensors(
    values: Mapping[str, torch.Tensor], mapping: Mapping[str, str]
) -> dict[str, torch.Tensor]:
    """Apply an explicit complete name map without positional or partial fallback."""
    if set(values) != set(mapping):
        raise ValueError(
            f"conformance name map must be complete; missing={sorted(set(values) - set(mapping))}, extra={sorted(set(mapping) - set(values))}"
        )
    if len(set(mapping.values())) != len(mapping):
        raise ValueError("conformance name map contains duplicate destination names")
    return {mapping[name]: values[name] for name in sorted(values)}

compare_conformance_layers

View source

def compare_conformance_layers(case_id: str, reference: Mapping[str, Mapping[str, torch.Tensor]], candidate: Mapping[str, Mapping[str, torch.Tensor]], *, policies: Mapping[str, Mapping[str, ComparisonPolicy]] | None=None) -> ConformanceReport

Source docstring:

Compare named tensor layers with explicit coverage and tolerance policies.

Parameter	Annotation	Default	Meaning
`case_id`	`str`	required	Defined by the source contract and implementation below.
`reference`	`Mapping[str, Mapping[str, torch.Tensor]]`	required	Defined by the source contract and implementation below.
`candidate`	`Mapping[str, Mapping[str, torch.Tensor]]`	required	Defined by the source contract and implementation below.
`policies`	`Mapping[str, Mapping[str, ComparisonPolicy]] \| None`	`None`	Defined by the source contract and implementation below.

Return annotation: ConformanceReport.

Return expressions (branch-dependent; names refer to the linked implementation):

ConformanceReport(case_id=case_id, comparisons=tuple(rows))

Explicit exceptions in this implementation; called helpers may raise additional errors:

Explicit exception expression
`ValueError(f'conformance policies reference absent fields: {unused}')`

Implementation

def compare_conformance_layers(
    case_id: str,
    reference: Mapping[str, Mapping[str, torch.Tensor]],
    candidate: Mapping[str, Mapping[str, torch.Tensor]],
    *,
    policies: Mapping[str, Mapping[str, ComparisonPolicy]] | None = None,
) -> ConformanceReport:
    """Compare named tensor layers with explicit coverage and tolerance policies."""
    policies = policies or {}
    rows: list[TensorComparison] = []
    for layer in sorted(set(reference) | set(candidate)):
        reference_fields = reference.get(layer, {})
        candidate_fields = candidate.get(layer, {})
        for field in sorted(set(reference_fields) | set(candidate_fields)):
            policy = policies.get(layer, {}).get(field, ComparisonPolicy())
            if field not in reference_fields or field not in candidate_fields:
                rows.append(
                    TensorComparison(
                        layer=layer,
                        field=field,
                        passed=False,
                        reason="missing from reference"
                        if field not in reference_fields
                        else "missing from candidate",
                        reference_shape=list(reference_fields[field].shape)
                        if field in reference_fields
                        else None,
                        candidate_shape=list(candidate_fields[field].shape)
                        if field in candidate_fields
                        else None,
                        reference_dtype=_dtype(reference_fields[field])
                        if field in reference_fields
                        else None,
                        candidate_dtype=_dtype(candidate_fields[field])
                        if field in candidate_fields
                        else None,
                        policy=policy,
                    )
                )
                continue
            expected = reference_fields[field]
            actual = candidate_fields[field]
            if expected.shape != actual.shape:
                reason = "shape mismatch"
                passed = False
                max_abs = max_rel = None
            elif expected.dtype != actual.dtype:
                reason = "dtype mismatch"
                passed = False
                max_abs = max_rel = None
            else:
                max_abs, max_rel = _error_bounds(expected, actual)
                expected_value = expected.detach().to(device="cpu")
                actual_value = actual.detach().to(device="cpu")
                if policy.mode == "exact":
                    passed = torch.equal(expected_value, actual_value)
                else:
                    passed = torch.allclose(
                        expected_value,
                        actual_value,
                        atol=policy.atol,
                        rtol=policy.rtol,
                        equal_nan=policy.equal_nan,
                    )
                reason = None if passed else "value mismatch"
            rows.append(
                TensorComparison(
                    layer=layer,
                    field=field,
                    passed=passed,
                    reason=reason,
                    reference_shape=list(expected.shape),
                    candidate_shape=list(actual.shape),
                    reference_dtype=_dtype(expected),
                    candidate_dtype=_dtype(actual),
                    policy=policy,
                    max_abs_error=max_abs,
                    max_rel_error=max_rel,
                )
            )
    declared = {
        (layer, field) for layer, fields in policies.items() for field in fields
    }
    compared = {(row.layer, row.field) for row in rows}
    unused = sorted(declared - compared)
    if unused:
        raise ValueError(f"conformance policies reference absent fields: {unused}")
    return ConformanceReport(case_id=case_id, comparisons=tuple(rows))

write_conformance_report

View source

def write_conformance_report(path: str | Path, report: ConformanceReport) -> Path

Serialize a ConformanceReport to the requested JSON path and return that Path.

Parameter	Annotation	Default	Meaning
`path`	`str \| Path`	required	Filesystem source or destination path, as described below.
`report`	`ConformanceReport`	required	Defined by the source contract and implementation below.

Return annotation: Path.

Return expressions (branch-dependent; names refer to the linked implementation):

destination

Implementation

def write_conformance_report(path: str | Path, report: ConformanceReport) -> Path:
    destination = Path(path)
    destination.parent.mkdir(parents=True, exist_ok=True)
    destination.write_text(
        json.dumps(report.to_dict(), indent=2, sort_keys=True) + "\n"
    )
    return destination

Constants and type aliases

Initial source expressions are shown, not evaluated runtime values. Legacy configuration may mutate module defaults.

Name	Annotation	Initial expression	Source
`CONFORMANCE_REPORT_SCHEMA`	`unannotated`	`'tools/snnsim.conformance-report/v1'`	Source
`ComparisonMode`	`unannotated`	`Literal['exact', 'numeric']`	Source

snnlab.sim.conformance

ComparisonPolicyCopy Anchor Link

TensorComparisonCopy Anchor Link

ConformanceReportCopy Anchor Link

ConformanceReport.passedCopy Anchor Link

ConformanceReport.to_dictCopy Anchor Link

ConformanceReport.require_passedCopy Anchor Link

canonical_json_tensorCopy Anchor Link

remap_named_tensorsCopy Anchor Link

compare_conformance_layersCopy Anchor Link

write_conformance_reportCopy Anchor Link

Constants and type aliasesCopy Anchor Link

On this page

ComparisonPolicy

TensorComparison

ConformanceReport

ConformanceReport.passed

ConformanceReport.to_dict

ConformanceReport.require_passed

canonical_json_tensor

remap_named_tensors

compare_conformance_layers

write_conformance_report

Constants and type aliases