Installation

Use this chapter to install TDSE Runtime in its Deployment/Target or Development/Authoring role, confirm the selected surface, and verify the installed package. These are two installation profiles of the same TDSE Runtime product; CPU capability is included in both.

The SDK provides Runtime, Builder, Circuit, and Full SDK libraries that you link into your application, plus a command-line tool (tdse) for benchmarking and profiling.

Once the verification step succeeds, continue directly to Hands-On Tutorial. That chapter is the shortest trustworthy first run.

For a first customer-style evaluation, keep the goal narrow:

1. prove the shipped package is intact
2. prove headers and libraries are discoverable from a downstream consumer
3. prove one tiny program links and runs before you move on to Builder or host integration

When this chapter is complete, you should be ready to start the hands-on tutorial without changing tools, package paths, or library names.

System Requirements

Every SDK user needs a compiler and CMake to build against the SDK libraries.

• Windows: Windows 10 or later, 64-bit. MSVC 2019 or later.
• Linux: x86_64 GNU/Linux, glibc-based (tested on Ubuntu 24.04). GCC 10+ or Clang 14+.
• CMake: 3.21 or later. On Linux, pkg-config is also supported.
• Disk space: ~200 MB.

Prebuilt SDK packages include the TDSE-bundled SuiteSparse, OpenBLAS, and CUDA payloads selected by the release build. Linux system packages also declare any distro-provided LAPACKE or standard ABI runtime selected by that build, so the package manager installs the complete dependency closure. The bundled OpenBLAS shared library still depends on standard system ABI libraries such as glibc and libgfortran.so.5.

This chapter assumes a shipped closed-source RC evaluation package rather than source access to TDSE itself.

Package Contents

Linux (FullSDK Release Aggregate)

tdse-sdk/
├── bin/
│   ├── tdse                         (unified CLI: matrix, series, probe, raw-to-netlist)
│   ├── tdse_plugin_doctor           (plugin health diagnostics)
│   ├── tdse_packgen                 (pack generation)
│   ├── tdse_pack_validate           (pack validation)
│   └── tdse_backend_caps            (solver backend capability report)
├── include/
│   ├── tdse.h                       (Runtime C API)
│   ├── tdse.hpp                     (Runtime C++ wrapper)
│   ├── tdse_builder.h               (Builder C API)
│   ├── tdse_builder.hpp
│   ├── circuit.h                    (Circuit C API)
│   ├── circuit.hpp                  (Circuit C++ wrapper)
│   ├── tdse_perf.h                  (performance profiler)
│   ├── tdse/
│   │   ├── tdse.h                   (Runtime core)
│   │   ├── tdse_plugin.h            (plugin info struct)
│   │   └── plugin/
│   │       ├── simulation.h         (simulation plugin ABI)
│   │       ├── manifest.hpp         (C++ manifest source API)
│   │       └── metrics.h            (plugin observability)
│   └── tdse/circuit/
│       ├── common.h                 (error codes, handle type, options)
│       ├── compile.h                (netlist compilation)
│       ├── compute.h                (frequency sweep, port series, probes)
│       ├── backend_job.h             (same-release backend EMT jobs)
│       ├── diagnostics.h            (solver stats, policy trace)
│       ├── init.h                   (struct initializers)
│       ├── nport.h / nport.hpp       (N-port Touchstone I/O)
│       ├── planning.h               (adaptive sweep planning)
│       ├── policy.h                 (solver backend selection)
│       ├── raw.h                    (PSS/E RAW import)
│       ├── seq.h                    (sequence network import)
│       └── workflow.h / workflow.hpp (high-level workflow API)
├── lib/
│   ├── libtdse.so                   (Runtime, always shared)
│   ├── libtdse_builder.a            (Builder, static)
│   ├── libtdse_circuit.a            (Circuit SDK, static)
│   ├── libtdse_circuit_cli.a        (Circuit CLI module, static)
│   ├── plugins/
│   │   └── sim/
│   │       ├── libtdse_sim_cpu_dense.so
│   │       ├── libtdse_sim_cpu_sparse.so
│   │       ├── libtdse_sim_cuda.so
│   │       └── plugin_manifest.json
│   ├── tdse/third_party/            (bundled: SuiteSparse, OpenBLAS, CUDA runtime)
│   ├── cmake/tdse/                  (CMake package config)
│   └── pkgconfig/
│       ├── tdse.pc                  (FullSDK pkg-config)
│       ├── tdse-runtime-sdk.pc      (RuntimeSDK pkg-config)
│       └── tdse-circuit-sdk.pc      (CircuitSDK pkg-config)
└── share/
    └── doc/
        └── tdse/
            ├── api/                  (Doxygen HTML API reference — open index.html)
            │   └── index.html
            ├── TDSE_Runtime_User_Guide.pdf
            └── TDSE_Circuit_User_Guide.pdf

