library ¤

def digest(self, path: Path) -> str | None:
    """Return the content digest, or ``None`` when the file is missing."""
    try:
        status = path.stat()
    except OSError:
        self._entries.pop(path, None)
        return None
    stamp = (status.st_mtime_ns, status.st_size)
    entry = self._entries.get(path)
    if entry is not None and entry[0] == stamp:
        return entry[1]
    read_at = time.time_ns()
    digest = hashlib.sha256(path.read_bytes()).hexdigest()
    if read_at - status.st_mtime_ns > self._SETTLE_NS:
        self._entries[path] = (stamp, digest)
    else:
        self._entries.pop(path, None)
    return digest

@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

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,
    )