Use this appendix when you need to answer platform questions: what Linux configurations are qualified, how installed-package validation is established, and what is supported on ARM64.

This is not part of the shortest bring-up path. Read it when the real question becomes support boundary, qualification boundary, deployment risk, or target platform scope.

Read it in two passes: support boundary first, then the smallest validation or acceptance lane that matches the claim you need to make.

For integration work, this appendix usually answers one of these questions:

is this host/platform combination inside the current support boundary
what installed-package shape has already been validated
what additional qualification is still the customer's responsibility, especially for RT/HIL

Read the status words in this appendix literally:

supported means part of the current RC delivery and support boundary
qualified means TDSE release validation has exercised that slice, often as an optional feature or lane
roadmap means planned or actively explored, but not part of the current RC commitment
customer qualification means the evaluation package may be usable there, but the final proof still belongs to the host program, target machine, or deployment process

Use the next two boundary chapters together with this one:

use Plugin System when deployment risk becomes ABI, manifest, routing, or plugin-health evidence
use Element Reference when deployment risk becomes source-deck coverage, unsupported directives, or netlist subset drift

Linux Support Scope

What Is Covered

Current Linux qualification covers the full SDK:

Runtime library, pack consumption, model create, lifecycle, step execution, and diagnostics
Builder transforms and pack write (libtdse_builder)
Circuit SDK, the circuit-domain circuit module (CPU dense + sparse KLU via SuiteSparse)
CLI (tdse binary) and Profiler
BLAS acceleration via OpenBLAS and LAPACK
Telemetry with optional OpenSSL HTTPS export
pkg-config and CMake package metadata
Linux tarball, DEB, and RPM package forms for the qualified host profile

Optional accelerator stacks that require separate qualification:

CUDA Circuit and CUDA Runtime backend (qualified on CUDA 12/13)
Intel oneMKL BLAS backend and MKL Pardiso sparse solver

Platform Support Matrix

Platform slice	Status	Notes
Windows	supported	primary supported SDK platform and release flow
Linux / WSL baseline	supported	full SDK parity: Runtime, Builder, Circuit SDK, CLI, Profiler
Linux AArch64 / ARM64	supported	CPU-only full SDK on Ubuntu 24.04 AArch64; AWS Graviton C8g is the current release evidence host
Linux optional accelerators	qualified	BLAS (OpenBLAS), LAPACK, KLU are validated; CUDA qualified on 12/13; MKL qualified separately
macOS ARM64 / Apple Silicon	roadmap	zero-cost repo wiring exists for an AWS EC2 Mac self-hosted runner, but native release support requires a future paid Apple Silicon run

Supported Host Configuration

Current standard Linux support target is:

Dimension	Supported Baseline
CPU / OS class	`x86_64` GNU/Linux and `aarch64` GNU/Linux
libc	glibc-based userland
tested on	`ubuntu-24.04`
qualification baseline	installed SDK package consumed on the qualified host profile
build configuration	release-candidate package contents
dependencies	default dependencies only; optional BLAS/LAPACK/KLU/CUDA stacks not required
toolchain family	GCC-based baseline; broader compiler confidence may come from additional qualification
package form	Full SDK tarball, Runtime SDK tarball, DEB/RPM system packages, and installed `pkg-config`/CMake exports produced by the SDK release process

The vendored Linux OpenBLAS lane uses OpenBLAS 0.3.33 with LP64 LAPACK/LAPACKE integrated into libopenblas.so. The current binary is built on Ubuntu 24.04 and requires glibc >= 2.38 plus the system libgfortran.so.5 runtime package (libgfortran5 on Ubuntu/Debian).

The following are not covered by the standard support scope:

musl-based distributions
Apple Silicon macOS native runtime inside the Linux support claim; macOS ARM64 has a separate roadmap lane below
non-Ubuntu ARM distributions unless separately qualified
static-link redistribution
Intel oneMKL BLAS backend (requires separate MKL installation and qualification)

Configurations outside this table may still work but are not covered by the standard support scope unless documented in a release note.

Validation Coverage