Third-party shared libraries (SuiteSparse, OpenBLAS, CUDA runtime) are bundled under lib/tdse/third_party/ so the SDK does not depend on separately installed copies of those libraries. Standard OS runtime libraries such as glibc and libgfortran.so.5 are still supplied by the host. The RuntimeSDK package is a subset: it omits Builder, Circuit SDK, plugins, CLI tools, and documentation; it contains only libtdse.so and the core Runtime headers.

Linux system packages are split by installation role and technical component. Package names do not define additional commercial products:

Package	Contents and compatibility level
tdse-runtime	TDSE Runtime Deployment/Target profile; binaries, selected providers, identities, and notices
tdse-runtime-authoring	TDSE Runtime Development/Authoring profile; Runtime plus stable C ABI headers, C++ wrappers, pkg-config, and CMake exports
tdse-runtime-sdk-experimental	Perf/backend-control and telemetry preview headers
tdse-circuit-sdk	TDSE Circuit domain component: static same-release Builder, Circuit, N-port, and Workflow APIs
tdse-plugin-sdk	Formal trusted in-process Simulation Plugin ABI v1 and same-toolchain manifest API
tdse-simulation-plugins	Built-in DSOs and manifest; exact CircuitSDK dependency (RuntimeSDK transitive)
tdse-full-sdk	Release aggregate/meta-package; CLI, documentation, and exact-version dependencies on SDK components

The relocatable archive equivalents are runtime-deployment and runtime-authoring. Every profile carries the product catalog, its schema, and a build-resolved product identity under share/tdse/product/.

For 1.0.0-rc1, Debian packages use 1.0.0~rc1-1 and RPM packages use 1.0.0-0.1.rc1. Both forms sort below the future GA EVR 1.0.0-1, so the normal package-manager upgrade path moves from RC to GA. Package validation checks this ordering with the native Debian and RPM version comparators.

The Backend Plugin draft and test/fault-injection headers are internal and are not installed by any customer SDK package. See docs/dev/sdk-stability-policy.md in the source distribution for the precise stability contract.

Windows (FullSDK Release Aggregate)

tdse-sdk/
├── bin/
│   ├── tdse.exe                     (unified CLI)
│   ├── tdse_plugin_doctor.exe       (plugin diagnostics)
│   ├── tdse.dll                     (Runtime)
│   └── *.dll                        (third-party dependencies)
├── include/
│   ├── tdse.h, tdse_builder.h, circuit.h …  (same as Linux)
│   ├── tdse/
│   └── tdse/circuit/
├── lib/
│   ├── tdse.lib                     (Runtime import library)
│   ├── tdse_builder.lib             (Builder, static)
│   ├── tdse_circuit.lib             (Circuit SDK, static)
│   ├── tdse_circuit_cli.lib         (Circuit CLI module, static)
│   ├── plugins/
│   │   └── sim/
│   │       ├── tdse_sim_cpu_dense.dll
│   │       ├── tdse_sim_cpu_sparse.dll
│   │       └── tdse_sim_cuda.dll
│   ├── cmake/tdse/                  (CMake package)
│   └── pkgconfig/
│       ├── tdse.pc
│       ├── tdse-runtime-sdk.pc
│       └── tdse-circuit-sdk.pc
└── share/
    └── doc/
        └── tdse/
            ├── api/
            │   └── index.html         (Doxygen HTML API reference)
            ├── TDSE_Runtime_User_Guide.pdf
            └── TDSE_Circuit_User_Guide.pdf
    └── tdse_runtime_sdk_variant.json

Third-party DLLs are placed in bin/ alongside the CLI executable — adding bin/ to your PATH makes everything discoverable.

Install TDSE

Linux

Extract the tarball and verify the package is intact:

mkdir -p /opt/tdse-sdk
tar -xf tdse-sdk-*-linux-x86_64.tar.gz -C /opt/tdse-sdk --strip-components=1
/opt/tdse-sdk/bin/tdse sdk version --json-out -

Expected output: a JSON line containing "status":"ok". If you see error while loading shared libraries, add the library directory:

export LD_LIBRARY_PATH=/opt/tdse-sdk/lib:$LD_LIBRARY_PATH

For convenience, add the CLI to your PATH:

export PATH="/opt/tdse-sdk/bin:$PATH"

Windows

Extract the zip archive to a directory of your choice, e.g. C:\tdse-sdk, then verify:

C:\tdse-sdk\bin\tdse sdk version --json-out -

For convenience, add bin\ to your PATH via System Properties → Environment Variables.

