cirq_spice_import/

lib.rs

//! SPICE import — converts `thevenin_types::Netlist` into `cirq_ir::Circuit`.
//!
//! This crate provides the bridge from legacy SPICE netlists into the canonical
//! Cirq IR. It enables gradual migration: existing SPICE files can be imported
//! into the Cirq toolchain without manual rewriting.

use std::collections::HashMap;

use cirq_ir::{
    AcAnalysis, AcSpec as IrAcSpec, Analysis as IrAnalysis, BehavioralMode, Circuit, Connection,
    DcAnalysis, DcSweep as IrDcSweep, Element as IrElement, ElementKind as IrElementKind,
    FrequencyScale, Id, Model as IrModel, Net, NoiseAnalysis, PzAnalysis, PzType, ResolvedParam,
    SensAnalysis, SourceSpec, TfAnalysis, TranAnalysis, TransferType, Value,
    Waveform as IrWaveform, XspiceConnection as IrXspiceConnection,
};
use thevenin_types::{
    AcVariation, Analysis as SpiceAnalysis, ElementKind as SpiceElementKind, Expr, Item, Netlist,
    Param, PzAnalysisType, PzInputType,
};

// ---------------------------------------------------------------------------
// Error type
// ---------------------------------------------------------------------------

/// Errors that can occur during SPICE-to-Cirq import.
#[derive(Debug, thiserror::Error)]
pub enum ImportError {
    /// The underlying SPICE parser failed.
    #[error("SPICE parse error: {0}")]
    Parse(#[from] thevenin_types::ParseError),

    /// An element type that has no Cirq IR equivalent was encountered.
    #[error("unsupported element: {0}")]
    UnsupportedElement(String),

    /// A model kind string could not be mapped to a `DeviceType`.
    #[error("unknown model kind: {0}")]
    UnknownModelKind(String),

    /// A model referenced by an element was not found in the netlist.
    #[error("model not found: {0}")]
    ModelNotFound(String),

    /// A source referenced in an analysis command was not found.
    #[error("source not found: {0}")]
    SourceNotFound(String),

    /// An expression could not be evaluated to a numeric value.
    #[error("unevaluable expression: {0}")]
    UnevaluableExpr(String),

    /// Subcircuit flattening failed.
    #[error("subcircuit flattening error: {0}")]
    SubcktError(#[from] thevenin::subckt::SubcktError),
}

// ---------------------------------------------------------------------------
// Net interning table
// ---------------------------------------------------------------------------

/// Assigns unique `Id`s to node name strings. Ground ("0") always gets `Id(0)`.
struct NetTable {
    map: HashMap<String, Id>,
    next_id: u32,
    globals: Vec<String>,
}

impl NetTable {
    fn new() -> Self {
        let mut map = HashMap::new();
        map.insert("0".to_owned(), Id(0));
        Self {
            map,
            next_id: 1,
            globals: Vec::new(),
        }
    }

    /// Intern a node name, returning its `Id`. Creates a new entry if unseen.
    fn intern(&mut self, name: &str) -> Id {
        if let Some(&id) = self.map.get(name) {
            return id;
        }
        let id = Id(self.next_id);
        self.next_id += 1;
        self.map.insert(name.to_owned(), id);
        id
    }

    /// Mark a set of node names as global.
    fn mark_global(&mut self, names: &[String]) {
        for name in names {
            self.globals.push(name.clone());
            // Ensure the node is interned.
            self.intern(name);
        }
    }

    /// Produce the final `Vec<Net>`, sorted by id.
    fn into_nets(self) -> Vec<Net> {
        let mut nets: Vec<Net> = self
            .map
            .iter()
            .map(|(name, &id)| {
                let is_global = name == "0" || self.globals.iter().any(|g| g == name);
                Net {
                    id,
                    name: name.clone(),
                    is_global,
                }
            })
            .collect();
        nets.sort_by_key(|n| n.id.0);
        nets
    }
}

// ---------------------------------------------------------------------------
// Helpers
// ---------------------------------------------------------------------------

/// Try to extract a numeric f64 from an `Expr`. Returns `Err` for parameter
/// references and brace expressions that require evaluation.
fn expr_to_f64(expr: &Expr) -> Result<f64, ImportError> {
    match expr {
        Expr::Num(v) => Ok(*v),
        Expr::Param(name) => Err(ImportError::UnevaluableExpr(format!(
            "parameter reference: {name}"
        ))),
        Expr::Brace(s) => Err(ImportError::UnevaluableExpr(format!(
            "brace expression: {{{s}}}"
        ))),
    }
}

/// Build a `SourceSpec` from a `thevenin_types::Source`.
fn build_source_spec(source: &thevenin_types::Source) -> Result<SourceSpec, ImportError> {
    let dc = source.dc.as_ref().and_then(|e| expr_to_f64(e).ok());
    let ac = source
        .ac
        .as_ref()
        .map(|ac| {
            Ok::<IrAcSpec, ImportError>(IrAcSpec {
                mag: expr_to_f64(&ac.mag).unwrap_or(0.0),
                phase: ac
                    .phase
                    .as_ref()
                    .map(expr_to_f64)
                    .transpose()?
                    .unwrap_or(0.0),
            })
        })
        .transpose()?;
    let waveform = source.waveform.as_ref().map(convert_waveform).transpose()?;
    Ok(SourceSpec { dc, ac, waveform })
}

/// Convert a `thevenin_types::Waveform` to an `IrWaveform`.
fn convert_waveform(w: &thevenin_types::Waveform) -> Result<IrWaveform, ImportError> {
    match w {
        thevenin_types::Waveform::Pulse {
            v1,
            v2,
            td,
            tr,
            tf,
            pw,
            per,
        } => Ok(IrWaveform::Pulse {
            v1: expr_to_f64(v1)?,
            v2: expr_to_f64(v2)?,
            td: td.as_ref().map(expr_to_f64).transpose()?,
            tr: tr.as_ref().map(expr_to_f64).transpose()?,
            tf: tf.as_ref().map(expr_to_f64).transpose()?,
            pw: pw.as_ref().map(expr_to_f64).transpose()?,
            per: per.as_ref().map(expr_to_f64).transpose()?,
        }),
        thevenin_types::Waveform::Sin {
            v0,
            va,
            freq,
            td,
            theta,
            phi,
        } => Ok(IrWaveform::Sin {
            v0: expr_to_f64(v0)?,
            va: expr_to_f64(va)?,
            freq: freq.as_ref().map(expr_to_f64).transpose()?,
            td: td.as_ref().map(expr_to_f64).transpose()?,
            theta: theta.as_ref().map(expr_to_f64).transpose()?,
            phi: phi.as_ref().map(expr_to_f64).transpose()?,
        }),
        thevenin_types::Waveform::Exp {
            v1,
            v2,
            td1,
            tau1,
            td2,
            tau2,
        } => Ok(IrWaveform::Exp {
            v1: expr_to_f64(v1)?,
            v2: expr_to_f64(v2)?,
            td1: td1.as_ref().map(expr_to_f64).transpose()?,
            tau1: tau1.as_ref().map(expr_to_f64).transpose()?,
            td2: td2.as_ref().map(expr_to_f64).transpose()?,
            tau2: tau2.as_ref().map(expr_to_f64).transpose()?,
        }),
        thevenin_types::Waveform::Pwl(points) => {
            let pairs = points
                .iter()
                .map(|pt| Ok((expr_to_f64(&pt.time)?, expr_to_f64(&pt.value)?)))
                .collect::<Result<Vec<(f64, f64)>, ImportError>>()?;
            Ok(IrWaveform::Pwl(pairs))
        }
        thevenin_types::Waveform::Sffm { v0, va, fc, fs, md } => Ok(IrWaveform::Sffm {
            v0: expr_to_f64(v0)?,
            va: expr_to_f64(va)?,
            fc: fc.as_ref().map(expr_to_f64).transpose()?,
            fs: fs.as_ref().map(expr_to_f64).transpose()?,
            md: md.as_ref().map(expr_to_f64).transpose()?,
        }),
        thevenin_types::Waveform::Am { va, vo, fc, fs, td } => Ok(IrWaveform::Am {
            va: expr_to_f64(va)?,
            vo: expr_to_f64(vo)?,
            fc: expr_to_f64(fc)?,
            fs: expr_to_f64(fs)?,
            td: td.as_ref().map(expr_to_f64).transpose()?,
        }),
    }
}

/// Convert an `Expr` to a `Value`.
fn expr_to_value(expr: &Expr) -> Value {
    match expr {
        Expr::Num(v) => Value::Real(*v),
        Expr::Param(s) => Value::String(s.clone()),
        Expr::Brace(s) => Value::String(format!("{{{s}}}")),
    }
}

/// Convert a slice of `thevenin_types::Param` to Cirq IR param pairs.
fn convert_params(params: &[Param]) -> Vec<(String, Value)> {
    params
        .iter()
        .map(|p| (p.name.clone(), expr_to_value(&p.value)))
        .collect()
}

fn connection(terminal: &str, net: Id) -> Connection {
    Connection {
        terminal: terminal.to_owned(),
        net,
    }
}

/// Map a SPICE model-kind string (e.g. "NPN", "D", "NMOS") to a `DeviceType`.
fn map_device_type(kind: &str) -> Result<cirq_ir::DeviceType, ImportError> {
    match kind.to_ascii_uppercase().as_str() {
        "D" => Ok(cirq_ir::DeviceType::Diode),
        "NPN" => Ok(cirq_ir::DeviceType::Npn),
        "PNP" => Ok(cirq_ir::DeviceType::Pnp),
        "NMOS" => Ok(cirq_ir::DeviceType::Nmos),
        "PMOS" => Ok(cirq_ir::DeviceType::Pmos),
        "NJF" => Ok(cirq_ir::DeviceType::NJfet),
        "PJF" => Ok(cirq_ir::DeviceType::PJfet),
        "NMF" | "GASFET" | "MESA" => Ok(cirq_ir::DeviceType::NMesfet),
        "PMF" => Ok(cirq_ir::DeviceType::PMesfet),
        other => Err(ImportError::UnknownModelKind(other.to_owned())),
    }
}

/// Determine `ElementKind` for a BJT based on its model type.
fn bjt_kind(
    model_name: &str,
    model_table: &HashMap<String, cirq_ir::DeviceType>,
) -> Result<IrElementKind, ImportError> {
    match model_table.get(&model_name.to_ascii_uppercase()) {
        Some(cirq_ir::DeviceType::Pnp) => Ok(IrElementKind::Pnp),
        Some(cirq_ir::DeviceType::Npn) | Some(_) => Ok(IrElementKind::Npn),
        None => Err(ImportError::ModelNotFound(model_name.to_owned())),
    }
}

/// Determine `ElementKind` for a MOSFET based on its model type.
fn mosfet_kind(
    model_name: &str,
    model_table: &HashMap<String, cirq_ir::DeviceType>,
) -> Result<IrElementKind, ImportError> {
    match model_table.get(&model_name.to_ascii_uppercase()) {
        Some(cirq_ir::DeviceType::Pmos) => Ok(IrElementKind::Pmos),
        Some(cirq_ir::DeviceType::Nmos) | Some(_) => Ok(IrElementKind::Nmos),
        None => Err(ImportError::ModelNotFound(model_name.to_owned())),
    }
}

/// Determine `ElementKind` for a JFET based on its model type.
fn jfet_kind(
    model_name: &str,
    model_table: &HashMap<String, cirq_ir::DeviceType>,
) -> Result<IrElementKind, ImportError> {
    match model_table.get(&model_name.to_ascii_uppercase()) {
        Some(cirq_ir::DeviceType::PJfet) => Ok(IrElementKind::PJfet),
        Some(cirq_ir::DeviceType::NJfet) | Some(_) => Ok(IrElementKind::NJfet),
        None => Err(ImportError::ModelNotFound(model_name.to_owned())),
    }
}

/// Determine `ElementKind` for a MESFET based on its model type.
fn mesfet_kind(
    model_name: &str,
    model_table: &HashMap<String, cirq_ir::DeviceType>,
) -> Result<IrElementKind, ImportError> {
    match model_table.get(&model_name.to_ascii_uppercase()) {
        Some(cirq_ir::DeviceType::PMesfet) => Ok(IrElementKind::PMesfet),
        Some(cirq_ir::DeviceType::NMesfet) | Some(_) => Ok(IrElementKind::NMesfet),
        None => Err(ImportError::ModelNotFound(model_name.to_owned())),
    }
}

// ---------------------------------------------------------------------------
// Main import function
// ---------------------------------------------------------------------------

/// Convert a parsed `thevenin_types::Netlist` into a `cirq_ir::Circuit`.
pub fn import_netlist(netlist: &Netlist) -> Result<Circuit, ImportError> {
    // 0. Flatten subcircuit calls so all elements are at the top level.
    let flat_netlist = thevenin::subckt::flatten_netlist(netlist)?;
    let netlist = &flat_netlist;

    // 1. Build model table: model name (uppercased) → DeviceType.
    //    Also collect model IR objects.
    let mut model_type_table: HashMap<String, cirq_ir::DeviceType> = HashMap::new();
    let mut ir_models: Vec<IrModel> = Vec::new();
    let mut model_id_counter: u32 = 0;
    let mut model_id_table: HashMap<String, Id> = HashMap::new();

    for item in &netlist.items {
        if let Item::Model(mdef) = item {
            let device_type = match map_device_type(&mdef.kind) {
                Ok(dt) => dt,
                Err(_) => continue, // skip unknown model kinds
            };
            let id = Id(model_id_counter);
            model_id_counter += 1;
            model_type_table.insert(mdef.name.to_ascii_uppercase(), device_type);
            model_id_table.insert(mdef.name.to_ascii_uppercase(), id);
            ir_models.push(IrModel {
                id,
                name: mdef.name.clone(),
                device_type,
                params: convert_params(&mdef.params),
            });
        }
    }

    // 2. Discover nets: scan all elements for node names.
    let mut net_table = NetTable::new();

    // Also handle .global directives.
    for item in &netlist.items {
        if let Item::Global(nodes) = item {
            net_table.mark_global(nodes);
        }
    }

    // Pre-scan elements for node names.
    for item in &netlist.items {
        if let Item::Element(elem) = item {
            intern_element_nodes(&elem.kind, &mut net_table);
        }
    }

    // Also intern nodes referenced in analyses (e.g. PZ node names).
    intern_analysis_nodes(&netlist.analysis, &mut net_table);

    // 3. Build element name → Id table for source lookups in analyses.
    let mut element_name_to_id: HashMap<String, Id> = HashMap::new();

    // 4. Convert elements.
    let mut ir_elements: Vec<IrElement> = Vec::new();
    let mut elem_id_counter: u32 = 0;

    for item in &netlist.items {
        let elem = match item {
            Item::Element(e) => e,
            _ => continue,
        };

        let id = Id(elem_id_counter);
        elem_id_counter += 1;

        element_name_to_id.insert(elem.name.to_ascii_uppercase(), id);

        let ir_elem =
            convert_element(id, elem, &mut net_table, &model_type_table, &model_id_table)?;

        if let Some(e) = ir_elem {
            ir_elements.push(e);
        }
    }

    // 5. Convert analysis.
    let ir_analyses = convert_analysis(&netlist.analysis, &element_name_to_id, &mut net_table)?;

    // 6. Collect .param items.
    let mut ir_params: Vec<ResolvedParam> = Vec::new();
    for item in &netlist.items {
        if let Item::Param(params) = item {
            for p in params {
                ir_params.push(ResolvedParam {
                    name: p.name.clone(),
                    value: expr_to_value(&p.value),
                });
            }
        }
    }

    // 7. Collect .options items.
    let mut ir_options: Vec<(String, cirq_ir::Value)> = Vec::new();
    for item in &netlist.items {
        if let Item::Options(params) = item {
            for p in params {
                let val = expr_to_value(&p.value);
                if let Some(existing) = ir_options.iter_mut().find(|o| o.0 == p.name) {
                    existing.1 = val;
                } else {
                    ir_options.push((p.name.clone(), val));
                }
            }
        }
    }

    // 8. Collect .temp.
    let mut ir_temp: Option<f64> = None;
    for item in &netlist.items {
        if let Item::Temp(t) = item {
            ir_temp = Some(*t);
        }
    }

    // 9. Collect .save targets.
    let mut ir_save: Vec<String> = Vec::new();
    for item in &netlist.items {
        if let Item::Save(targets) = item {
            for t in targets {
                if !ir_save.contains(t) {
                    ir_save.push(t.clone());
                }
            }
        }
    }

    // 10. Collect .func definitions.
    let mut ir_funcs: Vec<cirq_ir::FuncDef> = Vec::new();
    for item in &netlist.items {
        if let Item::Func { name, args, body } = item {
            ir_funcs.push(cirq_ir::FuncDef {
                name: name.clone(),
                args: args.clone(),
                body: body.clone(),
            });
        }
    }

    // 11. Collect .ic initial conditions.
    let mut ir_initial_conditions: Vec<(cirq_ir::Id, f64)> = Vec::new();
    for item in &netlist.items {
        if let Item::Ic(pairs) = item {
            for (node_name, val) in pairs {
                let net_id = net_table.intern(node_name);
                ir_initial_conditions.push((net_id, *val));
            }
        }
    }

    // 12. Collect .control blocks as code blocks with "control" language tag.
    let mut ir_code_blocks: Vec<cirq_ir::CodeBlock> = Vec::new();
    for item in &netlist.items {
        if let Item::Control(lines) = item {
            ir_code_blocks.push(cirq_ir::CodeBlock {
                language: "control".to_owned(),
                lines: lines.clone(),
            });
        }
    }

    // 13. Build circuit.
    let nets = net_table.into_nets();

    Ok(Circuit {
        name: netlist.title.clone(),
        nets,
        elements: ir_elements,
        models: ir_models,
        analyses: ir_analyses,
        params: ir_params,
        options: ir_options,
        temp: ir_temp,
        save: ir_save,
        funcs: ir_funcs,
        initial_conditions: ir_initial_conditions,
        code_blocks: ir_code_blocks,
    })
}

/// Parse SPICE source text and convert each resulting netlist into a `Circuit`.
pub fn import_spice(source: &str) -> Result<Vec<Circuit>, ImportError> {
    let netlists = Netlist::parse(source)?;
    netlists.iter().map(import_netlist).collect()
}

// ---------------------------------------------------------------------------
// Node interning for elements
// ---------------------------------------------------------------------------

fn intern_element_nodes(kind: &SpiceElementKind, nets: &mut NetTable) {
    match kind {
        SpiceElementKind::Resistor { pos, neg, .. }
        | SpiceElementKind::Capacitor { pos, neg, .. }
        | SpiceElementKind::Inductor { pos, neg, .. }
        | SpiceElementKind::VoltageSource { pos, neg, .. }
        | SpiceElementKind::CurrentSource { pos, neg, .. }
        | SpiceElementKind::BehavioralSource { pos, neg, .. } => {
            nets.intern(pos);
            nets.intern(neg);
        }
        SpiceElementKind::Diode { anode, cathode, .. } => {
            nets.intern(anode);
            nets.intern(cathode);
        }
        SpiceElementKind::Bjt {
            c, b, e, substrate, ..
        } => {
            nets.intern(c);
            nets.intern(b);
            nets.intern(e);
            if let Some(sub) = substrate {
                nets.intern(sub);
            }
        }
        SpiceElementKind::Mosfet {
            d,
            g,
            s,
            bulk,
            body,
            ..
        } => {
            nets.intern(d);
            nets.intern(g);
            nets.intern(s);
            nets.intern(bulk);
            if let Some(b) = body {
                nets.intern(b);
            }
        }
        SpiceElementKind::Jfet { d, g, s, .. } | SpiceElementKind::Mesa { d, g, s, .. } => {
            nets.intern(d);
            nets.intern(g);
            nets.intern(s);
        }
        SpiceElementKind::MutualCoupling { .. } => {
            // Coupling references inductor names, not nodes directly.
        }
        SpiceElementKind::Vcvs {
            out_pos,
            out_neg,
            in_pos,
            in_neg,
            ..
        }
        | SpiceElementKind::Vccs {
            out_pos,
            out_neg,
            in_pos,
            in_neg,
            ..
        } => {
            nets.intern(out_pos);
            nets.intern(out_neg);
            nets.intern(in_pos);
            nets.intern(in_neg);
        }
        SpiceElementKind::Ccvs {
            out_pos, out_neg, ..
        }
        | SpiceElementKind::Cccs {
            out_pos, out_neg, ..
        } => {
            nets.intern(out_pos);
            nets.intern(out_neg);
        }
        SpiceElementKind::SubcktCall { ports, .. } => {
            for p in ports {
                nets.intern(p);
            }
        }
        SpiceElementKind::Ltra {
            pos1,
            neg1,
            pos2,
            neg2,
            ..
        }
        | SpiceElementKind::Txl {
            pos1,
            neg1,
            pos2,
            neg2,
            ..
        } => {
            nets.intern(pos1);
            nets.intern(neg1);
            nets.intern(pos2);
            nets.intern(neg2);
        }
        SpiceElementKind::Cpl {
            in_nodes,
            out_nodes,
            gnd,
            ..
        } => {
            for n in in_nodes {
                nets.intern(n);
            }
            for n in out_nodes {
                nets.intern(n);
            }
            nets.intern(gnd);
        }
        SpiceElementKind::Xspice { connections, .. } => {
            for conn in connections {
                match conn {
                    thevenin_types::XspiceConnection::Scalar(s) => {
                        nets.intern(s);
                    }
                    thevenin_types::XspiceConnection::Array(arr) => {
                        for s in arr {
                            nets.intern(s);
                        }
                    }
                }
            }
        }
        SpiceElementKind::Raw(_) => {}
    }
}

fn intern_analysis_nodes(analysis: &SpiceAnalysis, nets: &mut NetTable) {
    match analysis {
        SpiceAnalysis::Noise {
            output, ref_node, ..
        } => {
            nets.intern(output);
            if let Some(r) = ref_node {
                nets.intern(r);
            }
        }
        SpiceAnalysis::Pz {
            node_i,
            node_g,
            node_j,
            node_k,
            ..
        } => {
            nets.intern(node_i);
            nets.intern(node_g);
            nets.intern(node_j);
            nets.intern(node_k);
        }
        _ => {}
    }
}

// ---------------------------------------------------------------------------
// Element conversion
// ---------------------------------------------------------------------------

/// Convert a single SPICE element to an IR element. Returns `None` for elements
/// that are intentionally skipped (e.g., subcircuit calls).
fn convert_element(
    id: Id,
    elem: &thevenin_types::Element,
    nets: &mut NetTable,
    model_types: &HashMap<String, cirq_ir::DeviceType>,
    model_ids: &HashMap<String, Id>,
) -> Result<Option<IrElement>, ImportError> {
    let name = &elem.name;

    match &elem.kind {
        SpiceElementKind::Resistor {
            pos,
            neg,
            value,
            params,
        } => {
            let mut ir_params = vec![("value".to_owned(), expr_to_value(value))];
            ir_params.extend(convert_params(params));
            Ok(Some(IrElement {
                id,
                name: name.clone(),
                kind: IrElementKind::Resistor,
                connections: vec![
                    connection("pos", nets.intern(pos)),
                    connection("neg", nets.intern(neg)),
                ],
                params: ir_params,
                model: None,
                source_spec: None,
            }))
        }

        SpiceElementKind::Capacitor {
            pos,
            neg,
            value,
            params,
        } => {
            let mut ir_params = vec![("value".to_owned(), expr_to_value(value))];
            ir_params.extend(convert_params(params));
            Ok(Some(IrElement {
                id,
                name: name.clone(),
                kind: IrElementKind::Capacitor,
                connections: vec![
                    connection("pos", nets.intern(pos)),
                    connection("neg", nets.intern(neg)),
                ],
                params: ir_params,
                model: None,
                source_spec: None,
            }))
        }

        SpiceElementKind::Inductor {
            pos,
            neg,
            value,
            params,
        } => {
            let mut ir_params = vec![("value".to_owned(), expr_to_value(value))];
            ir_params.extend(convert_params(params));
            Ok(Some(IrElement {
                id,
                name: name.clone(),
                kind: IrElementKind::Inductor,
                connections: vec![
                    connection("pos", nets.intern(pos)),
                    connection("neg", nets.intern(neg)),
                ],
                params: ir_params,
                model: None,
                source_spec: None,
            }))
        }

        SpiceElementKind::VoltageSource { pos, neg, source } => {
            let mut ir_params = Vec::new();
            if let Some(dc) = &source.dc {
                ir_params.push(("dc".to_owned(), expr_to_value(dc)));
            }
            if let Some(ac) = &source.ac {
                ir_params.push(("ac_mag".to_owned(), expr_to_value(&ac.mag)));
                if let Some(phase) = &ac.phase {
                    ir_params.push(("ac_phase".to_owned(), expr_to_value(phase)));
                }
            }
            let source_spec = Some(build_source_spec(source)?);
            Ok(Some(IrElement {
                id,
                name: name.clone(),
                kind: IrElementKind::VoltageSource,
                connections: vec![
                    connection("pos", nets.intern(pos)),
                    connection("neg", nets.intern(neg)),
                ],
                params: ir_params,
                model: None,
                source_spec,
            }))
        }

        SpiceElementKind::CurrentSource { pos, neg, source } => {
            let mut ir_params = Vec::new();
            if let Some(dc) = &source.dc {
                ir_params.push(("dc".to_owned(), expr_to_value(dc)));
            }
            if let Some(ac) = &source.ac {
                ir_params.push(("ac_mag".to_owned(), expr_to_value(&ac.mag)));
                if let Some(phase) = &ac.phase {
                    ir_params.push(("ac_phase".to_owned(), expr_to_value(phase)));
                }
            }
            let source_spec = Some(build_source_spec(source)?);
            Ok(Some(IrElement {
                id,
                name: name.clone(),
                kind: IrElementKind::CurrentSource,
                connections: vec![
                    connection("pos", nets.intern(pos)),
                    connection("neg", nets.intern(neg)),
                ],
                params: ir_params,
                model: None,
                source_spec,
            }))
        }

        SpiceElementKind::Diode {
            anode,
            cathode,
            model,
            params,
        } => {
            let model_id = model_ids.get(&model.to_ascii_uppercase()).copied();
            Ok(Some(IrElement {
                id,
                name: name.clone(),
                kind: IrElementKind::Diode,
                connections: vec![
                    connection("anode", nets.intern(anode)),
                    connection("cathode", nets.intern(cathode)),
                ],
                params: convert_params(params),
                model: model_id,
                source_spec: None,
            }))
        }

        SpiceElementKind::Bjt {
            c,
            b,
            e,
            substrate,
            model,
            params,
            off,
        } => {
            let kind = bjt_kind(model, model_types)?;
            let model_id = model_ids.get(&model.to_ascii_uppercase()).copied();
            let mut conns = vec![
                connection("collector", nets.intern(c)),
                connection("base", nets.intern(b)),
                connection("emitter", nets.intern(e)),
            ];
            if let Some(sub) = substrate {
                conns.push(connection("substrate", nets.intern(sub)));
            }
            let mut ir_params = convert_params(params);
            if *off {
                ir_params.push(("off".to_owned(), Value::Bool(true)));
            }
            Ok(Some(IrElement {
                id,
                name: name.clone(),
                kind,
                connections: conns,
                params: ir_params,
                model: model_id,
                source_spec: None,
            }))
        }

        SpiceElementKind::Mosfet {
            d,
            g,
            s,
            bulk,
            body,
            model,
            params,
        } => {
            let kind = mosfet_kind(model, model_types)?;
            let model_id = model_ids.get(&model.to_ascii_uppercase()).copied();
            let mut conns = vec![
                connection("drain", nets.intern(d)),
                connection("gate", nets.intern(g)),
                connection("source", nets.intern(s)),
                connection("bulk", nets.intern(bulk)),
            ];
            if let Some(b) = body {
                conns.push(connection("body", nets.intern(b)));
            }
            Ok(Some(IrElement {
                id,
                name: name.clone(),
                kind,
                connections: conns,
                params: convert_params(params),
                model: model_id,
                source_spec: None,
            }))
        }

        SpiceElementKind::Jfet {
            d,
            g,
            s,
            model,
            params,
        } => {
            let kind = jfet_kind(model, model_types)?;
            let model_id = model_ids.get(&model.to_ascii_uppercase()).copied();
            Ok(Some(IrElement {
                id,
                name: name.clone(),
                kind,
                connections: vec![
                    connection("drain", nets.intern(d)),
                    connection("gate", nets.intern(g)),
                    connection("source", nets.intern(s)),
                ],
                params: convert_params(params),
                model: model_id,
                source_spec: None,
            }))
        }

        SpiceElementKind::Mesa {
            d,
            g,
            s,
            model,
            params,
        } => {
            // MESA devices map to MESFET kind based on model, defaulting to NMesfet.
            let kind = mesfet_kind(model, model_types).unwrap_or(IrElementKind::NMesfet);
            let model_id = model_ids.get(&model.to_ascii_uppercase()).copied();
            Ok(Some(IrElement {
                id,
                name: name.clone(),
                kind,
                connections: vec![
                    connection("drain", nets.intern(d)),
                    connection("gate", nets.intern(g)),
                    connection("source", nets.intern(s)),
                ],
                params: convert_params(params),
                model: model_id,
                source_spec: None,
            }))
        }

        SpiceElementKind::MutualCoupling { l1, l2, coupling } => {
            // Coupling references inductor element names, not net nodes.
            // We store the inductor names as string params.
            Ok(Some(IrElement {
                id,
                name: name.clone(),
                kind: IrElementKind::Coupling,
                connections: Vec::new(),
                params: vec![
                    ("l1".to_owned(), Value::String(l1.clone())),
                    ("l2".to_owned(), Value::String(l2.clone())),
                    ("coupling".to_owned(), expr_to_value(coupling)),
                ],
                model: None,
                source_spec: None,
            }))
        }

        SpiceElementKind::Vcvs {
            out_pos,
            out_neg,
            in_pos,
            in_neg,
            gain,
        } => Ok(Some(IrElement {
            id,
            name: name.clone(),
            kind: IrElementKind::Vcvs,
            connections: vec![
                connection("out_pos", nets.intern(out_pos)),
                connection("out_neg", nets.intern(out_neg)),
                connection("in_pos", nets.intern(in_pos)),
                connection("in_neg", nets.intern(in_neg)),
            ],
            params: vec![("gain".to_owned(), expr_to_value(gain))],
            model: None,
            source_spec: None,
        })),

        SpiceElementKind::Vccs {
            out_pos,
            out_neg,
            in_pos,
            in_neg,
            gm,
        } => Ok(Some(IrElement {
            id,
            name: name.clone(),
            kind: IrElementKind::Vccs,
            connections: vec![
                connection("out_pos", nets.intern(out_pos)),
                connection("out_neg", nets.intern(out_neg)),
                connection("in_pos", nets.intern(in_pos)),
                connection("in_neg", nets.intern(in_neg)),
            ],
            params: vec![("gm".to_owned(), expr_to_value(gm))],
            model: None,
            source_spec: None,
        })),

        SpiceElementKind::Ccvs {
            out_pos,
            out_neg,
            vsrc,
            rm,
        } => Ok(Some(IrElement {
            id,
            name: name.clone(),
            kind: IrElementKind::Ccvs,
            connections: vec![
                connection("out_pos", nets.intern(out_pos)),
                connection("out_neg", nets.intern(out_neg)),
            ],
            params: vec![
                ("vsrc".to_owned(), Value::String(vsrc.clone())),
                ("rm".to_owned(), expr_to_value(rm)),
            ],
            model: None,
            source_spec: None,
        })),

        SpiceElementKind::Cccs {
            out_pos,
            out_neg,
            vsrc,
            gain,
        } => Ok(Some(IrElement {
            id,
            name: name.clone(),
            kind: IrElementKind::Cccs,
            connections: vec![
                connection("out_pos", nets.intern(out_pos)),
                connection("out_neg", nets.intern(out_neg)),
            ],
            params: vec![
                ("vsrc".to_owned(), Value::String(vsrc.clone())),
                ("gain".to_owned(), expr_to_value(gain)),
            ],
            model: None,
            source_spec: None,
        })),

        SpiceElementKind::Ltra {
            pos1,
            neg1,
            pos2,
            neg2,
            model,
            params,
        } => {
            let model_id = model_ids.get(&model.to_ascii_uppercase()).copied();
            Ok(Some(IrElement {
                id,
                name: name.clone(),
                kind: IrElementKind::TransmissionLine,
                connections: vec![
                    connection("in_pos", nets.intern(pos1)),
                    connection("in_neg", nets.intern(neg1)),
                    connection("out_pos", nets.intern(pos2)),
                    connection("out_neg", nets.intern(neg2)),
                ],
                params: convert_params(params),
                model: model_id,
                source_spec: None,
            }))
        }

        SpiceElementKind::Txl {
            pos1,
            neg1,
            pos2,
            neg2,
            model,
            params,
        } => {
            let model_id = model_ids.get(&model.to_ascii_uppercase()).copied();
            Ok(Some(IrElement {
                id,
                name: name.clone(),
                kind: IrElementKind::Txl,
                connections: vec![
                    connection("in_pos", nets.intern(pos1)),
                    connection("in_neg", nets.intern(neg1)),
                    connection("out_pos", nets.intern(pos2)),
                    connection("out_neg", nets.intern(neg2)),
                ],
                params: convert_params(params),
                model: model_id,
                source_spec: None,
            }))
        }

        SpiceElementKind::SubcktCall { subckt, .. } => {
            // If we reach here, flatten_netlist() didn't fully resolve this
            // call — the subcircuit definition is missing or flattening is
            // incomplete.  Report an error rather than silently dropping
            // the element (which would corrupt the circuit topology).
            Err(ImportError::UnsupportedElement(format!(
                "{name} (unresolved subcircuit call to `{subckt}`)"
            )))
        }

        SpiceElementKind::BehavioralSource { pos, neg, spec } => {
            let spec_trimmed = spec.trim();
            // Parse "V=expr" or "I=expr" to determine mode and extract expression.
            let (mode, expr_str) = if let Some(rest) = spec_trimmed
                .strip_prefix("V=")
                .or_else(|| spec_trimmed.strip_prefix("v="))
            {
                (BehavioralMode::Voltage, rest.trim().to_owned())
            } else if let Some(rest) = spec_trimmed
                .strip_prefix("I=")
                .or_else(|| spec_trimmed.strip_prefix("i="))
            {
                (BehavioralMode::Current, rest.trim().to_owned())
            } else {
                // Default to voltage mode with the full spec as the expression.
                (BehavioralMode::Voltage, spec_trimmed.to_owned())
            };
            Ok(Some(IrElement {
                id,
                name: name.clone(),
                kind: IrElementKind::BehavioralSource {
                    mode,
                    spec: expr_str,
                },
                connections: vec![
                    connection("pos", nets.intern(pos)),
                    connection("neg", nets.intern(neg)),
                ],
                params: Vec::new(),
                model: None,
                source_spec: None,
            }))
        }

        SpiceElementKind::Cpl {
            in_nodes,
            out_nodes,
            gnd,
            model,
            params,
        } => {
            let width = in_nodes.len();
            let mut conns = Vec::new();
            for (i, n) in in_nodes.iter().enumerate() {
                conns.push(connection(&format!("in{i}"), nets.intern(n)));
            }
            conns.push(connection("gnd", nets.intern(gnd)));
            for (i, n) in out_nodes.iter().enumerate() {
                conns.push(connection(&format!("out{i}"), nets.intern(n)));
            }
            let mut ir_params = convert_params(params);
            ir_params.push(("model".to_owned(), Value::String(model.clone())));
            Ok(Some(IrElement {
                id,
                name: name.clone(),
                kind: IrElementKind::CoupledLine { width },
                connections: conns,
                params: ir_params,
                model: None,
                source_spec: None,
            }))
        }

        SpiceElementKind::Xspice { connections, model } => {
            let mut ir_conns: Vec<Connection> = Vec::new();
            let mut xspice_conns: Vec<IrXspiceConnection> = Vec::new();
            let mut scalar_idx = 0usize;

            for conn_spec in connections {
                match conn_spec {
                    thevenin_types::XspiceConnection::Scalar(s) => {
                        let net_id = nets.intern(s);
                        ir_conns.push(connection(&format!("c{scalar_idx}"), net_id));
                        xspice_conns.push(IrXspiceConnection::Scalar(net_id));
                        scalar_idx += 1;
                    }
                    thevenin_types::XspiceConnection::Array(arr) => {
                        let ids: Vec<Id> = arr.iter().map(|s| nets.intern(s)).collect();
                        xspice_conns.push(IrXspiceConnection::Array(ids));
                    }
                }
            }

            Ok(Some(IrElement {
                id,
                name: name.clone(),
                kind: IrElementKind::Xspice {
                    connections: xspice_conns,
                },
                connections: ir_conns,
                params: vec![("model".to_owned(), Value::String(model.clone()))],
                model: None,
                source_spec: None,
            }))
        }

        SpiceElementKind::Raw(_) => {
            // Unrecognized element — skip gracefully rather than failing the
            // entire import.  The element is lost but the rest of the circuit
            // can still be simulated.
            Ok(None)
        }
    }
}

// ---------------------------------------------------------------------------
// Analysis conversion
// ---------------------------------------------------------------------------

fn convert_analysis(
    analysis: &SpiceAnalysis,
    element_names: &HashMap<String, Id>,
    nets: &mut NetTable,
) -> Result<Vec<IrAnalysis>, ImportError> {
    let ir = match analysis {
        SpiceAnalysis::Op => IrAnalysis::Op,

        SpiceAnalysis::Dc {
            src,
            start,
            stop,
            step,
            src2,
        } => {
            let src_id = element_names
                .get(&src.to_ascii_uppercase())
                .copied()
                .ok_or_else(|| ImportError::SourceNotFound(src.clone()))?;
            let mut sweeps = vec![IrDcSweep {
                source: src_id,
                start: expr_to_f64(start)?,
                stop: expr_to_f64(stop)?,
                step: expr_to_f64(step)?,
            }];
            if let Some(s2) = src2 {
                let s2_id = element_names
                    .get(&s2.src.to_ascii_uppercase())
                    .copied()
                    .ok_or_else(|| ImportError::SourceNotFound(s2.src.clone()))?;
                sweeps.push(IrDcSweep {
                    source: s2_id,
                    start: expr_to_f64(&s2.start)?,
                    stop: expr_to_f64(&s2.stop)?,
                    step: expr_to_f64(&s2.step)?,
                });
            }
            IrAnalysis::Dc(DcAnalysis { sweeps })
        }

        SpiceAnalysis::Ac {
            variation,
            n,
            fstart,
            fstop,
        } => {
            let scale = match variation {
                AcVariation::Dec => FrequencyScale::Decade,
                AcVariation::Oct => FrequencyScale::Octave,
                AcVariation::Lin => FrequencyScale::Linear,
            };
            IrAnalysis::Ac(AcAnalysis {
                start: expr_to_f64(fstart)?,
                stop: expr_to_f64(fstop)?,
                points: *n,
                scale,
            })
        }

        SpiceAnalysis::Tran {
            tstep,
            tstop,
            tstart,
            tmax,
            uic,
        } => IrAnalysis::Tran(TranAnalysis {
            step: expr_to_f64(tstep)?,
            stop: expr_to_f64(tstop)?,
            start: tstart.as_ref().map(expr_to_f64).transpose()?.unwrap_or(0.0),
            uic: *uic,
            tmax: tmax.as_ref().and_then(|e| expr_to_f64(e).ok()),
        }),

        SpiceAnalysis::Noise {
            output,
            ref_node,
            src,
            variation,
            n,
            fstart,
            fstop,
        } => {
            let output_id = nets.intern(output);
            let ref_id = ref_node.as_ref().map(|r| nets.intern(r)).unwrap_or(Id(0));
            let src_id = element_names
                .get(&src.to_ascii_uppercase())
                .copied()
                .ok_or_else(|| ImportError::SourceNotFound(src.clone()))?;
            let scale = match variation {
                AcVariation::Dec => FrequencyScale::Decade,
                AcVariation::Oct => FrequencyScale::Octave,
                AcVariation::Lin => FrequencyScale::Linear,
            };
            IrAnalysis::Noise(NoiseAnalysis {
                output_net: output_id,
                reference_net: ref_id,
                source: src_id,
                start: expr_to_f64(fstart)?,
                stop: expr_to_f64(fstop)?,
                points: *n,
                scale,
            })
        }

        SpiceAnalysis::Tf { output, input } => {
            let src_id = element_names
                .get(&input.to_ascii_uppercase())
                .copied()
                .ok_or_else(|| ImportError::SourceNotFound(input.clone()))?;
            IrAnalysis::Tf(TfAnalysis {
                output: output.clone(),
                source: src_id,
            })
        }

        SpiceAnalysis::Sens { output } => IrAnalysis::Sens(SensAnalysis {
            output: output.join(", "),
        }),

        SpiceAnalysis::Pz {
            node_i,
            node_g,
            node_j,
            node_k,
            input_type,
            analysis_type,
        } => {
            let transfer = match input_type {
                PzInputType::Vol => TransferType::Voltage,
                PzInputType::Cur => TransferType::Current,
            };
            let pz_type = match analysis_type {
                PzAnalysisType::Pol => PzType::Poles,
                PzAnalysisType::Zer => PzType::Zeros,
                PzAnalysisType::Pz => PzType::Both,
            };
            IrAnalysis::Pz(PzAnalysis {
                input_pos: nets.intern(node_i),
                input_neg: nets.intern(node_g),
                output_pos: nets.intern(node_j),
                output_neg: nets.intern(node_k),
                transfer,
                analysis_type: pz_type,
            })
        }
    };

    Ok(vec![ir])
}

// ---------------------------------------------------------------------------
// Tests
// ---------------------------------------------------------------------------

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn passive_network_two_resistors() {
        let spice = "\
Passive network
R1 a 0 1k
R2 a b 2k
.op
.end
";
        let circuits = import_spice(spice).unwrap();
        assert_eq!(circuits.len(), 1);
        let c = &circuits[0];

        // 3 nets: 0, a, b
        assert_eq!(c.nets.len(), 3);
        let ground = c.nets.iter().find(|n| n.name == "0").unwrap();
        assert_eq!(ground.id, Id(0));
        assert!(ground.is_global);

        // 2 elements
        assert_eq!(c.elements.len(), 2);

        let r1 = c.elements.iter().find(|e| e.name == "R1").unwrap();
        assert!(matches!(r1.kind, IrElementKind::Resistor));
        assert_eq!(r1.connections.len(), 2);
        // Value param
        let value_param = r1.params.iter().find(|p| p.0 == "value").unwrap();
        match &value_param.1 {
            Value::Real(v) => assert!((v - 1000.0).abs() < 1e-6),
            other => panic!("expected Real, got {other:?}"),
        }

        let r2 = c.elements.iter().find(|e| e.name == "R2").unwrap();
        assert!(matches!(r2.kind, IrElementKind::Resistor));
        let value_param2 = r2.params.iter().find(|p| p.0 == "value").unwrap();
        match &value_param2.1 {
            Value::Real(v) => assert!((v - 2000.0).abs() < 1e-6),
            other => panic!("expected Real, got {other:?}"),
        }

        // Analysis is Op
        assert_eq!(c.analyses.len(), 1);
        assert!(matches!(c.analyses[0], IrAnalysis::Op));
    }

    #[test]
    fn mos_inverter() {
        let spice = "\
MOS inverter
.model NMOD NMOS
.model PMOD PMOS
M1 out in vdd vdd PMOD W=10u L=1u
M2 out in 0 0 NMOD W=5u L=1u
V1 vdd 0 DC 3.3
.op
.end
";
        let circuits = import_spice(spice).unwrap();
        assert_eq!(circuits.len(), 1);
        let c = &circuits[0];

        assert_eq!(c.models.len(), 2);

        let m1 = c.elements.iter().find(|e| e.name == "M1").unwrap();
        assert!(matches!(m1.kind, IrElementKind::Pmos));
        assert_eq!(m1.connections.len(), 4);
        assert!(m1.model.is_some());

        let m2 = c.elements.iter().find(|e| e.name == "M2").unwrap();
        assert!(matches!(m2.kind, IrElementKind::Nmos));
        assert!(m2.model.is_some());
    }

    #[test]
    fn dc_sweep_analysis() {
        let spice = "\
DC sweep test
V1 in 0 DC 0
R1 in 0 1k
.dc V1 0 5 0.1
.end
";
        let circuits = import_spice(spice).unwrap();
        let c = &circuits[0];

        assert_eq!(c.analyses.len(), 1);
        match &c.analyses[0] {
            IrAnalysis::Dc(dc) => {
                assert_eq!(dc.sweeps.len(), 1);
                let sw = &dc.sweeps[0];
                assert!((sw.start - 0.0).abs() < 1e-12);
                assert!((sw.stop - 5.0).abs() < 1e-12);
                assert!((sw.step - 0.1).abs() < 1e-12);
            }
            other => panic!("expected Dc, got {other:?}"),
        }
    }

    #[test]
    fn ac_analysis() {
        let spice = "\
AC test
V1 in 0 DC 0 AC 1
R1 in 0 1k
.ac DEC 10 1 1Meg
.end
";
        let circuits = import_spice(spice).unwrap();
        let c = &circuits[0];

        assert_eq!(c.analyses.len(), 1);
        match &c.analyses[0] {
            IrAnalysis::Ac(ac) => {
                assert_eq!(ac.scale, FrequencyScale::Decade);
                assert_eq!(ac.points, 10);
                assert!((ac.start - 1.0).abs() < 1e-12);
                assert!((ac.stop - 1e6).abs() < 1e-6);
            }
            other => panic!("expected Ac, got {other:?}"),
        }
    }

    #[test]
    fn tran_analysis() {
        let spice = "\
Tran test
V1 in 0 DC 1
R1 in 0 1k
.tran 1n 100n
.end
";
        let circuits = import_spice(spice).unwrap();
        let c = &circuits[0];

        match &c.analyses[0] {
            IrAnalysis::Tran(tran) => {
                assert!((tran.step - 1e-9).abs() < 1e-18);
                assert!((tran.stop - 100e-9).abs() < 1e-18);
                assert!((tran.start - 0.0).abs() < 1e-18);
                assert!(!tran.uic);
            }
            other => panic!("expected Tran, got {other:?}"),
        }
    }

    #[test]
    fn model_mapping_all_types() {
        // Verify map_device_type for all known kinds.
        assert!(matches!(
            map_device_type("D"),
            Ok(cirq_ir::DeviceType::Diode)
        ));
        assert!(matches!(
            map_device_type("NPN"),
            Ok(cirq_ir::DeviceType::Npn)
        ));
        assert!(matches!(
            map_device_type("PNP"),
            Ok(cirq_ir::DeviceType::Pnp)
        ));
        assert!(matches!(
            map_device_type("NMOS"),
            Ok(cirq_ir::DeviceType::Nmos)
        ));
        assert!(matches!(
            map_device_type("PMOS"),
            Ok(cirq_ir::DeviceType::Pmos)
        ));
        assert!(matches!(
            map_device_type("NJF"),
            Ok(cirq_ir::DeviceType::NJfet)
        ));
        assert!(matches!(
            map_device_type("PJF"),
            Ok(cirq_ir::DeviceType::PJfet)
        ));
        assert!(matches!(
            map_device_type("NMF"),
            Ok(cirq_ir::DeviceType::NMesfet)
        ));
        assert!(matches!(
            map_device_type("PMF"),
            Ok(cirq_ir::DeviceType::PMesfet)
        ));
        assert!(matches!(
            map_device_type("GASFET"),
            Ok(cirq_ir::DeviceType::NMesfet)
        ));
        // Case insensitive
        assert!(matches!(
            map_device_type("nmos"),
            Ok(cirq_ir::DeviceType::Nmos)
        ));
        // Unknown
        assert!(map_device_type("BOGUS").is_err());
    }

    #[test]
    fn global_nets_marked() {
        let spice = "\
Global test
.global vdd vss
R1 vdd vss 1k
.op
.end
";
        let circuits = import_spice(spice).unwrap();
        let c = &circuits[0];

        let vdd = c.nets.iter().find(|n| n.name == "vdd").unwrap();
        assert!(vdd.is_global);

        let vss = c.nets.iter().find(|n| n.name == "vss").unwrap();
        assert!(vss.is_global);
    }

    #[test]
    fn subckt_call_expanded() {
        let spice = "\
Subckt test
.subckt INV in out vdd vss
M1 out in vdd vdd PMOD
M2 out in vss vss NMOD
.ends INV
.model PMOD PMOS
.model NMOD NMOS
X1 a b vcc gnd INV
R1 a 0 1k
.op
.end
";
        let circuits = import_spice(spice).unwrap();
        let c = &circuits[0];

        // X1 subckt call is expanded; R1 + two MOSFETs from the subcircuit body.
        assert_eq!(c.elements.len(), 3);

        // The expanded elements are prefixed with the instance name.
        // M1 uses PMOD (PMOS) and M2 uses NMOD (NMOS).
        let m1 = c.elements.iter().find(|e| e.name == "x1.m1").unwrap();
        assert!(matches!(m1.kind, IrElementKind::Pmos));

        let m2 = c.elements.iter().find(|e| e.name == "x1.m2").unwrap();
        assert!(matches!(m2.kind, IrElementKind::Nmos));

        // R1 is at top level, not prefixed.
        let r1 = c.elements.iter().find(|e| e.name == "R1").unwrap();
        assert!(matches!(r1.kind, IrElementKind::Resistor));
    }

    #[test]
    fn voltage_source_with_dc_and_ac() {
        let spice = "\
Source test
V1 in 0 DC 1.5 AC 1 90
R1 in 0 1k
.op
.end
";
        let circuits = import_spice(spice).unwrap();
        let c = &circuits[0];

        let v1 = c.elements.iter().find(|e| e.name == "V1").unwrap();
        assert!(matches!(v1.kind, IrElementKind::VoltageSource));
        let dc = v1.params.iter().find(|p| p.0 == "dc").unwrap();
        match &dc.1 {
            Value::Real(v) => assert!((v - 1.5).abs() < 1e-12),
            other => panic!("expected Real, got {other:?}"),
        }
        let ac_mag = v1.params.iter().find(|p| p.0 == "ac_mag").unwrap();
        match &ac_mag.1 {
            Value::Real(v) => assert!((v - 1.0).abs() < 1e-12),
            other => panic!("expected Real, got {other:?}"),
        }
        let ac_phase = v1.params.iter().find(|p| p.0 == "ac_phase").unwrap();
        match &ac_phase.1 {
            Value::Real(v) => assert!((v - 90.0).abs() < 1e-12),
            other => panic!("expected Real, got {other:?}"),
        }
    }

    #[test]
    fn params_collected() {
        let spice = "\
Param test
.param Rval=1k Cval=10p
R1 a 0 1k
.op
.end
";
        let circuits = import_spice(spice).unwrap();
        let c = &circuits[0];

        assert_eq!(c.params.len(), 2);
        assert_eq!(c.params[0].name, "Rval");
        assert_eq!(c.params[1].name, "Cval");
    }

    #[test]
    fn diode_with_model() {
        let spice = "\
Diode test
.model D1N4148 D
D1 anode cathode D1N4148
R1 anode 0 1k
.op
.end
";
        let circuits = import_spice(spice).unwrap();
        let c = &circuits[0];

        let d1 = c.elements.iter().find(|e| e.name == "D1").unwrap();
        assert!(matches!(d1.kind, IrElementKind::Diode));
        assert!(d1.model.is_some());
        assert_eq!(d1.connections[0].terminal, "anode");
        assert_eq!(d1.connections[1].terminal, "cathode");
    }

    #[test]
    fn bjt_npn_pnp() {
        let spice = "\
BJT test
.model QN NPN
.model QP PNP
Q1 c1 b1 e1 QN
Q2 c2 b2 e2 QP
.op
.end
";
        let circuits = import_spice(spice).unwrap();
        let c = &circuits[0];

        let q1 = c.elements.iter().find(|e| e.name == "Q1").unwrap();
        assert!(matches!(q1.kind, IrElementKind::Npn));
        assert_eq!(q1.connections[0].terminal, "collector");
        assert_eq!(q1.connections[1].terminal, "base");
        assert_eq!(q1.connections[2].terminal, "emitter");

        let q2 = c.elements.iter().find(|e| e.name == "Q2").unwrap();
        assert!(matches!(q2.kind, IrElementKind::Pnp));
    }

    #[test]
    fn controlled_sources() {
        let spice = "\
Controlled sources
E1 out1 0 in1 0 10
G1 out2 0 in2 0 0.5
R1 in1 0 1k
R2 in2 0 1k
R3 out1 0 1k
R4 out2 0 1k
.op
.end
";
        let circuits = import_spice(spice).unwrap();
        let c = &circuits[0];

        let e1 = c.elements.iter().find(|e| e.name == "E1").unwrap();
        assert!(matches!(e1.kind, IrElementKind::Vcvs));
        assert_eq!(e1.connections.len(), 4);
        let gain = e1.params.iter().find(|p| p.0 == "gain").unwrap();
        match &gain.1 {
            Value::Real(v) => assert!((v - 10.0).abs() < 1e-12),
            other => panic!("expected Real, got {other:?}"),
        }

        let g1 = c.elements.iter().find(|e| e.name == "G1").unwrap();
        assert!(matches!(g1.kind, IrElementKind::Vccs));
    }

    #[test]
    fn circuit_name_is_title() {
        let spice = "\
My Great Circuit
R1 a 0 1k
.op
.end
";
        let circuits = import_spice(spice).unwrap();
        assert_eq!(circuits[0].name, "My Great Circuit");
    }

    #[test]
    fn ground_always_id_zero() {
        let spice = "\
Ground test
R1 a 0 1k
.op
.end
";
        let circuits = import_spice(spice).unwrap();
        let c = &circuits[0];

        let ground = c.nets.iter().find(|n| n.id == Id(0)).unwrap();
        assert_eq!(ground.name, "0");
        assert!(ground.is_global);
    }

    #[test]
    fn mesa_maps_to_mesfet() {
        let spice = "\
MESFET test
.model ZM1 NMF
Z1 d g s ZM1
R1 d 0 1k
.op
.end
";
        let circuits = import_spice(spice).unwrap();
        let c = &circuits[0];
        let z1 = c.elements.iter().find(|e| e.name == "Z1").unwrap();
        assert!(matches!(z1.kind, IrElementKind::NMesfet));
        assert!(z1.model.is_some());
    }

    #[test]
    fn pmesa_maps_to_pmesfet() {
        let spice = "\
PMESFET test
.model ZM1 PMF
Z1 d g s ZM1
R1 d 0 1k
.op
.end
";
        let circuits = import_spice(spice).unwrap();
        let c = &circuits[0];
        let z1 = c.elements.iter().find(|e| e.name == "Z1").unwrap();
        assert!(matches!(z1.kind, IrElementKind::PMesfet));
        assert!(z1.model.is_some());

        // Verify the model was imported with the correct device type.
        let model = c.models.iter().find(|m| m.name == "ZM1").unwrap();
        assert_eq!(model.device_type, cirq_ir::DeviceType::PMesfet);
    }

    #[test]
    fn mesfet_round_trip() {
        // Build a SPICE Netlist with a Mesa element, import it to IR, convert back
        // to Netlist, and verify the Mesa element survives the round trip.
        use thevenin_types::{Analysis, Element, ElementKind as SK, Expr, Item, ModelDef, Param};

        let netlist = Netlist {
            title: "MESFET round-trip".to_string(),
            items: vec![
                Item::Model(ModelDef {
                    name: "mesmod".to_string(),
                    kind: "NMF".to_string(),
                    params: vec![Param {
                        name: "vto".to_string(),
                        value: Expr::Num(-1.3),
                    }],
                }),
                Item::Element(Element {
                    name: "Z1".to_string(),
                    kind: SK::Mesa {
                        d: "drain".to_string(),
                        g: "gate".to_string(),
                        s: "0".to_string(),
                        model: "mesmod".to_string(),
                        params: vec![],
                    },
                }),
            ],
            analysis: Analysis::Op,
            source: String::new(),
        };

        // Step 1: Import to IR.
        let ir = import_netlist(&netlist).unwrap();
        let z1_ir = ir.elements.iter().find(|e| e.name == "Z1").unwrap();
        assert!(matches!(z1_ir.kind, IrElementKind::NMesfet));

        // Step 2: Convert IR back to Netlist.
        let netlists_out = cirq_frontend::to_netlist::circuit_to_netlists(&ir).unwrap();
        let nl_out = &netlists_out[0];

        // Step 3: Verify the Mesa element survived.
        let z1_out = nl_out
            .items
            .iter()
            .find_map(|i| {
                if let Item::Element(e) = i {
                    if e.name == "Z1" { Some(e) } else { None }
                } else {
                    None
                }
            })
            .expect("Z1 should survive round-trip");
        match &z1_out.kind {
            SK::Mesa { d, g, s, model, .. } => {
                assert_eq!(d, "drain");
                assert_eq!(g, "gate");
                assert_eq!(s, "0");
                assert_eq!(model, "mesmod");
            }
            other => panic!("expected Mesa, got {other:?}"),
        }

        // Step 4: Verify model survived.
        let model_out = nl_out.items.iter().find_map(|i| {
            if let Item::Model(m) = i {
                if m.name == "mesmod" { Some(m) } else { None }
            } else {
                None
            }
        });
        assert!(model_out.is_some());
        assert_eq!(model_out.unwrap().kind, "NMF");
    }

    #[test]
    fn cpl_element_imported() {
        use thevenin_types::{Analysis, Element, ElementKind as SK};

        let netlist = Netlist {
            title: "CPL test".to_string(),
            items: vec![Item::Element(Element {
                name: "P1".to_string(),
                kind: SK::Cpl {
                    in_nodes: vec!["n1".to_string(), "n2".to_string()],
                    out_nodes: vec!["n3".to_string(), "n4".to_string()],
                    gnd: "0".to_string(),
                    model: "cpl_mod".to_string(),
                    params: vec![],
                },
            })],
            analysis: Analysis::Op,
            source: String::new(),
        };

        let circuit = import_netlist(&netlist).unwrap();
        let p1 = circuit.elements.iter().find(|e| e.name == "P1").unwrap();
        match &p1.kind {
            IrElementKind::CoupledLine { width } => assert_eq!(*width, 2),
            other => panic!("expected CoupledLine, got {other:?}"),
        }
        // Check connections: in0, in1, gnd, out0, out1
        assert_eq!(p1.connections.len(), 5);
        assert_eq!(p1.connections[0].terminal, "in0");
        assert_eq!(p1.connections[1].terminal, "in1");
        assert_eq!(p1.connections[2].terminal, "gnd");
        assert_eq!(p1.connections[3].terminal, "out0");
        assert_eq!(p1.connections[4].terminal, "out1");
        // Model stored as param
        let model_param = p1.params.iter().find(|p| p.0 == "model").unwrap();
        match &model_param.1 {
            Value::String(s) => assert_eq!(s, "cpl_mod"),
            other => panic!("expected String, got {other:?}"),
        }
    }

    #[test]
    fn xspice_element_imported() {
        use thevenin_types::{Analysis, Element, ElementKind as SK, XspiceConnection};

        let netlist = Netlist {
            title: "XSPICE test".to_string(),
            items: vec![Item::Element(Element {
                name: "A1".to_string(),
                kind: SK::Xspice {
                    connections: vec![
                        XspiceConnection::Scalar("in".to_string()),
                        XspiceConnection::Array(vec!["out1".to_string(), "out2".to_string()]),
                    ],
                    model: "buf_model".to_string(),
                },
            })],
            analysis: Analysis::Op,
            source: String::new(),
        };

        let circuit = import_netlist(&netlist).unwrap();
        let a1 = circuit.elements.iter().find(|e| e.name == "A1").unwrap();
        match &a1.kind {
            IrElementKind::Xspice { connections } => {
                assert_eq!(connections.len(), 2);
                match &connections[0] {
                    IrXspiceConnection::Scalar(_) => {}
                    other => panic!("expected Scalar, got {other:?}"),
                }
                match &connections[1] {
                    IrXspiceConnection::Array(ids) => assert_eq!(ids.len(), 2),
                    other => panic!("expected Array, got {other:?}"),
                }
            }
            other => panic!("expected Xspice, got {other:?}"),
        }
        // Scalar connection appears in ir_conns.
        assert_eq!(a1.connections.len(), 1);
        assert_eq!(a1.connections[0].terminal, "c0");
        // Model stored as param.
        let model_param = a1.params.iter().find(|p| p.0 == "model").unwrap();
        match &model_param.1 {
            Value::String(s) => assert_eq!(s, "buf_model"),
            other => panic!("expected String, got {other:?}"),
        }
    }

    #[test]
    fn subckt_round_trip_port_remapping() {
        // Verifies full round-trip: SPICE with subcircuit -> import -> IR
        // with correct prefix names and port remapping.
        let spice = "\
Subcircuit round-trip test
.subckt RBUF inp outp
R1 inp mid 100
R2 mid outp 200
.ends RBUF
X1 net_a net_b RBUF
X2 net_b net_c RBUF
V1 net_a 0 DC 5
R_load net_c 0 1k
.op
.end
";
        let circuits = import_spice(spice).unwrap();
        let c = &circuits[0];

        // Two instances expanded: X1 produces x1.r1, x1.r2; X2 produces x2.r1, x2.r2.
        // Plus V1 and R_load at the top level = 6 elements total.
        assert_eq!(c.elements.len(), 6);

        // Verify prefixed element names exist.
        let x1_r1 = c.elements.iter().find(|e| e.name == "x1.r1").unwrap();
        assert!(matches!(x1_r1.kind, IrElementKind::Resistor));
        let x1_r2 = c.elements.iter().find(|e| e.name == "x1.r2").unwrap();
        assert!(matches!(x1_r2.kind, IrElementKind::Resistor));
        let x2_r1 = c.elements.iter().find(|e| e.name == "x2.r1").unwrap();
        assert!(matches!(x2_r1.kind, IrElementKind::Resistor));
        let x2_r2 = c.elements.iter().find(|e| e.name == "x2.r2").unwrap();
        assert!(matches!(x2_r2.kind, IrElementKind::Resistor));

        // Verify port remapping: x1.r1 should connect to net_a (inp->net_a)
        // and x1.mid (internal node), not to "inp" or "outp".
        let x1_r1_node_names: Vec<&str> = x1_r1
            .connections
            .iter()
            .map(|conn| {
                c.nets
                    .iter()
                    .find(|n| n.id == conn.net)
                    .unwrap()
                    .name
                    .as_str()
            })
            .collect();
        assert!(
            x1_r1_node_names.contains(&"net_a"),
            "x1.r1 should connect to net_a (remapped port)"
        );
        assert!(
            x1_r1_node_names.contains(&"x1.mid"),
            "x1.r1 should connect to x1.mid (prefixed internal node)"
        );

        // x1.r2 connects x1.mid -> net_b (outp->net_b)
        let x1_r2_node_names: Vec<&str> = x1_r2
            .connections
            .iter()
            .map(|conn| {
                c.nets
                    .iter()
                    .find(|n| n.id == conn.net)
                    .unwrap()
                    .name
                    .as_str()
            })
            .collect();
        assert!(
            x1_r2_node_names.contains(&"x1.mid"),
            "x1.r2 should connect to x1.mid"
        );
        assert!(
            x1_r2_node_names.contains(&"net_b"),
            "x1.r2 should connect to net_b (remapped port)"
        );

        // x2.r1 connects net_b -> x2.mid
        let x2_r1_node_names: Vec<&str> = x2_r1
            .connections
            .iter()
            .map(|conn| {
                c.nets
                    .iter()
                    .find(|n| n.id == conn.net)
                    .unwrap()
                    .name
                    .as_str()
            })
            .collect();
        assert!(
            x2_r1_node_names.contains(&"net_b"),
            "x2.r1 should connect to net_b (remapped port)"
        );
        assert!(
            x2_r1_node_names.contains(&"x2.mid"),
            "x2.r1 should connect to x2.mid"
        );

        // Verify top-level elements are not prefixed.
        assert!(c.elements.iter().any(|e| e.name == "V1"));
        assert!(c.elements.iter().any(|e| e.name == "R_load"));
    }
}