TDSE ModelSpace

TDSE ModelSpace is TDSE's portable representation and package format for models, studies, assets, results, evidence, provenance, integrity metadata, and domain-specific profiles.

It is included as a capability of TDSE Circuit. It is not a separate product, SKU, or solver. TDSE Circuit lowers supported circuit content and owns circuit execution. TDSE Runtime executes a compiled Runtime Pack; it does not read a ModelSpace package and does not learn ModelSpace or Circuit domain concepts.

What you receive

A complete TDSE installation containing TDSE Circuit includes:

• include/tdse/circuit/modelspace.h, the stable v1 C workflow API;
• ModelSpace v1 schemas under share/tdse/schemas;
• registries, issue codes, and import capabilities under share/tdse/modelspace/registries;
• the product, lowering, and capability contracts under share/tdse/modelspace;
• the installed tdse circuit command surface.

The capability matrix assigns each item one of four states:

• INSTALLED;
• SOURCE_TREE_REFERENCE;
• INTERNAL_ONLY;
• NOT_AVAILABLE.

This prevents a repository qualification helper from being mistaken for a shipped customer command.

Package shape

A directory package created by the installed tdse circuit package command currently has this minimal layout:

manifest.json
case/
  case.tdse-modelspace.json

The root manifest.json closes the package entries, including each payload's relative path, SHA-256, declared size, role, license class, and redaction policy. The installed command does not require a fixed set of additional directories; any extra payloads must be declared in that manifest.

The installed package actions operate on directory packages. The separate source-tree reference tooling exercises .tdsems transport; it is not an installed customer command. SHA-256 proves payload integrity when extraction or replay verifies the bytes; it does not prove author identity or provide a digital signature.

Installed command line

The customer CLI is tdse. ModelSpace-backed TDSE Circuit actions do not add a second executable or a tdse circuit modelspace namespace.

tdse circuit import --format psse_raw --input case.raw --out case.json \
  --approximation-policy forbid --out-json import-report.json

tdse circuit package --package-action validate \
  --manifest manifest.json --out-json validation.json

tdse circuit package --package-action create \
  --case case.json --out-dir package --out-json package-create.json

tdse circuit summarize --case case.json --out-json summary.json

tdse circuit support-matrix --out-json support.json

tdse circuit workflow-run --case case.json --out-dir results \
  --out-json workflow.json

tdse circuit workflow-run --case case.json --out-dir results-z \
  --matrix z --out-json workflow-z.json

Use --out-json for the action report. Unknown options and unsupported actions return a nonzero exit code. The exact command list is available from:

tdse circuit --help

The repository tool tools/modelspace/modelspace_cli.py exercises the portable directory and .tdsems contracts, conversion report migration, and package mutation tests. It is source-tree reference and qualification tooling, not an installed customer executable. Do not document its create/export behavior as an installed tdse command.

Public C API

Include:

#include <tdse/circuit/modelspace.h>

Initialize requests and results separately:

tdse_modelspace_circuit_workflow_request_init()
tdse_modelspace_circuit_workflow_result_init()

Call tdse_modelspace_circuit_execute_workflow(), then release owned buffers with tdse_modelspace_circuit_workflow_result_destroy().

The v1 API covers validation, summary, import, region selection and qualification, lowering, Runtime Pack construction, coupled EMT, diagnostics, and technical directory-package actions. Coupled EMT and pack construction accept TDSE_CIRCUIT_MATRIX_Y for Norton form or TDSE_CIRCUIT_MATRIX_Z for Thevenin form; initialization and compatibility normalization default to Z. Select Y explicitly for Norton form. Its structures use struct_size for forward-compatible extension. The original preview V0 schema macros remain source-compatible aliases; new code must use the V1 names. No public type exposes CircuitIR, ParsedNetlist, AnalysisPlan, or RegionPlanningIR.

Capability meanings

Run tdse circuit support-matrix to read the installed evidence-backed matrix. The matrix's semantic, implementation, qualification, and distribution states must all be considered; a promoted file contract is not automatically a solver or external qualification claim.

Conversion report

Independent Source Declarations

Native imported ideal voltage/current sources and fixed Thevenin equivalents are LTI region members. Their prescribed waveforms are independent excitation. The SDK declares their lti, host_only, and region capabilities at import; applications must not rewrite those fields to force qualification. The installed model registry carries the same eligibility contract.

User-authored ModelSpace JSON is loaded as supplied. Incorrect declarations in an old SDK import should be resolved by reimporting with the corrected SDK and rebuilding the region Pack, retaining the original import evidence. See Independent Sources.

Conversion Evidence

Conversion report v2 uses a closed vocabulary:

• EXACT
• SEMANTICALLY_EQUIVALENT
• APPROXIMATED
• PRESERVED_AS_OPAQUE
• UNSUPPORTED

Reports bind source format and version, object and parameter mappings, units, defaults, dropped information, approximations, vendor extensions, unsupported required semantics, hashes, deterministic identity, diagnostics, execution eligibility, and round-trip eligibility.

Execution is rejected when a required executable semantic is unsupported, when an approximation lacks explicit acknowledgement, or when source/output evidence is stale. PRESERVED_AS_OPAQUE is never executable. Legacy v1 conversion reports require explicit migration to v2.

Package safety and trust

package validate checks the manifest's text safety, complete JSON syntax, duplicate JSON keys, schema, entry count, relative forward-slash paths, duplicate declared paths, lowercase SHA-256 syntax, declared sizes, license metadata, and package-size limits. package extract and package replay additionally compare non-redacted payload files with their declared size and SHA-256 before copying or accepting them.

package create and package extract stage their complete result in a same-parent temporary directory, then publish it by rename. To keep that publication non-destructive, --out-dir must not already exist; use a new directory for each operation. A failed operation leaves no partial result at that output path.

The installed directory-package actions do not provide a ZIP transport, case-collision checks, or a symlink/hardlink policy. Treat those as source-tree tooling or future product work unless the installed capability report explicitly changes this boundary.

ModelSpace does not have an independent signing key or trust root. A package may be called signed only when the containing TDSE release has valid production release-signing and provenance evidence. Test keys and local fixtures are not production evidence.

Stable workflow

The repository portable-package reference keeps one authoritative tdse.modelspace.circuit_case.v1 case. Its domain and study documents are derived views: validation rejects mismatched topology, base values, model IDs or simulation settings. The backend identity hashes the entire case, including electrical parameters, units and asset references. Model identities and EMT support come from the native Circuit registry; preserved unknown electrical models remain required and block execution.

The reference run-study command requires an explicit native --tdse-exe and executes only that package's declared case. Missing executors, invalid packages and native execution failures return failure. Historical execution fixtures cannot substitute for a run. Use a new output directory for each attempt; existing runs and failure receipts are retained. These portable-profile checks belong to source-tree reference tooling; the installed technical directory package carries a single case directly.

modelspace_first_emt_overlap_v1 is the tested end-to-end reference workflow: validate a ModelSpace directory package, lower its supported EMT technical profile through TDSE Circuit, execute with TDSE Circuit ownership, produce result/evidence references, round-trip the package through .tdsems, and reject unsupported required models.

This workflow is locally tested. It does not prove an external commercial simulator bridge, a power-flow solver, production package signing, or TDSE Runtime CPU/CUDA/FPGA qualification.