# Nodes

`Node` (`node.h`/`node.cpp`) represents one circuit node - a point in the equation system an instance's terminals or internal nodes can bind to. It is small and deliberately non-copyable/non-movable (`Node` objects are referenced by pointer everywhere, e.g. from `Instance`'s terminal list, see [Device, Instance, and Model Base Classes](devbase.md)), and inherits its flag storage from `FlagBase<NodeFlags>` (see [Flags](flags.md)).

## `NodeFlags`

- **`PotentialNode`/`FlowNode`** (packed into the low bit, `NodeTypeMask`) select which pair of legacy SPICE tolerances apply to this node - a "potential" (across) quantity like voltage uses `vntol`/`fluxtol` for its unknown and `abstol`/`chgtol` for its equation's residual, while a "flow" (through) quantity like current uses the opposite pairing. This SPICE-tolerance-mode distinction is a carryover convention from classic SPICE's separate voltage/current tolerance settings.
- **`Shuntable`** marks a node eligible for the small conductance/resistance shunting some convergence aids apply.
- **`InternalDeviceNode`** marks a node created by a device for its own internal use (not a user-visible circuit node) - kept separate from ordinary nodes so elaboration can avoid picking one as a "representative" node when multiple nodes are collapsed together, and so residual-based convergence testing (see `coreopnr.cpp`/`coretrannr.cpp`) skips it: an internal device node's residual isn't a meaningful convergence signal on its own.
- **`Ground`** marks a ground node; ground nodes are ordered before all others when nodes are assigned unknown indices.

## Identity and lifetime

`unknownIndex()`/`setUnknownIndex()` hold the `UnknownIndex` (see [Namespace and Types](common.md)) this node is mapped to in the equation system once elaboration assigns one - a node doesn't know its own equation-system position until that happens.

`incRef()`/`decRef()` maintain a simple reference count (throwing `std::length_error` on overflow or on decrementing below zero, since both indicate a bookkeeping bug rather than a recoverable condition). Nodes - especially internal ones created on demand by a device, see `Instance::getInternalNode()` in [Device, Instance, and Model Base Classes](devbase.md) - can be shared by more than one instance; the reference count is what lets a node be released (and its underlying circuit-level bookkeeping cleaned up) only once nothing still points at it, via `Instance::unbindTerminals()`/`unbindInternalNodes()`.
