graphspace 0.1.0__py3-none-any.whl

graphspace/__init__.py

@@ -0,0 +1,16 @@
+from ._version import __version__
+from .claims import Basis, Claim
+from .core import Analysis, Graph, Node, TensorSpec, ResourceContract, ExecutionRecord, MemoryPlan, MemoryValue
+from .uncertainty import Uncertain
+from .failures import (
+    GraphspaceError, ShapeMismatch, DTypeMismatch, ResourceLimitExceeded, UnknownValue, ContractViolation,
+    BackendUnavailable, LowConfidence,
+)
+
+__all__ = [
+    "__version__",
+    "Analysis", "Basis", "Claim",
+    "Graph", "Node", "TensorSpec", "ResourceContract", "ExecutionRecord", "MemoryPlan", "MemoryValue", "Uncertain",
+    "GraphspaceError", "ShapeMismatch", "DTypeMismatch", "ResourceLimitExceeded", "UnknownValue",
+    "ContractViolation", "BackendUnavailable", "LowConfidence",
+]

graphspace/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

graphspace/backends/__init__.py

@@ -0,0 +1,28 @@
+from collections.abc import Iterable
+import hashlib
+import json
+
+from ..failures import BackendUnavailable
+
+BACKENDS = ("python", "numpy")
+_INSTANCES: dict = {}
+
+
+def get_backend(name: str):
+    if name in _INSTANCES:
+        return _INSTANCES[name]
+    if name == "python":
+        from .python import PythonBackend
+        return _INSTANCES.setdefault(name, PythonBackend())
+    if name == "numpy":
+        from .numpy import NumpyBackend
+        return _INSTANCES.setdefault(name, NumpyBackend())
+    raise BackendUnavailable(f"unknown backend {name!r}", expected=list(BACKENDS), actual=name)
+
+
+def frame_digest(entries: Iterable[tuple[str, str, int, bytes]]) -> str:
+    digest = hashlib.sha256()
+    for name, dtype, length, payload in sorted(entries, key=lambda entry: entry[0]):
+        header = json.dumps([name, dtype, length]).encode()
+        digest.update(len(header).to_bytes(8, "little") + header + payload)
+    return digest.hexdigest()

graphspace/backends/numpy.py

