spice_analyser.py

# vim: set shiftwidth=2 softtabstop=2 ts=2 expandtab:
#
#    Copyright 2022 Google LLC
#
#    Licensed under the Apache License, Version 2.0 (the "License");
#    you may not use this file except in compliance with the License.
#    You may obtain a copy of the License at
#
#        https://www.apache.org/licenses/LICENSE-2.0
#
#    Unless required by applicable law or agreed to in writing, software
#    distributed under the License is distributed on an "AS IS" BASIS,
#    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
#    See the License for the specific language governing permissions and
#    limitations under the License.

import collections
import textwrap
import re
import csv
from enum import Enum
from datetime import datetime
import numpy as np
import math
import matplotlib.pyplot as plt

import pdb

import os
import circuit
import spice
import spice_util
from spice_util import NumericalValue, SIUnitPrefix

from google.protobuf import text_format
import proto.test_manifest_pb2 as manifest_pb
import proto.circuit_analysis_pb2 as analysis_pb


DUT_TYPE_TO_PROTO = {
    circuit.DesignRegion.DUTType.SUB_REGION:
        analysis_pb.DesignRegion.DeviceUnderTestType.SUB_REGION,
    circuit.DesignRegion.DUTType.MODULE:
        analysis_pb.DesignRegion.DeviceUnderTestType.MODULE,
    circuit.DesignRegion.DUTType.EXTERNAL_MODULE:
        analysis_pb.DesignRegion.DeviceUnderTestType.EXTERNAL_MODULE,
}

PROTO_TO_DUT_TYPE = {
    analysis_pb.DesignRegion.DeviceUnderTestType.SUB_REGION:
        circuit.DesignRegion.DUTType.SUB_REGION,
    analysis_pb.DesignRegion.DeviceUnderTestType.MODULE:
        circuit.DesignRegion.DUTType.MODULE,
    analysis_pb.DesignRegion.DeviceUnderTestType.EXTERNAL_MODULE:
        circuit.DesignRegion.DUTType.EXTERNAL_MODULE,
}

SIGNAL_FROM_XYCE_V_STATEMENT_RE = re.compile('^V\((.*)\)$')

class SpiceTestHarness:

  def __init__(self, design, region, spice_libs,
               output_directory=None, subckt_name=None, include_subckt=None,
               test_suffix=None, tags=[]):
    self.design = design
    self.region = region
    self.include_subckt = include_subckt
    self.output_directory = output_directory
    self.test_suffix = test_suffix
    self.tags = tags

    # FIXME(growly): This is a hack. Could just put this in DesignRegion.
    # Should rename DesignRegion to SpiceTestSpec or something.
    self.subckt_name = subckt_name or self.region.name

    self.spice_libs = spice_libs
    # TODO(growly): Replace with option from Design.
    self.ground_name = '0'
    self.ground_wire = circuit.Wire(
        circuit.Signal(self.ground_name, width=1), 0)
    self.vdd_v = 0.7
    self.default_fixed_dc_bias_v = self.vdd_v/2

    # Test-specific, in addition to those in the region.
    self.input_waveforms = []
    self.biases = []
    self.instances = []
    self.voltage_probes = []

    # Multiple objects might refer to the same parameter, collected here by
    # name.
    self.sweep_parameters = {}

  def AddBias(self, bias):
    self.biases.append(bias)

  def AddInputWaveform(self, input_waveform):
    self.input_waveforms.append(input_waveform)

  def AddInstance(self, instance):
    self.instances.append(instance)

  def AddVoltageProbe(self, probe):
    self.voltage_probes.append(probe)

  def DeckPreamble(self):
    pins = self.region.OrderedWires()
    pin_names = []
    for pin in pins:
      if not isinstance(pin, circuit.Wire):
        raise NotImplementedError()
      pin_names.append(pin.SpiceName())

    spice_test = textwrap.dedent(f"""\
        ** {self.description}
        ** Harness generated by bigspicy.py at {datetime.utcnow().ctime()} UTC
        .OPTIONS DEVICE TNOM=25  ; converted options using xdm
        .PREPROCESS REPLACEGROUND TRUE
        .GLOBAL VSS  ; TODO(growly): parameterise.
        R0 VSS 0 R=0
        """)
    spice_test += '\n' + self.ReportComment() + '\n'

    for lib in self.spice_libs:
      spice_test += f'.INCLUDE {lib}\n'

    if self.include_subckt:
      spice_test += f'.INCLUDE {self.include_subckt}\n'

    spice_test += '\n' + self.ParamStatements()

    spice_test += textwrap.dedent(f"""
        ** circuit under test
        X0 {' '.join(pin_names)} {self.subckt_name}
        """)
    return spice_test

  def GetOrCreateSweepParameter(self, sweep_parameter):
    try:
      return self.sweep_parameters[sweep_parameter.name]
    except KeyError:
      self.sweep_parameters[sweep_parameter.name] = sweep_parameter
      return sweep_parameter

  def ReportComment(self):
    return ''

  def ParamStatements(self):
    out = ''
    for parameter in self.sweep_parameters.values():
      out += f'.PARAM {parameter.name}={parameter.low}\n'
    return out

  def StepStatements(self):
    out = ''
    for parameter in self.sweep_parameters.values():
      out += f'.STEP {parameter.name} {parameter.low} {parameter.high} {parameter.step}\n'
    return out


