vnuli 0.1.0__py3-none-any.whl

vnuli/__init__.py

@@ -0,0 +1,3 @@
+"""Vnuli engineering investigation tools."""
+
+__all__ = []

vnuli/adapters/__init__.py

@@ -0,0 +1 @@
+"""External data source adapter contracts."""

vnuli/adapters/base.py

@@ -0,0 +1,41 @@
+"""Source-independent adapter contract for Vnuli data."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Sequence
+
+from vnuli.domain.channel import Channel
+from vnuli.domain.run import Run
+from vnuli.domain.test import Test
+from vnuli.domain.timeseries import TimeSeries
+
+
+class DataAdapter(ABC):
+    """Boundary that normalizes external data sources into domain objects."""
+
+    @abstractmethod
+    def list_tests(self) -> Sequence[Test]:
+        """Return available tests as domain objects."""
+
+    @abstractmethod
+    def list_runs(self, test_id: str | None = None) -> Sequence[Run]:
+        """Return available runs, optionally filtered by stable parent test ID."""
+
+    @abstractmethod
+    def list_channels(self, run_id: str) -> Sequence[Channel]:
+        """Return channels available for a stable run ID."""
+
+    @abstractmethod
+    def load_timeseries(
+        self,
+        run_id: str,
+        channel_ids: Sequence[str],
+        start: float,
+        end: float,
+    ) -> Sequence[TimeSeries]:
+        """Return requested channel samples where start <= timestamp <= end.
+
+        Concrete adapters normalize source-specific storage and boundary behavior
+        to this inclusive Vnuli contract.
+        """

vnuli/adapters/csv.py

@@ -0,0 +1,176 @@
+"""CSV-backed adapter for the synthetic Prototype 0.1 fixture."""
+
+from __future__ import annotations
+
+import csv
+import json
+from math import isfinite
+from pathlib import Path
+from typing import Mapping, Sequence
+
+from vnuli.adapters.base import DataAdapter
+from vnuli.domain.channel import Channel
+from vnuli.domain.run import Run
+from vnuli.domain.test import Test
+from vnuli.domain.timeseries import TimeSeries
+
+METADATA_FILENAME = "synthetic_test_001_metadata.json"
+SAMPLES_FILENAME = "synthetic_test_001.csv"
+
+
+class CSVAdapter(DataAdapter):
+    """Read AI-visible CSV fixture metadata into domain objects."""
+
+    def __init__(self, sample_data_dir: Path | str = "sample_data") -> None:
+        self._sample_data_dir = Path(sample_data_dir)
+        self._samples_path = self._sample_data_dir / SAMPLES_FILENAME
+        metadata = _load_metadata(self._sample_data_dir / METADATA_FILENAME)
+
+        self._test = _load_test(metadata)
+        self._run = _load_run(metadata)
+        self._channels = _load_channels(metadata)
+        self._channel_ids = frozenset(channel.id for channel in self._channels)
+
+    def list_tests(self) -> Sequence[Test]:
+        return (self._test,)
+
+    def list_runs(self, test_id: str | None = None) -> Sequence[Run]:
+        if test_id is None or test_id == self._run.test_id:
+            return (self._run,)
+        return ()
+
+    def list_channels(self, run_id: str) -> Sequence[Channel]:
+        if run_id != self._run.id:
+            raise ValueError(f"Unknown run_id: {run_id}")
+        return self._channels
+
+    def load_timeseries(
+        self,
+        run_id: str,
+        channel_ids: Sequence[str],
+        start: float,
+        end: float,
+    ) -> Sequence[TimeSeries]:
+        if run_id != self._run.id:
+            raise ValueError(f"Unknown run_id: {run_id}")
+
+        selected_channel_ids = _validate_channel_ids(channel_ids)
+        unknown_channel_ids = [
+            channel_id
+            for channel_id in selected_channel_ids
+            if channel_id not in self._channel_ids
+        ]
+        if unknown_channel_ids:
+            raise ValueError(f"Unknown channel_id: {unknown_channel_ids[0]}")
+
+        start_bound = _validate_bound("start", start)
+        end_bound = _validate_bound("end", end)
+        if end_bound < start_bound:
+            raise ValueError("end must be >= start")
+
+        timestamps: list[float] = []
+        values_by_channel = {
+            channel_id: []
+            for channel_id in selected_channel_ids
+        }
+
+        with self._samples_path.open(newline="", encoding="utf-8") as file:
+            reader = csv.DictReader(file)
+            for row in reader:
+                timestamp = float(row["time_seconds"])
+                if start_bound <= timestamp <= end_bound:
+                    timestamps.append(timestamp)
+                    for channel_id in selected_channel_ids:
+                        values_by_channel[channel_id].append(float(row[channel_id]))
+
+        return tuple(
+            TimeSeries(
+                channel_id=channel_id,
+                timestamps=timestamps,
+                values=values_by_channel[channel_id],
+            )
+            for channel_id in selected_channel_ids
+        )
+
+
+def _load_metadata(path: Path) -> Mapping[str, object]:
+    with path.open(encoding="utf-8") as file:
+        metadata = json.load(file)
+
+    if not isinstance(metadata, Mapping):
+        raise TypeError("CSV metadata must be a JSON object")
+    return metadata
+
+
+def _load_test(metadata: Mapping[str, object]) -> Test:
+    test_data = metadata["test"]
+    if not isinstance(test_data, Mapping):
+        raise TypeError("CSV metadata test must be an object")
+
+    return Test(
+        id=test_data["id"],  # type: ignore[arg-type]
+        name=test_data["name"],  # type: ignore[arg-type]
+    )
+
+
+def _load_run(metadata: Mapping[str, object]) -> Run:
+    run_data = metadata["run"]
+    if not isinstance(run_data, Mapping):
+        raise TypeError("CSV metadata run must be an object")
+
+    return Run(
+        id=run_data["id"],  # type: ignore[arg-type]
+        test_id=run_data["test_id"],  # type: ignore[arg-type]
+        name=run_data["name"],  # type: ignore[arg-type]
+        channel_ids=run_data["channel_ids"],  # type: ignore[arg-type]
+        duration=run_data["duration_seconds"],  # type: ignore[arg-type]
+    )
+
+
+def _load_channels(metadata: Mapping[str, object]) -> tuple[Channel, ...]:
+    channels_data = metadata["channels"]
+    if not isinstance(channels_data, Sequence) or isinstance(channels_data, (str, bytes)):
+        raise TypeError("CSV metadata channels must be a sequence")
+
+    channels = []
+    for channel_data in channels_data:
+        if not isinstance(channel_data, Mapping):
+            raise TypeError("CSV metadata channel entries must be objects")
+        channels.append(Channel.from_dict(channel_data))
+
+    return tuple(channels)
+
+
+def _validate_channel_ids(channel_ids: object) -> tuple[str, ...]:
+    if isinstance(channel_ids, (str, bytes)) or not isinstance(channel_ids, Sequence):
+        raise TypeError("channel_ids must be a non-empty sequence of strings")
+
+    normalized = tuple(_validate_channel_id(channel_id) for channel_id in channel_ids)
+    if not normalized:
+        raise ValueError("channel_ids must not be empty")
+    if len(set(normalized)) != len(normalized):
+        raise ValueError("channel_ids must be unique")
+
+    return normalized
+
+
+def _validate_channel_id(channel_id: object) -> str:
+    if not isinstance(channel_id, str):
+        raise TypeError("channel_ids must contain strings")
+
+    normalized = channel_id.strip()
+    if not normalized:
+        raise ValueError("channel_ids must not contain empty values")
+
+    return normalized
+
+
+def _validate_bound(name: str, value: object) -> float:
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        raise TypeError(f"{name} must be a finite number")
+
+    bound = float(value)
+    if not isfinite(bound):
+        raise ValueError(f"{name} must be a finite number")
+
+    return bound

vnuli/adapters/nasa_milling.py

@@ -0,0 +1,434 @@
+"""NASA Milling Dataset adapter for the original MATLAB source file."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from math import isfinite, isnan
+from typing import Any
+
+import numpy as np
+from scipy.io import loadmat
+
+from vnuli.adapters.base import DataAdapter
+from vnuli.config import (
+    SIGNAL_UNIT_POLICY_SOURCE_NATIVE,
+    TIME_BASIS_GENERATED_ZERO,
+    NasaMillingMatConfig,
+)
+from vnuli.domain.channel import Channel
+from vnuli.domain.run import Run
+from vnuli.domain.test import Test
+from vnuli.domain.timeseries import TimeSeries
+from vnuli.domain.units import Unit
+
+SIGNAL_FIELDS = (
+    "smcAC",
+    "smcDC",
+    "vib_table",
+    "vib_spindle",
+    "AE_table",
+    "AE_spindle",
+)
+SCALAR_FIELDS = ("case", "run", "VB", "time", "DOC", "feed", "material")
+REQUIRED_FIELDS = (*SCALAR_FIELDS, *SIGNAL_FIELDS)
+
+CHANNEL_DESCRIPTIONS: Mapping[str, Mapping[str, str]] = {
+    "smcAC": {
+        "name": "AC spindle motor current",
+        "quantity": "spindle motor current",
+        "location": "spindle motor",
+    },
+    "smcDC": {
+        "name": "DC spindle motor current",
+        "quantity": "spindle motor current",
+        "location": "spindle motor",
+    },
+    "vib_table": {
+        "name": "Table vibration",
+        "quantity": "vibration",
+        "location": "table",
+    },
+    "vib_spindle": {
+        "name": "Spindle vibration",
+        "quantity": "vibration",
+        "location": "spindle",
+    },
+    "AE_table": {
+        "name": "Table acoustic emission",
+        "quantity": "acoustic emission",
+        "location": "table",
+    },
+    "AE_spindle": {
+        "name": "Spindle acoustic emission",
+        "quantity": "acoustic emission",
+        "location": "spindle",
+    },
+}
+
+
+@dataclass(frozen=True)
+class _Record:
+    run: Run
+    signal_values: Mapping[str, tuple[float, ...]]
+    sample_count: int
+
+
+class NasaMillingMatAdapter(DataAdapter):
+    """Read the NASA Milling Dataset MATLAB file into domain objects."""
+
+    def __init__(self, config: NasaMillingMatConfig) -> None:
+        if not isinstance(config, NasaMillingMatConfig):
+            raise TypeError("config must be a NasaMillingMatConfig")
+        if config.time_basis != TIME_BASIS_GENERATED_ZERO:
+            raise ValueError(
+                f"time_basis must be {TIME_BASIS_GENERATED_ZERO!r}"
+            )
+        if config.signal_unit_policy != SIGNAL_UNIT_POLICY_SOURCE_NATIVE:
+            raise ValueError(
+                f"signal_unit_policy must be {SIGNAL_UNIT_POLICY_SOURCE_NATIVE!r}"
+            )
+
+        self._config = config
+        self._test = Test(
+            id=config.dataset_id,
+            name=config.dataset_name,
+            metadata={
+                "adapter": config.adapter,
+                "source_format": "matlab_v5",
+                "source_path": str(config.mat_path),
+            },
+        )
+
+        records = _load_records(config)
+        self._records_by_run_id = {record.run.id: record for record in records}
+        self._runs = tuple(record.run for record in records)
+        self._channels = _build_channels(config)
+        self._channel_ids = frozenset(channel.id for channel in self._channels)
+
+        self._test = Test(
+            id=config.dataset_id,
+            name=config.dataset_name,
+            metadata={
+                "adapter": config.adapter,
+                "source_format": "matlab_v5",
+                "source_path": str(config.mat_path),
+                "record_count": len(self._runs),
+            },
+        )
+
+    def list_tests(self) -> Sequence[Test]:
+        return (self._test,)
+
+    def list_runs(self, test_id: str | None = None) -> Sequence[Run]:
+        if test_id is None or test_id == self._test.id:
+            return self._runs
+        return ()
+
+    def list_channels(self, run_id: str) -> Sequence[Channel]:
+        self._record_for_run_id(run_id)
+        return self._channels
+
+    def load_timeseries(
+        self,
+        run_id: str,
+        channel_ids: Sequence[str],
+        start: float,
+        end: float,
+    ) -> Sequence[TimeSeries]:
+        record = self._record_for_run_id(run_id)
+        selected_channel_ids = _validate_channel_ids(channel_ids)
+        for channel_id in selected_channel_ids:
+            if channel_id not in self._channel_ids:
+                raise ValueError(f"Unknown channel_id: {channel_id}")
+
+        start_bound = _validate_bound("start", start)
+        end_bound = _validate_bound("end", end)
+        if end_bound < start_bound:
+            raise ValueError("end must be >= start")
+
+        timestamps = np.arange(record.sample_count, dtype=float) / self._config.sample_rate_hz
+        mask = (timestamps >= start_bound) & (timestamps <= end_bound)
+        bounded_timestamps = tuple(float(timestamp) for timestamp in timestamps[mask])
+
+        return tuple(
+            TimeSeries(
+                channel_id=channel_id,
+                timestamps=bounded_timestamps,
+                values=tuple(
+                    record.signal_values[channel_id][index]
+                    for index in np.nonzero(mask)[0]
+                ),
+            )
+            for channel_id in selected_channel_ids
+        )
+
+    def _record_for_run_id(self, run_id: str) -> _Record:
+        try:
+            return self._records_by_run_id[run_id]
+        except KeyError as error:
+            raise ValueError(f"Unknown run_id: {run_id}") from error
+
+
+def _load_records(config: NasaMillingMatConfig) -> tuple[_Record, ...]:
+    mat_data = loadmat(config.mat_path, squeeze_me=True, struct_as_record=False)
+    if "mill" not in mat_data:
+        raise ValueError("NASA Milling MAT file must contain top-level variable 'mill'")
+
+    source_records = _normalize_records(mat_data["mill"])
+    if not source_records:
+        raise ValueError("NASA Milling 'mill' variable must contain at least one record")
+
+    return tuple(
+        _build_record(config, source_record, index)
+        for index, source_record in enumerate(source_records)
+    )
+
+
+def _normalize_records(value: object) -> tuple[object, ...]:
+    if _is_struct_like(value):
+        return (value,)
+
+    if isinstance(value, np.ndarray):
+        flattened = tuple(item for item in value.ravel())
+        if flattened and all(_is_struct_like(item) for item in flattened):
+            return flattened
+
+    raise TypeError("NASA Milling 'mill' variable must be a MATLAB struct array")
+
+
+def _build_record(
+    config: NasaMillingMatConfig,
+    source_record: object,
+    index: int,
+) -> _Record:
+    _require_consumed_fields(source_record)
+
+    source_case = _required_integer_scalar(source_record, "case", index)
+    source_run = _required_integer_scalar(source_record, "run", index)
+    scalar_time = _required_numeric_scalar(source_record, "time", index)
+    doc = _required_numeric_scalar(source_record, "DOC", index)
+    feed = _required_numeric_scalar(source_record, "feed", index)
+    material = _required_integer_scalar(source_record, "material", index)
+    vb = _required_numeric_scalar(source_record, "VB", index, allow_nan=True)
+
+    signal_values = {
+        field_name: _required_signal_values(source_record, field_name, index)
+        for field_name in SIGNAL_FIELDS
+    }
+    sample_counts = {len(values) for values in signal_values.values()}
+    if len(sample_counts) != 1:
+        raise ValueError(
+            f"NASA Milling record {index} signal fields must have matching lengths"
+        )
+    sample_count = sample_counts.pop()
+    if sample_count == 0:
+        raise ValueError(f"NASA Milling record {index} signal fields must not be empty")
+
+    vb_missing = isnan(vb)
+    run_id = (
+        f"{config.dataset_id}_RECORD_{index:03d}_"
+        f"CASE_{source_case:02d}_RUN_{source_run:02d}"
+    )
+    generated_time_end = (sample_count - 1) / config.sample_rate_hz
+    run = Run(
+        id=run_id,
+        test_id=config.dataset_id,
+        name=f"NASA Milling record {index:03d} case {source_case} run {source_run}",
+        channel_ids=SIGNAL_FIELDS,
+        duration=None,
+        metadata={
+            "source_record_index": index,
+            "source_case": source_case,
+            "source_run": source_run,
+            "VB": None if vb_missing else vb,
+            "VB_missing": vb_missing,
+            "time": scalar_time,
+            "time_unit_status": "unknown",
+            "DOC": doc,
+            "feed": feed,
+            "material": material,
+            "sample_count": sample_count,
+            "generated_time_start": 0.0,
+            "generated_time_end": generated_time_end,
+            "sample_rate_hz": config.sample_rate_hz,
+            "time_basis": config.time_basis,
+            "time_basis_source": "configuration",
+            "source_path": str(config.mat_path),
+        },
+    )
+    return _Record(run=run, signal_values=signal_values, sample_count=sample_count)
+
+
+def _build_channels(config: NasaMillingMatConfig) -> tuple[Channel, ...]:
+    channels = []
+    for field_name in SIGNAL_FIELDS:
+        description = CHANNEL_DESCRIPTIONS[field_name]
+        channels.append(
+            Channel(
+                id=field_name,
+                name=description["name"],
+                quantity=description["quantity"],
+                units=Unit(f"source_native:{field_name}"),
+                sample_rate=config.sample_rate_hz,
+                location=description["location"],
+                metadata={
+                    "unit_status": "not_encoded_in_source",
+                    "unit_token_semantics": "opaque_source_native_placeholder",
+                    "unit_policy": config.signal_unit_policy,
+                    "source_field": field_name,
+                    "time_basis": config.time_basis,
+                    "sample_rate_hz": config.sample_rate_hz,
+                    "time_basis_source": "configuration",
+                    "source_path": str(config.mat_path),
+                },
+            )
+        )
+    return tuple(channels)
+
+
+def _require_consumed_fields(source_record: object) -> None:
+    missing_fields = [
+        field_name
+        for field_name in REQUIRED_FIELDS
+        if not _has_field(source_record, field_name)
+    ]
+    if missing_fields:
+        raise ValueError(
+            "NASA Milling record is missing required field: "
+            f"{missing_fields[0]}"
+        )
+
+
+def _required_integer_scalar(
+    source_record: object,
+    field_name: str,
+    record_index: int,
+) -> int:
+    value = _required_numeric_scalar(source_record, field_name, record_index)
+    if isnan(value) or not value.is_integer():
+        raise ValueError(
+            f"NASA Milling record {record_index} field '{field_name}' must be an integer"
+        )
+    return int(value)
+
+
+def _required_numeric_scalar(
+    source_record: object,
+    field_name: str,
+    record_index: int,
+    *,
+    allow_nan: bool = False,
+) -> float:
+    raw_value = _get_field(source_record, field_name)
+    array = np.asarray(raw_value)
+    if array.size != 1:
+        raise ValueError(
+            f"NASA Milling record {record_index} field '{field_name}' must be scalar"
+        )
+    try:
+        value = float(array.reshape(-1)[0])
+    except (TypeError, ValueError) as error:
+        raise TypeError(
+            f"NASA Milling record {record_index} field '{field_name}' must be numeric"
+        ) from error
+
+    if allow_nan and isnan(value):
+        return value
+    if not isfinite(value):
+        raise ValueError(
+            f"NASA Milling record {record_index} field '{field_name}' must be finite"
+        )
+    return value
+
+
+def _required_signal_values(
+    source_record: object,
+    field_name: str,
+    record_index: int,
+) -> tuple[float, ...]:
+    raw_value = _get_field(source_record, field_name)
+    array = np.asarray(raw_value)
+    if array.ndim == 0:
+        raise ValueError(
+            f"NASA Milling record {record_index} field '{field_name}' must be a signal array"
+        )
+    if array.ndim > 1:
+        non_singleton_dims = [dimension for dimension in array.shape if dimension != 1]
+        if len(non_singleton_dims) != 1:
+            raise ValueError(
+                f"NASA Milling record {record_index} field '{field_name}' "
+                "must be one-dimensional"
+            )
+    try:
+        values = tuple(float(value) for value in array.reshape(-1))
+    except (TypeError, ValueError) as error:
+        raise TypeError(
+            f"NASA Milling record {record_index} field '{field_name}' must be numeric"
+        ) from error
+
+    if any(not isfinite(value) and not isnan(value) for value in values):
+        raise ValueError(
+            f"NASA Milling record {record_index} field '{field_name}' "
+            "contains a value the TimeSeries domain cannot represent"
+        )
+    return values
+
+
+def _is_struct_like(value: object) -> bool:
+    if hasattr(value, "_fieldnames"):
+        return True
+    if isinstance(value, np.void) and value.dtype.names:
+        return True
+    return False
+
+
+def _has_field(source_record: object, field_name: str) -> bool:
+    if hasattr(source_record, "_fieldnames"):
+        return field_name in source_record._fieldnames  # noqa: SLF001
+    if isinstance(source_record, np.void) and source_record.dtype.names:
+        return field_name in source_record.dtype.names
+    return False
+
+
+def _get_field(source_record: object, field_name: str) -> Any:
+    if hasattr(source_record, "_fieldnames"):
+        return getattr(source_record, field_name)
+    if isinstance(source_record, np.void) and source_record.dtype.names:
+        return source_record[field_name]
+    raise TypeError("NASA Milling record must be a MATLAB struct")
+
+
+def _validate_channel_ids(channel_ids: object) -> tuple[str, ...]:
+    if isinstance(channel_ids, (str, bytes)) or not isinstance(channel_ids, Sequence):
+        raise TypeError("channel_ids must be a non-empty sequence of strings")
+
+    normalized = tuple(_validate_channel_id(channel_id) for channel_id in channel_ids)
+    if not normalized:
+        raise ValueError("channel_ids must not be empty")
+    if len(set(normalized)) != len(normalized):
+        raise ValueError("channel_ids must be unique")
+
+    return normalized
+
+
+def _validate_channel_id(channel_id: object) -> str:
+    if not isinstance(channel_id, str):
+        raise TypeError("channel_ids must contain strings")
+
+    normalized = channel_id.strip()
+    if not normalized:
+        raise ValueError("channel_ids must not contain empty values")
+
+    return normalized
+
+
+def _validate_bound(name: str, value: object) -> float:
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        raise TypeError(f"{name} must be a finite number")
+
+    bound = float(value)
+    if not isfinite(bound):
+        raise ValueError(f"{name} must be a finite number")
+
+    return bound

vnuli/analysis/__init__.py

@@ -0,0 +1,2 @@
+"""Deterministic analysis primitives for Vnuli."""
+