prism_tensor/
lib.rs

1//! Prism standard-library tensor-compute sub-crate.
2//!
3//! `prism-tensor` realizes the tensor Layer-3 of the standard library
4//! named in [Wiki ADR-031][09-adr-031]: declares `TensorAxis` and
5//! `ActivationAxis` through the [`axis!`][09-adr-030] SDK macro and
6//! supplies parametric CPU integer-precision reference impls
7//! preserving bit-determinism per fixed `(HostTypes, HostBounds,
8//! AxisTuple)` selection (per ADR-030's per-axis
9//! substitution-determinism note).
10//!
11//! ## Scope
12//!
13//! - **`TensorAxis`** — fixed-shape matmul. Parametric reference:
14//!   [`CpuI8MatmulSquare<DIM>`] for `DIM × DIM` `i8` × `i8` → `i16`
15//!   matrices. `DIM` is unconstrained at the axis level; the
16//!   application's [`HostBounds::AXIS_OUTPUT_BYTES_MAX`][hb] per
17//!   [ADR-037][09-adr-037] enforces the per-application ceiling
18//!   structurally (`<Impl as TensorAxis>::MAX_OUTPUT_BYTES =
19//!   2 * DIM * DIM <= B::AXIS_OUTPUT_BYTES_MAX`).
20//! - **`ActivationAxis`** — element-wise nonlinearity. Parametric
21//!   reference: [`CpuI8VectorActivation<N>`] for length-`N` `i8`
22//!   vectors. `N` is unconstrained at the axis level; the
23//!   application's `HostBounds::AXIS_OUTPUT_BYTES_MAX` enforces the
24//!   ceiling structurally (`<Impl as ActivationAxis>::MAX_OUTPUT_BYTES
25//!   = N <= B::AXIS_OUTPUT_BYTES_MAX`).
26//! - **[`dtype`]** — GGML / GGUF / ONNX tensor element-type alphabet
27//!   per [ADR-057][09-adr-057]: 43 sealed [`dtype::Dtype`] impls
28//!   (continuous floats, ONNX FLOAT8 / complex / packed-4-bit,
29//!   signed / unsigned integers, boolean, GGML legacy block-32
30//!   quantization, GGML K-series block-256 quantization, GGML
31//!   IQ-series importance-aware quantization) exposed through the
32//!   [`dtype::TensorDtypeRegistry`] shape-IRI registry as
33//!   `Term::Recurse` targets for container-format realizations.
34//!   Compression-operator codomain context: per [ADR-058][09-adr-058]
35//!   the κ-derivation is the framework's compression operator; tensor
36//!   element types occupy the R-level of the operator-geometry
37//!   codomain per [ADR-059][09-adr-059].
38//! - **[`shape`]** — higher-rank tensor shape carriers:
39//!   [`shape::Tensor3Shape`] (rank-3) and [`shape::Tensor4Shape`]
40//!   (rank-4). Common GGUF / ONNX rank coverage; higher ranks compose
41//!   through `partition_product!` per ADR-033/044.
42//!
43//! [hb]: uor_foundation::HostBounds::AXIS_OUTPUT_BYTES_MAX
44//!
45//! ## ConstrainedTypeShape declarations
46//!
47//! Per ADR-031's `Tensor<Element, Shape>` shape commitment:
48//!
49//! - **[`MatrixShape<ROWS, COLS, ELEM_BYTES>`]** — rank-2 tensor shape.
50//! - **[`VectorShape<N, ELEM_BYTES>`]** — rank-1 tensor shape.
51//! - **[`Tensor3Shape<D0, D1, D2, ELEM_BYTES>`][shape::Tensor3Shape]** — rank-3 tensor shape.
52//! - **[`Tensor4Shape<D0, D1, D2, D3, ELEM_BYTES>`][shape::Tensor4Shape]** — rank-4 tensor shape.
53//! - **[`dtype`]** — 43 fixed-byte-count element-type shapes
54//!   (continuous floats, ONNX FLOAT8 / complex / packed-4-bit,
55//!   signed / unsigned integers, boolean, GGML legacy / K-series /
56//!   IQ-series quantization).
57//!
58//! Higher-rank tensors compose through `partition_product!` per
59//! ADR-033/044; the axis layer fixes the atom shape.
60//!
61//! ## Closure under uor-foundation (ADR-013)
62//!
63//! Every axis trait declared here has
64//! `::uor_foundation::pipeline::AxisExtension` as a supertrait;
65//! parametric impls hand-write their `AxisExtension` impl since the
66//! `axis!`-emitted companion macro takes `:ident`.
67//!
68//! ## See also
69//!
70//! - [Wiki: 09 Architecture Decisions § ADR-030 — `axis!` SDK macro][09-adr-030]
71//! - [Wiki: 09 Architecture Decisions § ADR-031 — `prism` is the standard library][09-adr-031]
72//! - [Wiki: 09 Architecture Decisions § ADR-037 — `HostBounds` ceilings on the principal data path][09-adr-037]
73//! - [Wiki: 09 Architecture Decisions § ADR-057 — Bounded recursive structural typing][09-adr-057]
74//! - [Wiki: 09 Architecture Decisions § ADR-058 — κ-derivation as the framework's compression operator][09-adr-058]
75//! - [Wiki: 09 Architecture Decisions § ADR-059 — Atlas image inside E₈ as the codomain of κ-derivation][09-adr-059]
76//!
77//! [09-adr-030]: https://github.com/UOR-Foundation/UOR-Framework/wiki/09-Architecture-Decisions
78//! [09-adr-031]: https://github.com/UOR-Foundation/UOR-Framework/wiki/09-Architecture-Decisions
79//! [09-adr-037]: https://github.com/UOR-Foundation/UOR-Framework/wiki/09-Architecture-Decisions
80//! [09-adr-057]: https://github.com/UOR-Foundation/UOR-Framework/wiki/09-Architecture-Decisions
81//! [09-adr-058]: https://github.com/UOR-Foundation/UOR-Framework/wiki/09-Architecture-Decisions
82//! [09-adr-059]: https://github.com/UOR-Foundation/UOR-Framework/wiki/09-Architecture-Decisions
83
84#![no_std]
85#![cfg_attr(docsrs, feature(doc_cfg))]
86
87pub mod activation;
88pub mod dtype;
89pub mod shape;
90pub mod tensor;
91pub mod verbs;
92
93pub use activation::{ActivationAxis, CpuI8VectorActivation};
94pub use shape::{Tensor3Shape, Tensor4Shape};
95pub use tensor::{CpuI8MatmulSquare, MatrixShape, TensorAxis, VectorShape};
96
97/// Wiki ADR-031 standard-library version banner.
98pub const STANDARD_LIBRARY_VERSION: &str = env!("CARGO_PKG_VERSION");
prism_tensor/lib.rs

prism_tensor/
lib.rs
