netlist_io ¤

@classmethod
def from_file(
    cls,
    path: str | Path,
    *,
    section: str | None = None,
    temperature_c: float = 27.0,
    include_paths: tuple[Path, ...] = (),
    dialect: str = "ngspice",
    statistical_mode: str = "reject",
) -> Library:
    """Read a library and select a named corner section when requested.

    statistical_mode="nominal" explicitly evaluates agauss at its nominal
    value. The default rejects random functions; sampling is unsupported.
    """
    library = cls(temperature_c=temperature_c, include_paths=include_paths, dialect=dialect, statistical_mode=statistical_mode)
    library.include(path, section=section)
    return library

def include(self, path: str | Path, *, section: str | None = None) -> None:
    """Add a library to the same root scope, preserving declaration order."""
    source = Path(path).resolve()
    statements = self._read(source, section, (), set())
    self._populate(self.frame, statements)
    self._sources.append((source, section))

def inspection_sources(self) -> list[dict[str, str]]:
    """Fingerprint actual parsed source dependencies without native loading."""
    records = []
    for path in sorted(self._parsed, key=str):
        digest = self._digests.digest(path)
        if digest is None:
            msg = f"{path}: library source not found"
            raise NetlistError(msg)
        records.append({"path": str(path), "sha256": digest})
    return records

def instantiate(
    self, subcircuit: str, nodes: tuple[str, ...] | None = None, settings: dict[str, float] | None = None, *, name: str = "X1"
) -> ResolvedCircuit:
    """Expand a library subcircuit without loading executable OSDI modules."""
    found = self.frame.find(subcircuit.lower(), "subcircuits")
    if found is None:
        msg = f"unknown subcircuit {subcircuit!r}"
        raise NetlistError(msg)
    _, definition = found
    ports = tuple(_nodes(definition[0].node))
    actual_nodes = nodes if nodes is not None else ports
    instances: list[ResolvedInstance] = []
    self._instantiate(definition, actual_nodes, settings or {}, name, instances, ())
    return ResolvedCircuit(instances, list(self.loads), dict(zip(ports, actual_nodes, strict=True)), self.temperature_c)

def refreshed(self) -> Library:
    """Reuse unchanged parsed cards or reparse edited, removed or shadowed source dependencies."""
    unchanged = all(self._digests.digest(path) == fingerprint for path, fingerprint in self._parsed_fingerprints.items())
    if unchanged and not any(c.is_file() for candidates, found in self._lookups.items() for c in candidates[:found]):
        return self
    return self.with_temperature(self.temperature_c)

def resolve(self) -> ResolvedCircuit:
    """Expand instances declared at the top level of a loaded circuit file."""
    instances: list[ResolvedInstance] = []
    self._calls(self.frame, {}, "", instances, ())
    return ResolvedCircuit(instances, list(self.loads), temperature_c=self.temperature_c)

def with_temperature(self, temperature_c: float) -> Library:
    """Reparse source declarations at a new temperature without mutation."""
    if not self._sources:
        msg = "Temperature override requires reparsable library source declarations"
        raise ValueError(msg)
    library = type(self)(
        temperature_c=temperature_c,
        include_paths=self.include_paths,
        dialect=self.dialect,
        statistical_mode=self.scope.statistical_mode,
    )
    for path, section in self._sources:
        library.include(path, section=section)
    return library

@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

def compile(
    self,
    *,
    module_paths: tuple[Path, ...] = (),
    osdi_modules: tuple[Path, ...] = (),
    compiler: str | None = None,
    cache_dir: Path | None = None,
    backend: str = "dense",
    analysis: str = "dc",
    state_policy: str = "reject",
    simparams: Mapping[str, float] | None = None,
) -> Any:
    """Compile with immutable native analysis mode: dc (default), ac, or tran.

    simparams supplies numeric $simparam settings to all native devices.
    Separate registrations are required to change mode. For AC, retain
    DC conductance and obtain capacitance from an AC registration.

    osdi_modules registers compiled `.osdi`/`.va` files by their own
    descriptor name directly, for libraries (e.g. plain ngspice model
    cards) that reference a module by name without a `load` statement.
    """
    from circulax.netlist_io.osdi import compile_resolved

    return compile_resolved(
        self,
        module_paths=module_paths,
        osdi_modules=osdi_modules,
        compiler=compiler,
        cache_dir=cache_dir,
        backend=backend,
        analysis=analysis,
        state_policy=state_policy,
        simparams=simparams,
    )