Coding standards

A standard is part of the API

A large library is read more often than it is written. OA therefore treats naming, ownership, failure behavior, and formatting as interface contracts rather than personal style. The rules below are OA's own and follow the public architecture, generated API, and current source contracts.

Matrix, not Tensor

OA uses Matrix as the general multidimensional numerical value for dense compute and ML. It carries shape, strides, dtype, device, storage offset, and optional autograd state. A second Tensor name would duplicate that contract without adding useful behavior.

That convention is deliberately narrower than “everything is a matrix.” An Image retains pixel layout and format; Audio retains sample rate and channel meaning; a VideoFrame retains planes and timing. Each may expose a zero-copy matrix view when representation and lifetime permit it, but numerical storage never erases domain semantics.

C++ and Python spell one contract

The two front ends preserve public names and operation families. C++ uses ::and explicit status/event handling; Python uses ., raises binding errors, and borrows a lazily managed native engine. Parity means the same values, semantics, and Vulkan implementation—not identical lifetime syntax or overloads.

1#include <oa/oa.h>
2
3oa::Result<oa::Event> runExample(
4	oa::Engine& inEngine,
5	const oa::Matrix& inMatrix,
6	const oa::Matrix& inWeights
7) {
8	[[maybe_unused]] oa::Matrix outputMatrix =
9		oa::FnMatrix::matMulNt(inMatrix, inWeights);
10
11	return inEngine.submit();
12}
13

FnMatrix is the operation namespace in both languages, and its results remain device-resident. C++ exposes explicit engine submission; Python borrows a lazily managed native engine and does not currently publish an Engine class or public submit method.

Naming

Directory segments and importable modules remain lowercase. Maintained C++ and Python source filenames are camelCase. Names should be grep-friendly; single letters belong only to tight loops and conventional local mathematics. The deliberate Fn* exception keeps primary operation namespaces PascalCase for syntax similarity with their semantic value classes in both languages.

oa::Syntax

This illustrative wrapper exists to show naming in context; it is not an additional OA API.

1#include <oa/oa.h>
2
3// namespace / module: lowercase
4namespace oa::example {
5
6// types / classes: PascalCase
7class MatrixJob {
8public:
9	// methods / functions and parameters: camelCase
10	oa::Matrix execute(
11		const oa::Matrix& inMatrix,
12		const oa::Matrix& inWeights
13	) {
14		// local variables: camelCase
15		oa::Matrix outputMatrix = oa::FnMatrix::matMulNt(
16			inMatrix, inWeights
17		);
18		return outputMatrix;
19	}
20
21	oa::Result<oa::Event> submit(oa::Engine& inEngine) {
22		auto submittedEvent = inEngine.submit();
23		return submittedEvent;
24	}
25};
26
27} // namespace oa::example
28

Foundation, not oa::std

OA owns the bounded C++ foundation vocabulary needed by its shipped library. Containers, strings, ownership, synchronization, memory, paths, formatting, and algorithms live directly under oa. There is no oa::std, oastd, or OaStd*compatibility layer, and the target is not a complete STL clone. oa::Vector is the canonical owning sequence; the former pre-1.0 oa::Vec spelling has been removed.

1#include <oa/core/types.h>
2
3oa::Vector<oa::F32> samples;
4oa::String label;
5oa::Optional<oa::Path> outputPath;
6
7samples.pushBack(0.5F);
8auto owner = oa::makeUnique<oa::String>();
9auto movedOwner = oa::move(owner);
10

This is an original OA implementation written from scratch for the product's admitted workloads—not an STL source port or renamed wrapper surface. A small auditable vocabulary gives OA explicit failure behavior, allocation control, reproducibility, and a portable adapter boundary. The current fixed-host benchmark keeps both wins and retained overhead visible; each ratio is OA time divided by the equivalent host operation.

