essim/doc/user/analysis.md

# essim — how the analysis classifies things

essim looks at signal names and the way pins are wired to decide
whether a net is a **power rail**, a **ground**, a **diff pair**, a
**bus**, etc. This page summarises those rules in plain language so you
know what to expect when you run `analyze` (the `[a]` shortcut on the
dashboard) or when you read the numbers on the home screen.

Nothing here mutates anything you cannot fix manually: every
inference can be overridden with `set-signal-type`, and the rules are
re-run on every `load` so the picture stays consistent with the
netlists currently in memory.

## Signal type — Power / Gnd / Other

Every signal is classified into one of three buckets.

**Gnd** if the name matches one of:
`GND`, `GROUND`, `EARTH`, `SHIELD`, `CHASSIS` (or starts with any of
those followed by `_`). The name alone is enough — false positives
here are essentially nil.

**Power** is a two-stage decision:

1. The name has to suggest power — it contains `PWR`, `POWER`,
   `VCC`, `VDD`, `VEE`, `VSS`, `VBAT`, or starts with `VS_`, `VS3_`,
   `+5V`-style or `-12V`-style prefixes.
2. The wiring has to corroborate it. essim requires at least one of:
   - the signal lands on **4 or more pins** (a real rail goes to
     decouplers + ICs + connectors, so it almost always has many
     pads), or
   - the name contains a **voltage value** — `3V3`, `5V`, `12V`,
     `0V9`, `5V0`, etc. (any `V` next to a digit).

   *Hard floor*: a signal touching **fewer than 3 pins** is
   **never** Power, even if both 1 and the voltage motif are
   present. Physically you cannot have a rail on 1 or 2 pads.

**Other** in every other case.

This rule deliberately rejects things that look like power but
aren't: `PWR_OK` (status), `VSEL_0` (voltage select), `VDD_SENSE`
(sense feedback) — they all match step 1 but fail steps 2/3. The
analyze screen lists them under **Suspect Power** with the reason
attached (`fan-out 1, no voltage` etc.). Inspect, then either accept
the suspect status or force it back with `set-signal-type`.

## NC (no-connect) pins

A pin is shown as `(NC)` in the explore detail when it has no signal
attached. essim distinguishes three reasons:

- **Imported NC** — the netlist explicitly says the pin is
  unconnected (Mentor format: signal name `unconnected` or
  `unconnected (by TERM)`; Altium format: the pin is simply omitted
  from every signal block).
- **Dropped singleton** — after import, essim removes every signal
  that touches exactly one pin. A net with a single endpoint cannot
  carry signal anywhere, so the pin is detached and tagged. This
  catches both intentional sentinels and the per-IC `NC_*` labels
  that customers often put on dead pads.
- **Filled at connect** — when you `connect` two parts that don't
  agree on which pins exist (a Mentor part may have all pads, an
  Altium part only the wired ones), essim materialises the missing
  pads on the smaller side. They are unconnected *locally* on that
  module but are bridged to a real signal on the other module via
  the connection — so they do not count as orphans.

The dashboard's "NC" row summarises orphan counts (imported and
dropped only; filled-at-connect pins are excluded). The analyze
screen's "Types" tab adds a trailing line with the totals.

## Signal groups

essim groups signals that share an obvious structural pattern. They
are detected per module — a multi-card bus on the system is the BFS
union of the per-module groups it touches.

**Diff pair** — two signals named `STEM_P` and `STEM_N`
(case-insensitive, `_` required before the polarity letter). Both
halves must be present. Lone `_P` halves are flagged as orphans;
lone `_N` halves are *not* flagged (the `_N` suffix is overloaded
with active-low semantics — `RESET_N`, `BOOTMODE_N` — and flagging
them would flood the report).

**Diff bus** — at least two diff pairs whose stems share a common
prefix and only differ by a trailing index: `MDI0_P`/`MDI0_N`,
`MDI1_P`/`MDI1_N`, … → `MDI[0..3]_P/N`. Both `STEMN` and `STEM_N`
forms work (`MDI0`, `PCIE_TX_0`).

**Bus** — at least two signals with a common stem and a trailing
integer index. Two notations: `DATA[0]`, `DATA[1]`, … (bracketed)
or `ADDR_0`, `ADDR_1`, … (underscore — *strict*: an underscore is
required between the stem and the digits, so a name like
`GETH_01_VDD12` is *not* a bus).

**Anomalies** are emitted alongside groups:

- *Diff pair orphan*: a `_P` with no matching `_N`.
- *Diff bus gap*: e.g. `MDI[0..3]` has `MDI0`, `MDI1`, `MDI3` (`MDI2`
  missing).
- *Bus gap*: same idea on plain buses.

Internal Mentor net names that start with `$` (like `$N12345`) are
skipped from every group/bus detection.

## Issues reported by `analyze`

The Issues tab of the analyze screen aggregates everything that
deserves attention:

| Tag | What it means |
|---|---|
| `[pin-role]` | A connector pin is typed (via `set-connector-type`) as Power or Gnd but the actual signal landing on it disagrees. |
| `[net-mix]` | A net bridged across modules carries both Power and Gnd signals — almost always a topology mistake. |
| `[diff-pair-orphan]` | `STEM_P` with no `STEM_N` in the same module. |
| `[bus-gap]` | A bus is missing one or more index values inside its range. |
| `[diff-bus-gap]` | A diff bus is missing one or more lane indices. |

Zero issues = the module passes every structural check essim knows
how to run today.

## Overrides

Every classification is advisory. To force a different type:

- **Signal type**: from the `net` or `explore` screen, press Enter
  on a signal entry → a popup lets you pick `power` / `gnd` /
  `other`. Or type `set-signal-type <module> <signal> <type>` in the
  console (or from the palette).
- **Connector type**: `set-connector-type <module> <part> <connector-kind>`
  (also via the dashboard `[t]` shortcut). This drives the pin role
  expectations, which feed the `pin-role` check.

Overrides survive `save`/`restore` but are recomputed at every
`load` (i.e. the inference re-runs).