# essim — user guide

A short, task-oriented introduction to using essim. For an exhaustive
reference of every command, see [`commands.md`](commands.md) (auto-
generated from the binary). For scripting and `$variable` expansion,
see [`scripting.md`](scripting.md).

## What essim is

A digital twin for the inter-card connections inside a system. You
**load** modules (cards/boards) from netlist or pinout files, **tag**
their connectors with a `connector_type`, **connect** them across
modules, and **verify** that the signal types match the connector role
expectations. You can save a snapshot, restore it later, or replay a
session as a script.

```
┌──────────┐    ┌──────────┐
│ Module A │    │ Module B │
│  Part J1 │◀──▶│  Part P1 │   <— a Connection (built by `connect`)
│   pins   │    │   pins   │
└──────────┘    └──────────┘
```

## First session

After launching `./build/essim`, the prompt accepts a sequence of
commands. The most common bring-up looks like this:

```text
> new
> load backplane /path/to/netlists/backplane.NET altium
> load payload1  /path/to/netlists/payload.qcv mentor
> set-type backplane J20 vpx-3u-bkp-p0
> set-type payload1  P0  vpx-3u-payload-p0
> connect backplane J20 payload1 P0
> verify
> save my-system.essim
```

Things to try at any time:

| Action | How |
|---|---|
| List every command | `help` |
| Help on one command | `help <name>` |
| Scroll back through output | `PageUp` / `PageDown`, `Home`, `End` |
| Re-run a previous command | ↑ / ↓ (also `history` is on disk) |
| Tab-complete a command name | `set‹Tab›` → `set-type` etc. |
| Cancel a multi-step prompt | `Esc` |
| Leave essim | `quit` (or `exit`) |

## Interactive screens

Some commands open a dedicated full-screen layout when invoked with no
arguments (the help listing tags these `[interactive]`). They all
share the same conventions:

- A title bar `essim → <name> — <short description>` is shown at the
  top.
- `Tab` cycles focus between fields; the active field's label flips to
  reverse video so it's obvious where the next keystroke goes.
- `Esc` leaves the screen and returns to the main prompt.
- The screens are user-facing only — they are **never** allowed inside
  a sourced script. A sourced script must use the inline form of these
  commands instead.

Today's interactive screens: `connect`, `search`, `set-type`,
`explore`, `net`. See [`commands.md`](commands.md) for each.

## Saving, restoring, replaying

Three orthogonal mechanisms persist your work:

- `save <file>` writes a **binary-tab-delimited snapshot** of the whole
  system (modules, parts, signals, connector types, signal-type
  overrides, connections, pin maps). `restore <file>` replaces the
  current system with the snapshot.
- `script-save <file>` writes a **replay-ready text script** of every
  command issued since the last `new`. The interactive bits and the
  noisy commands (`clear`, `help`, …) are filtered out automatically.
- `source <file>` reads a script line by line. Comments start with
  `#`, blank lines are skipped, leading `~/` in paths is expanded, and
  while a script is running a centred "Computing…" modal shows the
  progress (one line per ~30 ms tick).

A typical workflow: experiment in the shell, `script-save` the part
that works, hand-edit the script to introduce `$variables` (see
[`scripting.md`](scripting.md)), then `source` it whenever you start
fresh.

## Where to look next

- [`commands.md`](commands.md) — exhaustive command reference,
  regenerated from the binary on every `cmake --build build --target doc`.
- [`analysis.md`](analysis.md) — how essim classifies signals
  (Power / Gnd / Other), how it detects buses and diff pairs, what
  the `analyze` screen actually reports and why.
- [`scripting.md`](scripting.md) — `set` / `$var` / `${var}`, `source`
  semantics, the script-save denylist.
- [`DESIGN.md`](../../DESIGN.md) — implementation notes, useful if
  you want to add a command or a screen.
- [`../api/`](../api/) — auto-generated C++ API reference.