class TransientTest(SpiceTestHarness):

  def __init__(self,
               design,
               region,
               test_manifest,
               spice_libs,
               output_directory=None,
               include_subckt=None,
               subckt_name=None,
               step_size_fs=0.01,
               duration_ps=4000.0,
               input_delay_ps=1.0,
               input_rise_time_ps=5.0,
               input_fall_time_ps=5.0,
               input_width_ps=2000.0,
               input_period_ps=4000.0,
               test_suffix=None,
               tags=[]):
    super().__init__(design, region, spice_libs,
                     output_directory=output_directory,
                     subckt_name=subckt_name,
                     include_subckt=include_subckt,
                     test_suffix=test_suffix,
                     tags=tags)

    if include_subckt:
      root = include_subckt.removesuffix('.sp')
    else:
      root = os.path.join(output_directory, region.name)
    suffix = f'.transient_{self.test_suffix}.sp' if self.test_suffix else '.transient.sp'
    self.test_file_name = root + suffix

    self.description = f'Transient Analysis for region "{self.region.name}"'
    self.step_size_fs = step_size_fs
    self.duration_ps = duration_ps

    self.fft_specs = []
    self.delay_measurements = []
    self.other_measurements = []

    self.default_input_driver = spice.StepInput(
        self.ground_wire,
        reference_wire=self.ground_wire,
        low_voltage=NumericalValue(0.0),
        high_voltage=NumericalValue(self.vdd_v),
        delay_s=NumericalValue(
            input_delay_ps, SIUnitPrefix.PICO),
        rise_time_s=NumericalValue(
            input_rise_time_ps, SIUnitPrefix.PICO),
        fall_time_s=NumericalValue(
            input_fall_time_ps, SIUnitPrefix.PICO),
        pulse_width_s=NumericalValue(
            input_width_ps, SIUnitPrefix.PICO),
        period_s=NumericalValue(
            input_period_ps, SIUnitPrefix.PICO))

    for transient in test_manifest.transient_analyses:
      if transient.spice_source_file == self.test_file_name:
        print('warning: overwriting existing test entry in manifest for '
              f'{transient.spice_source_file}')
        test_manifest.transient_analyses.remove(transient)

    self.manifest = test_manifest.transient_analyses.add()
    self.manifest.design_region_name = region.name
    self.manifest.spice_source_file = self.test_file_name
    self.manifest.tags.extend(self.tags)

  def ReportComment(self):
    loads = ' '.join(map(lambda load: load.wire.SpiceName(), self.region.loads.values()))
    ports = ' '.join(map(lambda port: port.wire.SpiceName(), self.region.port_network_ports.values()))
    dc_biases = ' '.join(map(lambda dc_bias: dc_bias.wire.SpiceName(), self.region.dc_biases.values()))
    dc_sources = ' '.join(map(lambda dc_load: dc_load.wire.SpiceName(), self.region.dc_sources.values()))
    drivers = ' '.join(map(lambda driver: driver.wire.SpiceName(), self.region.simulated_drivers.values()))
    probes = ' '.join(map(lambda probe: probe.wire.SpiceName(), self.region.voltage_probes.values()))
    sub_probes = ' '.join(map(lambda probe: 'X0:' + probe.wire.SpiceName(), self.region.subcircuit_voltage_probes))
    return textwrap.dedent(f"""\
        ** bigspicy info:
        **  loads: {loads}
        **  ports: {ports}
        **  fixed nets (dc biases): {dc_biases}
        **  fixed dc sources: {dc_sources}
        **  inputs (simulated drivers): {drivers}
        **  outputs (voltage probes): {probes}
        **  subcircuit probes (voltage probes): {probes}
        """)

  def AddFFTSpec(self, fft_spec):
    self.fft_specs.append(fft_spec)

  def AddDelayMeasurement(self, measurement):
    self.delay_measurements.append(measurement)

  def AddOtherMeasurement(self, measurement):
    self.other_measurements.append(measurement)

  def Write(self):
    spice_test = self.DeckPreamble()

    spice_writer = spice.SpiceWriter(self.design)
    if self.instances:
      spice_test += '\n** test-specific instances\n'
      for instance in self.instances:
        spice_test += spice_writer.SpiceInstance(instance, generate_names=False)

    num_dc_sources = 1
    print_list = []
    if self.region.dc_sources:
      spice_test += '\n** dc sources\n'
      for dc_source in self.region.dc_sources.values():
        potential_v = dc_source.value or self.default_fixed_dc_bias_v
        spice_test += f'VSRC{num_dc_sources} {dc_source.wire.SpiceName()} {self.ground_name} DC {potential_v}'
        num_dc_sources += 1

    spice_test += '\n** simulated signal drivers\n'
    for driver in self.region.simulated_drivers.values():
      device_name = f'VSRC{num_dc_sources}'
      node_name = driver.wire.SpiceName()
      if driver.input_waveform is None:
        self.default_input_driver.wire = driver.wire
        spice_test += self.default_input_driver.SpiceLine(
            device_name) + '\n'
      else:
        spice_test += driver.input_waveform.SpiceLine(device_name) + '\n'
      print_list.append(f'V({node_name})')
      num_dc_sources += 1

    for input_waveform in self.input_waveforms:
      device_name = f'VSRC{num_dc_sources}'
      node_name = input_waveform.wire.SpiceName()
      spice_test += input_waveform.SpiceLine(device_name) + '\n'
      print_list.append(f'V({node_name})')
      num_dc_sources += 1

    for probe in list(self.region.voltage_probes.values()) + self.voltage_probes:
      node_name = probe.wire.SpiceName()
      print_list.append(f'V({probe.wire.SpiceName()})')

    for probe in self.region.subcircuit_voltage_probes:
      node_name = probe.wire.SpiceName()
      print_list.append(f'V(X0:{probe.wire.SpiceName()})')

    # DC sources at 0V potential are equivalent to a 0 resistance path to ground.
    biases = list(self.region.dc_biases.values()) + self.biases
    if biases:
      spice_test += '\n** dc biases\n'
      num_dc_biases = 1
      for dc_bias in biases:
        bias_v = dc_bias.value or self.default_fixed_dc_bias_v
        spice_test += f'.NODESET {dc_bias.wire.SpiceName()} {bias_v}\n'
        num_dc_biases += 1

    if self.region.loads:
      spice_test += '\n** simulated loads\n'
      num_caps = 1
      for load in self.region.loads.values():
        spice_test += f'C{num_caps} {load.wire.SpiceName()} {self.ground_name} C={load.value}\n'
        num_caps += 1

    for fft_spec in self.fft_specs:
      spice_test += '\n' + fft_spec.SpiceLine()

    spice_test += textwrap.dedent(f"""
        .TRAN {self.step_size_fs}f {self.duration_ps}p
        .PRINT TRAN FORMAT=GNUPLOT {' '.join(sorted(print_list))}
        """)

    for delay_measurement in self.delay_measurements:
      targ_name = delay_measurement.sink_wire.SpiceName()
      targ_value = str(delay_measurement.sink_value) or str(self.vdd_v/2)
      delay_computation = self.manifest.delay_computations.add()
      if delay_measurement.source_wire:
        trig_name = delay_measurement.source_wire.SpiceName()
        delay_computation.trigger_node = trig_name
        trig_value = str(delay_measurement.source_value) or str(self.vdd_v/2)
        variable_name = delay_measurement.name or f'{trig_name}_to_{targ_name}_delay'
        spice_test += (
            f'.MEASURE TRAN {variable_name} TRIG V({trig_name})={trig_value} '
            f'TARG V({targ_name})={targ_value}\n')
      else:
        variable_name = delay_measurement.name or f'{targ_name}_time'
        spice_test += (
            f'.MEASURE TRAN {variable_name} WHEN V({targ_name})={targ_value}\n')
      delay_computation.spice_variable_name = variable_name.upper()
      delay_computation.target_node = targ_name

    for measurement in self.other_measurements:
      target_name = measurement.target_wire.SpiceName()
      measure_type = measurement.measure_type
      measure_spec = spice.Measurement.MEASURE_TYPE_TO_XYCE[measure_type]
      variable_name = measurement.name or f'{target_name}_{measure_spec}'
      measure_pb = self.manifest.measurements.add()
      measure_pb.spice_variable_name = variable_name.upper()
      measure_pb.target_node = target_name
      spice_test += (
          f'.MEASURE TRAN {variable_name} {measure_spec} V({target_name})')
      if measurement.target_value:
        spice_test += f'={measurement.target_value}'
      if measurement.from_time:
        spice_test += f' FROM={measurement.from_time}'
      spice_test += '\n'

    # This is the full matrix of input to output delays.
    # TODO(growly): Express as more general spice.DelayMeasurements that are
    # passed in.
    for driver in self.region.simulated_drivers.values():
      trig_name = driver.wire.SpiceName()
      #spice_test += f'.MEASURE TRAN {node_name}_cross WHEN V({node_name})={self.vdd_v / 2}\n'
      for probe in self.region.voltage_probes.values():
        targ_name = probe.wire.SpiceName()
        #spice_test += f'.MEASURE TRAN {node_name}_cross WHEN V({node_name})={self.vdd_v / 2}\n'
        variable_name = f'{trig_name}_to_{targ_name}_delay'
        spice_test += f'.MEASURE TRAN {variable_name} TRIG V({trig_name})={self.vdd_v/2} TARG V({targ_name})={self.vdd_v/2}\n'
        delay_computation = self.manifest.delay_computations.add()
        delay_computation.spice_variable_name = variable_name.upper()
        delay_computation.trigger_node = trig_name
        delay_computation.target_node = targ_name

    # Measurements of signals in the subcircuit.
    for delay_measurement in self.region.subcircuit_delay_measurements:
      trig_name = f'X0:{delay_measurement.source_wire.SpiceName()}'
      targ_name = f'X0:{delay_measurement.sink_wire.SpiceName()}'
      variable_name = f'{trig_name}_to_{targ_name}_delay'
      spice_test += f'.MEASURE TRAN {variable_name} TRIG V({trig_name})={self.vdd_v/2} TARG V({targ_name})={self.vdd_v/2}\n'
      delay_computation = self.manifest.delay_computations.add()
      delay_computation.spice_variable_name = variable_name.upper()
      delay_computation.trigger_node = trig_name
      delay_computation.target_node = targ_name

    spice_test += '.END\n'

    with open(self.test_file_name, 'w') as f:
      f.write(spice_test)
    print(f'wrote {self.test_file_name}')