These representative rows come from the 32-case foundation campaign and the host-memory campaign that now lives under oa/core/std/memory.h. They are seven-process medians from one CPU, compiler, host library, workload, and date—not a universal performance or security claim. The Foundation benchmark page owns the protocol, complete result set, spread, correctness gate, rejected alternatives, and reproduction steps.

Print and format with braces

Use oa::format when you need an owning oa::String, oa::print for one complete newline-terminated record, and oa::write when no newline should be added. The syntax uses sequential {} and {:spec} fields in the style familiar from Python and {fmt}, while remaining a bounded OA dialect rather than a full {fmt} compatibility layer or runtime dependency.

1#include <oa/core/std/print.h>
2
3const oa::String summary = oa::format(
4	"epoch={} loss={:.4f}", epoch, loss
5);
6
7OA_RETURN_IF_ERROR(oa::print("{}", summary));
8OA_RETURN_IF_ERROR(oa::print(
9	oa::PrintStream::Error,
10	"failed: {}", reason
11));
12
13// Same-line progress: write adds no newline and flush is explicit.
14OA_RETURN_IF_ERROR(oa::write("\rprogress={:5.1f}%", percent));
15OA_RETURN_IF_ERROR(oa::flush());
16

Format strings are compile-time character-array literals. Pass untrusted runtime text as an oa::StringViewso it is treated as data rather than reparsed as a format program. Malformed fields, argument mismatches, invalid type/specifier pairs, null C strings, and excessive width, precision, or output fail through OA's always-on contract. Host output failures remain recoverable through the returned oa::Status.

Vulkan Linear Math

VLM is OA's compact host-side spatial-math library, not a vision-language model and not a second tensor engine. It provides packed vectors, quaternions, matrices, transforms, and projections for cameras, UI, rendering, animation, simulation, and format conversion.

The 2026-08-30 fixed-host qualification covers 50 operation families in both F32 and F64. All 100 whole-workload checksum oracles passed. Across the 27 families with equivalent valid-input arithmetic, OA reached parity or better in both precisions and used 13.4% less time by geometric mean for F32 and 11.9% less for F64 against GLM 1.1.0. The table shows representative arithmetic results; checked and fail-closed operations remain separate because their GLM peers omit OA's validation. See the complete VLM benchmark for all 50 rows, provenance, spread, safety costs, and reproduction.

1#include <oa/core/vlm.h>
2
3const oa::vlm::Vec3 eye{0.0F, 2.0F, 5.0F};
4const oa::vlm::Vec3 target{0.0F, 0.0F, 0.0F};
5const oa::vlm::Mat4 view = oa::vlm::lookAt(
6	eye,
7	target,
8	{0.0F, 1.0F, 0.0F}
9);
10const oa::vlm::Mat4 projection = oa::vlm::perspective(
11	60.0F,
12	16.0F / 9.0F,
13	0.1F,
14	1000.0F
15);
16
17const oa::vlm::Vec3 worldPoint{1.0F, 1.0F, 0.0F};
18oa::vlm::Vec3 ndc;
19const bool visible = oa::vlm::tryProjectPoint(
20	worldPoint,
21	view * projection,
22	ndc
23);
24

Common GLM Vulkan integrations enable [0, 1] clip depth through a compile-time definition and apply a Y sign correction to the projection matrix. Those are valid adapter choices. VLM instead fixes one OA-wide convention: projection depth is Vulkan-native, raster Y belongs to viewport state, and callers do not scatter transposes, * -1 repairs, or compensating -90° rotations through camera, render, and application code. External axes, units, handedness, and quaternion order convert once at the format boundary. The public VLM value surface is currently C++ only; Python parity remains unshipped.

Core libraries and third-party code

Tests, generators, bindings, and SDK programs may use the host standard library inside their declared boundary. Shipped product code uses the OA foundation vocabulary; native OS, compiler, Vulkan, C-runtime, and third-party APIs terminate in focused adapters. Linked-binary independence and the remaining installed-header adapter closure retain separate qualification gates.