Set Up Your Project

CMake

Point CMAKE_PREFIX_PATH to the SDK root and link the targets your application needs:

set(TDSE_REQUIRED_RELEASE_VERSION "1.0.0-rc1")
find_package(tdse CONFIG REQUIRED)
target_link_libraries(my_app PRIVATE tdse::tdse tdse::tdse_builder)

Prerelease suffixes cannot be expressed by CMake's numeric package-version grammar. Set TDSE_REQUIRED_RELEASE_VERSION before finding the full or Circuit package so a different RC or final release fails during configuration.

cmake -DCMAKE_PREFIX_PATH=/path/to/tdse-sdk ..

Available targets:

Target	What it provides
tdse::tdse	Runtime (step loop, lifecycle, diagnostics)
tdse::tdse_builder	Builder (pack creation)
tdse::tdse_circuit	Circuit SDK
tdse::tdse_circuit_cli	Circuit CLI command module
tdse::tdse_plugin_sdk	Header-only Simulation Plugin ABI

If your application only needs the Runtime, use find_package(tdseRuntimeSDK) which exports tdse::tdse alone.

Plugin authors can install only the PluginSDK component and use its independent package without linking Runtime or Circuit libraries:

find_package(tdsePluginSDK CONFIG REQUIRED)
target_link_libraries(my_plugin PRIVATE tdse::tdse_plugin_sdk)

pkg-config (Linux)

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

Manual Flags

If you are not using CMake or pkg-config:

Linux:

g++ -std=c++20 my_app.cpp \
    -I/opt/tdse-sdk/include \
    -L/opt/tdse-sdk/lib \
    -ltdse_builder -ltdse -lm \
    -Wl,-rpath,/opt/tdse-sdk/lib \
    -o my_app

Windows:

cl my_app.c ^
  /I"C:\tdse-sdk\include" ^
  /link "C:\tdse-sdk\lib\tdse.lib" "C:\tdse-sdk\lib\tdse_builder.lib"

Verify Your Setup

Compile and run a minimal program to confirm your project can find headers and link against both Runtime and Builder.

// test_sdk.cpp
#include <tdse/tdse.h>
#include <tdse/tdse_builder.h>
#include <cstdio>

int main() {
    const char* v = tdse_version_string();
    if (!v) return 1;
    std::printf("TDSE %s\n", v);
    std::printf("builder status: %s\n", tdse_builder_status_message(0));
    return v ? 0 : 1;
}

Linux:

g++ -std=c++20 test_sdk.cpp \
    -I/opt/tdse-sdk/include \
    -L/opt/tdse-sdk/lib \
    -ltdse_builder -ltdse -lm \
    -Wl,-rpath,/opt/tdse-sdk/lib \
    -o test_sdk
./test_sdk

Windows:

cl test_sdk.cpp ^
  /I"C:\tdse-sdk\include" ^
  /link "C:\tdse-sdk\lib\tdse.lib" "C:\tdse-sdk\lib\tdse_builder.lib"
test_sdk.exe

Expected output: TDSE 1.0.0-rc1 (or your installed version).

Check Individual Components

Use these commands to confirm specific SDK components are present. They are not required for normal use — they help diagnose setup problems.

Headers:

# Linux
ls /opt/tdse-sdk/include/tdse/tdse.h
ls /opt/tdse-sdk/include/tdse/tdse_builder.h

rem Windows
dir "C:\tdse-sdk\include\tdse\tdse.h"
dir "C:\tdse-sdk\include\tdse_builder.h"

Libraries:

# Linux
ls /opt/tdse-sdk/lib/libtdse.so
ls /opt/tdse-sdk/lib/libtdse_builder.a

rem Windows
dir "C:\tdse-sdk\lib\tdse.lib"
dir "C:\tdse-sdk\lib\tdse_builder.lib"

Plugins (required for Circuit SDK commands):

# Linux
ls /opt/tdse-sdk/lib/plugins/sim/libtdse_sim_cpu_dense.so
ls /opt/tdse-sdk/lib/plugins/sim/libtdse_sim_cpu_sparse.so
ls /opt/tdse-sdk/lib/plugins/sim/libtdse_sim_cuda.so
ls /opt/tdse-sdk/lib/plugins/sim/plugin_manifest.json
ls /opt/tdse-sdk/bin/tdse_plugin_doctor

rem Windows
dir "C:\tdse-sdk\lib\plugins\sim\tdse_sim_cpu_dense.dll"
dir "C:\tdse-sdk\lib\plugins\sim\plugin_manifest.json"
dir "C:\tdse-sdk\bin\tdse_plugin_doctor.exe"

Inspect Installed Variant

