File Formats

circuitRF stores a project as a folder of small, human-readable, text files — diffable and version-control friendly. The core idea: the **schematic** (what you draw) is the source of truth; the **netlist** (what the engine runs) is derived from it.

Schematic vs. netlist

Two complementary artifacts, related one way at the engine boundary:

  .csch  (schematic: placement, wires, labels, canvas objects, view state)
     │  net extraction  — headless, deterministic
     ▼
  design model  ≡  what a .cnl represents
     │
     ▼
  engine → DataSet (results)

.csch — the schematic: where each component sits, how wires route, net labels, junction dots, canvas objects, zoom/pan. It carries no elaborated netlist, matrices, or results. This is what you edit and save.
.cnl — the netlist, and only the netlist: components, parameters, nets, variables, analyses, measurements. A hand-authored .cnl and one produced by extracting a schematic are the same kind of artifact — a pure netlist the engine consumes. See the Netlist format chapter.

A hand-authored .cnl with no .csch is fine — it simulates, it just has no drawing to edit visually until you draw one.

The file family at a glance

Extension	What it is
`.csch`	Schematic view — placement, wires, labels, canvas objects, analyses, measurements.
`.csym`	Symbol view — a cell's glyph: drawing primitives + pins mapped to ports. See the Symbol Editor.
`.ccell`	Cell manifest — the cell's declared parameters + defaults, which view is primary per type, and the `IsTestBench` flag.
`.clay`	Layout view — the cell's physical geometry: shapes on layers, instances, PCell placements, bitmaps, the display unit and the snap grid. A real, first-class view; see The Layout Editor.
`.cdd`	Data Display config — placed plots/tables/contours, their binding to a run's results, markers, view state.
`.cnl`	Netlist — the engine's input (derived from a schematic, or hand-authored).
`.cws`	Workspace config — the top-level "what am I working on" document. References libraries, known files, the default technology and assembly rules, and any other projects or kits this one uses.
`.cwsuser`	Your own view of a workspace — the panel arrangement, which tabs were open, which tree categories you expanded, and the colour theme. Sits beside the `.cws`. Optional, personal, and safe to delete; see Your own view of a workspace.
`.clib`	Library manifest — name, version, metadata (cells are discovered by scanning, not listed here).
`.ccolor`	Color theme — a named light+dark palette for rendering.
`.ctech`	Technology — the layer table (GDSII layer/datatype pairs, colours, purposes), the substrate stackup, the DRC rules, and the default display unit and snap grid. Shared at workspace level: every layout in the workspace resolves against one of these. See Technology.
`.cem`	EM setup — one electromagnetic run's configuration: which layout, the stackup mapping, the ports and their reference impedances, the mesh settings, the frequency plan and the de-embedding choice. See EM Setup.
`.charm`	harmonicaRF document — the DUT, the source and load termination planes at every harmonic, the package, the display configuration and the markers. See harmonicaRF.
`.wBond`	wBond design — bondwire geometry: the wires, their arrays and profiles, the substrate and the solver settings. Self-contained and shareable. See wBond.
`.crail`	railRF document — the rails, their sources, loads and reference, the parts and the part library they resolve against, the target and the band. See railRF.
`.csmith`	Smith Chart document — a generator impedance over frequency and an ordered cascade of two-pin elements, plus what the chart is normalized to, the overlays, the markers and the constant-Q setting. Numbers are in base SI. See Smith Chart.

These are circuitRF's own formats. The interchange formats it reads and writes — GDSII, DXF, Gerber plus Excellon drill, and .kicad_pcb board files — are not in this family and are not documents you open: they are imported into cells, or exported from them. See Interchange for what each carries and what it cannot.

Which of these are documents you open

.csch, .csym, .clay, .cdd, .ctech, .cem, .charm, .wBond, .crail and .csmith each open as a tab in the workspace. .ccell, .clib, .cws and .cwsuser are manifests the application maintains for you — though double-clicking either half of a workspace opens the whole workspace. .cnl is the engine's input and is normally derived rather than edited.

Workspace › Library › Cell

The conceptual hierarchy maps to folders of the small files above — never one monolithic blob.

Cell = a folder of views

<CellName>/
   .ccell              manifest: parameters + defaults + primary view per type + IsTestBench
   schematic/  *.csch  schematic views
   symbol/     *.csym  symbol views
   layout/     *.clay  layout views

