SemanticTensor
Native Tensor values with explicit coordinate identity, physical units, exact arithmetic, reindexing and acknowledged numerical boundaries.
SemanticTensor is an opt in native facade over existing Tensor storage. It retains scientific axes, ordered coordinate identity and declared physical units. Import aner.tensor. Plain Tensor operations retain their existing lightweight contracts; scientific values use registered semantic operations or an explicitly acknowledged raw export.
Coordinate aware station anomalies demonstrates the practical difference. Current measurements in A/B order and a baseline in B/A order have equal shapes but cannot be subtracted positionally. Explicit reindexing produces the correct anomalies 1 and 8.
Construction and coordinate identity
tensor.semantic(values, axis, coordinates, unit) creates a single column observation tensor with one declared sample axis and a unique ordered String coordinate per row. Duplicate labels and extent mismatches fail. Declaring identical display text does not silently prove independently constructed scientific domains are the same.
Arithmetic requires exact axis, coordinate and unit compatibility. reindex_like(reference) explicitly reconciles a complete coordinate set with the reference order and domain. It rejects missing, extra or duplicate coordinates; there is no implicit intersection, interpolation or dropped station. Gather and unit conversion apply the same transformation to values and their retained descriptors.
Contextual model batches can carry ordered heterogeneous feature units. That schema is not equivalent to assigning the entire input matrix the unit of its first feature. A derived model internal representation needs the registered contract appropriate to that operation.
Units and absolute temperatures
The bounded native registry currently contains 1, m, km, s, h, m/s, km/h, N, N/m, kg, degC, K, delta_degC, delta_K, J, kWh, W, kW, and Pa. Supported conversions use declared dimension, scale and quantity kind. Numeric values do not establish their own unit, and a String label is not a measurement verification.
Absolute Celsius and Kelvin temperatures are affine points. Subtracting two compatible absolute temperatures yields a temperature difference, such as delta_degC. Adding two absolute temperatures through ordinary addition fails; an explicitly defined mean of temperature points is a different operation. Compatible differences can be added to absolute points. Incompatible dimensions fail before executing the arithmetic.
Unit conversion applies its scale and offset to the values. A coordinate temperature of 10 degC becomes 283.15 K. A temperature difference has no absolute temperature offset. Currency conversion, coordinate reference systems and arbitrary scientific equivalencies are outside this registry.
Numerical boundaries and placement
The scientific facade preserves context through its registered operations. Tracked scientific transformations retain at most 64 registered operation records, including records merged from both branches. Additional operations fail with a located E_RESOURCE_BUDGET diagnostic and leave earlier values intact. The records retain old/new units and derived meaning; they are not a general replayable provenance graph.
Scalar value(row, column) is a readout, useful for inspection. Reconstructing a new Tensor from readout scalars does not recover source identities, fit permissions or uncertainty.
Raw export requires an explicit reason and reports the discarded contracts. It is intended for an acknowledged interoperability boundary, not ordinary contextual model training. Unsupported transformations must fail rather than reuse coordinate labels after their meaning has changed.
Placement and precision follow explicitly supported native Tensor operations. Availability is probed at runtime; transfers and dtype changes are explicit and preserve the registered scientific context. Actual storage precision and device remain inspectable. Backend support is operation specific and must not be inferred merely from a physical GPU name. reindex_like and gather_rows currently require CPU storage and reject differentiable graphs until a backward permutation rule is implemented. Registered arithmetic and explicit compatible transfers have their separate supported rules.
Native API signatures
Qualified functions and the corresponding recognized receiver methods use the same native contracts. self denotes the receiver in the qualified signature. Lists of names or units contain Strings; index lists contain Int64 values. Wrong List element types fail instead of coercing values.
| Native signature | Result |
|---|---|
tensor.summary(self: SemanticTensor) | String |
tensor.explain(self: SemanticTensor) | String |
tensor.semantic(values: Tensor, axis: String, coordinates: List, unit: String) | SemanticTensor |
tensor.rows(self: SemanticTensor) | Int64 |
tensor.cols(self: SemanticTensor) | Int64 |
tensor.unit(self: SemanticTensor) | String |
tensor.dtype(self: SemanticTensor) | String |
tensor.device(self: SemanticTensor) | String |
tensor.coordinates(self: SemanticTensor) | List |
tensor.value(self: SemanticTensor, row: Int64, column: Int64) | Float64 |
tensor.gather_rows(self: SemanticTensor, indices: List) | SemanticTensor |
tensor.add(self: SemanticTensor, other: SemanticTensor) | SemanticTensor |
tensor.subtract(self: SemanticTensor, other: SemanticTensor) | SemanticTensor |
tensor.convert(self: SemanticTensor, unit: String) | SemanticTensor |
tensor.astype(self: SemanticTensor, dtype: String) | SemanticTensor |
tensor.to(self: SemanticTensor, device: String) | SemanticTensor |
tensor.reindex_like(self: SemanticTensor, reference: SemanticTensor) | SemanticTensor |
tensor.export_values(self: SemanticTensor, reason: String) | ContextExport |
ContextExport.values(self: ContextExport) | Tensor |
ContextExport.report(self: ContextExport) | String |
Time and space complexity
Let n be rows, p columns, r rank and b total coordinate bytes.
| Operation | Time | Additional space |
|---|---|---|
| Validate imported coordinates | O(n log n) String comparisons plus coordinate byte inspection | O(n + b) coordinate descriptors and validation index |
| Exact checked arithmetic | O(np + n + b) | O(np) numerical output plus retained descriptor references |
| Explicit exact reindexing | O(n log n) String comparisons plus O(np) value packing | O(n + np) permutation/index and copied values |
| Unit conversion | O(np) plus descriptor validation | O(np) converted output |
| Gather rows | O(np) for selected output | O(np + n) selected values and coordinate descriptors |
| Read one scalar | O(1), plus any device synchronization | O(1) readout |
Axes admit at most 65,536 coordinates, with at most 1,024 bytes per label and 8 MiB coordinate bytes. Public model input facades respect the same coordinate bound even when an underlying packed batch can hold more rows.
Reindexing is a real allocation when values change order. Newly imported descriptors require validation; sharing validated descriptors can avoid repeated coordinate construction. Transfers add O(np) destination storage and actual synchronization time, independently of semantic meaning. Reported transfer/cast destination buffer bytes include the actual retained numerical buffers: CPU Float32 includes its typed buffer and widened read cache. These counts exclude the source/parent value, temporary workspace, gradients, descriptor and allocator overhead and process RSS. They are not a peak live memory measurement.
Dependencies, backends and limitations
Use the compatible native development engine and VS Code helper 0.1.38 or newer. The station example is CPU Float64, deterministic, contains its complete dataset in source and requires no external files or service. Native CPU Float64 and local Metal/MPS Float32 semantic arithmetic were exercised in this implementation. Compatible CUDA Tensor placement is supported by the runtime, but contextual CUDA execution was not tested on a remote GPU in this release. Metal/MPS requires Float32; a requested unsupported precision does not silently change here.
Named axis broadcasting, general contractions, blind scientific reshape, interpolation, geographic regridding and arbitrary nonlinear unit aware differentiation remain future operations. Measurement uncertainty is opt in EvidenceTensor; ordinary semantic values do not invent uncertainty or probability.