RAW Import

This is the canonical customer workflow for importing supported PSS/E RAW data into TDSE Circuit. It records conversion policy, diagnostics, approximations, and the handoff to Circuit authoring or ModelSpace.

RAW Import

Not every circuit starts as a SPICE netlist. In power systems, the starting point is often a PSS/E RAW case file - a grid description with buses, generators, branches, loads, and transformers. RAW Import converts these files into circuit netlists that Circuit SDK can compile, then validates them against the original case data.

The conversion process reads the RAW file, builds an equivalent circuit model for each power-system element, stitches them together, and writes out a SPICE netlist. Base- frequency validation runs automatically - the generated netlist is solved at the nominal system frequency and the resulting bus voltages and branch flows are compared against the original RAW data.

RAW import lives inside Circuit SDK. It is not a standalone workflow - use it as the entry point when your starting artifact is a PSS/E case, then continue through the normal compile-and-compute pipeline described in this chapter.

CLI

For most users, the first successful path is:

tdse circuit raw-to-netlist \
  --raw-kind file --raw case.raw \
  --out-netlist ./case_from_raw.cir \
  --out-report-json ./raw_report.json \
  --json-out -

If that command succeeds, the usual next step is to run tdse circuit matrix on the generated netlist and then hand the result to Builder.

The key flags:

Flag	Meaning	Default
--raw-kind file|text|stdin	How the RAW input is provided	(required)
--raw <path_or_text>	RAW source	(required)
--out-netlist <path|->	Output netlist path	-
--out-report-json <path|->	Output validation report	-
--unit pu|si	Per-unit or SI output	pu
--transformer-model series_only|ideal_tap_series|tap_split_shunt	Equivalent circuit model	ideal_tap_series
--load-model shunt|series|zip_split	Load equivalent model	shunt
--include-generator-sources 0|1	Include generator Norton equivalents	1
--include-fallback-source 0|1	Add fallback source for unexcited buses	1
--include-tran 0|1	Emit .tran directive	1
--include-options 0|1	Emit .options directive	1
--dt <sec>	Time step for .tran directive	5e-5
--tstop <sec>	Stop time for .tran directive	0.4
--freq-hz|--nominal-frequency-hz <hz>	Base frequency in Hz	60
--global-bus-shunt-c-f <farad>	Global bus shunt capacitance	0
--include-inactive-bus 0|1	Include inactive buses in validation	0
--ac-adjust-from-sine 0|1	Adjust AC phasors from sine reference	1
--mag-tol-pu <x>	Magnitude tolerance for validation	0.03
--ang-tol-deg <x>	Angle tolerance in degrees	3.0
--complex-tol-pu <x>	Complex tolerance for validation	0.08
--report-top-k <N>	Top-K worst-case buses in the report	20

C API

The C API uses the standard size-then-fill pattern. Call once with NULL output buffers to get sizes (returns TDSE_STATUS_BUFFER_TOO_SMALL), allocate, then call again:

#include <tdse/circuit.h>

int convert_raw_file(const char* raw_path) {
    tdse_circuit_raw_options_t raw_opt =
        tdse_circuit_raw_options_init();
    raw_opt.import_options.load_model = TDSE_CIRCUIT_RAW_LOAD_SHUNT;
    raw_opt.import_options.transformer_model =
        TDSE_CIRCUIT_RAW_TRANSFORMER_IDEAL_TAP_SERIES;

    tdse_circuit_raw_request_t req =
        tdse_circuit_raw_request_init();
    req.source_kind = TDSE_CIRCUIT_RAW_SOURCE_FILE;
    req.raw_path = raw_path;
    req.options = &raw_opt;
    req.report_mode = TDSE_CIRCUIT_REPORT_BUFFER;

    tdse_circuit_raw_result_t result =
        tdse_circuit_raw_result_init();
    int rc = tdse_circuit_raw_to_netlist(&req, &result);

    if (rc == TDSE_STATUS_BUFFER_TOO_SMALL) {
        char* netlist_buf = malloc(result.required_netlist_count);
        char* report_buf  = malloc(result.required_report_count);
        req.out_netlist = netlist_buf;
        req.out_netlist_len = result.required_netlist_count;
        req.out_report_json = report_buf;
        req.out_report_json_len = result.required_report_count;

        rc = tdse_circuit_raw_to_netlist(&req, &result);
        // ... use netlist_buf and report_buf ...
        free(netlist_buf);
        free(report_buf);
    }
    return rc;
}

