# Namespace and Types

`common.h` is the root header nearly every other file in the library includes, directly or transitively. It defines the `NAMESPACE` macro the whole codebase is wrapped in, and the narrow, purpose-specific integer typedefs used throughout as indices, counts, and identifiers - collected in one place so their widths can be tuned (or widened, as several of the comments below note) without hunting down every use site.

## `NAMESPACE`

`#define NAMESPACE sim` - every class and function in the library lives in `namespace sim`, reached everywhere via this macro (and referred to as `NAMESPACE` in the code's own comments and throughout these docs) rather than writing `sim` directly, so the codebase's namespace name is a single line to change.

## Narrow-width identifiers and indices

Most of these are `uint32_t` (or `int32_t`, where negative values carry meaning) rather than `size_t`. This is deliberate: they are counts and indices stored per-entry in structures that can exist in very large numbers - one [`Rpn::Entry`](rpnexpr.md) per token of every expression in a netlist, one [`Loc`](sourceloc.md) per entry, and so on - so halving their width from a 64-bit `size_t` to 32 bits directly halves the memory those structures need.

- **`IdentifierIndex`** - the raw integer behind [`Id`](identifier.md), whose ordinary/static index ranges split this type's space in two.
- **`SourceLineNumber`/`SourceColumnNumber`** - line/column counters for a [source location](sourceloc.md).
- **`FileStackIndex`/`FileStackFileIndex`** - identify a [`FileStack`](filestack.md) and, within it, one source, respectively; `FileStackFileIndex` being signed is what carries the negative-namespace convention documented there.
- **`LocationIndex`** - the index a compiled [`Rpn::Entry`](rpnexpr.md) stores into its expression's shared `Locations` table; that type's own reserved sentinel values (`badLocationIndex`/`maxLocationIndex`) are defined in `Rpn` itself, not here.
- **`IntegerValue`** - the concrete C++ type behind [`Value`](value.md)'s `Int`. The comment above it notes this is the one place to change to widen it to `int64_t`, since the rest of the codebase works through the `Int` alias rather than `IntegerValue` directly.
- **`RpnArity`/`RpnJumpOffset`** - function/pack argument counts and compiled jump-offset deltas (see [Expression Format](rpnexpr.md) and [Builtin Operators and Functions](rpnbuiltin.md)).
- **`RefCountIndex`** - a generic reference count.
- **`ParameterIndex`/`TerminalIndex`** - per-instance parameter and terminal indices.
- **`LocalStorageIndex`/`GlobalStorageIndex`** - offsets into per-instance and whole-circuit storage for simulation state (device states, residual/Jacobian contributions). `GlobalStorageIndex` is deliberately `size_t` rather than a narrower type, since it indexes across every instance in a circuit at once and needs the full addressable range.
- **`HistoryDepthIndex`/`HistoryDepthIndexDelta`** - an index into a per-quantity history (e.g. transient integration's past-value record) and its signed delta counterpart, derived via `std::make_signed<HistoryDepthIndex>::type` rather than declared as a second, independent typedef - so the two types can't drift out of sync if `HistoryDepthIndex`'s width ever changes.
- **`EquationIndex`/`UnknownIndex`/`NodeIndex`** - equation-system indices; `NodeIndex` is a type alias for `UnknownIndex` (a circuit node is one particular kind of unknown). The comment above them flags that switching the sparse linear solver (KLU) to 64-bit indexing is only a matter of widening these typedefs (and `MatrixEntryIndex` below).
- **`MatrixEntryIndex`** - a sparse matrix entry index, signed because KLU requires it, subject to the same 32-/64-bit tradeoff as the equation/unknown indices above.
- **`Complex`** - `std::complex<double>`, the numeric type used throughout the AC/small-signal solvers.

## Pool sizing constants

`stringPoolBlockSize`/`stringPoolGrowthFactor`/`stringPoolRetries` are the shared defaults every [`CStringPool`](pool.md) in the codebase is constructed with - `Id`'s string pools ([Identifiers](identifier.md)) and `FileStack`'s ([File Stack](filestack.md)) both use them. Centralizing the three numbers here means every string pool in the process grows and retries by the same policy, rather than each call site repeating (and potentially disagreeing on) the same tuning constants.

## `timeRelativeTolerance`

`std::numeric_limits<double>::epsilon()*8` - a shared relative-tolerance constant for comparing time values, used where an exact floating-point equality check would be too strict (e.g. transient analysis in `coretran.cpp`, circuit elaboration setup in `elsetup.h`).

## `DBGCHECK`

`DBGCHECK(cond, msg)` throws `std::runtime_error(msg)` if `cond` is true, but only in a `SIMDEBUG` build (or when `FORCE_DBGCHECK` is defined - a header-local override, commented out by default, for temporarily enabling the checks in an otherwise release build without a full debug rebuild); in an ordinary build the macro expands to nothing, and `cond` is never even evaluated. This is the project's convention for asserting an internal invariant - a condition that should be structurally impossible given the surrounding code, such as [`Evaluator`](rpneval.md)'s end-of-evaluation stack-depth check, [`FileStack`](filestack.md)'s out-of-range id lookup, or [`DenseMatrix`](densematrix.md)'s size/shape preconditions - without paying for the check, or for constructing its message string, in a release build. Because the whole macro disappears outside `SIMDEBUG`/`FORCE_DBGCHECK`, `cond` needs to be an expression with no side effects the surrounding code relies on.

## Outside the namespace: `SIM_SIZE_T_MAX` and `NoiseType`

`SIM_SIZE_T_MAX` (`std::numeric_limits<std::size_t>::max()`, used as a sentinel/limit value in a handful of device implementations, e.g. `tdnzohflicker.cpp`) and `NoiseType` are both declared *after* the closing brace of `namespace sim` - in the global namespace, unlike everything above them. `NoiseType` is a C++ `enum class` whose values are initialized directly from OSDI's C preprocessor macros (`NOISE_TYPE_WHITE`, `NOISE_TYPE_FLICKER`, `NOISE_TYPE_TABLE`, pulled in via `#include "osdi.h"` right above it) - the comment "must match OSDI macros" is the reason it exists at all: OSDI is a C ABI, so its noise-type constants are plain macros, and `NoiseType` is the simulator's own typed mirror of them, kept next to that `#include` rather than tucked inside `namespace sim`.