Each TDSE Linux RC is validated on the supported host profile through installed-package consumption, release-build checks, threading stress tests, long-duration soak tests, and install/package smoke checks. Additional release-engineering lanes may use broader internal coverage, but the customer-visible claim is anchored to the delivered package on the qualified host profile.

Supported Usage

A supported Linux deployment means the application consumes the shipped SDK package or bundle through pkg-config or CMake exports, validates packs before model create, uses the standard create-diagnostics flow, runs CLI and Profiler commands cleanly on the qualified host profile, and passes the included tests for the current release.

Runtime Requirements

The Linux runtime expects one handle per execution thread, no same-handle concurrent step entry, and validated pack bytes as input. Circuit SDK (circuit-domain circuit), Builder, and CLI are fully supported on Linux. CUDA GPU acceleration requires a compatible NVIDIA driver and CUDA toolkit.

Reporting Issues

When reporting a Linux Runtime SDK issue, please collect:

package version
package format used
tdse_pack_validate output
tdse_model_create_diagnostics_t
tdse_model_info(...)
tdse_model_state_info(...)
tdse_model_last_error_info(...)
compiler, distro, and glibc baseline

Issue Categories

The following are treated as product defects: a qualified configuration regresses on unchanged inputs, install or export smoke fails on the supported host profile, or tdse_model_create(...) fails with a previously qualified pack.

The following are outside the standard support scope and may require a separate qualification agreement: unsupported distros or host classes (musl, non-Ubuntu ARM), optional dependency stacks outside the current scope, or same-handle concurrent stepping.

macOS ARM64 Roadmap Boundary

macOS ARM64 is prepared as a separate native-package qualification lane, not as part of the current Linux AArch64 support claim.

Current no-cost repository readiness includes:

a disabled-by-default self-hosted workflow for self-hosted, macOS, ARM64, tdse-macos-arm64
native Apple Silicon host assertions before any build runs
CPU-only SDK and Runtime SDK zip bundle generation through the standard bundle machinery
SBOM, provenance, metadata, installed-files manifest, and signing-receipt checks
a macOS ARM64 artifact gate that inspects generated Mach-O files with file and fails if they are not arm64

This lane is intentionally disabled unless the repository variable TDSE_ENABLE_SELF_HOSTED_MACOS_ARM64=1 is set. Keeping the variable unset means the workflow does not request a runner and does not create AWS EC2 Mac cost.

Native macOS ARM64 release support still requires a future paid Apple Silicon execution on an EC2 Mac Dedicated Host or equivalent local Apple Silicon runner. Until that run passes, macOS ARM64 packages are not part of the supported release boundary.

Linux/WSL Validation Guide

This section summarizes the Linux validation lanes used to establish RC confidence. It is release-validation context, not the primary path for a closed-source SDK evaluation package.

Supported Workflow

For normal customer evaluation, stay on the installed-package path from Installation and Getting Started.
RC qualification evidence is organized into default, extended, and release validation lanes.
Escalate from default to extended when the question becomes install-tree or package consumption.
Escalate to release when the question becomes release-candidate confidence or support evidence.

CTest Tiers

The Linux release process treats validation as lanes with different purposes. Use the smallest lane that answers your current question.

Tier	When to use it	What it emphasizes
`default`	day-to-day development	core unit/integration correctness without install/package burden
`extended`	install-tree or package validation	install smoke, Runtime SDK/full-SDK package consumption, Linux package artifact checks
`release`	release-candidate confidence	randomized CLI smoke, clean-host consumption, ABI/provenance/release evidence gates
`all`	pre-merge or final qualification on a prepared machine	runs the three lanes in sequence

Use default unless you are explicitly validating an install tree, a package artifact, or a release candidate.

Prerequisites

These lanes depend on the TDSE release-validation environment. Closed-source RC consumers do not need to reproduce them just to evaluate the installed SDK package.

Install And Package Layout

Linux installs are intentionally prefix-relative.

In a standard Linux install under /opt/tdse-sdk, the important paths are:

/opt/tdse-sdk/bin/tdse
/opt/tdse-sdk/lib/libtdse.so
/opt/tdse-sdk/lib/libtdse_builder.a
/opt/tdse-sdk/lib/libtdse_circuit.a
/opt/tdse-sdk/lib/plugins/sim/libtdse_sim_cpu_dense.so
/opt/tdse-sdk/lib/plugins/sim/libtdse_sim_cpu_sparse.so
/opt/tdse-sdk/lib/plugins/sim/libtdse_sim_cuda.so
/opt/tdse-sdk/lib/plugins/sim/plugin_manifest.json
/opt/tdse-sdk/lib/pkgconfig/tdse.pc
/opt/tdse-sdk/lib/pkgconfig/tdse-runtime-sdk.pc
/opt/tdse-sdk/lib/cmake/tdse/
/opt/tdse-sdk/lib/cmake/tdseRuntimeSDK/
/opt/tdse-sdk/share/tdse/tdse_sdk_variant.json
/opt/tdse-sdk/share/tdse/tdse_runtime_sdk_variant.json

Use the installed CMake package:

cmake -S <consumer-source> \
  -B build/package-consumer-cpu \
  -DCMAKE_PREFIX_PATH=/opt/tdse-sdk \
  -DTDSE_CIRCUIT_TARGETS=AUTO
cmake --build build/package-consumer-cpu
LD_LIBRARY_PATH=/opt/tdse-sdk/lib:${LD_LIBRARY_PATH} \
  build/package-consumer-cpu/<consumer-binary>

Use the installed pkg-config package:

export PKG_CONFIG_PATH=/opt/tdse-sdk/lib/pkgconfig:${PKG_CONFIG_PATH}
c++ -std=c++20 app.cpp -o app $(pkg-config --cflags --libs tdse)

Optional feature slices:

sparse CPU: append $(pkg-config --variable=sparse_libs tdse)
CUDA: append $(pkg-config --variable=cuda_libs tdse)

Linux Package Targets

The SDK release process produces tarball, DEB, and RPM packages for Linux deployment.

For customers, the important point is not the internal artifact staging path but the validation outcome: tarballs are checked for relocation, installed pkg-config/CMake metadata is checked for downstream discovery, and .deb/.rpm payloads are checked for completeness.

Acceptance Shapes

The release process validates more than one package-consumption shape. From a customer-handbook perspective, the important ones are:

Shape	What it proves
Runtime SDK install	a runtime-only consumer can link and run against `tdse::tdse`
Full SDK install	Runtime, Builder, Circuit, CLI, and package metadata work together from the installed tree
Clean-host CPU-only consumer	a downstream machine without optional accelerators can still consume the supported CPU slice
Clean-host full-feature consumer	installed-package discovery and optional feature wiring behave as shipped

Use the smallest acceptance shape that matches the support claim you need to make. Do not infer clean-host or full-feature release confidence from a same-host default build alone.

This is why the handbook points you to installed-package examples instead of relying on same-host validation alone: the install tree itself is part of the supported surface.

Notes

The default configuration is the supported day-to-day Linux baseline.
RC consumers should treat the installed package as the supported surface. Engineering-only validation lanes may explain how confidence was established, but they are not required reading for first evaluation.

Troubleshooting

Missing compiler or linker tools: Install build-essential.
pkg-config consumer cannot find TDSE: Add <prefix>/lib/pkgconfig to PKG_CONFIG_PATH before building the downstream app.
CMake configure succeeds but runtime install smoke cannot find shared libraries: Re-run the release team's extended Linux validation lane; that lane already sets the needed runtime environment for its smoke checks.
Linux package targets fail to produce .rpm: Install the host rpm toolchain so rpmbuild is available.
Stale build state after large branch changes: Clean the local build directory and configure again.
You need ARM64 details: Start with the ARM64/AArch64 support section below.

Linux ARM64 / AArch64 Support

Current Status

TDSE Linux AArch64 support is qualified for CPU-only full SDK use on ubuntu-24.04 AArch64. The current release evidence host is AWS Graviton C8g.

