TDSE Circuit Co-Simulation Workflow

TDSE Circuit owns import, validation, region selection, host EMT solving, event execution, TDSE Runtime coupling, waveform comparison, diagnostics, and the public CLI/API. ModelSpace is the current package and evidence format for new TDSE Circuit workflow documentation. TDSE Runtime executes only qualified selected regions through explicit pack binding.

Use tdse circuit co-sim as the product entry point for TDSE Circuit plus TDSE Runtime co-simulation. The workflow writes a reusable evidence bundle containing the input package, selected region, qualification report, Runtime pack binding, host baseline waveforms, TDSE-coupled waveforms, waveform comparison report, artifact index, manifest, and markdown report.

Selecting Norton or Thevenin Coupling

ModelSpace Circuit supports both equivalent-source forms through the same host EMT and TDSE Runtime workflow. Select the matrix family when building the region pack:

tdse circuit region-to-pack `
  --case <case.json> `
  --region <region_id> `
  --out <region.pack> `
  --out-json <pack_binding.json> `
  --matrix z

--matrix y selects the admittance/Norton form i = Yv + I_SC; --matrix z selects the impedance/Thevenin form v = Zi + V_OC. New region packs default to z; select --matrix y explicitly for Norton form. The subsequent co-sim command reads the pack binding and uses its recorded matrix family, including existing Y bindings.

The public ModelSpace C API exposes the same choice through the appended tdse_modelspace_circuit_workflow_request_t::matrix_kind field. Use TDSE_CIRCUIT_MATRIX_Y or TDSE_CIRCUIT_MATRIX_Z, preferably starting from tdse_modelspace_circuit_workflow_request_init(). Callers compiled against the older request layout, without this field, receive the current Z compatibility default. Initialize the current request and explicitly select Y when Norton behavior is required.

Native Circuit Execution and Source Accounting

Circuit owns the complete transient solve for both the full-network baseline and Runtime-coupled execution. The coupled path uses native Circuit controlled sources for the port relation: CCVS plus voltage sources for Z/Thevenin, or VCCS plus current sources for Y/Norton. Circuit performs element stamping, event handling, integration, and the linear solve.

For Z, the native branch equation is B^T v - Z0 i = hr + ir, with current positive from the host into the selected region. The accepted branch current is committed to Runtime. For Y, the relation is i = Y0 v + hr + ir, and the accepted port voltage is committed. Region elements are replaced by the boundary equivalent in the external network; internal sources contribute through IR and must not be added again as external sources.

The coupling report records host_boundary_solve_mode as circuit_native_thevenin or circuit_native_norton, and native_circuit_execution records actual compile/probe calls. The former private full-host MNA residual is unavailable (available=false, values null); this does not mean a measured residual of zero.

Before running a customer-visible co-simulation, inspect why a region is or is not eligible:

tdse circuit explain-region `
  --case <case.json> `
  --region <region_id> `
  --out-json <region_explanation.json>

The explanation report lists selected components, boundary ports, rejected components, TDSE Runtime eligibility, host execution path, and suggested smaller or larger LTI regions. It is the preferred triage artifact when a selected network slice does not qualify for TDSE Runtime participation.

Region Qualification Remediation

explain-region and recommend-regions include remediation_hints for stable issue codes. Use the table below as the first response path before changing the model or opening a support bundle.

• REGION_*: check the declared region and its supported LTI components.
• UNKNOWN_*: fix missing component or node ids in the ModelSpace case.
• UNSUPPORTED_TDSE_REGION_*: keep host-only, non-LTI, switching, or unsupported-boundary models in TDSE Circuit host EMT, or split a supported LTI subregion. Independent voltage/current sources are eligible LTI members; a prescribed time-dependent waveform is not a reason to exclude them.
• MODELSPACE_TDSE_REGION_NATIVE_CIRCUIT_LOWERING_UNSUPPORTED: the selected LTI model family is not registered with the native TDSE Circuit lowerer. This is a model-promotion gap, not a restriction imposed by TDSE Runtime; add the model's exact Circuit representation before selecting the region.
• MODELSPACE_TDSE_REGION_NATIVE_CIRCUIT_LOWERING_FAILED: the model family is known, but its terminals, parameters, or referenced LTI dependencies do not form a valid native Circuit netlist.
• TDSE_REGION_*: repair non-finite values and positive passive parameters.
• INVALID_PORT_PRIMARY or NON_CONTIGUOUS_PORT_ORDER: use voltage or current primary and contiguous port order from zero.
• EVENT_TARGET_INSIDE_TDSE_REGION: move event-targeted components back to host EMT.

Gold labels are explicit:

• circuit_sdk_host_parity proves co-simulation equivalence for an eligible selected region.
• analytic proves physics for closed-form microcases.
• external_simulator proves physics or import behavior when an open tool such as ngspice, GNUATP, pandapower, PYPOWER, OpenDSS, or GridLAB-D is available.

