IO API

Unified I/O layer: parsing waveform outputs into xarray.Dataset objects.

Low-level Parsers

`Trace` `dataclass`

Um traço: nome, unidade (quando existir) e vetor de valores (np.ndarray).

Source code in spicelab/io/raw_reader.py

@dataclass(frozen=True)
class Trace:
    """Um traço: nome, unidade (quando existir) e vetor de valores (np.ndarray)."""

    name: str
    unit: str | None
    values: NDArray[Any]
    _complex: NDArray[Any] | None = None  # apenas AC: vetor complex

    def magnitude(self) -> NDArray[Any]:
        if self._complex is not None:
            return cast(NDArray[Any], np.abs(self._complex))
        return cast(NDArray[Any], np.abs(self.values))

    def real(self) -> NDArray[Any]:
        if self._complex is not None:
            return self._complex.real
        return self.values

    def imag(self) -> NDArray[Any]:
        if self._complex is not None:
            return self._complex.imag
        return np.zeros_like(self.values, dtype=float)

    def phase_deg(self) -> NDArray[Any]:
        if self._complex is not None:
            return np.angle(self._complex, deg=True)
        return np.zeros_like(self.values, dtype=float)

`TraceSet`

Conjunto de traços indexado por nome. O primeiro traço é o eixo X (time/freq).

Acesso

ts["V(out)"] -> Trace ts.x -> Trace (primeira coluna) ts.names -> lista de nomes ts.to_dataframe() -> pandas.DataFrame (se pandas instalado)

Source code in spicelab/io/raw_reader.py

class TraceSet:
    """
    Conjunto de traços indexado por nome. O primeiro traço é o eixo X (time/freq).

    Acesso:
        ts["V(out)"] -> Trace
        ts.x -> Trace (primeira coluna)
        ts.names -> lista de nomes
        ts.to_dataframe() -> pandas.DataFrame (se pandas instalado)
    """

    def __init__(
        self,
        traces: list[Trace],
        *,
        meta: dict[str, Any] | None = None,
    ) -> None:
        if not traces:
            raise ValueError("TraceSet requires at least one trace")
        self._traces = traces
        self._by_name: dict[str, Trace] = {t.name: t for t in traces}
        self.meta: dict[str, Any] = meta or {}

        # valida tamanhos
        n = len(self._traces[0].values)
        for t in self._traces[1:]:
            if len(t.values) != n:
                raise ValueError("All traces must have same length")

    @property
    def x(self) -> Trace:
        return self._traces[0]

    @property
    def names(self) -> list[str]:
        return [t.name for t in self._traces]

    def __getitem__(self, key: str) -> Trace:
        try:
            return self._by_name[key]
        except KeyError as e:
            raise KeyError(f"Trace '{key}' not found. Available: {self.names}") from e

    def to_dataframe(self) -> Any:
        # Evita depender de stubs do pandas: import dinâmico via importlib, tipado como Any
        try:
            pd: Any = importlib.import_module("pandas")
        except Exception as exc:  # pragma: no cover
            raise RuntimeError("pandas is required for to_dataframe()") from exc
        data = {t.name: t.values for t in self._traces}
        return pd.DataFrame(data)

    @classmethod
    def from_dataset(cls, dataset: Any) -> TraceSet:
        """Build a TraceSet from an xarray.Dataset-like object."""

        try:
            import numpy as _np
        except Exception as exc:  # pragma: no cover - numpy optional
            raise RuntimeError("numpy is required to convert dataset into TraceSet") from exc

        if not hasattr(dataset, "data_vars"):
            raise TypeError("Expected an xarray.Dataset-like object with 'data_vars'")

        coords = getattr(dataset, "coords", {})
        coord_names = ("time", "freq", "frequency", "index")
        coord_obj = None
        coord_key = None
        for name in coord_names:
            if name in coords:
                coord_obj = coords[name]
                coord_key = name
                break
        if coord_obj is not None:
            x_values = _np.asarray(getattr(coord_obj, "values", coord_obj), dtype=float)
            x_name = str(getattr(coord_obj, "name", None) or coord_key or "index")
        else:
            data_vars = list(getattr(dataset, "data_vars", {}))
            if not data_vars:
                raise ValueError("Dataset has no data variables to build TraceSet")
            first = _np.asarray(dataset[data_vars[0]].values)
            length = first.shape[0] if first.ndim > 0 else 1
            x_values = _np.arange(length, dtype=float)
            x_name = "index"

        x_values = _np.asarray(x_values, dtype=float).reshape(-1)
        axis_len = x_values.shape[0]
        traces: list[Trace] = [Trace(x_name, None, x_values)]

        for name, data in getattr(dataset, "data_vars", {}).items():
            arr = _np.asarray(data.values)
            if arr.ndim == 0:
                arr = _np.full((axis_len,), float(arr))
            elif arr.shape[0] != axis_len:
                try:
                    arr = arr.reshape(axis_len, -1)
                    arr = arr[:, 0]
                except Exception as exc:  # pragma: no cover - defensive reshape
                    raise ValueError(
                        f"Unable to align data variable '{name}' with independent axis"
                    ) from exc
            else:
                arr = arr.reshape(axis_len)
            arr = _np.real_if_close(arr)
            traces.append(Trace(str(name), None, _np.asarray(arr)))

        meta = dict(getattr(dataset, "attrs", {}))
        return cls(traces, meta=meta)

