TDSE Runtime
Runtime product scope, reading paths, terminology, and conventions.
Scope
TDSE Runtime is the required core product for every customer. CPU capability is included. GPU and FPGA are optional hardware Add-ons whose build presence, device visibility, authorization, product runtime, and qualification are reported separately.
This manual covers authoring, integration, deployment preparation, target operation, and support from one complete TDSE installation. These are usage scenarios, not products, SKUs, or installation configurations. Builder is the Runtime API and workflow for pack creation; it is not a separate product, library, or package. CLI, Profiler, Telemetry, and plugin integration are technical surfaces delivered around Runtime. TDSE Circuit is a separately purchased domain component with its own user and integration guide.
How To Use This Manual
Follow the shortest path that matches the current task:
| Reader goal | Start here | Continue with |
|---|---|---|
| Evaluate the package | Installation | Hands-On Tutorial |
| Author a Runtime Pack | Builder and Data Contracts | Runtime Lifecycle |
| Embed Runtime in a host | Runtime Integration | Step Execution |
| Prepare a target deployment | Installation | Platform Notes |
| Tune or accelerate Runtime | Backend Selection and Performance | Runtime Performance Tuning |
| Diagnose an incident | Runtime Troubleshooting Runbook | Troubleshooting |
| Start from a circuit or RAW case | TDSE Circuit manual | the applicable Integration Playbook (SDK source: docs/integrations/README.md) |
For a closed-source evaluation package:
- verify the installed package and product identity;
- complete one Builder-to-Runtime tutorial;
- select the example closest to the intended host;
- validate CPU behavior before enabling a hardware Add-on;
- qualify the final host target and payload independently.
Book Structure
- Onboarding: installation, tutorial, examples, and concepts.
- Authoring: Builder inputs, validation, and Runtime Pack creation.
- Runtime integration: lifecycle, step order, variable timestep, concurrency, threading, and multi-model use.
- Hardware and performance: CPU, GPU Add-on, FPGA Add-on, Profiler, Telemetry, backend policy, and tuning.
- Deployment and operations: platform constraints, plugins, diagnostics, troubleshooting, and acceptance checklists.
Exact declarations belong to the API Reference (SDK source: docs/api-reference/c-api.md).
Exact command flags belong to the CLI Reference.
Current capability and qualification claims belong to the
Runtime Backend Support Matrix (SDK source: docs/user-guide/runtime-backend-support-matrix.md). These
references are not additional formal user manuals.
Runtime Flow
Runtime consumes an identified Runtime Pack and participates in a host-owned simulation step:
Validated data -> Builder -> Runtime Pack -> TDSE Runtime -> host trial/commit
- Builder creates the reusable pack during model preparation.
- Runtime loads the pack and evaluates the packaged operator.
- The host owns time, scheduling, acceptance, rollback, and global solving.
- A partner target uses the supported Redistributable Payload containing the Runtime binary, selected providers, product identity, dependency records, and notices.
TDSE Runtime is not a general-purpose circuit simulator. Customers whose starting point is a circuit netlist, RAW/SEQ case, or Circuit-owned ModelSpace workflow use TDSE Circuit before the Runtime handoff.
Document Conventions
Typographic conventions used throughout this guide:
| Convention | Meaning | Example |
|---|---|---|
| Bold | Emphasis, important terms on first use | The Runtime executes the pack |
| Italic | New terms, parameter names in prose | the runtime pack is read-only |
Monospace | Code, API symbols, file paths, command-line input | call tdse_model_create() |
Monospace bold | Commands to type exactly as shown | cmake --build build --parallel 4 |
The guide uses four callout styles. Each appears here exactly as it does in the rest of the book:
WARNING: Critical information that prevents data loss or incorrect results.
IMPORTANT: Information essential to correct usage.
NOTE: Supplementary information or clarification.
TIP: Shortcut or recommended practice.
Key Terminology
The terminology below covers the technical abbreviations and runtime terms used most often in the handbook.
Core Terms
| Term | Meaning |
|---|---|
| H | Impulse Response - Time-domain impulse response (delayed-history operator) |
| IR | Independent Response - Pre-computed independent response sequence (optional) |
| op | Instantaneous Operator - Immediate response term (G0 or R0) at current timestep |
| hr | History Response - Delayed-history contribution from past timesteps |
| ir | Independent Response Term - Contribution from pre-computed IR sequence |
| dr | Direct Response - Post-commit direct response term |
| Builder | TDSE Runtime API and workflow that creates runtime packs from validated input data; not a separate product or library |
| Runtime | Required core product and execution engine for runtime packs |
| pack | Runtime Pack - Compressed binary model file created by Builder |
| trial step | Current not-yet-committed evaluation context created by tdse_step_begin(...) |
| committed step | Last accepted step after tdse_step_commit(...) |
| port | Interface variable pair defining coupling between linear and nonlinear subsystems |
| impulse response | Time-domain response of the linear subsystem to a unit impulse at a port |
Lifecycle Terms
| Term | Meaning |
|---|---|
| close | Explicit shutdown request that returns immediately with a status |
| destroy | Recommended shutdown call with a caller-chosen wait budget |
| release | Final cleanup path, usually used in RAII or finally-style code |
| ownership handoff | Moment a caller must stop treating a handle as locally owned |
| bounded destroy | Destroy with an explicit wait budget and a result the caller can inspect |
Diagnostics Terms
| Term | Meaning |
|---|---|
| create diagnostics | Request-scoped data returned through tdse_model_create_diagnostics_t |
| model info | Static metadata snapshot for a live handle |
| state info | Dynamic execution-state snapshot for a live handle |
| last error info | Sticky snapshot of the most recent non-OK runtime result |
| pack error token | Symbolic name derived from create_diag.pack_error_code |
Concurrency Terms
| Term | Meaning |
|---|---|
| same-handle concurrent use | Overlapping runtime API entry on the same tdse_model_t* |
| execution thread | Logical worker or simulation thread that owns one runtime handle |
| finalizer cleanup | Cleanup path that does not itself define host lifecycle policy |
Revision History
| Version | Date | Description |
|---|---|---|
| 1.0.0-rc1 | 2026-08-15 | Current release candidate; see the repository changelog for release history and later unreleased contract changes. |