@@ -0,0 +1,127 @@
+from collections.abc import Mapping
+from typing import Any
+
+from ..core import FLOAT_DTYPES, INT_RANGES, Dims, Node, TensorSpec, _product
+from ..failures import BackendUnavailable, ContractViolation, DTypeMismatch, ShapeMismatch
+from . import frame_digest
+from .python import PythonBackend
+
+
+class NumpyBackend:
+    name = "numpy"
+
+    def __init__(self) -> None:
+        try:
+            import numpy
+        except ImportError as error:
+            raise BackendUnavailable(
+                "backend 'numpy' requires NumPy",
+                actual="numpy not installed", remediation="pip install 'graphspace[numpy]'",
+            ) from error
+        self.np = numpy
+        self.version = numpy.__version__
+        self._python = PythonBackend()
+
+    def session(self):
+        return self.np.errstate(all="ignore")
+
+    def length(self, name: str, data: Any) -> int:
+        if isinstance(data, self.np.ndarray):
+            return int(data.size)
+        return self._python.length(name, data)
+
+    def coerce(self, name: str, data: Any, spec: TensorSpec, dims: Dims):
+        np = self.np
+        shape = spec.concrete_shape(dims)
+        if not isinstance(data, np.ndarray):
+            return np.array(self._python.coerce(name, data, spec, dims), dtype=spec.dtype).reshape(shape)
+        if isinstance(data, np.ma.MaskedArray):
+            raise DTypeMismatch(
+                f"input {name} is a masked array",
+                node=name, expected="ndarray", actual="MaskedArray", remediation="pass data.filled(value) or data.compressed()",
+            )
+        data = np.asarray(data)
+        if data.size != _product(shape):
+            raise ShapeMismatch(
+                f"input {name} has {data.size} elements, shape {spec.shape} needs {_product(shape)}",
+                node=name, expected=_product(shape), actual=int(data.size),
+            )
+        if data.ndim > 1 and data.shape != shape:
+            raise ShapeMismatch(f"input {name} has shape {data.shape}, expected {shape}", node=name, expected=shape, actual=data.shape)
+        allowed = "fiu" if spec.dtype in FLOAT_DTYPES else "iu"
+        if data.dtype.kind not in allowed:
+            raise DTypeMismatch(
+                f"input {name} has dtype {data.dtype}, not usable as {spec.dtype}",
+                node=name, expected=spec.dtype, actual=str(data.dtype),
+            )
+        if spec.dtype in INT_RANGES and data.size:
+            low, high = INT_RANGES[spec.dtype]
+            if int(data.min()) < low or int(data.max()) > high:
+                raise DTypeMismatch(
+                    f"input {name}: value outside {spec.dtype} range",
+                    node=name, expected=[low, high], actual=f"{int(((data < low) | (data > high)).sum())} values out of range",
+                )
+        array = data if data.dtype == spec.dtype else data.astype(spec.dtype)
+        return array.reshape(shape)
+
+    def run(self, node: Node, args: list, in_shapes: list[tuple[int, ...]], out_shape: tuple[int, ...], out: Any = None):
+        np = self.np
+        dtype = node.output_spec.dtype
+        if dtype in INT_RANGES and node.operation in {"add", "multiply", "subtract", "matmul"}:
+            wide = np.int64 if dtype == "int32" and node.operation != "matmul" else object
+            result = self._apply(node, [arg.astype(wide) for arg in args], out_shape, None)
+            low, high = INT_RANGES[dtype]
+            if result.size and (result.min() < low or result.max() > high):
+                raise DTypeMismatch(
+                    f"{node.output}: value outside {dtype} range",
+                    node=node.output, expected=[low, high], actual=f"{int(((result < low) | (result > high)).sum())} values out of range",
+                )
+            return result.astype(dtype)
+        return self._apply(node, args, out_shape, out)
+
+    def _apply(self, node: Node, args: list, out_shape: tuple[int, ...], out: Any):
+        np = self.np
+        if node.operation == "add":
+            return np.add(*args, out=out, order="C")
+        if node.operation == "multiply":
+            return np.multiply(*args, out=out, order="C")
+        if node.operation == "subtract":
+            return np.subtract(*args, out=out, order="C")
+        if node.operation == "divide":
+            return np.divide(*args, out=out, order="C")
+        if node.operation == "relu":
+            return np.maximum(args[0], args[0].dtype.type(0), out=out, order="C")
+        if node.operation == "scale":
+            return np.multiply(args[0], args[0].dtype.type(node.attribute("factor")), out=out, order="C")
+        if node.operation == "reshape":
+            return args[0].reshape(out_shape)
+        if node.operation == "transpose":
+            return args[0].transpose(node.attribute("axes"))
+        if node.operation == "matmul":
+            return np.matmul(*args, out=out)
+        if node.operation == "softmax":
+            values = args[0]
+            result = np.subtract(values, values.max(axis=-1, keepdims=True, initial=-np.inf), out=out, order="C")
+            np.exp(result, out=result)
+            return np.divide(result, result.sum(axis=-1, keepdims=True), out=result)
+        if node.operation == "layer_norm":
+            values, gamma, beta = args
+            width = values.shape[-1]
+            result = np.subtract(values, values.mean(axis=-1, keepdims=True), out=out, order="C")
+            rows = result.reshape(-1, width)
+            variance = np.einsum("ij,ij->i", rows, rows).reshape(result.shape[:-1] + (1,))
+            np.divide(variance, width, out=variance)
+            np.add(variance, node.attribute("eps"), out=variance)
+            np.sqrt(variance, out=variance)
+            np.divide(result, variance, out=result)
+            np.multiply(result, gamma, out=result)
+            return np.add(result, beta, out=result)
+        raise ContractViolation(f"{node.name}: unsupported operation {node.operation}", node=node.name, actual=node.operation)
+
+    def digest(self, values: Mapping[str, tuple[str, Any]]) -> str:
+        np = self.np
+        entries = []
+        for name, (dtype, data) in values.items():
+            wide = np.ascontiguousarray(data, dtype="<f8" if dtype in FLOAT_DTYPES else "<i8")
+            entries.append((name, dtype, int(wide.size), wide.tobytes()))
+        return frame_digest(entries)

graphspace/backends/python.py

