MathBlocks is an immutable mathematical-operation contract for deterministic CPU and CUDA execution. It provides versioned operations, typed values, and composable computation programs.
Each operation has an identifier and a positive version. Its version binds operand rules, output rules, units, shapes, capacity, scratch, validity, and execution behavior.
The standard catalog contains 337 operations. Each operation has CPU regression evidence, CUDA regression evidence, and a contract-shape performance target.
A caller can combine compatible operations in any directed acyclic graph. Unknown versions and incompatible types fail before execution.
CPU and CUDA code stays in the single Supprocom.MathBlocks production
assembly. Supprocom.MathBlocks.Cuda is only a namespace in that assembly.
MathBlocks does not propose formulas. It does not own mutation, crossover, selection, archives, cursors, or checkpoints.
MathBlockProgramBuilder creates a typed program without reflection or internal
type names. MathBlocksCPUWorker executes independent nodes in parallel by
graph level.
This program calculates the area of a rectangle.
usingSupprocom.MathBlocks;varbuilder=newMathBlockProgramBuilder(MathBlockCatalog.Standard);varwidth=builder.Input("width",MathBlockType.Scalar());varheight=builder.Input("height",MathBlockType.Scalar());vararea=builder.Apply("scalar.multiply",inputs:[width,height]);varprogram=builder.Output("area",area).Build();varoutput=program.Evaluate(newDictionary<string,MathBlockValue>{["width"]=MathBlockValue.Scalar(6d),["height"]=MathBlockValue.Scalar(4d)});Console.WriteLine(output["area"].AsScalar());MathBlockOpenMath exports a typed program with the MathBlocks OpenMath Profile
- The profile uses OpenMath 2.0 Revision 2 XML.
The UTF-8 encoding of each exported string conforms to Canonical XML 1.1 without comments. The exported node sequence gives one exact operation order.
The importer rebuilds the typed program and returns its operations in that same order. It rejects unknown symbols, forward references, and invalid types.
varnotation=MathBlockOpenMath.Export(program);varimported=MathBlockOpenMath.Import(notation);foreach(varoperationinimported.Operations)Console.WriteLine(operation.Identity);varsameNotation=MathBlockOpenMath.Export(imported.Program);Direct UTF-8 APIs avoid an intermediate string. Stream APIs leave each caller-owned endpoint open. The async forms use async I/O and accept cancellation.
varutf8=MathBlockOpenMath.ExportUtf8(program);varfromBytes=MathBlockOpenMath.ImportUtf8(utf8);awaitusingvaroutput=File.Create("program.openmath.xml");awaitMathBlockOpenMath.WriteUtf8Async(program,output);awaitusingvarinput=File.OpenRead("program.openmath.xml");varfromStream=awaitMathBlockOpenMath.ReadUtf8Async(input);The byte APIs accept UTF-8 only. Import accepts an optional UTF-8 byte-order mark, but canonical output never writes one.
Nonthrowing import returns one result or one structured diagnostic. Validation also reports whether valid input already has the canonical form.
varuntrustedNotation=notation;varattempt=MathBlockOpenMath.TryImport(untrustedNotation);if(!attempt.Succeeded){Console.WriteLine(attempt.Diagnostic!.Code);Console.WriteLine(attempt.Diagnostic.Message);}varvalidation=MathBlockOpenMath.Validate(untrustedNotation);if(validation.IsValid&&validation.Canonicality==MathBlockOpenMathCanonicality.Noncanonical){varcanonicalNotation=MathBlockOpenMath.Normalize(untrustedNotation);}Import options can apply smaller resource limits. They can also require the canonical form or capture source locations.
varoptions=newMathBlockOpenMathImportOptions{MaximumNodes=10_000,MaximumOutputs=100,MaximumValueElements=1_000_000,CaptureSourceLocations=true};vardetailed=MathBlockOpenMath.Import(notation,options);foreach(varoccurrenceindetailed.OperationOccurrences){Console.WriteLine($"{occurrence.NodeIndex}: {occurrence.Operation.Identity}");}MathBlockOpenMath.Profile exposes the 337 exact operation symbols and the
seven embedded Profile 1 artifacts. Artifact streams are read-only and do not
use the package installation path.
The profile preserves shared nodes, constants, units, shapes, and named outputs. It uses exact hexadecimal binary64 values.
Profile 1 contains all 337 operations from MathBlockCatalog.Standard.
Export rejects custom operation implementations. These operations require a
separate content dictionary identity.
The package contains the four content dictionaries, their content dictionary group, and the restricted profile schema. The profile source is in the repository OpenMath directory.
Import rejects a document that exceeds
MathBlockOpenMath.MaximumDocumentCharacters. Import does not retrieve a
schema or content dictionary from the network.
The OpenMath API guide defines every data path, option, diagnostic, ownership rule, and security boundary.
This API reads semantic OpenMath XML. It does not read presentation text such
as sin(x) + x^2.
MathBlockCudaDeviceModule exposes the supported device source, complete
dispatch table, source fingerprint, and ABI fingerprint.
MathBlockCudaDeviceModule.Operations contains one public contract for each
standard operation. Each contract exposes its family, opcode, arity, rules,
execution behavior, and immutable fingerprint.
ResolveOutputType applies the CPU type contract. PlanCUDA applies the same
checked shape, capacity, and scratch authority as CUDA execution.
MathBlockCudaSlotDescriptor defines the 48-byte host and device slot.
MathBlockCudaValueCodec writes and reads every supported value kind without
internal types.
A consumer appends its CUDA kernel with ComposeSource. It can also compile the
complete source with CompilePtx.
The device function has this supported signature.
__device__ void mathblocks_operation_dispatch(
int family,
int opcode,
const MathBlockSlot* const* inputs,
int input_count,
MathBlockSlot* output)
All threads in one 128-thread block must call the dispatcher uniformly. The dispatcher completes one operation before the consumer calls the next operation.
This CUDA fragment composes addition and multiplication inside a consumer-owned kernel.
extern"C"__global__voidrectangle_area(MathBlockSlot* slots)
{
if (blockIdx.x != 0)
return;
const MathBlockSlot* sum_inputs[2] = { &slots[0], &slots[1] };
mathblocks_operation_dispatch(ADD_FAMILY, ADD_OPCODE, sum_inputs, 2, &slots[2]);
const MathBlockSlot* area_inputs[2] = { &slots[2], &slots[3] };
mathblocks_operation_dispatch(
MULTIPLY_FAMILY,
MULTIPLY_OPCODE,
area_inputs,
2,
&slots[4]);
}The host generates the four constants from
MathBlockCudaDeviceModule.GetOperation. Do not hardcode family or opcode
values in production code.
The external package gate compiles a consumer-owned CUDA kernel. It executes all 337 operation identities and one nested DAG in one launch.
The gate performs one immutable arena upload, one launch, one synchronization, and one download. MathBlocks does not control that transaction.
MathBlocksCUDAWorker compiles a typed program into one resident CUDA graph. It
remains a stateless operation utility.
The first input update performs one upload. A resident execution performs one graph launch, one synchronization, and one output download.
Callers can queue resident executions before synchronization. The compiled program serializes state changes for safe concurrent calls.
The exact parity policy requires CUDA results to match CPU results. Parity includes data bits, shape, type, unit, and invalid state.
Each operation fingerprint binds its identity, version, family, opcode, arity, rule identities, execution behavior, and device-source fingerprint.
It also binds every regression case and every performance-case input. The performance iteration count and maximum warm latency are part of the same identity.
The source fingerprint binds the exact CUDA definitions and dispatch implementation. The ABI fingerprint binds the exact dispatcher signature, slot layout, graph-edge layout, run layout, versioned value-codec schema, codec implementation, source, and complete operation table.
A consumer must reject a stored ABI fingerprint that differs from the loaded package. A package version change does not replace this check.
Each operation has a sub-millisecond target on its contract shape. The CPU gate measures warm p95 latency. The CUDA gate measures warm median latency.
These targets are test contracts. Results depend on hardware, input shape, operating-system scheduling, percentile, and measurement method.
Rolling median and rolling quantile use exact order statistics without a semantic window limit. General probabilities use linear radix preparation and indexed sliding heaps.
The general work bound is O(N log W). Quantile probabilities zero and one use
a linear monotonic deque and do not sort.
A width of one uses a parallel copy. Checked scratch arithmetic rejects an unrepresentable resource requirement before launch.
This Git repository contains source text and project metadata only. It does not contain or redistribute NVIDIA, CUDA, TorchSharp, or LibTorch binaries.
Get MathBlocks version 0.4.1 from NuGet.org with this command after
publication.
dotnet add package Supprocom.MathBlocks --version 0.4.1
The package declares three external native-acquisition dependencies. This dependency graph is the same on all pack hosts.
Install the .NET 10 SDK before project restore. Install a compatible NVIDIA driver before CUDA execution.
Windows CUDA execution requires x64 Windows. It requires
libtorch-cuda-12.8-win-x64-part1 and libtorch-cuda-12.8-win-x64-part8
version 2.10.0.
Linux CUDA execution requires x64 Linux and TorchSharp-cuda-linux version
0.107.0. That package supplies its declared Linux dependencies.
NuGet downloads all declared packages during restore. It stores them outside this Git repository in the user package cache.
Use this command to restore the source tests.
dotnet restore Supprocom.MathBlocks.Tests/Supprocom.MathBlocks.Tests.csproj
The build can copy runtime assets into ignored output directories. Do not commit or redistribute those output directories.
Review each third-party license before package use. See THIRD-PARTY-NOTICES.md for the recorded identities.
MathBlocks targets .NET 10. CUDA tests require a compatible NVIDIA driver and CUDA toolkit.
dotnet build Supprocom.MathBlocks.Tests/Supprocom.MathBlocks.Tests.csproj --configuration Release
dotnet test Supprocom.MathBlocks.Tests/Supprocom.MathBlocks.Tests.csproj --configuration Release
The external consumer project restores only the packed public package. It has no project reference to the production project.
MathBlocks uses the GNU Affero General Public License version 3 only. The SPDX
expression is AGPL-3.0-only.
The AGPL does not change third-party licenses for CUDA, TorchSharp, LibTorch, or test packages. See THIRD-PARTY-NOTICES.md.