For in-memory RAW text, set source_kind = TDSE_CIRCUIT_RAW_SOURCE_TEXT and pass raw_text / raw_text_len. The rest of the pattern is identical.

For the full RAW-to-pack pipeline in a single call, use tdse_circuit_workflow_raw_to_pack() which chains RAW import, compilation, frequency sweep (or adaptive planning), and Builder handoff.

Transformer Models

Transformers in PSS/E RAW files have tap ratios and phase shifts. The model you choose determines how these are represented in the circuit netlist:

Model	Enum constant	Description
series_only	RAW_TRANSFORMER_SERIES_ONLY	Only series impedance, ignores tap ratio. Simplest
ideal_tap_series	RAW_TRANSFORMER_IDEAL_TAP_SERIES	Ideal tap in series with leakage impedance
tap_split_shunt	RAW_TRANSFORMER_TAP_SPLIT_SHUNT	Tap split into series + shunt. Most physical, more nodes

Two-winding transformers are converted directly. Three-winding transformers are decomposed into three two-winding equivalents connected at a star point.

Load Models

RAW import converts PSS/E load records into circuit-domain equivalents. Three models are available:

SHUNT (default): Each load becomes an admittance from the load bus to ground, computed from the load's MW/MVAR at the system base voltage. Use when you care about impedance loading effects and are not modeling load dynamics separately.

SERIES: Each load becomes a series RL impedance to ground that preserves real and reactive power draw at nominal voltage. Use for transient or fault studies where the shunt approximation is too coarse.

ZIP_SPLIT: The load is decomposed into constant-impedance (Z), constant-current (I), and constant-power (P) components using ZIP coefficients from the RAW data. Use when the case contains ZIP coefficients and you need faithful reproduction across varying bus voltages.

Model	Fidelity	Complexity	Best for
SHUNT	Low	Minimal	Quick screening, topology checks
SERIES	Medium	Low	Transient and fault studies
ZIP_SPLIT	High	Medium	Voltage-sensitive studies with ZIP data

Validation Report

After conversion, the import result includes a raw_import_report_t with counts of every entity found and converted:

Field	Meaning
bus_count	Total buses in the RAW case
branch_count	Total branches (lines + transformers)
generator_count	Generator/machine records
load_count	Load records found
fixed_shunt_count	Fixed shunt devices
switched_shunt_count	Switched shunt devices
two_winding_transformer_count	Two-winding transformers converted
three_winding_transformer_count	Three-winding transformers (decomposed into 2W)
unsupported_record_count	Records that could not be converted
validation_warning_count	Validation warnings generated
base_freq_hz	System base frequency read from the case
system_mva_base	System MVA base from the case

The JSON report (when report_mode = BUFFER) contains the same counts plus per-bus and per-branch detail. Use it to audit what was converted before handing the netlist to Builder.

Error Recovery

RAW import returns the unified tdse_status_t values. Decode them with tdse_circuit_status_message() or tdse_status_message().

Status	Cause	Fix
TDSE_STATUS_INVALID_ARG	Missing struct_size, NULL file path, or bad source kind	Initialize every versioned struct and verify source kind
TDSE_STATUS_PARSE	Malformed RAW file or unexpected section	Check the supported PSS/E RAW format and reduce the case
TDSE_STATUS_IO	File not found or unreadable	Verify path and permissions
TDSE_STATUS_UNSUPPORTED	RAW feature not supported by this SDK version	Inspect unsupported-record counts and the report
TDSE_STATUS_BUFFER_TOO_SMALL	Size query or caller buffer too small	Allocate the reported sizes and retry
TDSE_STATUS_INTERNAL	Unexpected internal error	Report with the case file and command line
TDSE_STATUS_VALIDATION_FAILED	Generated netlist failed validation	Inspect the validation report and smallest failing subset

Thread-local detail text is available via tdse_circuit_raw_get_last_error_text().

Support Boundary

RAW import is a conversion path, not a promise of perfect one-to-one replay of every original study environment. Treat the generated netlist as a new engineering handoff point - validate it before sending it to production Builder flows:

Area	What to expect	What to validate next
buses and branch topology	Direct structural mapping into a circuit netlist	Node naming, connectivity, port selection
generators and source injections	Converted to circuit-domain equivalents	Source polarity, port response, drive conditions
transformers	Depends on model selection	Tap behavior, shunt/series interpretation
loads	Depends on model (shunt, series, zip_split)	Chosen approximation matches study intent
base-frequency semantics	Validated and recorded in the report	Report matches expected system base
unsupported records	Appear as warnings or omissions	Import report first, then matrix/probe comparison