@@ -0,0 +1,184 @@
+from collections.abc import Mapping, Sequence
+from contextlib import nullcontext
+from typing import Any
+import array
+import math
+import platform
+import sys
+
+from ..core import FLOAT_DTYPES, INT_RANGES, Dims, Node, TensorSpec, _product
+from ..failures import ContractViolation, DTypeMismatch, ShapeMismatch
+from . import frame_digest
+
+
+class PythonBackend:
+    name = "python"
+    version = platform.python_version()
+
+    def session(self):
+        return nullcontext()
+
+    def length(self, name: str, data: Any) -> int:
+        if isinstance(data, (str, bytes)) or not isinstance(data, Sequence):
+            raise DTypeMismatch(
+                f"input {name} must be a flat sequence of numbers, got {type(data).__name__}",
+                node=name, expected="sequence", actual=type(data).__name__,
+            )
+        return len(data)
+
+    def coerce(self, name: str, data: Any, spec: TensorSpec, dims: Dims) -> list:
+        expected = _product(spec.concrete_shape(dims))
+        if self.length(name, data) != expected:
+            raise ShapeMismatch(
+                f"input {name} has {len(data)} elements, shape {spec.shape} needs {expected}",
+                node=name, expected=expected, actual=len(data),
+            )
+        if spec.dtype in FLOAT_DTYPES:
+            if all(type(value) is float for value in data):
+                return data if isinstance(data, list) else list(data)
+            if any(isinstance(value, bool) or not isinstance(value, (int, float)) for value in data):
+                raise DTypeMismatch(
+                    f"input {name} must contain only numbers for {spec.dtype}",
+                    node=name, expected=spec.dtype, actual=_first_invalid(data, (int, float)),
+                )
+            return [float(value) for value in data]
+        if not all(type(value) is int for value in data) and any(
+            isinstance(value, bool) or not isinstance(value, int) for value in data
+        ):
+            raise DTypeMismatch(
+                f"input {name} must contain only ints for {spec.dtype}",
+                node=name, expected=spec.dtype, actual=_first_invalid(data, (int,)),
+            )
+        values = [int(value) for value in data]
+        check_range(name, values, spec.dtype)
+        return values
+
+    def run(
+        self, node: Node, args: list[list], in_shapes: list[tuple[int, ...]], out_shape: tuple[int, ...], out: Any = None,
+    ) -> list:
+        result = self._apply(node, args, in_shapes, out_shape)
+        check_range(node.output, result, node.output_spec.dtype)
+        return result
+
+    def _apply(self, node: Node, args: list[list], in_shapes: list[tuple[int, ...]], out_shape: tuple[int, ...]) -> list:
+        operation = node.operation
+        if operation in BINARY:
+            left, right = args
+            if in_shapes[0] != out_shape:
+                left = [left[index] for index in broadcast_indices(in_shapes[0], out_shape)]
+            if in_shapes[1] != out_shape:
+                right = [right[index] for index in broadcast_indices(in_shapes[1], out_shape)]
+            function = BINARY[operation]
+            return [function(a, b) for a, b in zip(left, right)]
+        if operation == "relu":
+            zero = 0.0 if node.output_spec.dtype in FLOAT_DTYPES else 0
+            return [zero if value < zero else value for value in args[0]]
+        if operation == "scale":
+            factor = node.attribute("factor")
+            return [value * factor for value in args[0]]
+        if operation == "reshape":
+            return args[0]
+        if operation == "transpose":
+            return [args[0][index] for index in transpose_indices(in_shapes[0], node.attribute("axes"))]
+        if operation == "matmul":
+            left, right = args
+            (rows, inner), (_, columns) = in_shapes
+            return [sum(left[row * inner + k] * right[k * columns + col] for k in range(inner)) for row in range(rows) for col in range(columns)]
+        if operation == "softmax":
+            return [value for row in _rows(args[0], out_shape) for value in _softmax(row)]
+        if operation == "layer_norm":
+            values, gamma, beta = args
+            eps = node.attribute("eps")
+            return [value for row in _rows(values, out_shape) for value in _layer_norm(row, gamma, beta, eps)]
+        raise ContractViolation(f"{node.name}: unsupported operation {operation}", node=node.name, actual=operation)
+
+    def digest(self, values: Mapping[str, tuple[str, list]]) -> str:
+        entries = []
+        for name, (dtype, data) in values.items():
+            packed = array.array("d" if dtype in FLOAT_DTYPES else "q", data)
+            if sys.byteorder == "big":
+                packed.byteswap()
+            entries.append((name, dtype, len(data), packed.tobytes()))
+        return frame_digest(entries)
+
+
+def _divide(a: float, b: float) -> float:
+    if b != 0:
+        return a / b
+    if a != a or a == 0:
+        return math.nan
+    return math.copysign(math.inf, a) * math.copysign(1.0, b)
+
+
+BINARY = {
+    "add": lambda a, b: a + b,
+    "subtract": lambda a, b: a - b,
+    "multiply": lambda a, b: a * b,
+    "divide": _divide,
+}
+
+
+def _strides(shape: tuple[int, ...]) -> list[int]:
+    strides = [1] * len(shape)
+    for axis in range(len(shape) - 2, -1, -1):
+        strides[axis] = strides[axis + 1] * shape[axis + 1]
+    return strides
+
+
+def _expand(sizes: tuple[int, ...], strides: list[int]) -> list[int]:
+    indices = [0]
+    for size, stride in zip(sizes, strides):
+        indices = [base + step * stride for base in indices for step in range(size)]
+    return indices
+
+
+def broadcast_indices(in_shape: tuple[int, ...], out_shape: tuple[int, ...]) -> list[int]:
+    padded = (1,) * (len(out_shape) - len(in_shape)) + tuple(in_shape)
+    strides = [0 if size == 1 else stride for size, stride in zip(padded, _strides(padded))]
+    return _expand(out_shape, strides)
+
+
+def transpose_indices(in_shape: tuple[int, ...], axes: tuple[int, ...]) -> list[int]:
+    strides = _strides(in_shape)
+    return _expand(tuple(in_shape[axis] for axis in axes), [strides[axis] for axis in axes])
+
+
+def _rows(values: list, shape: tuple[int, ...]):
+    width = shape[-1]
+    for start in range(0, len(values), width or 1):
+        yield values[start:start + width]
+
+
+def _softmax(row: list) -> list:
+    if any(value != value for value in row):
+        return [math.nan] * len(row)
+    peak = max(row, default=0.0)
+    exponents = [math.exp(value - peak) if value - peak == value - peak else math.nan for value in row]
+    total = sum(exponents)
+    return [_divide(value, total) for value in exponents]
+
+
+def _layer_norm(row: list, gamma: list, beta: list, eps: float) -> list:
+    width = len(row)
+    mean = sum(row) / width if width else math.nan
+    centered = [value - mean for value in row]
+    deviation = math.sqrt(sum(value * value for value in centered) / width + eps) if width else math.nan
+    return [value / deviation * g + b for value, g, b in zip(centered, gamma, beta)]
+
+
+def check_range(name: str, values: list, dtype: str) -> None:
+    if dtype not in INT_RANGES:
+        return
+    low, high = INT_RANGES[dtype]
+    if values and (min(values) < low or max(values) > high):
+        raise DTypeMismatch(
+            f"{name}: value outside {dtype} range",
+            node=name, expected=[low, high], actual=f"{sum(not low <= value <= high for value in values)} values out of range",
+        )
+
+
+def _first_invalid(data: Sequence, allowed: tuple[type, ...]) -> str:
+    for value in data:
+        if isinstance(value, bool) or not isinstance(value, allowed):
+            return type(value).__name__
+    return ""