The installed package manifests tell you which public targets and optional features are present. Read these before guessing whether a machine has sparse CPU, CUDA, full SDK headers, or only RuntimeSDK.

Linux:

cat /opt/tdse-sdk/share/tdse/tdse_sdk_variant.json
cat /opt/tdse-sdk/share/tdse/tdse_runtime_sdk_variant.json
cat /opt/tdse-sdk/share/tdse/tdse_circuit_sdk_variant.json

Windows:

type C:\tdse-sdk\share\tdse\tdse_sdk_variant.json
type C:\tdse-sdk\share\tdse\tdse_runtime_sdk_variant.json
type C:\tdse-sdk\share\tdse\tdse_circuit_sdk_variant.json

Typical tdse_sdk_variant.json fields include:

• build_variant - package flavor such as full-feature
• package_profile - always sdk
• features - optional slices such as sparse_cpu and cuda
• recommended_circuit_targets - the target list used by -DTDSE_CIRCUIT_TARGETS=AUTO
• exported_targets - the exact installed CMake targets

Typical tdse_runtime_sdk_variant.json fields include:

• build_variant - the RuntimeSDK bundle flavor for this release
• package_profile - always RuntimeSDK
• config_package - the installed CMake package name, typically tdseRuntimeSDK
• exported_targets - the exact installed RuntimeSDK CMake targets

Use these manifests when:

• a downstream consumer needs to choose between RuntimeSDK, CircuitSDK, and the full SDK
• a build system wants to enable sparse CPU or CUDA only when installed
• you need to confirm that AUTO target selection is doing what you expect

If you consume the SDK through CMake, the package_consumer_targets example described in Examples Guide demonstrates the intended out-of-tree install-tree flow. If you consume the full SDK through pkg-config, the feature slices are exposed through variables such as sparse_libs and cuda_libs.

Acceptance Ladder

Use this ladder when you need more confidence than "the files extracted correctly."

1. Basic link proof Run tdse sdk version --json-out - and compile the tiny program in this chapter. This proves the CLI, headers, and core libraries are discoverable.
2. Installed-package consumer proof Build one of the out-of-tree package-consumer examples against the installed SDK: package_consumer_targets for CMake or package_consumer_pkgconfig for pkg-config.
3. Runtime and plugin proof Run tdse_plugin_doctor against the installed manifest, then complete the Hands-On Tutorial path to prove Builder -> Runtime execution still works on this machine.

For Linux packaging and release-candidate validation, the broader install, package, and clean-host gates are summarized in Platform Notes.

If your next question is "can a downstream build consume this install tree cleanly?", stop here and run one package-consumer example before reading deeper SDK chapters. That is a better first PoC signal than jumping straight into advanced Runtime or Circuit details.

Compatibility Promises

These are the public compatibility rules you can rely on when integrating against the installed SDK:

• Pack format: Runtime accepts supported pack versions and reports incompatibility at create time through normal diagnostics and validation APIs.
• Public structs: most extensible Runtime, Builder, Circuit, and plugin-facing request/config/diagnostic structs use a struct_size field for forward-compatible growth. Intentionally frozen payloads are documented as exceptions.
• Plugin ABI: formal v1 uses a sized/versioned result and caller-owned side buffers. An older same-major minor is accepted only when it was published and is covered by executable compatibility evidence.
• Installed-package consumption: the shipped install tree is exercised through CMake/package-export and pkg-config smoke paths, not only through ad hoc same-machine linking.

Troubleshooting

Symptom	Likely cause	Fix
tdse/tdse.h: No such file or directory	Include path not set	Add -I<prefix>/include
libtdse.so: cannot open shared object file	Library path not set (Linux)	export LD_LIBRARY_PATH=<prefix>/lib
LNK1181: cannot open input file 'tdse.lib'	Linker path not set (Windows)	/LIBPATH:<prefix>\lib or use CMake
find_package(tdse) fails	CMake cannot locate the SDK	-DCMAKE_PREFIX_PATH=<prefix>
No simulation engine plugin loaded	Plugin artifact missing or manifest path wrong	Check <prefix>/lib/plugins/sim/ and plugin_manifest.json
tdse: command not found	CLI not on PATH	Add <prefix>/bin to PATH

In production deployments:

• point TDSE_PLUGIN_MANIFEST at <prefix>/lib/plugins/sim/plugin_manifest.json
• enable TDSE_PLUGIN_STRICT_MODE=1
• use tdse_plugin_doctor as the first support or field diagnostic command

Next Step

If the install and verification steps succeeded:

• go to Hands-On Tutorial for the first end-to-end Builder -> Runtime run
• then use Examples Guide to find the closest runnable reference for your real workflow