Skip to content

Experiment Dossiers and Result Records

The experiment-depth API turns the family, scaling, and reproduction registries into one ordered contract. It is useful when generating study plans, validating result metadata, or extending a family without losing its source boundary.

Inspect a Dossier

from silva_networks import silva_experiment_dossier

dossier = silva_experiment_dossier("silva_fno_deq")
print(dossier.equation)
print(dossier.preserved_mechanisms)
print(dossier.configurable_parts)
for stage in dossier.stages:
    print(stage.name, stage.evidence_status)

Every dossier contains six progressive stages:

\[ \mathcal E_{\mathrm{contract}} \subset \mathcal E_{\mathrm{primitive}} \subset \mathcal E_{\mathrm{equivalence}} \subset \mathcal E_{\mathrm{compact}} \subset \mathcal E_{\mathrm{subset}} \subset \mathcal E_{\mathrm{source}}. \]

Later stages require additional evidence and artifacts. A compact result does not automatically satisfy subset or source-scale requirements.

Validate a Result Record

from silva_networks import SILVAResultRecord

record = SILVAResultRecord(
    family="silva_fno_deq",
    evidence_status="compact-verified",
    dataset="analytic periodic field",
    dataset_version="v1",
    split="seeded four-sample fixture",
    configuration="field-comparison-v1",
    seed=122,
    metrics=(("mse", 0.145),),
    data_fingerprint="sha256:...",
    code_revision="working-tree-revision",
    hardware="CPU; float32",
    deviations=("compact 8 by 8 grid",),
)
assert record.validate() == ()

Public Objects

silva_networks.research_depth

Experiment dossiers and evidence records for SILVA model families.

The reproduction registry describes source obligations. This module turns those obligations into an ordered experiment ladder that can be inspected, serialized, and used by documentation or experiment runners without hiding which evidence has actually been collected.

SILVAExperimentStage dataclass

One falsifiable stage in a family reproduction ladder.

Source code in src/silva_networks/research_depth.py 
27
28
29
30
31
32
33
34
35
@dataclass(frozen=True)
class SILVAExperimentStage:
    """One falsifiable stage in a family reproduction ladder."""

    name: str
    objective: str
    procedure: tuple[str, ...]
    acceptance_checks: tuple[str, ...]
    evidence_status: EvidenceStatus

SILVAExperimentDossier dataclass

Complete source-to-scale experiment contract for one family.

Source code in src/silva_networks/research_depth.py 
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
@dataclass(frozen=True)
class SILVAExperimentDossier:
    """Complete source-to-scale experiment contract for one family."""

    family: str
    title: str
    domain: str
    task_contract: str
    source_relation: str
    equation: str
    constructor_signature: str
    paper_refs: tuple[int, ...]
    repositories: tuple[str, ...]
    datasets: tuple[str, ...]
    data_sources: tuple[str, ...]
    data_access: tuple[str, ...]
    storage_plan: tuple[str, ...]
    preprocessing: tuple[str, ...]
    metrics: tuple[str, ...]
    compact_data: tuple[str, ...]
    preserved_mechanisms: tuple[str, ...]
    configurable_parts: tuple[str, ...]
    source_scale_steps: tuple[str, ...]
    benchmark_requirements: tuple[str, ...]
    notebooks: tuple[str, ...]
    tests: tuple[str, ...]
    compact_defaults: tuple[tuple[str, str], ...]
    full_defaults: tuple[tuple[str, str], ...]
    stages: tuple[SILVAExperimentStage, ...]
    required_artifacts: tuple[str, ...]

    def as_dict(self) -> dict[str, Any]:
        """Return a JSON-compatible dossier record."""

        return asdict(self)

as_dict 

as_dict()

Return a JSON-compatible dossier record.

Source code in src/silva_networks/research_depth.py 
69
70
71
72
def as_dict(self) -> dict[str, Any]:
    """Return a JSON-compatible dossier record."""

    return asdict(self)

SILVAResultRecord dataclass

Minimum reproducibility metadata required for a measured family result.

Source code in src/silva_networks/research_depth.py 
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
@dataclass(frozen=True)
class SILVAResultRecord:
    """Minimum reproducibility metadata required for a measured family result."""

    family: str
    evidence_status: EvidenceStatus
    dataset: str
    dataset_version: str
    split: str
    configuration: str
    seed: int
    metrics: tuple[tuple[str, float], ...]
    data_fingerprint: str
    code_revision: str
    hardware: str
    deviations: tuple[str, ...] = ()

    def validate(self) -> tuple[str, ...]:
        """Return missing or inconsistent result-record fields."""

        errors: list[str] = []
        if self.family not in available_silva_families():
            errors.append(f"unknown family: {self.family}")
        for name in (
            "dataset",
            "dataset_version",
            "split",
            "configuration",
            "data_fingerprint",
            "code_revision",
            "hardware",
        ):
            if not getattr(self, name).strip():
                errors.append(f"empty result-record field: {name}")
        if not self.metrics:
            errors.append("at least one measured metric is required")
        if self.evidence_status == "source-scale-reproduced" and self.deviations:
            errors.append(
                "source-scale-reproduced records cannot contain undeclared protocol deviations"
            )
        return tuple(errors)

    def as_dict(self) -> dict[str, Any]:
        """Return a JSON-compatible reproducibility record."""

        return asdict(self)

