RAW Import

Use this chapter when your starting artifact is a PSS/E RAW case and your first question is not "how does the adapter work internally?" but "how do I get from this file to a usable netlist or pack?"

RAW import lives inside Adapter Circuit. Keep this page as the quick bridge: enough to get oriented, then move into the detailed chapter only when you need the full conversion behavior or API details.

Treat this chapter as the RAW-specific branch of Adapter Circuit, not as a standalone main path. Most readers should understand the overall Adapter Circuit workflow first and then return here only if RAW conversion is their real starting artifact.

Start Here

Use this table to pick the shortest workable route:

If you need to...	Start here	Then continue with
convert a RAW file into a circuit netlist	tdse adapter circuit raw-to-netlist	CLI Reference
convert RAW and then build a pack	Adapter Circuit	Builder and Data Contracts
convert RAW directly into a pack with one public workflow	Adapter Circuit	Examples Guide
call RAW import from C or C++	Adapter Circuit	Examples Guide
validate why RAW conversion failed	Troubleshooting	CLI Reference

If your real goal is a qualified .pack and you do not need to inspect the intermediate netlist, prefer the workflow path first. Drop to raw-to-netlist when you need to review the converted artifact, archive import reports, or isolate a mismatch before Builder.

Shortest CLI Path

For most users, the first successful path is:

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

What you should expect from this command:

• a circuit-compatible netlist file
• a JSON report with conversion counts and validation detail
• a CLI JSON envelope that scripts can archive

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

What RAW Import Covers

RAW import is responsible for translating grid-domain source data into circuit-domain artifacts that the rest of Adapter Circuit can process. In practice that usually means:

• buses, branches, loads, generators, and transformers are mapped into a netlist form
• base-frequency and compatibility checks are recorded in the import report
• the generated netlist becomes the new handoff point for matrix, series, probe, and Builder workflows

The detailed conversion behavior, supported model notes, and API-level usage live in Adapter Circuit. Keep this chapter as the quick bridge, not the long reference.

Support Boundary And Validation Expectations

RAW import is broad, but it is still a conversion path, not a promise of perfect one-to-one replay of every original study environment.

Use this table to decide how much validation you need after import:

Area	What to expect	What to validate next
buses and branch topology	usually direct structural mapping into a circuit netlist	node naming, connectivity, and port selection
generators and source injections	converted into circuit-domain equivalents used by Adapter	source polarity, port response, and expected drive conditions
transformers	behavior depends on the selected transformer model	tap behavior, shunt/series interpretation, and DC/low-frequency response
loads	behavior depends on the chosen load model (shunt, series, zip_split)	whether the chosen approximation matches the study intent
base-frequency semantics	validated and recorded in the import report	that the report matches your expected system base
unsupported or unusual records	may appear as warnings, omitted features, or validation findings	import report first, then matrix/probe comparison before Builder

Practical rule: treat the generated netlist as a new engineering handoff point. Do not send it straight to production Builder flows until one of the following is true:

• a matrix or probe run looks physically right
• the conversion report shows only expected approximations
• the resulting pack clears the normal qualification checks from Adapter Circuit

Recommended Next Step

Once RAW conversion works:

1. inspect the generated report and netlist when you need conversion visibility
2. if your goal is a short supported pack path, move to the workflow API; otherwise run matrix on the converted netlist
3. move to production Builder or pack handoff only after the adapter-side output or workflow qualification looks correct