Slice	Status	Notes
`x86_64` GNU/Linux	supported	current Linux qualification baseline
native `arm64` / `aarch64` GNU/Linux	supported	CPU-only full SDK, OpenBLAS/LAPACK/KLU, CLI, Profiler, tarball, DEB, and RPM package gates
AWS Graviton AArch64	qualified	current ARM performance and package evidence host
AArch64 sanitizer/nightly lane	qualified	self-hosted clang ASan/UBSan plus short soak smoke when the nightly variable is enabled
NVIDIA CUDA on ARM64	roadmap	feasibility lane for Grace/Jetson-class hosts; not part of the CPU-only ARM support claim
Apple Silicon host running Ubuntu ARM64 VM/container	customer qualification	useful developer host; not a native macOS product target

Supported ARM64 Feature Set

The supported ARM64 slice includes:

Runtime SDK and full SDK build/install.
Builder, Circuit SDK, CLI, Profiler, telemetry, OpenBLAS, LAPACK/LAPACKE, and SuiteSparse/KLU where the distro packages are installed.
Linux tarballs named with the canonical linux-aarch64 suffix.
DEB packages with Architecture: arm64.
RPM packages with aarch64 architecture.
pkg-config and CMake downstream consumers from the installed tree.

ARM NEON and SVE are internal AArch64 kernel paths. They are exposed through build-feature JSON from tdse_backend_caps as compiled_neon, compiled_sve, runtime_cpuid_neon, runtime_cpuid_sve, supported_simd_width_bits, and compiled_simd_width_bits. Per-model diagnostics distinguish those host/build facts from cpu_selected_simd_width_bits and cpu_selected_simd_isa, which describe the latest actual execution. The compatibility field active_simd_width is an eligible-lane hint, not execution evidence. They do not add public backend enum values; the existing public cpu_simd_avx2 and cpu_simd_avx512 backend entries remain present for ABI compatibility and are reported unavailable on ARM.

Not part of the first ARM64 support claim:

native macOS ARM64 packages
Windows ARM64 packages
CUDA or FPGA/XRT acceleration on ARM
non-glibc Linux distributions
non-Ubuntu ARM distro package semantics unless separately qualified

ARM64 Validation Lane

On a prepared Ubuntu 24.04 AArch64 host:

sudo apt-get update
sudo apt-get install -y build-essential cmake ninja-build python3 \
  libopenblas-dev liblapacke-dev rpm binutils

cmake -S . -B build-arm64-release -G Ninja \
  -DCMAKE_BUILD_TYPE=Release \
  -DTDSE_BLAS_VENDOR=OpenBLAS \
  -DTDSE_ENABLE_TELEMETRY=ON \
  -DTDSE_ENABLE_EXTENDED_CTEST_GATES=ON \
  -DTDSE_ENABLE_RELEASE_CTEST_GATES=ON

cmake --build build-arm64-release --parallel "$(nproc)"

ctest --test-dir build-arm64-release --output-on-failure -j 1 \
  -R "^(arm_runtime_features_gate|arm_sve_width_evidence_gate|arm_cuda_feasibility_probe_gate|runtime_backend_routing_gate|tdse_tests_telemetry_smoke|cpu_route_quality_arm_graviton_gate|cpu_batch_regression_gate)$"

ctest --test-dir build-arm64-release --output-on-failure -j 1 \
  -R "^(sdk_install_smoke_gate|runtime_only_install_smoke_gate|linux_package_artifacts_gate)$"

The ARM package gate validates that tarball metadata and root names use aarch64, DEB packages use arm64, RPM packages use aarch64, and extracted ELF binaries report the expected AArch64 machine type when readelf is available.

The SVE evidence gate writes arm_sve_width_evidence.json and .md under the build tree. It records Linux SVE vector length from prctl, CPU inventory, and the TDSE build-feature JSON. Use this artifact when comparing Graviton, Grace, or other SVE-capable ARM hosts.

The ARM CUDA feasibility probe writes arm_cuda_feasibility.json and .md. On CPU-only ARM hosts it is expected to pass with cuda_not_configured; on a Grace/Jetson-class runner it should move to cuda_hardware_visible before any CUDA-on-ARM support claim is made.

ARM64 Sanitizer And CUDA Feasibility Lanes

