model ¤

@classmethod
def from_file(
    cls,
    path: str | Path,
    subcircuit: str,
    *,
    section: str | None = None,
    sections: tuple[str, ...] = (),
    dialect: str = "ngspice",
    temperature_c: float = 27.0,
    include_paths: tuple[Path, ...] = (),
    **options: Any,
) -> LibraryModel:
    """Register lazily; parse the selected corner only when instantiated.

    @tags circulax-simulation
    """
    model = cls(None, subcircuit, **options)
    model._source = (Path(path), section, tuple(sections), dialect, temperature_c, include_paths)
    return model

def inspection_identity(self, settings: Mapping[str, Any] | None = None) -> dict[str, Any]:
    """Return deterministic read-only provenance and resolved topology.

    Source/include contents and available native artifact bytes contribute
    to the fingerprint. Native artifacts are not loaded or ABI-validated;
    this identity does not establish backend readiness.
    """
    resolved = self.resolve(settings)
    library = self._select_library({**self.defaults, **(settings or {})})
    artifacts = {Path(path).resolve() for path in self.options["osdi_modules"]}
    artifacts.update(Path(path).resolve() for _, path in resolved.loads)
    artifacts.update(Path(path).resolve() for path, _ in self._modules.get(library.revision, {}).values())
    native: list[dict[str, Any]] = []
    for path in sorted(artifacts, key=str):
        record: dict[str, Any] = {"path": str(path)}
        if path.is_file():
            record["sha256"] = hashlib.sha256(path.read_bytes()).hexdigest()
        else:
            record["missing"] = True
        native.append(record)
    identity = {
        "sources": library.inspection_sources(),
        "native_artifacts": native,
        "resolved": {
            "ports": dict(resolved.ports),
            "temperature_c": resolved.temperature_c,
            "corner": {**self.defaults, **(settings or {})}.get(
                "corner", self._source[1] if self._source is not None else None
            ),
            "instances": [
                {
                    "name": instance.name,
                    "module": instance.module,
                    "nodes": list(instance.nodes),
                    "parameters": dict(instance.parameters),
                }
                for instance in resolved.instances
            ],
            "loads": [{"name": name, "path": str(path)} for name, path in resolved.loads],
        },
    }
    identity["fingerprint"] = hashlib.sha256(json.dumps(identity, sort_keys=True, separators=(",", ":")).encode()).hexdigest()
    return identity

def instantiate(self, settings: Mapping[str, Any] | None = None) -> NetlistDefinition:
    """Build the resolved topology and retain reusable native models."""
    resolved = self.resolve(settings)
    library = self._select_library({**self.defaults, **(settings or {})})
    signature = self._artifact_signature(resolved)
    cached = self._modules.get(library.revision) if self._module_signatures.get(library.revision) == signature else None
    netlist, models, modules = build_resolved(resolved, **self.options, modules=cached, expose_internal_nodes=False)
    self._modules[library.revision] = modules
    self._module_signatures[library.revision] = signature
    return NetlistDefinition(netlist, models)

def resolve(self, settings: Mapping[str, Any] | None = None) -> ResolvedCircuit:
    """Evaluate settings and cards without building or provisioning models.

    Returns ordered electrical leaf topology and public terminal aliases
    using the same corner, unit and expression bindings as execution.
    Source files may be parsed and cached; no native model, compiler or
    simulator is loaded or executed by this operation.

    @tags circulax-simulation
    """
    values = {**self.defaults, **(settings or {})}
    library = self._select_library(values)
    for name, translation in self.parameter_values.items():
        if name in values:
            if values[name] not in translation:
                msg = f"unsupported value {values[name]!r} for {name!r}; expected one of {tuple(translation)!r}"
                raise ValueError(msg)
            values[name] = translation[values[name]]
    for name, (source, target) in self.parameter_units.items():
        if name in values:
            values[name] = convert_unit(values[name], source, target)
    mapped = {
        self.params_map.get(name, name): value
        for name, value in values.items()
        if name in self.params_map or (not self.expressions and name != "temperature_c")
    }
    mapped.update({name: evaluate_source(expression, values) for name, expression in self.expressions.items()})
    resolved = library.instantiate(self.subcircuit, settings=mapped)
    if self.port_map:
        unknown = set(self.port_map.values()) - resolved.ports.keys()
        if unknown:
            msg = f"unknown library terminals {sorted(unknown)}"
            raise ValueError(msg)
        ports = {name: node for name, node in resolved.ports.items() if name not in self.port_map.values()}
        ports.update({alias: resolved.ports[terminal] for alias, terminal in self.port_map.items()})
        resolved.ports = ports
    return resolved