Nonlinear and switching models execute in TDSE Circuit host EMT and remain TDSE Runtime-region ineligible. Fixed passive models, including RC snubbers, are LTI regardless of their use in a power-electronics circuit. Every supported ModelSpace LTI family is lowered through the same native TDSE Circuit netlist path used by host EMT and by tdse_circuit_workflow_handle_to_pack.

The product invariant is explicit: every active ModelSpace model registered with the lti capability must have an exact native TDSE Circuit lowering and must be eligible for a TDSE Runtime region when its parameters and referenced dependencies are valid. A missing lowering for such a model is an SDK or registry defect to fix; it is not a reason to declare the electrical model unsupported.

The promoted host EMT power-electronics scope is intentionally narrow: Shockley and ideal-piecewise diode microcases, ideal event switches, PWM event-table switching, H-bridge switching, buck-style primitive switching, and RC snubber behavior. Native simplified BJT and LEVEL=1 MOSFET models also execute through ModelSpace host lowering. Thyristor, IGBT, advanced power MOSFET models, VSC, MMC, HVDC, PLL, PWM controller, and converter-control families remain roadmap-only. See the exact model table in Element Reference.

For ModelSpace package format troubleshooting, use the ModelSpace promoted format, backend boundary, and evidence asset sections in 21-modelspace-v1.md.

Grid-scale performance campaigns are maintained in tdse_benchmark. The SDK keeps the functional Circuit product gold suite and native measurement providers used by those campaigns.

Run the product gold suite before publishing new claims:

python tools/circuit/run_circuit_sdk_gold_suite.py `
  --repo-root . `
  --tdse-exe build-vs2022-x64\Release\tdse.exe `
  --out-dir build-vs2022-x64\circuit_sdk_gold_suite `
  --out-json build-vs2022-x64\circuit_sdk_gold_suite.json

The gold-suite report separates analytic physics checks, open external simulator evidence, and TDSE Circuit host-vs-TDSE Runtime parity. Current ModelSpace support claims are exercised by the installed support matrix, package validation, native-import tests, and package-local EMT runner tests.

To compare two workflow evidence manifests from different runs or releases, use the report diff tool:

python tools/reports/circuit_sdk_workflow_diff.py `
  --left previous\manifest.json `
  --right current\manifest.json `
  --out-json workflow_diff.json

The diff report lists changed workflow fields, numeric metric deltas, quality gate changes, artifact hash changes, added or removed issue codes, and a machine-readable regression-risk summary.

User-Facing Diagnostics Map

TDSE Circuit workflow reports are designed so a customer can triage common failures without reading source code. Use these report fields first:

• diagnostic_index.unsupported_models: components or records that cannot run in the promoted host EMT or TDSE selected-region scope.
• diagnostic_index.approximation_decisions: imported records that were converted through an explicit approximation policy.
• diagnostic_index.tdse_region_blockers: selected-region issues that prevent TDSE Runtime participation.
• diagnostic_index.solver_failures: host EMT topology, event, convergence, or numerical failures.
• diagnostic_index.coupling_errors: Runtime ABI, pack hash, port order, sign convention, timestep, or boundary stamping failures.

Stable issue-code families map to troubleshooting locations:

• RAW_*, SEQ_*, SPICE_*, ATP_*, DSS_*, GLM_*, and EMTP_*: 21-modelspace-v1.md
• REGION_*, TDSE_REGION_*, and UNSUPPORTED_TDSE_REGION_*: 20-circuit-cosim-product-workflow.md#region-qualification-remediation
• HOST_SOLVER_*: 21-modelspace-v1.md
• COUPLING_*, PACK_*, and RUNTIME_*: this workflow report's TDSE Runtime participation and pack-binding sections
• ASSET_* and TOUCHSTONE_ASSET_*: 21-modelspace-v1.md
• DIAGNOSTICS_*: 07-troubleshooting.md#first-response-checklist

Every user-facing workflow command should emit a concise one-line CLI result and write the full machine-readable JSON report through --out-json. For release comparisons, use either:

tdse circuit workflow-diff `
  --left previous\manifest.json `
  --right current\manifest.json `
  --out-json workflow_diff.json

or the Python report tool shown above. Both diff outputs include a triage summary, next actions, changed fields, quality-gate changes, artifact hash changes, issue-code changes, troubleshooting links, and support-bundle paths.

For escalation, collect a redacted support bundle:

tdse circuit collect-diagnostics `
  --case <case.json> `
  --out <support.zip> `
  --out-json <support_manifest.json>

The support manifest records case identity, reports, hashes, command logs, SDK/Runtime/CLI versions, toolchain details, license-aware skips, and the redaction policy. Proprietary assets are excluded by default and represented by hashes unless an internal escalation explicitly allows inclusion.