graphspace/claims.py

@@ -0,0 +1,28 @@
+from collections.abc import Iterable
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any
+
+
+class Basis(str, Enum):
+    DECLARED = "declared"
+    PROVEN = "proven"
+    INFERRED = "inferred"
+    ESTIMATED = "estimated"
+    RUNTIME_CHECKED = "runtime_checked"
+    MEASURED = "measured"
+    BACKEND_REPORTED = "backend_reported"
+
+
+@dataclass(frozen=True)
+class Claim:
+    name: str
+    value: Any
+    basis: Basis
+
+
+def find_claim(claims: Iterable[Claim], name: str) -> Claim:
+    for claim in claims:
+        if claim.name == name:
+            return claim
+    raise KeyError(name)

graphspace/cli.py

@@ -0,0 +1,24 @@
+from .core import Graph, ResourceContract, TensorSpec
+
+
+def demo() -> int:
+    graph = Graph("demo_add", ResourceContract.max_memory(65536, deterministic=True))
+    spec = TensorSpec((2, 4), "float32")
+    graph.input("a", spec)
+    graph.input("b", spec)
+    output = graph.add("a", "b")
+    graph.output(output)
+    result, record = graph.execute({"a": [1.0] * 8, "b": [2.0] * 8})
+    print(f"graph={record.graph_name}")
+    print(f"result_elements={len(result)}")
+    print(f"peak_memory_bytes={record.peak_memory_bytes}")
+    print(f"deterministic={record.deterministic}")
+    return 0
+
+
+def main() -> int:
+    return demo()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())