`from_dataset(dataset)` `classmethod`

Build a TraceSet from an xarray.Dataset-like object.

Source code in spicelab/io/raw_reader.py

@classmethod
def from_dataset(cls, dataset: Any) -> TraceSet:
    """Build a TraceSet from an xarray.Dataset-like object."""

    try:
        import numpy as _np
    except Exception as exc:  # pragma: no cover - numpy optional
        raise RuntimeError("numpy is required to convert dataset into TraceSet") from exc

    if not hasattr(dataset, "data_vars"):
        raise TypeError("Expected an xarray.Dataset-like object with 'data_vars'")

    coords = getattr(dataset, "coords", {})
    coord_names = ("time", "freq", "frequency", "index")
    coord_obj = None
    coord_key = None
    for name in coord_names:
        if name in coords:
            coord_obj = coords[name]
            coord_key = name
            break
    if coord_obj is not None:
        x_values = _np.asarray(getattr(coord_obj, "values", coord_obj), dtype=float)
        x_name = str(getattr(coord_obj, "name", None) or coord_key or "index")
    else:
        data_vars = list(getattr(dataset, "data_vars", {}))
        if not data_vars:
            raise ValueError("Dataset has no data variables to build TraceSet")
        first = _np.asarray(dataset[data_vars[0]].values)
        length = first.shape[0] if first.ndim > 0 else 1
        x_values = _np.arange(length, dtype=float)
        x_name = "index"

    x_values = _np.asarray(x_values, dtype=float).reshape(-1)
    axis_len = x_values.shape[0]
    traces: list[Trace] = [Trace(x_name, None, x_values)]

    for name, data in getattr(dataset, "data_vars", {}).items():
        arr = _np.asarray(data.values)
        if arr.ndim == 0:
            arr = _np.full((axis_len,), float(arr))
        elif arr.shape[0] != axis_len:
            try:
                arr = arr.reshape(axis_len, -1)
                arr = arr[:, 0]
            except Exception as exc:  # pragma: no cover - defensive reshape
                raise ValueError(
                    f"Unable to align data variable '{name}' with independent axis"
                ) from exc
        else:
            arr = arr.reshape(axis_len)
        arr = _np.real_if_close(arr)
        traces.append(Trace(str(name), None, _np.asarray(arr)))

    meta = dict(getattr(dataset, "attrs", {}))
    return cls(traces, meta=meta)

`parse_ngspice_ascii_raw(path)`

Parser robusto para NGSpice ASCII RAW.

Retorna TraceSet onde a primeira coluna é o eixo X (tipicamente 'time' ou 'frequency').

Source code in spicelab/io/raw_reader.py

def parse_ngspice_ascii_raw(path: str) -> TraceSet:
    """
    Parser robusto para NGSpice ASCII RAW.

    Retorna TraceSet onde a primeira coluna é o eixo X (tipicamente 'time' ou 'frequency').
    """
    with open(path, encoding="utf-8", errors="ignore") as f:
        lines = f.read().splitlines()

    meta, i0 = _parse_header(lines)
    nvars = int(meta["nvars"])
    npoints = int(meta["npoints"])
    vars_meta, i1 = _parse_variables(lines, i0, nvars)
    data, complex_cols = _parse_values(lines, i1, nvars, npoints)

    traces: list[Trace] = []
    for j, (name, unit) in enumerate(vars_meta):
        traces.append(
            Trace(
                name=name,
                unit=unit,
                values=data[:, j].copy(),
                _complex=complex_cols[j],
            )
        )
    return TraceSet(traces, meta=meta)