A cell need not have every view. A view sub-folder with exactly one file makes that file primary by default; .ccell records the primary when there are several. A placed component references its cell by relative path and resolves its glyph through the cell's primary symbol — so a broken path shows a "Not Found" glyph, and a resolved cell with a missing primary symbol shows a plain-rectangle stand-in. The cell folder is the unit you copy to share or reuse a cell.

Library = a folder of cells

<LibraryName>/
   .clib               manifest: name, version, metadata
   <CellA>/  …
   <CellB>/  …

Membership is filesystem-is-truth — the Project Tree discovers cells by scanning, so the .clib stays lightweight (no cell index). The standard component libraries ship in this shape. File → Add Library points the workspace at an external library folder.

Workspace = the project that references the above

A workspace is a folder (its name = the folder name) containing a .cws file. Membership is the filesystem; the .cws records configuration only: referenced libraries, "Known Files" bookmarks, the default technology and assembly rules, and the other projects and kits this one uses. It references, never embeds — the same cell or library can be used by multiple workspaces.

Beside it sits a second, optional file: the .cwsuser, which is yours rather than the project's.

Your own view of a workspace

The .cwsuser holds the things that describe your afternoon rather than the design: where you put the panels, which tabs were open and which one was in front, which categories of the Project Tree you had expanded, and which colour theme you were using. Nothing in it affects a simulation, a schematic or a layout.

Three things follow, and all three are deliberate:

It is optional, always. A workspace with no .cwsuser opens perfectly normally, on the default arrangement — exactly like a brand-new one. Nothing is reported and nothing is wrong. This is the usual state of a workspace somebody hands you.
It does not travel. It is left out of a workspace archive, because your monitor layout is of no use to whoever you send the archive to. It is carried by File ▸ Save Workspace As, because that copy is still yours, on the same machine, and the window switches straight to it.
Deleting it is a repair, not a risk. If your panels have ended up somewhere unusable, close the workspace, delete the .cwsuser, and open the workspace again. You get the default arrangement back and lose nothing but the arrangement.

Double-clicking either the .cws or the .cwsuser opens the whole workspace — they are two halves of one thing. A .cwsuser on its own, with no .cws beside it, is not a workspace, and circuitRF says so rather than opening an empty window.

What makes a TestBench

A TestBench is not a separate file type — it is a cell whose schematic carries analyses and measurements, making it runnable. "TestBench" is a role, marked by the IsTestBench flag in the cell's .ccell, which the Project Tree uses to show it as runnable. A testbench is authored, saved, and version-controlled exactly like any other cell.

Port numbers are 1-based for you, positional in the netlist

Everything you see — symbol pins, dialogs, error messages — numbers ports from 1 (a VNA has port 1 and port 2, never port 0). The .cnl doesn't list port numbers at all: a component line names its nets in terminal order, and the engine infers the port from position. Net extraction emits nets in the symbol's terminal order — the one seam where the two conventions meet, and a tested one.

The generated `netlist.cnl`

The GUI does not keep per-cell .cnl files. When you simulate a TestBench, extraction writes a single netlist.cnl to the workspace root and the engine runs it. It is:

Overwritten every run — one scratch netlist for the latest simulation, whichever testbench produced it.
Stamped with provenance — a header comment records which TestBench produced it and when (e.g. ; netlist.cnl — generated from TestBench "PA_loadpull" at 2026-06-06T14:22:31Z).
Human-inspectable and re-runnable — it's exactly what the engine saw, and you can re-run it headless from the command line.

It is a generated scratch artifact, not part of the saved project — the .csch is the source of truth.

Shared rules

Text, JSON-friendly, human-diffable, with stable key ordering for clean diffs.
Paths, not payloads — bitmaps store a file path, never pixels; a missing image shows a placeholder box, never a crash. Relative paths (under the project) are preferred so a moved or shared project keeps its images; absolute paths are accepted.
Enums serialize as names, so files stay readable and stable across versions.
Runtime identity is never persisted — internal object IDs are regenerated on load and carry no meaning across sessions.
Alpha policy — a format_version is written and rejected on mismatch; there is no silent migration. (circuitRF is pre-release; formats may break and regenerate until near release.)

See also: Netlist format · Grid & Connectivity · Symbol Editor. Full design: docs/design/project-file-formats.md.