class LinearAnalysisTest(SpiceTestHarness):
  class Type(Enum):
    Y = 1
    Z = 2
    S = 3
    H = 4

  TYPE_TO_PROTO = {
      Type.Y: manifest_pb.LinearAnalysis.Type.Y,
      Type.Z: manifest_pb.LinearAnalysis.Type.Z,
      Type.S: manifest_pb.LinearAnalysis.Type.S,
      Type.H: manifest_pb.LinearAnalysis.Type.H
  }

  def __init__(self, design, region, test_manifest, spice_libs,
               output_directory=None,
               include_subckt=None,
               subckt_name=None,
               parameter_type=Type.Y,
               start_freq_hz=1E0,
               stop_freq_hz=100E12,
               num_points=100,
               tags=[]):
    super().__init__(design,
                     region,
                     spice_libs,
                     subckt_name=subckt_name,
                     output_directory=output_directory,
                     include_subckt=include_subckt,
                     tags=tags)
    
    if include_subckt:
      root = include_subckt.removesuffix('.sp')
    else:
      root = os.path.join(self.output_directory, region.name)
    self.test_file_name = f'{root}.linear{parameter_type.name}.sp'
    
    self.description = (
        f'Linear {parameter_type.name}-parameter test for region '
        f'"{self.region.name}"')
    self.start_freq_hz = start_freq_hz
    self.stop_freq_hz = stop_freq_hz
    self.num_points = num_points
    self.parameter_type = parameter_type

    for linear in test_manifest.linear_analyses:
      if linear.spice_source_file == self.test_file_name:
        print('warning: overwriting existing test entry in manifest for '
              f'{linear.spice_source_file}')
        test_manifest.linear_analyses.remove(linear)

    self.manifest = test_manifest.linear_analyses.add()
    self.manifest.design_region_name = region.name
    self.manifest.analysis_type = LinearAnalysisTest.TYPE_TO_PROTO[parameter_type]
    self.manifest.spice_source_file = self.test_file_name
    self.manifest.sweep_type = manifest_pb.LinearAnalysis.SweepType.DECADE
    self.manifest.start_freq_hz = self.start_freq_hz
    self.manifest.stop_freq_hz = self.stop_freq_hz
    self.manifest.num_points  = self.num_points
    self.manifest.tags.extend(self.tags)

  def ReportComment(self):
    loads = ' '.join(map(lambda load: load.wire.SpiceName(),
                         list(self.region.loads.values())))
    ports = ' '.join(map(lambda port: port.wire.SpiceName(),
                         list(self.region.port_network_ports.values())))
    dc_biases = ' '.join(map(lambda dc_bias: dc_bias.wire.SpiceName(), self.region.dc_biases))
    return textwrap.dedent(f"""\
        ** bigspicy report:
        **  loads: {loads} 
        **  ports: {ports} 
        **  fixed nets (dc sources) @ {self.default_fixed_dc_bias_v}V: {dc_biases}
        """)

  def Write(self):
    spice_test = self.DeckPreamble()

    # When performing N-port network analysis:
    if not self.region.port_network_ports:
      raise RuntimeError('need ports for Linear test')

    num_dc_sources = 0
    print_list = []
    if self.region.dc_sources:
      spice_test += '\n** dc sources\n'
      for dc_source in self.region.dc_sources.values():
        potential_v = dc_source.value or self.default_fixed_dc_bias_v
        spice_test += f'VSRC{num_dc_sources} {dc_source.wire.SpiceName()} {self.ground_name} DC {potential_v}'
        num_dc_sources += 1

    spice_test += '\n** N-port ports\n'
    num_ports = 0
    for port in self.region.port_network_ports.values():
      port_pb = self.manifest.ports.add()
      port_pb.number = num_ports + 1
      port_pb.node = port.wire.SpiceName()
      port_pb.generating_impedance_ohms = 0

      if port.dc_bias is not None:
        param = port.dc_bias
        node_name = port.wire.SpiceName() + '_syn'
        spice_test += (f'V{num_dc_sources} {port.wire.SpiceName()} '
                       f'{node_name} DC {{{param.name}}}\n')
        num_dc_sources += 1
      else:
        node_name = port.wire.SpiceName()
      spice_test += f'P{num_ports} {node_name} {self.ground_name} port={num_ports+1} z0=0\n'

      num_ports += 1

    # DC sources at 0V potential are equivalent to a 0 resistance path to ground.
    if self.region.dc_biases:
      spice_test += '\n** dc biases\n'
      num_dc_biases = 0
      for dc_bias in self.region.dc_biases.values():
        spice_test += f'.NODESET {dc_bias.wire.SpiceName()} 0\n'
        num_dc_biases += 1

    if self.region.loads:
      spice_test += '\n** simulated loads ommitted for linear analysis\n'
      #num_caps = 0
      #for load in self.region.loads:
      #  spice_test += f'C{num_caps} {load.wire.SpiceName()} {self.ground_name} C={load.value}\n'
      #  num_caps += 1

    spice_test += '\n' + self.StepStatements()

    spice_test += textwrap.dedent(f"""
        .AC DEC {self.num_points} {self.start_freq_hz} {self.stop_freq_hz}
        .PRINT AC FORMAT=CSV
        .LIN LINTYPE={self.parameter_type.name}
        .END
        """)

    with open(self.test_file_name, 'w') as f:
      f.write(spice_test)
    print(f'wrote {self.test_file_name}')


class LinearAnalysisResults:

  def __init__(self):
    self.ac_params = None
    self.ac_analysis = None
    self.ports = []
    self.tags = []