For nightly sanitizer confidence on a native Ubuntu AArch64 runner:

cmake -S . -B build-arm64-asan -G Ninja \
  -DCMAKE_BUILD_TYPE=RelWithDebInfo \
  -DCMAKE_C_COMPILER=clang \
  -DCMAKE_CXX_COMPILER=clang++ \
  -DCMAKE_C_FLAGS="-fsanitize=address,undefined -fno-omit-frame-pointer" \
  -DCMAKE_CXX_FLAGS="-fsanitize=address,undefined -fno-omit-frame-pointer" \
  -DCMAKE_EXE_LINKER_FLAGS="-fsanitize=address,undefined" \
  -DCMAKE_SHARED_LINKER_FLAGS="-fsanitize=address,undefined" \
  -DTDSE_BLAS_VENDOR=OpenBLAS \
  -DTDSE_ENABLE_CUDA=OFF \
  -DTDSE_CIRCUIT_ENABLE_CUDA_SOLVER=OFF \
  -DTDSE_ENABLE_EXTENDED_CTEST_GATES=ON \
  -DTDSE_ENABLE_CLI_SOAK_GATES=ON

ASAN_OPTIONS="detect_leaks=0:strict_string_checks=1:halt_on_error=1" \
UBSAN_OPTIONS="print_stacktrace=1:halt_on_error=1" \
cmake --build build-arm64-asan --parallel "$(nproc)"

ASAN_OPTIONS="detect_leaks=0:strict_string_checks=1:halt_on_error=1" \
UBSAN_OPTIONS="print_stacktrace=1:halt_on_error=1" \
ctest --test-dir build-arm64-asan --output-on-failure -j 1 \
  -R "^(tdse_tests_telemetry_smoke|runtime_backend_routing_gate|runtime_threading_stress|cpu_batch_regression_gate|arm_runtime_features_gate|arm_sve_width_evidence_gate|arm_cuda_feasibility_probe_gate|tdse_cli_randomized_smoke|plugin_soak_smoke)$"

For CUDA-on-ARM feasibility, use a separate self-hosted runner with NVIDIA hardware and CUDA toolkit already installed. Recommended labels:

self-hosted
linux
ARM64
tdse-arm64-cuda

Then enable the repository variable TDSE_ENABLE_ARM_CUDA_FEASIBILITY=1. The workflow configures TDSE_ENABLE_CUDA=ON and TDSE_CIRCUIT_ENABLE_CUDA_SOLVER=ON, then runs arm_cuda_feasibility_probe_gate, circuit_cuda_feasibility_gate, and circuit_solver_release_readiness_cuda_gate.

GitHub Without Paid ARM Runners

The repository provides .github/workflows/tdse-arm-self-hosted.yml for a self-hosted native ARM64 runner. It does not require GitHub-hosted ARM runners or a paid GitHub plan.

Recommended runner labels:

self-hosted
linux
ARM64
tdse-arm64

For AWS validation, attach an ephemeral GitHub self-hosted runner to an Ubuntu 24.04 Graviton instance, then run the workflow manually with workflow_dispatch. Automatic push execution is guarded by the repository variable TDSE_ENABLE_SELF_HOSTED_ARM=1; leave it unset if the runner is not always online.

For scheduled ARM sanitizer/soak evidence, set TDSE_ENABLE_SELF_HOSTED_ARM_NIGHTLY=1 only when an ARM runner is expected to be online for the Tuesday scheduled window. Without that variable, the workflow can still be run manually and will not consume paid hosted ARM capacity.

Keep the runner operational model simple:

use a short-lived AWS instance for release evidence
stop or terminate it after the workflow finishes
keep secrets out of the runner image
refresh the runner registration token for each ephemeral host

Real-Time and HIL Deployment

Use this section when TDSE must meet a real-time or hardware-in-the-loop timing budget, not just run correctly offline.

Keep the host/TDSE boundary simple in real-time deployments:

the host owns the wall-clock scheduler, solver sequencing, and any external I/O or device synchronization
TDSE exchanges model data only at step boundaries through tdse_step_begin(...), tdse_step_op(...), tdse_step_hr_v2(...), tdse_step_ir_v2(...), tdse_step_commit_v2(...), and optional tdse_step_dr_v2(...)
a practical HIL integration usually treats primary as the host-to-TDSE input vector and op / hr / ir / dr as TDSE-to-host outputs used inside the host's accepted-step policy

For most teams, RT/HIL readiness is a three-lane progression:

Lane	What it proves
offline fixed-step proof	step order and committed-state discipline are correct
target-machine timing proof	the host and TDSE fit within the wall-clock budget
field qualification proof	scheduler, I/O, and platform variance are acceptable on the real target

Step-Loop Timing Budget

In a real-time simulation, each time step must complete within a fixed wall-clock budget. For TDSE, the per-step cost depends on:

Factor	Impact on Step Time	Mitigation
`np` (port count)	quadratic: `O(np^2)` in operator multiply	minimize port count
`nh` (history depth)	linear: `O(nh)` in convolution	use IRC compression for large `nh`
`nq > np` (rectangular view)	additional rows in operator	only use when measurements require it
backend choice	GPU has higher per-step overhead but better throughput for large `np`	CPU for `np < 10`, GPU for `np > 50`
variable dt (non-uniform path)	interpolation adds overhead per history tap	prefer fixed `dt = model_dt` for real-time

Worst-Case Execution Time (WCET)

For real-time certification, measure WCET under these conditions:

Use deterministic mode (tdse_ext_context_set_deterministic_mode(ext, 1)) to eliminate scheduling jitter
Run the worst-case model configuration (largest np, nh in the deployment)
Measure over at least 10,000 consecutive steps
Record the maximum observed step time plus a safety margin (recommended: 20% margin)

The step-loop APIs with the highest individual latency are:

tdse_step_hr_v2(): proportional to nh * nq (convolution over all history taps)
tdse_step_op(): proportional to nq * np (dense matrix factorization for the operator)
tdse_step_commit_v2(): low constant cost (state advancement only)

Multi-Rate Coupling Time Budget

When coupling TDSE with an EMT solver at a different time step:

EMT step (e.g., 50 us):
├─ TDSE sub-steps: EMT_dt / TDSE_dt steps
│  ├─ each TDSE step: begin + op + hr + ir + commit
│  └─ per-step budget: EMT_dt / N_substeps
└─ remaining budget: host EMT solve + overhead

Example: EMT step = 50 μs, TDSE model_dt = 1 μs → 50 TDSE sub-steps per EMT step. Each TDSE sub-step must complete in under 50 μs / 50 = 1 μs (minus host overhead).

Deterministic Mode for Real-Time

Enable deterministic mode for all real-time deployments:

tdse_ext_context_t* ext = tdse_ext_context_create();
tdse_ext_context_set_deterministic_mode(ext, 1);
tdse_model_create_with_context(ext, pack_data, pack_size, &diag, &model);

This ensures:

bit-identical results across runs
reduced runtime-side variability from non-deterministic execution choices
more reproducible timing behavior during measurement

Deterministic mode improves measurement discipline, but it does not replace host-level WCET measurement, scheduler tuning, or target-machine qualification.

The throughput reduction from deterministic mode is acceptable in most real-time scenarios because the time budget is fixed regardless.

HIL Integration Patterns

For hardware-in-the-loop deployments:

Dedicated core allocation. Pin the TDSE worker thread to dedicated CPU cores. Use OS affinity APIs (pthread_setaffinity_np on Linux, SetThreadAffinityMask on Windows).
Pre-allocate all resources. Create all model handles before the real-time loop starts. No dynamic allocation during stepping.
Avoid OS interference. Isolate CPU cores from the OS scheduler (Linux isolcpus boot parameter) for the lowest jitter.
Monitor guard metrics. In real-time, continuous monitoring is essential. Poll tdse_ext_context_get_runtime_guard_metrics() on the model's extension context periodically (e.g., every 1000 steps) and log any threshold crossing.
Plan for graceful degradation. If a step exceeds its budget, the host must decide whether to skip the commit (reject the trial) or accept the latency overrun. TDSE's trial/commit separation supports both strategies.

Platform Notes