validate 

validate()

Return missing or inconsistent result-record fields.

Source code in src/silva_networks/research_depth.py 
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
def validate(self) -> tuple[str, ...]:
    """Return missing or inconsistent result-record fields."""

    errors: list[str] = []
    if self.family not in available_silva_families():
        errors.append(f"unknown family: {self.family}")
    for name in (
        "dataset",
        "dataset_version",
        "split",
        "configuration",
        "data_fingerprint",
        "code_revision",
        "hardware",
    ):
        if not getattr(self, name).strip():
            errors.append(f"empty result-record field: {name}")
    if not self.metrics:
        errors.append("at least one measured metric is required")
    if self.evidence_status == "source-scale-reproduced" and self.deviations:
        errors.append(
            "source-scale-reproduced records cannot contain undeclared protocol deviations"
        )
    return tuple(errors)

as_dict 

as_dict()

Return a JSON-compatible reproducibility record.

Source code in src/silva_networks/research_depth.py 
117
118
119
120
def as_dict(self) -> dict[str, Any]:
    """Return a JSON-compatible reproducibility record."""

    return asdict(self)

silva_experiment_dossier 

silva_experiment_dossier(family)

Return the complete progressive experiment dossier for a family or alias.

Source code in src/silva_networks/research_depth.py 
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
def silva_experiment_dossier(family: str) -> SILVAExperimentDossier:
    """Return the complete progressive experiment dossier for a family or alias."""

    key = canonical_silva_family(family)
    spec = silva_reproduction_spec(key)
    guide = silva_family_guide(key)
    return SILVAExperimentDossier(
        family=key,
        title=guide.role,
        domain=_domain_for(key),
        task_contract=guide.data_contract,
        source_relation=spec.source_relation,
        equation=spec.equation,
        constructor_signature=spec.constructor_signature,
        paper_refs=spec.paper_refs,
        repositories=spec.repositories,
        datasets=spec.datasets,
        data_sources=spec.data_sources,
        data_access=spec.data_access,
        storage_plan=spec.storage_plan,
        preprocessing=spec.preprocessing,
        metrics=spec.metrics,
        compact_data=spec.compact_data,
        preserved_mechanisms=spec.preserved_mechanisms,
        configurable_parts=spec.configurable_parts,
        source_scale_steps=spec.source_scale_steps,
        benchmark_requirements=spec.benchmark_requirements,
        notebooks=spec.notebooks,
        tests=spec.tests,
        compact_defaults=_defaults(key, "smoke"),
        full_defaults=_defaults(key, "full"),
        stages=_stage_ladder(spec),
        required_artifacts=_REQUIRED_ARTIFACTS,
    )

all_silva_experiment_dossiers 

all_silva_experiment_dossiers()

Return experiment dossiers in canonical family order.

Source code in src/silva_networks/research_depth.py 
360
361
362
363
def all_silva_experiment_dossiers() -> tuple[SILVAExperimentDossier, ...]:
    """Return experiment dossiers in canonical family order."""

    return tuple(silva_experiment_dossier(name) for name in available_silva_families())

audit_silva_experiment_dossiers 

audit_silva_experiment_dossiers()

Return completeness errors for the progressive experiment registry.

Source code in src/silva_networks/research_depth.py 
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
def audit_silva_experiment_dossiers() -> tuple[str, ...]:
    """Return completeness errors for the progressive experiment registry."""

    errors: list[str] = []
    dossiers = all_silva_experiment_dossiers()
    if len(dossiers) != len(available_silva_families()):
        errors.append("experiment dossier count does not match the family registry")
    for dossier in dossiers:
        if len(dossier.stages) != 6:
            errors.append(f"{dossier.family}: expected six experiment stages")
        if dossier.stages[-1].evidence_status != "planned":
            errors.append(f"{dossier.family}: source-scale stage must remain explicitly planned")
        for field in (
            "title",
            "domain",
            "task_contract",
            "equation",
            "constructor_signature",
            "paper_refs",
            "repositories",
            "datasets",
            "metrics",
            "compact_defaults",
            "full_defaults",
            "required_artifacts",
        ):
            if not getattr(dossier, field):
                errors.append(f"{dossier.family}: empty dossier field {field}")
    return tuple(errors)

Where to Go Next

Question Page
Where is every family dossier? Family Reproduction Dossiers
How are compact comparisons measured? Compact Benchmarks
How should results be labeled? Result Records