Platform Notes

Use this appendix when you need to answer platform questions: what Linux configurations are qualified, how installed-package validation is established, and what is planned for 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)
• Adapter Circuit, the circuit-domain adapter 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 Adapter 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, Adapter Circuit, CLI, Profiler
Linux optional accelerators	qualified	BLAS (OpenBLAS), LAPACK, KLU are validated; CUDA qualified on 12/13; MKL qualified separately

Supported Host Configuration

Current standard Linux support target is:

Dimension	Supported Baseline
CPU / OS class	x86_64 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, RuntimeCore tarball, DEB/RPM system packages, and installed pkg-config/CMake exports produced by the SDK release process

The following are not covered by the standard support scope:

• musl-based distributions
• arm64 or aarch64 (on roadmap, see ARM64 section below)
• 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. Adapter Circuit (circuit-domain adapter), 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 RuntimeCore 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, arm64), optional dependency stacks outside the current scope, or same-handle concurrent stepping.

---

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, RuntimeCore/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_adapter_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-runtimecore.pc
• /opt/tdse-sdk/lib/cmake/tdse/
• /opt/tdse-sdk/lib/cmake/tdseRuntimeCore/
• /opt/tdse-sdk/share/tdse/tdse_sdk_variant.json
• /opt/tdse-sdk/share/tdse/tdse_runtimecore_variant.json

Use the installed CMake package:

cmake -S <consumer-source> \
  -B build/package-consumer-cpu \
  -DCMAKE_PREFIX_PATH=/opt/tdse-sdk \
  -DTDSE_ADAPTER_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
RuntimeCore install	a Runtime-only consumer can link and run against tdse::tdse
Full SDK install	Runtime, Builder, Adapter, 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 a plan for ARM64 or Apple Silicon: Start with the ARM64/AArch64 roadmap section below.

Linux ARM64 / AArch64 Roadmap

Current Status

TDSE Linux support is currently qualified for x86_64 on ubuntu-24.04. That means arm64 / aarch64 is not part of the standard supported host profile today.

At the same time, ARM64 matters for:

• Apple Silicon developer laptops running Linux VMs or containerized validation environments
• AWS Graviton build and simulation fleets
• on-prem Linux clusters that are gradually adding ARM64 capacity

Slice	Status	Notes
x86_64 GNU/Linux	supported	current Linux qualification baseline
Apple Silicon macOS host running Linux VM/container	roadmap	useful as a developer and validation host, not yet a supported product target
native arm64 / aarch64 GNU/Linux	roadmap	no validation, package, or release qualification yet

Phase Plan

Phase 1: Toolchain Bring-Up

Exit criteria:

• configure + build succeed on native aarch64 GNU/Linux
• qualification tests pass with default dependencies
• RuntimeCore install + relocation smoke pass
• pkg-config and CMake package consumers both compile and run

Target hosts:

• AWS Graviton runner or equivalent native aarch64 Linux host
• Apple Silicon developer host using an Ubuntu ARM64 VM or container

Phase 2: Linux Package Parity

Exit criteria:

• ARM64 tarballs are generated in the same layout as x86_64
• ARM64 .deb and .rpm packages are generated in the validation pipeline
• package artifact smoke validates tarball, pkg-config, and CMake consumption on ARM64

Target hosts:

• ubuntu-24.04 ARM64 runner
• at least one non-Ubuntu validation host for package-install sanity

Phase 3: Performance And Support Qualification

Exit criteria:

• threading stress, sanitizer, and soak tests are green on ARM64
• package notes document any architecture-specific performance or backend limits
• Linux support scope is expanded to name the qualified ARM64 host profile explicitly

Known Technical Risks

• SIMD paths are currently tuned around x86 feature detection and may need NEON-aware follow-up work
• optional CUDA paths are not part of the initial ARM64 support claim
• external dependency availability can differ across distros, especially SuiteSparse/KLU packaging
• Apple Silicon developer convenience does not automatically imply macOS product support

Current ARM64 Position

Until Phase 3 is complete, the current ARM64 position is:

• ARM64/AArch64 enablement is on the public roadmap
• Linux support today is qualified on x86_64 GNU/Linux only
• Apple Silicon is a development-host convenience story, not a separate supported runtime platform

What Completion Looks Like

This roadmap will be considered complete when all of the following are true:

• ARM64 validation infrastructure exists
• install/package smoke exists for ARM64
• Linux support scope names the ARM64 host profile directly
• the handbook and package-consumer paths treat ARM64 Linux as an ordinary Linux package consumer path

---

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(...), tdse_step_ir(...), tdse_step_commit(...), and optional tdse_step_dr(...)
• 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:

1. Use deterministic mode (tdse_ext_set_deterministic_mode(1)) to eliminate scheduling jitter
2. Run the worst-case model configuration (largest np, nh in the deployment)
3. Measure over at least 10,000 consecutive steps
4. 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(): 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(): 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_set_deterministic_mode(1);

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:

1. Dedicated core allocation. Pin the TDSE worker thread to dedicated CPU cores. Use OS affinity APIs (pthread_setaffinity_np on Linux, SetThreadAffinityMask on Windows).

2. Pre-allocate all resources. Create all model handles before the real-time loop starts. No dynamic allocation during stepping.

3. Avoid OS interference. Isolate CPU cores from the OS scheduler (Linux isolcpus boot parameter) for the lowest jitter.

4. Monitor guard metrics. In real-time, continuous monitoring is essential. Poll tdse_ext_get_runtime_guard_metrics() periodically (e.g., every 1000 steps) and log any threshold crossing.

5. 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.