Examples Guide

Audience: Anyone looking for a runnable reference implementation that matches their integration scenario. Start here after Installation and the first hands-on tutorial run.

Use this chapter to match the shipped evaluation examples to real integration paths. If you are not sure which chapter to read next, choose the example closest to your source data and follow the linked workflow from there.

Use this chapter in two passes:

1. pick the example family that matches your starting artifact
2. use the linked chapter as the durable reference after the example runs

For a one-day minimal integration, the usual path is:

1. run Hands-On Tutorial once so create, step, and destroy are already proven on your machine
2. choose exactly one example that matches your real starting point
3. switch from the example to the linked chapter and keep that chapter as the contract source for production code

Start Here

If your starting point looks like this	Best first example	Then read
I just finished Hands-On Tutorial and want one more minimal Runtime example	runtime_bare_metal	Runtime Lifecycle and Step Execution
I already have FRF data	builder_frf_1p or builder_frf_2p	Builder and Data Contracts
I need circuit-to-pack workflow	workflow_cpp_quickstart	Adapter Circuit
I need host embedding patterns	mna_block_embed_2p	Adapter Circuit
I need RAW conversion	raw_import_api or raw_import_cpp	Adapter Circuit and CLI Reference
I need observability or perf work	telemetry_basic	Telemetry and Profiler

Fastest evaluation picks:

• runtime_bare_metal when you want one more Runtime-only proof after Hands-On Tutorial
• workflow_cpp_quickstart when you want the shortest netlist -> pack PoC path
• package_consumer_targets or package_consumer_pkgconfig when you need proof that a downstream build can consume the installed SDK cleanly

If you are still in the first 30 minutes of an evaluation, ignore the full index below and choose only one of those three paths.

Example Index

Core Runtime

Example	What It Does
runtime_bare_metal	Load a pack, create a model, run a step loop — no Builder or Adapter involved
variable_dt	Pass different dt values at each step; demonstrates non-uniform time-stepping

Builder

Example	What It Does
builder_frf_1p	Build a pack from synthetic 1-port FRF data, then verify via Runtime step loop
builder_frf_2p	Same for a 2-port passive admittance
builder_irc	Apply IRC compression (MULTIRES_V1, MULTIRES_V2_MOMENT1) and compare tap counts

Adapter Circuit

Example	What It Does
circuit_adapter_1p	Minimal host circuit solver: stamp TDSE into a 1-port MNA system, solve, step
circuit_adapter_2p	Same for 2-port with explicit KCL stamping
mna_block_embed_2p	Embed TDSE 2-port contributions into a 4-node MNA network
adapter_cpp_quickstart	C++ wrapper: compile a netlist, compute Y matrix, AC probe, adaptive plan, build H
adapter_cpp_threaded_lanes	Multi-threaded pattern: per-worker handles with compile and request policy overrides
workflow_cpp_quickstart	High-level netlist_to_pack workflow: one call from SPICE file to .pack file
netlist_to_pack_np	Low-level Adapter-to-Builder handoff with manual/adaptive sweep planning (advanced)
raw_import_api	Convert PSS/E RAW to netlist via C API
raw_import_cpp	Same RAW conversion using the C++ wrapper (raw::fileToNetlist)
nport_y2p_ac	AC probe with an NPORT element loaded from a Touchstone .y2p file
tail_scan	Run scanTailVsNfreq to determine the required frequency resolution for a circuit
region_prepare	Resolve named circuit regions into explicit port definitions
try_api	Use the try* no-throw C++ API variants with manual error-code checking

Telemetry

Example	What It Does
telemetry_basic	Initialize telemetry service, attach to model, run steps, inspect JSON output

Deployment

Example	What It Does
package_consumer_targets	Consume TDSE via CMake find_package(tdse)
package_consumer_pkgconfig	Consume TDSE via pkg-config

Choosing the Right Example

What are you trying to do?
├─ "I just want to see the Runtime step loop"
│  → runtime_bare_metal
├─ "I have FRF data and want to build a pack"
│  → builder_frf_1p (1 port) or builder_frf_2p (2+ ports)
├─ "I want to compress a long impulse response"
│  → builder_irc
├─ "I have a circuit netlist and want end-to-end"
│  → circuit_adapter_1p or circuit_adapter_2p
├─ "I want to embed TDSE in my host solver"
│  → mna_block_embed_2p
├─ "I want to use the C++ wrapper API"
│  → adapter_cpp_quickstart
├─ "I want the fastest netlist-to-pack path"
│  → workflow_cpp_quickstart
├─ "I need full control of the Adapter-to-Builder pipeline"
│  → netlist_to_pack_np
├─ "I want to convert a PSS/E RAW file in code"
│  → raw_import_api (C) or raw_import_cpp (C++)
├─ "I want to check causality / find the right nfreq"
│  → tail_scan
├─ "I want to resolve a circuit region into ports"
│  → region_prepare
├─ "I want non-throwing error handling in C++"
│  → try_api
├─ "I want to run with variable time steps"
│  → variable_dt
├─ "I need multi-threaded adapter usage"
│  → adapter_cpp_threaded_lanes
├─ "I need step-level telemetry in production"
│  → telemetry_basic
├─ "I need to package TDSE for my build system"
│  → package_consumer_targets (CMake) or package_consumer_pkgconfig (pkg-config)

After The Tutorial

If you came here directly from Hands-On Tutorial, the cleanest next moves are:

• stay in Core Runtime if you are proving host loop ownership and shutdown behavior
• move to Builder if your real input is already validated FRF or impulse-response data
• move to Adapter Circuit if your real input starts as a netlist, RAW case, or NPORT workflow
• move to Telemetry or Deployment only after a normal create-step-destroy path is already stable

From Example To Real Integration

Use the example only long enough to prove the path. Then switch to the chapter that owns the real contract for production code.

If the example proved...	Durable chapter to keep open	Avoid jumping to this too early
pack create / destroy and one host step loop	Runtime Lifecycle and Step Execution	Variable dt or multi-model topics before the fixed-step path is stable
Builder packaging from FRF or H / IR data	Builder and Data Contracts	low-level Adapter flows you do not actually need
netlist or RAW input can become a qualified .pack	Adapter Circuit	direct low-level Builder tuning before the input path is trusted
package consumption works in a downstream build	Installation and Platform Notes	performance or plugin tuning before the install surface is stable

Building the Examples

If your evaluation package includes example projects, build them from the delivered example root:

cmake -S <example-root> -B <example-root>/build -DCMAKE_BUILD_TYPE=Release
cmake --build <example-root>/build -j"$(nproc)"

To build a specific example, use its documented CMake target name. For example:

cmake --build <example-root>/build --target tdse_example_builder_frf_1p

For package consumption examples, install the SDK first:

cmake -S <package-consumer-example-root> -B build -DCMAKE_PREFIX_PATH=/opt/tdse-sdk
cmake --build build