Add Xyce simulator support behind SimulatorInterface abstraction

Extract shared state and logic from NgspiceInterface into a
SimulatorInterface ABC, add XyceInterface for explicit-stepping
co-simulation via Xyce's C API, and make netlist generation
simulator-aware (YDAC devices, .TRAN, .PRINT TRAN for Xyce).

AnalogBlock gains a simulator="ngspice"|"xyce" parameter;
MixedSignalBridge gains simulator_lib= (ngspice_lib deprecated).
All existing tests pass unchanged. Remove deprecated sync_period_ns.

Author: mguthaus

CLAUDE.md

@@ -0,0 +1,92 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Build & Test Commands
+
+```bash
+pip install -e ".[dev]"        # Install for development
+pytest tests/ -v               # Run all unit tests
+pytest tests/test_pins.py -v   # Run a single test file
+pytest tests/ -k "test_hysteresis"  # Run tests matching pattern
+mypy src/cocotbext/ams/ --ignore-missing-imports  # Type check
+ruff check src/ tests/         # Lint
+```
+
+Integration examples (require ngspice + iverilog):
+```bash
+cd examples/sar_adc && make SIM=icarus
+cd examples/pll && make SIM=icarus
+```
+
+## Architecture
+
+cocotbext-ams bridges cocotb's digital simulation with an analog SPICE simulator (ngspice or Xyce) via shared library APIs (ctypes). It uses **event-driven synchronization** rather than fixed-interval lock-step.
+
+### Supported Simulators
+
+- **ngspice** (default): Callback-driven via libngspice. `GetSyncData` callback triggers sync points.
+- **Xyce**: Explicit-stepping via `xyce_simulateUntil()`. The stepping loop triggers sync points at each interval.
+
+Both run inside a `@bridge` thread and periodically call `_on_sync_point()` (a `@resume` function). The difference is only what triggers that call — ngspice's internal callback vs Xyce's explicit loop.
+
+### Module Dependency Flow
+
+```
+_bridge.py (MixedSignalBridge, AnalogBlock)
+  ├── _simulator.py (SimulatorInterface — ABC with shared state)
+  │     ├── _ngspice.py (NgspiceInterface — ctypes wrapper for libngspice)
+  │     └── _xyce.py    (XyceInterface — ctypes wrapper for Xyce C API)
+  ├── _pins.py    (DigitalPin — D/A and A/D conversion with hysteresis)
+  ├── _netlist.py (generate_netlist — simulator-aware SPICE deck augmentation)
+  └── _vcd.py     (AnalogVcdWriter — real+digital VCD output)
+```
+
+### Simulator Abstraction (`_simulator.py`)
+
+`SimulatorInterface` ABC holds all shared state (`_vsrc_values`, `_node_voltages`, `_spice_time`, `_next_sync_time`, `_prev_digital_values`, `_output_pin_configs`, `_vcd_writer`, etc.) and implements `_check_crossings()` and `_write_vcd()`. Subclasses implement `load_circuit()`, `run_simulation()`, `get_node_voltage()`, `set_vsrc()`, `halt()`, `reset()`, `is_running()`.
+
+### Two Asymmetric Data Paths
+
+**Digital → Analog:** `ValueChange` monitor coroutines update `_vsrc_values` dict instantly. For ngspice, it reads these via `GetVSRCData` callback. For Xyce, they are pushed via `xyce_updateTimeVoltagePairs()` at each step.
+
+**Analog → Digital:** Voltages are read from the simulator and `_check_crossings()` detects threshold crossings. When a crossing is detected, the sync mechanism forces new digital values onto Verilog and advances digital time.
+
+A fallback `max_sync_interval_ns` (default 100ns) ensures periodic sync even without crossings.
+
+### Thread Model
+
+- The simulator runs a blocking simulation in a `@bridge` thread
+- **ngspice:** `GetVSRCData` / `SendData` / `GetSyncData` callbacks fire from the ngspice thread; `GetSyncData` calls `@resume` to sync
+- **Xyce:** The explicit stepping loop calls `@resume` at each sync interval
+- `_vsrc_values` dict is safe via GIL (cocotb writes, simulator reads)
+- `_node_voltages` is only read at sync points when the simulator is paused
+
+### Netlist Augmentation
+
+`_netlist.py` wraps the user's `.subckt` with simulator-specific syntax:
+
+| Feature | ngspice | Xyce |
+|---------|---------|------|
+| Runtime sources | `v_name node 0 dc 0 external` | `YDAC v_name DAC node 0` |
+| Output save | `.save v(node)` | `.PRINT TRAN v(node)` |
+| Tran command | `.tran step stop uic` | `.TRAN step stop` |
+| Include | `.include path` | `.INCLUDE path` |
+| End marker | `.end` | `.END` |
+
+The `simulator=` parameter on `generate_netlist()` dispatches to the right generator.
+
+### Vector Name Normalization
+
+ngspice reports names as `"tran1.v(d0)"`, `"v(d0)"`, or `"d0"`. All forms are stored in `_node_voltages` so lookups work with any variant. Xyce stores both the expression form (`v(d0)`) and bare name (`d0`).
+
+## Testing Conventions
+
+- Unit tests in `tests/` do NOT require ngspice or Xyce — they test pins, netlist generation, and VCD writing in isolation.
+- Tests that need `NgspiceInterface` create mock instances via `__new__` and manually set required attributes (`_node_voltages`, `_crossing_detected`, `_prev_digital_values`, `_output_pin_configs`, `_spice_time`). These attributes now come from `SimulatorInterface.__init__()`.
+- Xyce netlist generation is tested via `test_generate_xyce_netlist()` without requiring Xyce to be installed.
+- Integration tests live in `examples/` and require ngspice + iverilog. Xyce integration testing requires Xyce installed.
+
+## Git Commit Rules
+
+- Never add "Co-Authored-By: Claude" or any Claude attribution to commit messages.