class SpiceAnalyser:

  def __init__(self, design, output_directory, spice_libs):
    self.design = design
    self.spice_writer = spice.SpiceWriter(design)
    self.output_directory = output_directory
    self.spice_libs = spice_libs

    self.regions = {}

    self.manifest = manifest_pb.TestManifest()
    self.analysis = analysis_pb.CircuitAnalysis()

    # A sparse matrix of the delays (plural!) measured between some source
    # and sink wire. A wire is a net - a signal and an index.
    self.wire_delays = collections.defaultdict(
        lambda: collections.defaultdict(list))

  def LoadRegionList(self, region_list):
    self.regions = {region.name: region for region in region_list}

  def _LoadDesignRegionsFromAnalysis(self):
    regions = []
    for region_pb in self.analysis.design_regions:
      region = circuit.DesignRegion([])
      region.name = region_pb.name
      region.dut_type = PROTO_TO_DUT_TYPE[region_pb.dut_type]
      # We need to have the complete module loaded for this to make sense.
      if region.dut_type in (
          circuit.DesignRegion.DUTType.SUB_REGION,
          circuit.DesignRegion.DUTType.MODULE):
        module = self.design.known_modules[region_pb.for_top_module]
      else:
        module = self.design.external_modules[region_pb.for_top_module]
      region.module = module

      for instance_name in region_pb.instances:
        region.instances.append(module.instances[instance_name])
      for dc_bias in region_pb.dc_biases:
        wire = SpiceAnalyser._NetToWire(module, dc_bias.net)
        region.dc_biases[wire.SpiceName()] = spice.DCVoltageSource(wire)
      for voltage_probe in region_pb.voltage_probes:
        wire = SpiceAnalyser._NetToWire(module, voltage_probe.net)
        region.voltage_probes[wire.SpiceName()] = spice.VoltageProbe(wire)
      for driver in region_pb.drivers:
        wire = SpiceAnalyser._NetToWire(module, driver.net)
        region.simulated_drivers[wire.SpiceName()] = spice.SimulatedDriver(wire)
      for port_pb in region_pb.ports:
        wire = SpiceAnalyser._NetToWire(module, port_pb.net)
        spice_port = spice.Port(wire)
        spice_port.load_capacitance = NumericalValue(port_pb.load_capacitance_f)
        region.port_network_ports[wire.SpiceName()] = spice_port

      region.loads = []
      regions.append(region)

    self.LoadRegionList(regions)

  def _LoadTestManifest(self):
    for linear in self.manifest.linear_analyses:
      try:
        region = self.regions[linear.design_region_name]
      except KeyError:
        continue
      
      ports = {port.wire.SpiceName(): port
               for port in region.port_network_ports.values()}
      for test_port in linear.ports:
        try:
          port = ports[test_port.node]
          port.number = test_port.number
        except KeyError:
          continue

  def _ReadProtos(self, manifest_proto_path, analysis_proto_path):
    with open(manifest_proto_path, 'rb') as f:
      self.manifest.ParseFromString(f.read())
    with open(analysis_proto_path, 'rb') as f:
      self.analysis.ParseFromString(f.read())
    self._LoadDesignRegionsFromAnalysis()
    self._LoadTestManifest()

  @staticmethod
  def _NetToWire(module, net_pb):
    if type(module) is circuit.Module:
      signal_name = net_pb.signal_name
      signal = module.signals[signal_name]
      index = net_pb.index
      return circuit.Wire(signal, index)
    elif type(module) is circuit.ExternalModule:
      signal = module.ports[net_pb.signal_name].signal
      return circuit.Wire(signal, net_pb.index)

  @staticmethod
  def _NameToWire(module, spice_name, strip_prefixes=False):

    def SplitIndex(string):
      match = re.match('^(.*)\.(\d+)$', string)
      if not match:
        return string, 0
      return match.group(1), int(match.group(2))

    name = spice_name
    if strip_prefixes:
      name = SpiceAnalyser._StripStringPrefix(name, 'X0')
    name, index = SplitIndex(name)

    if type(module) is circuit.ExternalModule:
      try:
        signal = module.ports[name].signal
        return circuit.Wire(signal, index)
      except KeyError:
        print(f'Could not find port for external module from spice net {spice_name}')

    try:
      signal = module.signals[name]
      return circuit.Wire(signal, index)
    except KeyError:
      print(f'Could not find signal and index for spice net {spice_name}')
      return None

  @staticmethod
  def _StripStringPrefix(string, prefix):
    if string.startswith(prefix):
      return string[len(prefix) + 1:]
    return string

  def _ReadTransientResults(self, tags=None):
    tags_set = set(tags) if tags else None
    regions = []
    for transient in self.manifest.transient_analyses:
      if tags_set and not tags_set.intersection(set(transient.tags)):
        continue
      region_name = transient.design_region_name
      try:
        region = self.regions[region_name]
      except KeyError as e:
        print(f'Region not found: {region_name}; test: {transient}')
        continue

      module = region.module
      regions.append(region)

      strip_prefixes = False
      if region.dut_type == circuit.DesignRegion.DUTType.MODULE:
        strip_prefixes = True

      # NOTE(growly): Xyce variable names are printed uppercase. We have to
      # make our matches case-insensitive.
      # NOTE(growly): We should include in the test manifest what kinds of
      # results to expect. For example, the .mt0 files will only be created if
      # the test has a .MEASURE statement. Likewise, .fft0 will only be created
      # if there are .FFT statements.
      measure_results_file = f'{transient.spice_source_file}.mt0'

      delays = {}
      for delay_computation in transient.delay_computations:
        trigger = delay_computation.trigger_node
        target = delay_computation.target_node
        variable_name = delay_computation.spice_variable_name.upper()
        delays[variable_name] = (trigger, target)

      others = {}
      for measurement in transient.measurements:
        others[measurement.spice_variable_name] = None

      measured = spice_util.ReadMeasurementsFile(measure_results_file)
      for key, value in measured.items():
        variable_name = key.upper()

        if variable_name in others:
          others[variable_name] = value
          continue

        try:
          trigger, target = delays[variable_name]
        except KeyError as e:
          print(f'Unexpected measurement "{variable_name}" in file '
                f'{measure_results_file} for {transient}')
          continue

        try:
          trigger_wire = SpiceAnalyser._NameToWire(
              module, trigger, strip_prefixes)
        except:
          trigger_wire = None
        try:
          target_wire = SpiceAnalyser._NameToWire(
              module, target, strip_prefixes)
        except:
          trigger_wire = None

        if trigger_wire and target_wire:
          self.wire_delays[trigger_wire][target_wire].append(
              (transient.tags, value, transient))
        else:
          region.other_delays.append(
              (variable_name, trigger, target, value, transient))

      region.other_measurements[measure_results_file] = (
          others, transient)

      fft_results_file = f'{transient.spice_source_file}.fft0'
      fft = spice_util.ReadFFTFile(fft_results_file)
      # Just store results per signal name, don't bother resolving to
      # Signal/Wire objects.
      # TODO(growly): To track additional dimensionality to FFT results, just
      # as we do for LinearAnalysisResults, contain them in an 'FFTResult'
      # object or similar.
      region.fft_results[fft_results_file] = fft

      probe_results_file = f'{transient.spice_source_file}.prn'
      probe_results = spice_util.ReadPrintFileForTimeSeries(probe_results_file)
      if 'TIME' in probe_results:
        time = probe_results['TIME']
        for key, series in probe_results.items():
          if key in ('TIME', 'Index'):
            continue
          match = SIGNAL_FROM_XYCE_V_STATEMENT_RE.match(key)
          if match:
            signal_name = match.group(1)
            series = probe_results[key]
            region.probe_results[
                signal_name] = np.array([time, series]).transpose()

        region.transient_pbs.append(transient)

    return regions

  def _ReadLinearResults(self, tags=None):
    tags_set = set(tags) if tags else None
    regions = []
    for linear in self.manifest.linear_analyses:
      if tags_set and not tags_set.intersection(set(linear.tags)):
        continue

      region_name = linear.design_region_name
      try:
        region = self.regions[region_name]
      except KeyError as e:
        print(f'Region not found: {region_name}; test: {linear}')
        continue
      num_ports = len(region.port_network_ports)
      linear_sweep_file = f'{linear.spice_source_file}.s{num_ports}p'
      linear_step_file = f'{linear.spice_source_file}.res'

      module = region.module
      regions.append(region)

      results = LinearAnalysisResults()
      results.tags.extend(linear.tags)

      ports_pb = sorted(linear.ports, key=lambda x: x.number)
      for port in ports_pb:
        wire = SpiceAnalyser._NameToWire(module, port.node)
        results.ports.append(wire)
      results.ac_analysis = spice_util.ReadACAnalysisFile(linear_sweep_file)
      results.ac_params = spice_util.ReadStepFile(linear_step_file)
      region.linear_analyses = results

      region.linear_pbs.append(linear)

    return regions

  def _GetEffectiveLoadCapacitanceForSpicePort(self, port):
    if port.load_capacitance:
      return port.load_capacitance
    wire = port.wire
    signal = wire.signal
    index = wire.index
    possible_ports = signal.FindLoadPorts(index=index)
    if not possible_ports:
      return None
    # Just take the first one.
    port_name, module, load_port = possible_ports.pop()
    if type(module) is circuit.ExternalModule:
      return module.MakeReasonableGuessAtInputCapacitanceForPort(port_name, index)
    return None

  def _ApproximateDelaysFromAdmittances(self, region, results):
    # TODO(growly): Same problems as _FindSmallSignalInputCapacitance.
    results = region.linear_analyses
    if not results or not results.ac_analysis:
      return

    num_ports = len(region.port_network_ports)
    print(f'approximating delay from {num_ports}-port network Y parameters '
          f'for {region.name}')
    module = region.module
    for step, ac in results.ac_analysis.items():
      # We don't have multiple params for these runs yet:
      params = results.ac_params[step] if step in results.ac_params else None
      if params:
        raise NotImplementedError('can\'t do approximations per step yet')

      num_points = len(ac)
      phase_delays = collections.defaultdict(lambda: collections.defaultdict(
        lambda: np.zeros((num_points, 2))))

      for spice_port in region.port_network_ports.values():
        # Here we deal only with numpy data structures, so indices are 0-based,
        # as is sane.
        i = spice_port.number - 1

        # We load all ports but i with the input capacitance we expect for the
        # module.
        load_capacitances = np.zeros(num_ports)
        for other_spice_port in region.port_network_ports.values():
          if other_spice_port is spice_port:
            continue
          load = self._GetEffectiveLoadCapacitanceForSpicePort(other_spice_port)
          if load is not None:
            load_capacitances[other_spice_port.number - 1] = load.InBaseUnits().value

        frequencies_hz = []
        for k, (freq_hz, small_signal_params) in enumerate(ac.items()):
          frequencies_hz.append(freq_hz)

          Y = small_signal_params.matrix + np.diag(
              load_capacitances * np.complex(0, 1) * 2 * np.pi * freq_hz)

          # Set up system to solve. Fix input port current to 1 and other to 0,
          # since they are not independent.
          I = np.zeros(num_ports)
          I[i] = 1.0
          
          V = np.linalg.solve(Y, I)
          
          # Overall input admittance at port i:
          #Y_in = 1/V[i]

          period = 1/freq_hz
          for other_spice_port in region.port_network_ports.values():
            if other_spice_port is spice_port:
              continue
            j = other_spice_port.number - 1
            transfer_i_j = V[j]/V[i]
            phase = np.angle(transfer_i_j)
            phase_delay = -phase/(2*np.pi)*period

            # We have the phase_delay of the freq_hz harmonic component from
            # input i to output j.
            phase_delays[spice_port][other_spice_port][k, 0] = freq_hz
            phase_delays[spice_port][other_spice_port][k, 1] = phase_delay

      return phase_delays


  def ReportWholeModuleInputRamps(self):
    # Separate regions from the module test:
    sub_regions = []
    whole_module_regions = []
    for region in self.regions.values():
      if region.HasResultsForTag('module_test'):
        whole_module_regions.append(region)
      if region.HasResultsForTag('region_test'):
        sub_regions.append(region)

    sub_region_drivers = []
    for region in sub_regions:
      sub_region_drivers.extend(region.simulated_drivers.values())

    print(f'will extract input ramps from {len(sub_regions)} regions in '
          f'{len(whole_module_regions)} whole module regions')
    for region in whole_module_regions:
      results_by_signal = region.probe_results
      if not results_by_signal:
        continue

      signals_to_plot = [
          driver.wire.SpiceName().upper()
          for driver in region.simulated_drivers.values()] + [
          'X0:' + driver.wire.SpiceName().upper()
          for driver in sub_region_drivers]

      for spice_name in signals_to_plot:
        if spice_name not in results_by_signal:
          continue

        print(f'extracting probe data for {spice_name} in {region.name}')

        results = results_by_signal[spice_name]

        time = results[:, 0]
        values = results[:, 1]

        # Centre graphs around VDD/2.
        min_y = min(values)
        max_y = max(values)
        half_y = (max_y - min_y)/2 + min_y
        x_centre = None
        for i, y in enumerate(values):
          if y > half_y:
            x_centre = time[i]
            break

        if x_centre is not None:
          window = 60E-11  # seconds
          x_min = x_centre - window/2
          x_min_index = 0
          x_max = x_centre + window/2
          x_max_index = len(values)
          for i, x in enumerate(time):
            if x >= x_min and x_min_index == 0:
              x_min_index = i
            if x >= x_max and x_max_index == len(values):
              x_max_index = i
          values = values[x_min_index:x_max_index]
          time = time[x_min_index:x_max_index]

        h = plt.figure()
        plt.plot(time, values)
        file_name = f'auto.{region.name}.{spice_name}.input_ramp.png'
        save_path = os.path.join(self.output_directory, file_name)
        plt.title(f'{spice_name} ramp, {region.name}')
        plt.xlabel('time (s)')
        plt.ylabel('voltage (V)')
        #plt.show()
        plt.savefig(save_path)
        plt.close(h)
        

  def AnalyseModuleTests(self,
                         manifest_proto_path,
                         analysis_proto_path,
                         csv_file_path):
    self._ReadProtos(manifest_proto_path, analysis_proto_path)
    tags = ['module_test', 'region_test']
    self._ReadTransientResults(tags=tags)
    self._ReadLinearResults(tags=tags)

    #self.ReportWholeModuleInputRamps()

    # TODO(you): Other analysis can go here.

    if csv_file_path:
      self.DumpRegionTestDelayMeasurements(csv_file_path)

  def DumpRegionTestDelayMeasurements(self, csv_file_name):
    headers = set()
    rows = []
    for source, sinks in self.wire_delays.items():
      for sink, values in sinks.items():
        row = {
            'source': source.SpiceName(),
            'sink': sink.SpiceName()
        }
        for tags, measurement, _ in values:
          tag = tags[0] if tags else 'none'
          row[tag] = measurement
          headers.add(tag)
        rows.append(row)

    with open(csv_file_name, 'w') as f:
      field_names = ['source', 'sink'] + sorted(headers)
      csv_writer = csv.DictWriter(f, field_names)
      csv_writer.writeheader()
      for row in rows:
        csv_writer.writerow(row)

  def _FindSmallSignalInputCapacitance(self, region):
    results = region.linear_analyses
    if not results or not results.ac_analysis:
      return
    module = region.module
    for step, ac in results.ac_analysis.items():
      params = results.ac_params[step] if step in results.ac_params else None
      # TODO(growly): A more elegant structure is needed to reason about
      # and manipulate the multi-dimensional capacitance results.
      if not params:
        continue
      voltage_params = {key: value for key, value in params.items() if 'V_BIAS' in key}
      # NOTE(growly): We arbitrarily pick the 0.35V point for each bias voltage
      # and find the input capacitance there.
      if any(float(value) != 0.35 for _, value in voltage_params.items()):
        continue
      for test_port in region.port_network_ports.values():
        i = test_port.number
        min_C_ii = None
        max_C_ii = None
        sum_C_ii = 0.0
        for freq_hz, matrix in ac.items():
          # Z_ii is the input impedance assuming all other ports open.
          # We start here.
          Z_ii = matrix[i, i]
          C_ii = -1/(2*math.pi*freq_hz*np.imag(Z_ii))
          min_C_ii = C_ii if min_C_ii is None else min(C_ii, min_C_ii)
          max_C_ii = C_ii if max_C_ii is None else max(C_ii, max_C_ii)
          sum_C_ii += C_ii
        avg_C_ii = sum_C_ii / len(ac)

        if not type(module) is circuit.ExternalModule:
          raise NotImplementedError()
        # TODO(growly): Unfortunately in ExternalModules we call Signals the
        # same names as the Ports connecting to them.
        port_name = test_port.wire.signal.name
        port_index = test_port.wire.index
        module.input_capacitances[port_name][port_index] = avg_C_ii

    # TODO(growly): Find large-signal input capacitance through transient
    # analysis.

  def _FindLargeSignalStepInputCapacitance(self, region):
    # In _AddLargeSignalStepInputCapacitance we set up a measurement for
    # the RC delay. In the measurement results we expect to have this delay,
    # which is just \tau = RC, and we set R = 10k, so we solve for C.
    # TODO(growly): It would be nice if this were contained in the test
    # description or, even better, computed by Xyce directly using an EQN
    # .MEASURE expression.
    results = region.other_delays
    module = region.module
    for name, trigger, target, value, transient_pb in results:
      if 'RC_DELAY' in name and trigger == 'in':
        C = value / 10000.0
        module.large_signal_step_capacitances[target] = C

  def _FindLargeSignalSinusoidalInputCapacitance(self, region):
    results_by_file = region.other_measurements
    module = region.module
    for _, (results, transient_pb) in results_by_file.items():
      # To compute large signal sinusoidal capacitance, we need:
      #   output amplitude, input amplitude, phase delay
      in_max = None
      in_min = None
      port_max = None
      port_min = None
      in_cross_time = None
      port_cross_time = None

      port_name = None

      for measurement in transient_pb.measurements:
        variable_name = measurement.spice_variable_name
        if variable_name not in results or (results[variable_name] is None):
          continue
        if variable_name == 'IN_MAX':
          in_max = results[variable_name]
        elif variable_name == 'IN_MIN':
          in_min = results[variable_name]
        elif variable_name.endswith('_MAX'):
          assert port_name is None or port_name == measurement.target_node
          port_name = measurement.target_node
          port_max = results[variable_name]
        elif variable_name.endswith('_MIN'):
          assert port_name is None or port_name == measurement.target_node
          port_name = measurement.target_node
          port_min = results[variable_name]
        elif variable_name == 'IN_WHEN':
          in_cross_time = results[variable_name]
        elif variable_name.endswith('_WHEN'):
          assert port_name is None or port_name == measurement.target_node
          port_name = measurement.target_node
          port_cross_time = results[variable_name]
      
      if any(x is None for x in (
        in_max, in_min, port_max, port_min, port_cross_time, in_cross_time)):
        continue

      # In _AddLargeSignalSinusoidalInputCapacitanceTest, we made the base_freq:
      # 25.0 * (1/1500E-12)
      freq_hz = 25.0 * (1/1500E-12)

      # But in general Xyce will, by default, take 1/(test_duration) as the
      # base frequency.

      period = 1/ freq_hz

      # In this test, we have applied a pure sinusoid at the input and measured
      # the effect on this sinusoid by measuring the sinusoid at the output.
      # From the amplitude and phase offset we can compute the transfer
      # function, notably modeling it as:
      # Vo = A * exp(-i * phase_offset) * Vi
      # Vo = beta * Vi
      phase_offset = 2*np.pi*(port_cross_time - in_cross_time)/period
      output_amplitude = port_max - port_min
      input_amplitude = in_max - in_min
      if input_amplitude == 0:
        continue
      A = output_amplitude/input_amplitude
      beta = A * np.exp(-np.complex(0, 1)*phase_offset)
      
      # Since we have created a basic voltage divider between the input R and
      # the input capacitance C, the transfer function is also:
      # Vo = Z_i / (Z_R + Z_i), where Z_i is the input impedance to the port
      # Z_i = Z_C + Z_R_i, and Z_R is the resistance impedance (10k) we
      # inserted.
      Z_R = 10000.0
      
      # Therefore, we can equate and solve for beta:
      Z_i = Z_R*(beta/(1-beta))
      
      # Whose equivalent capacitive component is:
      C = -1/(2*np.pi*freq_hz*np.imag(Z_i))
      module.large_signal_sinusoidal_capacitances[port_name] = C

  def FindInputCapacitances(self, manifest_proto_path, analysis_proto_path):
    self._ReadProtos(manifest_proto_path, analysis_proto_path)
    tags = ['measure_input_capacitance']
    transients = self._ReadTransientResults(tags=tags)
    linears = self._ReadLinearResults(tags=tags)

    regions_with_results = set(transients + linears)
    for region in regions_with_results:
      self._FindSmallSignalInputCapacitance(region)
      self._FindLargeSignalStepInputCapacitance(region)
      self._FindLargeSignalSinusoidalInputCapacitance(region)

  def DumpInputCapacitances(self, csv_file_name):
    # This works because most cells re-use port names.
    headers = set()
    rows = []
    for module in self.design.external_modules.values():
      if not type(module) is circuit.ExternalModule:
        continue
      row = {}
      for port_name in module.port_order:
        delay_guess = module.MakeReasonableGuessAtInputCapacitanceForPort(
            port_name)
        if not delay_guess:
          continue
        row[port_name] = delay_guess
        headers.add(port_name)
      if row:
        row['module_name'] = module.name
        rows.append(row)
        print(f'{row=}')

    with open(csv_file_name, 'w') as f:
      field_names = ['module_name'] + sorted(headers)
      csv_writer = csv.DictWriter(f, field_names)
      csv_writer.writeheader()
      for row in rows:
        csv_writer.writerow(row)

  def _AddSmallSignalInputCapacitanceTest(self, module, region, subckt_file):
    # NOTE(growly): A brief "hand-" study of the input capacitance of pin A
    # on the AND2x2 cell suggested that the measured small signal capacitance
    # lines up with the Liberate-provided characterisations, and is somewhat
    # flat over, the range 10 kHz to 100 GHz. As a shortcut to more cleverly
    # determining the effective capacitance, we will take the simple average
    # over this range:
    linearZ = LinearAnalysisTest(self.design,
                                 region,
                                 self.manifest,
                                 self.spice_libs,
                                 output_directory=self.output_directory,
                                 include_subckt=subckt_file,
                                 parameter_type=LinearAnalysisTest.Type.Z,
                                 start_freq_hz=1E5,
                                 stop_freq_hz=1E10,
                                 tags=['measure_input_capacitance'])


    for port_name, port in module.ports.items():
      signal = port.signal
      if signal.name in self.design.power_net_names or (
          signal.name in self.design.ground_net_names):
        continue
      for index in range(signal.width):
        wire = circuit.Wire(signal, index)
        port_bias_param = linearZ.GetOrCreateSweepParameter(spice.SweepParameter(
            # TODO(growly): Make these NumericalValues.
            f'V_BIAS_{port_name}_{index}', low=0.0, high=0.7, step=0.35))
        port = spice.Port(wire, port_bias_param)
        if wire.SpiceName() in region.port_network_ports:
          raise Exception('a new wire, that would have been appended, is now '
                          f'overwriting another port {port}: {wire.SpiceName()}')
        region.port_network_ports[wire.SpiceName()] = port

    if not region.port_network_ports:
      print(f'design region {region.name} for module {module.name} has not '
            'defined any port network ports, no linear test will be written')
      # No ports. Nothing to test. Abandon.
      return
    
    linearZ.Write()

  def _AddLargeSignalSinusoidalInputCapacitanceTest(
      self, module, region, subckt_file, input_wire, all_input_wires, output_wire,
      ground_wire, suffix):
    transient, test_input_wire = self._MakeLargeSignalInputCapacitanceTest(
        module, region, subckt_file, input_wire, all_input_wires, output_wire,
        ground_wire, suffix)

    # We target the same base frequency as we end up using for the FFT of the
    # whole-module transient test, which is dictated (according to the Xyce reference)
    # by the period of that test. It ends up being 1.67E10 Hz for a transient simulation
    # of 1500 ps.
    base_freq_hz = 25.0 * (1/1500E-12)
    offset_v = NumericalValue(0.35)

    measurement_window_start = NumericalValue(0.4, SIUnitPrefix.NANO) # Seconds.

    transient.AddInputWaveform(spice.SinusoidalInput(
        test_input_wire, ground_wire,
        offset_v=offset_v,
        amplitude_v=NumericalValue(0.35),
        frequency_hz=NumericalValue(base_freq_hz)))
    transient.AddFFTSpec(spice.FFTSpec(test_input_wire))
    transient.AddFFTSpec(spice.FFTSpec(input_wire))

    measurement = spice.Measurement(
        test_input_wire, spice.Measurement.MeasureType.MAX)
    measurement.from_time = measurement_window_start
    transient.AddOtherMeasurement(measurement)

    measurement = spice.Measurement(
        test_input_wire, spice.Measurement.MeasureType.MIN)
    measurement.from_time = measurement_window_start
    transient.AddOtherMeasurement(measurement)

    measurement = spice.Measurement(
        input_wire, spice.Measurement.MeasureType.MAX)
    measurement.from_time = measurement_window_start
    transient.AddOtherMeasurement(measurement)

    measurement = spice.Measurement(
        input_wire, spice.Measurement.MeasureType.MIN)
    measurement.from_time = measurement_window_start
    transient.AddOtherMeasurement(measurement)

    in_cross = spice.Measurement(test_input_wire, spice.Measurement.MeasureType.WHEN)
    in_cross.target_value = offset_v
    in_cross.from_time = measurement_window_start
    transient.AddOtherMeasurement(in_cross)

    port_cross = spice.Measurement(input_wire, spice.Measurement.MeasureType.WHEN)
    port_cross.target_value = offset_v
    port_cross.from_time = measurement_window_start
    transient.AddOtherMeasurement(port_cross)

    transient.Write()

  def _AddLargeSignalStepInputCapacitanceTest(
      self, module, region, subckt_file, input_wire, all_input_wires, output_wire,
      ground_wire, suffix):

    high_voltage = NumericalValue(0.7)
    transient, test_input_wire = self._MakeLargeSignalInputCapacitanceTest(
        module, region, subckt_file, input_wire, all_input_wires, output_wire,
        ground_wire, suffix)
    transient.AddInputWaveform(spice.StepInput(
        test_input_wire, ground_wire,
        low_voltage=NumericalValue(0.0),
        high_voltage=high_voltage,
        delay_s=NumericalValue(1.0, SIUnitPrefix.PICO),
        rise_time_s=NumericalValue(0.1, SIUnitPrefix.FEMTO),
        fall_time_s=NumericalValue(5.0, SIUnitPrefix.PICO),
        pulse_width_s=NumericalValue(2, SIUnitPrefix.NANO),
        period_s=NumericalValue(4, SIUnitPrefix.NANO)))

    rc_delay = spice.DelayMeasurement(test_input_wire, input_wire)
    rc_delay.name = f'{input_wire.SpiceName()}_rc_delay'
    # We measure from VDD/2 because we set the rise time to be infinetismal (.1
    # fs), and we just want to approximate the step point.
    rc_delay.source_value = NumericalValue(
        high_voltage.InBaseUnits().value / 2.0, None)
    rc_delay.sink_value = NumericalValue(
        high_voltage.InBaseUnits().value * (1.0 - math.exp(-1.0)), None)

    transient.AddDelayMeasurement(rc_delay)

    transient.Write()

  def _MakeLargeSignalInputCapacitanceTest(
      self, module, region, subckt_file, input_wire, all_input_wires, output_wire,
      ground_wire, suffix):
    """Generate the TransientTest common to large signal input capacitance tests.
    """
    transient = TransientTest(self.design,
                              region,
                              self.manifest,
                              self.spice_libs,
                              include_subckt=subckt_file,
                              output_directory=self.output_directory,
                              subckt_name=module.name,
                              input_delay_ps=1.0,
                              input_rise_time_ps=0.00001,
                              input_fall_time_ps=5.0,
                              input_width_ps=2000.0,
                              duration_ps=1000.0,
                              test_suffix=suffix,
                              tags=['measure_input_capacitance'])

    for wire in all_input_wires:
      if wire is input_wire:
        continue
      transient.AddBias(spice.DCVoltageSource(wire, value=NumericalValue(0.35)))

    # Oh man this is ugly, now that we've come this far.
    test_input_signal = circuit.Signal('in', width=1)
    input_resistor = circuit.Resistor(
        test_input_signal, input_wire.signal,
        value=NumericalValue(10, SIUnitPrefix.KILO))
    input_resistor.name = 'R1'
    transient.AddInstance(input_resistor)

    test_input_wire = circuit.Wire(test_input_signal, 0)
    transient.AddVoltageProbe(spice.VoltageProbe(input_wire))

    return transient, test_input_wire

  def AddInputCapacitanceTests(self, module):
    region = circuit.DesignRegion()
    region.name = module.name
    region.module = module
    if type(module) is circuit.Module:
      region.dut_type = circuit.DesignRegion.DUTType.MODULE
    elif type(module) is circuit.ExternalModule:
      region.dut_type = circuit.DesignRegion.DUTType.EXTERNAL_MODULE
    subckt_file = None
    if type(module) is circuit.Module:
      # Do not write out external modules; assume the definitions are included
      # in spice libraries given to use.
      subckt_file = os.path.join(self.output_directory, f'{module.name}.sp')
      self.spice_writer.WriteModule(module, subckt_file)
      print('wrote ' + subckt_file)

    # Set up the subcircuit for testing.
    self.AddDCSourcesForPowerNets(module, region)
    # FIXME(growly): Figure this out once!
    ground_wire = circuit.Wire(circuit.Signal('0'), 0)

    in_wires = []
    inout_wires = []
    out_wires = []
    for _, port in module.ports.items():
      # port is a circuit.Port.
      wires = [circuit.Wire(port.signal, i) for i in range(port.signal.width)]
      if port.direction == circuit.Port.Direction.INPUT:
        in_wires.extend(wires)
      elif port.direction == circuit.Port.Direction.INOUT:
        inout_wires.extend(wires)
      elif port.direction == circuit.Port.Direction.OUTPUT:
        out_wires.extend(wires)

    region.in_wires = in_wires
    region.inout_wires = inout_wires
    region.out_wires = out_wires

    for out_wire in out_wires:
      region.loads.append(
          spice.CapacitiveLoad(
              out_wire, value=NumericalValue(2.0, SIUnitPrefix.FEMTO)))

    self._AddSmallSignalInputCapacitanceTest(module, region, subckt_file)

    num_linear_tests = 0
    for in_wire in in_wires:
      for out_wire in out_wires:
        self._AddLargeSignalStepInputCapacitanceTest(
            module, region, subckt_file, in_wire, in_wires, out_wire,
            ground_wire, suffix=str(num_linear_tests))
        self._AddLargeSignalSinusoidalInputCapacitanceTest(
            module, region, subckt_file, in_wire, in_wires, out_wire,
            ground_wire, suffix=str(num_linear_tests + 1))
        num_linear_tests += 2

    self.AddRegionToAnalysisProto(region)

  def AddDCSourcesForPowerNets(self, module, region):
    for power_net in self.design.power_net_names:
      power_signal = None
      if type(module) is circuit.Module:
        try:
          power_signal = module.signals[power_net]
        except KeyError:
          continue
      elif type(module) is circuit.ExternalModule:
        try:
          power_signal = module.ports[power_net].signal
        except KeyError:
          continue
      else:
        continue
      for i in range(power_signal.width):
        wire = circuit.Wire(power_signal, i)
        region.dc_sources[wire.SpiceName()] = spice.DCVoltageSource(
            wire, value=NumericalValue(0.7, None))

  def AddModuleTest(self, module, use_regions=False):
    """Add a whole-module test, testing only inputs/outputs.

    If use_regions is True, also include probes from stored regions that may
    apply, so that they can be compared."""

    region = circuit.DesignRegion()
    region.name = module.name
    region.module = module
    region.dut_type = circuit.DesignRegion.DUTType.MODULE

    subckt_file = os.path.join(self.output_directory, f'{module.name}.sp')
    self.spice_writer.WriteModule(module, subckt_file)
    print('wrote ' + subckt_file)

    port_order = module.port_order

    self.AddDCSourcesForPowerNets(module, region)
    
    # TODO(growly): Make it easy to determine the logical input values.
    for port_name, port in module.ports.items():
      wires = [circuit.Wire(port.signal, i) for i in range(port.signal.width)]
      if port.direction == circuit.Port.Direction.INPUT:
        # Attach a driver to each input port.
        region.simulated_drivers.update({
          wire.SpiceName(): spice.SimulatedDriver(wire) for wire in wires})
      elif port.direction in (circuit.Port.Direction.INOUT, circuit.Port.Direction.OUTPUT):
        # Attach a probe to each output.
        region.voltage_probes.update({
          wire.SpiceName(): spice.VoltageProbe(wire) for wire in wires})
        # Attach a fake load.
        region.loads.update({
            wire.SpiceName(): spice.CapacitiveLoad(
                wire, value=NumericalValue(2, SIUnitPrefix.FEMTO))
            for wire in wires})
      else:
        # Port is direction NONE?
        pass

    linearY = None
    transient = TransientTest(self.design,
                              region,
                              self.manifest,
                              self.spice_libs,
                              include_subckt=subckt_file,
                              subckt_name=module.name,
                              duration_ps=2000.0,
                              tags=['module_test'])

    if use_regions:
      for region_name, sub_region in self.regions.items():
        # TODO(growly): We assume that there is only one subcircuit, the module
        # we are testing, since there is no other indication of the instance in
        # which each wire/signal appears.
        for driver in sub_region.simulated_drivers.values():
          region.subcircuit_voltage_probes.append(
              spice.VoltageProbe(driver.wire))

          transient.AddFFTSpec(spice.FFTSpec(driver.wire, in_subcircuit='X0'))

          for voltage_probe in sub_region.voltage_probes.values():
            region.subcircuit_delay_measurements.append(
                spice.DelayMeasurement(driver.wire, voltage_probe.wire))
        region.subcircuit_voltage_probes.extend(sub_region.voltage_probes.values())

    transient.Write()
    self.AddRegionToAnalysisProto(region)

  # We are interested in the ${metric} of a particular DesignRegion. Start
  # with Delay. The scheme must ground inout pins, load output pins, and ramp
  # some input pin, or something, or just get the Y-parameters.
  def AddRegionTest(self, region):
    subckt_file = os.path.join(self.output_directory, f'auto.{region.name}.sp')
    self.spice_writer.WriteRegion(subckt_file, region)
    print('wrote ' + subckt_file)

    linearY = LinearAnalysisTest(self.design,
                                 region,
                                 self.manifest,
                                 self.spice_libs,
                                 include_subckt=subckt_file,
                                 tags=['region_test'])
    linearY.Write()

    transient = TransientTest(self.design,
                              region,
                              self.manifest,
                              self.spice_libs,
                              include_subckt=subckt_file,
                              duration_ps=1500,
                              tags=['region_test'])
    #for driver in region.simulated_drivers:
    #  transient.AddFFTSpec(spice.FFTSpec(driver.wire))

    transient.Write()
    self.AddRegionToAnalysisProto(region)

  def AddRegionToAnalysisProto(self, region):
    for region_pb in self.analysis.design_regions:
      if region_pb.name == region.name:
        print(f'warning: overwriting analysis entry for region "{region.name}" '
              'in analysis protocol buffer')
        self.analysis.design_regions.remove(region_pb)

    region_pb = self.analysis.design_regions.add()
    region_pb.name = region.name
    region_pb.dut_type = DUT_TYPE_TO_PROTO[region.dut_type]
    if region.dut_type == circuit.DesignRegion.DUTType.SUB_REGION:
      region_pb.for_top_module = self.design.top.name
    else:
      region_pb.for_top_module = region.module.name
    for instance in region.instances:
      region_pb.instances.append(instance.name)
    for dc_bias in region.dc_biases.values():
      dc_bias_pb = region_pb.dc_biases.add()
      dc_bias_pb.net.signal_name = dc_bias.wire.signal.name
      dc_bias_pb.net.index = dc_bias.wire.index
    for load in region.loads.values():
      load_pb = region_pb.loads.add()
      load_pb.net.signal_name = load.wire.signal.name
      load_pb.net.index = load.wire.index
      load_pb.value_f = load.value.InBaseUnits().value
    for driver in region.simulated_drivers.values():
      driver_pb = region_pb.drivers.add()
      driver_pb.net.signal_name = driver.wire.signal.name
      driver_pb.net.index = driver.wire.index
    for voltage_probe in region.voltage_probes.values():
      voltage_probe_pb = region_pb.voltage_probes.add()
      voltage_probe_pb.net.signal_name = voltage_probe.wire.signal.name
      voltage_probe_pb.net.index = voltage_probe.wire.index
    for port in region.port_network_ports.values():
      port_pb = region_pb.ports.add()
      port_pb.net.signal_name = port.wire.signal.name
      port_pb.net.index = port.wire.index
      if port.load_capacitance is not None:
        port_pb.load_capacitance_f = port.load_capacitance.InBaseUnits().value

  def _WriteManifest(self, file_name):
    manifest_file_name = file_name or os.path.join(
        self.output_directory, 'test_manifest.pb')
    with open(manifest_file_name, 'wb') as f:
      f.write(self.manifest.SerializeToString())

    text_manifest_file_name = os.path.join(self.output_directory, 'test_manifest.pb.txt')
    with open(text_manifest_file_name, 'w') as f:
      f.write(text_format.MessageToString(self.manifest))

  def _WriteAnalysis(self, file_name):
    analysis_file_name = file_name or os.path.join(
        self.output_directory, 'analysis.pb')
    with open(analysis_file_name, 'wb') as f:
      f.write(self.analysis.SerializeToString())

    text_analysis_file_name = os.path.join(self.output_directory, 'analysis.pb.txt')
    with open(text_analysis_file_name, 'w') as f:
      f.write(text_format.MessageToString(self.analysis))

  def AddRegionTests(self):
    for _, region in self.regions.items():
      self.AddRegionTest(region)

  def AddInputCapacitanceTestsForKnownModules(self, used_by_module=None):
    modules = set()
    if used_by_module is not None:
      for name, instance in used_by_module.instances.items():
        module = instance.module
        if type(instance.module) is circuit.Module and (
            module.name not in circuit.PRIMITIVE_MODULES):
          modules.add(module)
    else:
      modules.update(
          module for module in self.design.known_modules.values()
          if module.name not in circuit.PRIMITIVE_MODULES)

    for module in modules:
      self.AddInputCapacitanceTests(module)

  def AddInputCapacitanceTestsForExternalModules(self, used_by_module=None):
    ext_modules = set()
    if used_by_module is not None:
      for name, instance in used_by_module.instances.items():
        ext_module = instance.module
        if type(instance.module) is circuit.ExternalModule and (
            ext_module.name not in circuit.PRIMITIVE_MODULES):
          ext_modules.add(ext_module)
    else:
      ext_modules.update(
          ext_module for ext_module in self.design.external_modules.values()
          if ext_module.name not in circuit.PRIMITIVE_MODULES)

    for ext_module in ext_modules:
      self.AddInputCapacitanceTests(ext_module)

  def WriteMetadata(self, manifest_file_name, analysis_file_name):
    self._WriteManifest(manifest_file_name)
    self._WriteAnalysis(analysis_file_name)