`parse_ngspice_ascii_raw_multi(path)`

Lê um arquivo ASCII com múltiplos plots (p.ex. .step nativo) e retorna uma lista de TraceSet (um por bloco).

Source code in spicelab/io/raw_reader.py

def parse_ngspice_ascii_raw_multi(path: str) -> list[TraceSet]:
    """
    Lê um arquivo ASCII com múltiplos plots (p.ex. .step nativo) e retorna
    uma lista de TraceSet (um por bloco).
    """
    with open(path, encoding="utf-8", errors="ignore") as f:
        lines = f.read().splitlines()

    i = 0
    out: list[TraceSet] = []
    while i < len(lines):
        # procurar início de um bloco (Title:/Plotname:/Variables:)
        # Reutiliza as funções privadas para cada bloco
        # pular linhas vazias
        while i < len(lines) and not lines[i].strip():
            i += 1
        if i >= len(lines):
            break
        # precisa ver se há um cabeçalho válido
        try:
            meta, i0 = _parse_header(lines[i:])
            nvars = int(meta["nvars"])
            npoints = int(meta["npoints"])
            vars_meta, i1 = _parse_variables(lines[i:], i0, nvars)
            data, complex_cols = _parse_values(lines[i:], i1, nvars, npoints)
        except Exception:
            # se não conseguiu, avança uma linha e tenta de novo
            i += 1
            continue

        traces: list[Trace] = []
        for j, (name, unit) in enumerate(vars_meta):
            traces.append(
                Trace(name=name, unit=unit, values=data[:, j].copy(), _complex=complex_cols[j])
            )
        out.append(TraceSet(traces, meta=meta))
        # avançar: i += i1 + npoints ... mas já usamos slices; então mova i para frente
        # tenta achar próximo 'Title:' após o bloco atual
        # heurística simples: move i até encontrar próxima 'Title:' ou EOF
        k = i + i1 + npoints + 4  # + margem
        i = max(i + 1, k)
    return out

`parse_ngspice_raw(path)`

Dispatcher para RAW ASCII ou binário.

Suporta formato binário de linha simples (LTspice/NGSpice) para casos reais e complexos.

Source code in spicelab/io/raw_reader.py

def parse_ngspice_raw(path: str) -> TraceSet:
    """Dispatcher para RAW ASCII ou binário.

    Suporta formato binário de linha simples (LTspice/NGSpice) para casos reais e complexos.
    """
    with open(path, "rb") as f:
        blob = f.read()
    # Heurísticas:
    # 1. ASCII header: contém 'Binary:' sem null interleaving.
    # 2. UTF-16 (wide) header: contém padrão intercalado
    #    B\x00i\x00n\x00a... ou grande densidade de nulls.
    head_scan = blob[:8192]
    wide_pattern = b"B\x00i\x00n\x00a\x00r\x00y\x00:\x00"
    is_ascii_binary = b"Binary:" in head_scan or b"binary" in head_scan.lower()
    is_wide_binary = wide_pattern in head_scan

    if is_ascii_binary:
        meta, data_bytes = _parse_binary_header_and_data(blob)
        return _parse_binary_payload(meta, data_bytes)
    if is_wide_binary:
        # Localizar fim da linha 'Binary:' (padrão newline UTF-16 '\n\x00')
        marker_pos = head_scan.find(wide_pattern)
        newline_pat = b"\n\x00"
        nl_pos = head_scan.find(newline_pat, marker_pos)
        if nl_pos == -1:
            raise ValueError("UTF-16 binary RAW: newline after Binary: not found")
        header_bytes = blob[: nl_pos + 2]
        # Remover nulls para obter texto ascii simplificado
        ascii_header = header_bytes[::2].decode("utf-8", errors="ignore")
        # Reaproveitar parser ascii-binary: reconstruir bytes artificiais com ascii header e newline
        rebuilt = ascii_header.encode("utf-8") + blob[nl_pos + 2 :]
        meta, data_bytes = _parse_binary_header_and_data(rebuilt)
        return _parse_binary_payload(meta, data_bytes)
    # caso contrário tratar como ASCII
    return parse_ngspice_ascii_raw(path)