README.md

@@ -5,7 +5,7 @@
 <h1 align="center">cocotbext-ams</h1>
 
 <p align="center">
-  <strong>An ngspice bridge for <a href="https://github.com/cocotb/cocotb">cocotb</a> — open-source mixed-signal co-simulation</strong>
+  <strong>An analog simulator bridge for <a href="https://github.com/cocotb/cocotb">cocotb</a> — open-source mixed-signal co-simulation</strong>
 </p>
 
 <p align="center">
@@ -23,15 +23,17 @@
 - [Prerequisites](#prerequisites)
 - [Installation](#installation)
 - [Quick Start](#quick-start)
-- [Tutorial: PWM DAC with SAR Controller](docs/tutorial/index.md)
 - [API Reference](#api-reference)
+- [Tutorial: PWM DAC with SAR Controller](docs/tutorial/index.md)
 - [Examples](#examples)
 - [Architecture Details](#architecture-details)
+- [Troubleshooting](#troubleshooting)
 
 ## Overview
 
-cocotbext-ams synchronizes cocotb's digital simulation with ngspice's analog
-simulation via the libngspice shared library API. This allows you to co-simulate
+cocotbext-ams synchronizes cocotb's digital simulation with an analog SPICE
+simulator via shared library APIs. It supports **ngspice** (default) and
+**Xyce** (Sandia's open-source parallel SPICE), allowing you to co-simulate
 SPICE netlists alongside Verilog/VHDL testbenches using entirely open-source
 tools.
 
@@ -44,27 +46,30 @@ cocotb testbench (Python async)
 MixedSignalBridge (orchestrator)
   |-- reads Verilog signals via cocotb handles
   |-- converts digital <-> analog (threshold-based)
-  '-- drives ngspice via NgspiceInterface
-       |                    |
-       v                    v
-  HDL Simulator         libngspice.so
-  (Icarus/Verilator)    (ngspice 45+)
+  '-- drives simulator via SimulatorInterface
+       |                         |
+       v                         v
+  HDL Simulator           libngspice.so  or  libxycecinterface.so
+  (Icarus/Verilator)      (ngspice 45+)     (Xyce 7+)
 ```
 
 The bridge uses **event-driven synchronization**: instead of exchanging signals
 at a fixed interval, it reacts to actual signal changes:
 
-- **Digital → Analog:** `ValueChange` monitor coroutines update ngspice voltage
-  sources the instant a Verilog signal changes — no sync overhead needed since
-  ngspice reads the values on every internal evaluation step.
-- **Analog → Digital:** Threshold-crossing detection in ngspice's `SendData`
-  callback triggers an immediate sync when a SPICE output crosses a digital
-  threshold, forcing the new value onto the Verilog signal.
+- **Digital → Analog:** `ValueChange` monitor coroutines update voltage source
+  values the instant a Verilog signal changes — no sync overhead needed.
+- **Analog → Digital:** Threshold-crossing detection triggers an immediate sync
+  when a SPICE output crosses a digital threshold, forcing the new value onto
+  the Verilog signal.
 - A configurable **maximum sync interval** (default 100 ns) ensures periodic
   fallback synchronization even when no crossings occur.
 
+**Supported simulators:**
+- **ngspice** (default) — callback-driven via libngspice's shared library API
+- **Xyce** — explicit stepping via Xyce's C interface (`xyce_simulateUntil()`)
+
 **Signal bridging:**
-- **Digital → Analog:** Verilog 1/0 mapped to VDD/VSS via EXTERNAL voltage sources in SPICE
+- **Digital → Analog:** Verilog 1/0 mapped to VDD/VSS via voltage sources in SPICE
 - **Analog → Digital:** SPICE node voltage compared against a threshold (with optional hysteresis), result forced onto Verilog output
 - **Analog-only pins:** remain X in Verilog, fully simulated in SPICE
 
@@ -84,7 +89,8 @@ comparator output q (second), SAR value register (third), and done signal
 
 - **Python** >= 3.10
 - **cocotb** >= 2.0
-- **ngspice** shared library (`libngspice.so` / `libngspice.dylib`)
+- **ngspice** shared library (`libngspice.so` / `libngspice.dylib`) *or*
+  **Xyce** shared library (`libxycecinterface.so`)
 - A Verilog simulator supported by cocotb (e.g., Icarus Verilog)
 
 ### Installing ngspice
@@ -109,7 +115,7 @@ brew install ngspice
 conda install -c conda-forge ngspice
 ```
 
-#### Building from source
+#### Building ngspice from source
 
 If your distribution doesn't package the shared library, or you need a specific version:
 
@@ -120,6 +126,25 @@ mkdir build && cd build
 make -j$(nproc) && sudo make install
 ```
 
+### Installing Xyce
+
+Xyce is an open-source parallel SPICE simulator from Sandia National Laboratories.
+To use Xyce with cocotbext-ams, you need the shared library build
+(`libxycecinterface.so`).
+
+See the [Xyce installation guide](https://xyce.sandia.gov/documentation-tutorials/building-guide/)
+for build instructions. When building, enable the shared library:
+
+```bash
+cmake -DBUILD_SHARED_LIBS=ON ...
+```
+
+If the library is installed in a non-standard location, pass the path explicitly:
+
+```python
+bridge = MixedSignalBridge(dut, blocks, simulator_lib="/path/to/libxycecinterface.so")
+```
+
 ## Installation
 
 ```bash
@@ -202,10 +227,31 @@ async def test_my_block(dut):
 ```
 
 The `analog_vcd` parameter writes a VCD file with `real`-typed signals at
-full ngspice resolution.  Load it alongside the HDL simulator's digital VCD
+full simulator resolution.  Load it alongside the HDL simulator's digital VCD
 in Surfer, GTKWave, or any viewer that supports real-valued VCD signals to
 see analog and digital waveforms together.
 
+#### Using Xyce instead of ngspice
+
+```python
+block = AnalogBlock(
+    name="dut",
+    spice_file="my_block.sp",
+    subcircuit="my_block",
+    digital_pins={...},
+    analog_inputs={"ain": 0.9},
+    vdd=1.8,
+    simulator="xyce",              # use Xyce instead of ngspice
+)
+
+bridge = MixedSignalBridge(dut, [block],
+                           simulator_lib="/path/to/libxycecinterface.so")
+await bridge.start(duration_ns=50_000)
+```
+
+The bridge auto-generates a Xyce-compatible netlist (YDAC devices, `.TRAN`,
+`.PRINT TRAN`) and drives the simulation via Xyce's explicit stepping API.
+
 ## API Reference
 
 ### `DigitalPin(direction, width=1, vdd=1.8, vss=0.0, threshold=None, hysteresis=0.0)`
@@ -231,24 +277,32 @@ Describes an analog block (SPICE subcircuit) to be co-simulated.
 | `spice_file`    | Path to the SPICE netlist |
 | `subcircuit`    | Name of the `.subckt` |
 | `digital_pins`  | `dict[str, DigitalPin]` — pin name to configuration |
-| `analog_inputs` | `dict[str, float]` — analog input name to initial voltage (EXTERNAL, changeable at runtime) |
+| `analog_inputs` | `dict[str, float]` — analog input name to initial voltage (changeable at runtime) |
 | `vdd`           | Supply voltage (default 1.8) |
 | `vss`           | Ground voltage (default 0.0) |
 | `tran_step`     | SPICE transient step size (default `"0.1n"`) |
 | `extra_lines`   | Additional SPICE lines for the generated netlist (e.g., `.include` directives for PDK libraries) |
+| `simulator`     | `"ngspice"` (default) or `"xyce"` |
 
-### `MixedSignalBridge(dut, analog_blocks, max_sync_interval_ns=100.0, ngspice_lib=None)`
+### `MixedSignalBridge(dut, analog_blocks, max_sync_interval_ns=100.0, simulator_lib=None)`
 
 The main orchestrator.
 
+| Parameter | Description |
+|-----------|-------------|
+| `dut` | cocotb DUT handle |
+| `analog_blocks` | List of `AnalogBlock` descriptions |
+| `max_sync_interval_ns` | Maximum time between sync points in nanoseconds (default 100.0) |
+| `simulator_lib` | Path to the simulator shared library (auto-detected if None) |
+
 | Method | Description |
 |--------|-------------|
 | `await start(duration_ns, analog_vcd=None, vcd_nodes=None)` | Load circuit, start co-simulation. Pass `analog_vcd="file.vcd"` to record analog waveforms. `vcd_nodes` adds extra SPICE nodes beyond the auto-included output pins. |
 | `await stop()` | Halt simulation, release forced signals |
 | `set_analog_input(block, name, voltage)` | Change an analog input voltage at runtime |
 | `get_analog_voltage(block, node)` | Probe any SPICE node voltage |
 
-> **Migration note:** The old `sync_period_ns` parameter still works but emits a `DeprecationWarning`. Rename it to `max_sync_interval_ns`.
+> **Migration note:** The old `ngspice_lib` parameter still works but emits a `DeprecationWarning`. Rename it to `simulator_lib`.
 
 ### Sync interval selection
 
@@ -275,10 +329,21 @@ paths, runtime analog control, VCD export, and waveform viewing.
 
 ## Architecture Details
 
+### Simulator abstraction
+
+Both ngspice and Xyce inherit from `SimulatorInterface`, which holds all
+shared state (voltage source values, node voltages, crossing detection,
+VCD writer) and implements common logic (`_check_crossings()`,
+`_write_vcd()`). Subclasses implement the simulator-specific ctypes wrapper
+and control flow.
+
 ### Thread model
 
 The bridge uses cocotb's `@bridge` / `@resume` mechanism for thread
-synchronization:
+synchronization. Both simulators run a blocking simulation in a
+`@bridge` thread and periodically call a `@resume` function at sync points:
+
+**ngspice:**
 
 1. `@bridge` runs ngspice's blocking `tran` command in a dedicated thread.
 2. `GetVSRCData` fires on every ngspice evaluation step, reading the
@@ -288,42 +353,63 @@ synchronization:
 4. `GetSyncData` fires at each internal timestep. If a crossing was detected
    (or the fallback interval elapsed), it calls a `@resume` function that
    blocks the ngspice thread and transfers control to the cocotb scheduler.
+
+**Xyce:**
+
+1. `@bridge` runs an explicit stepping loop in a dedicated thread.
+2. At each step: push VSRC values via `xyce_updateTimeVoltagePairs()`,
+   advance via `xyce_simulateUntil()`, read voltages via
+   `xyce_obtainResponse()`, check crossings.
+3. At sync intervals, calls the same `@resume` function as ngspice.
+
+**Common to both:**
+
 5. The cocotb scheduler forces new digital values onto Verilog and advances
    digital time by the actual elapsed SPICE time via `await Timer(...)`.
-6. When the `@resume` function returns, the ngspice thread resumes.
+6. When the `@resume` function returns, the simulator thread resumes.
 
 This is event-driven: sync only happens when analog outputs actually cross
 a digital threshold, or at the fallback ceiling interval.
 
 ### Netlist augmentation
 
-The bridge auto-generates a wrapper SPICE deck around the user's subcircuit:
-- Digital input pins become `EXTERNAL` voltage sources (ngspice calls
-  `GetVSRCData` to read their values)
-- Analog inputs also use `EXTERNAL` sources so they can be changed at runtime
-- Output nodes are probed via `.save` directives
-- Power supplies are added automatically
+The bridge auto-generates a wrapper SPICE deck around the user's subcircuit,
+with simulator-specific syntax:
+
+| Feature | ngspice | Xyce |
+|---------|---------|------|
+| Runtime sources | `v_name node 0 dc 0 external` | `YDAC v_name DAC node 0` |
+| Output probing | `.save v(node)` | `.PRINT TRAN v(node)` |
+| Transient analysis | `.tran step stop uic` | `.TRAN step stop` |
+| End marker | `.end` | `.END` |
+
+Power supplies are standard DC sources in both formats.
 
 ### Vector name normalization
 
 ngspice may report vector names with plot prefixes (e.g., `tran1.v(d0)`) or
 wrapped in `v()`. The bridge normalizes lookups so you can query by bare node
-name (`d0`), `v(d0)`, or the full qualified name.
+name (`d0`), `v(d0)`, or the full qualified name. Xyce stores both the
+expression form and bare name.
 
 ## Troubleshooting
 
-### ngspice not found
+### Simulator library not found
 
 ```
-FileNotFoundError: Cannot find libngspice.so
+FileNotFoundError: Cannot find libngspice shared library.
 ```
 
-Install the ngspice shared library for your platform (see
-[Installing ngspice](#installing-ngspice) above). If the library is installed
+Install the ngspice or Xyce shared library for your platform (see
+[Prerequisites](#prerequisites) above). If the library is installed
 in a non-standard location, pass the path explicitly:
 
 ```python
-bridge = MixedSignalBridge(dut, blocks, ngspice_lib="/path/to/libngspice.so")
+# ngspice
+bridge = MixedSignalBridge(dut, blocks, simulator_lib="/path/to/libngspice.so")
+
+# Xyce
+bridge = MixedSignalBridge(dut, blocks, simulator_lib="/path/to/libxycecinterface.so")
 ```
 
 ### Signal not found
@@ -354,8 +440,9 @@ If the simulation appears to hang, check:
    updates. Check your cocotb log output.
 2. **Too-tight sync interval:** Very small `max_sync_interval_ns` values
    (< 1ns) can make the simulation extremely slow. Start with 50-100ns.
-3. **ngspice convergence:** Complex SPICE circuits may fail to converge.
-   Check the cocotb log for `ngspice: stderr` warnings.
+3. **Simulator convergence:** Complex SPICE circuits may fail to converge.
+   Check the cocotb log for `ngspice: stderr` warnings (ngspice) or
+   Xyce error messages.
 
 ### Debugging sync behavior