PSF Utilities — Read Spectre Data Files

https://github.com/KenKundert/psf_utils/actions/workflows/build.yaml/badge.svg https://pepy.tech/badge/psf_utils/month https://img.shields.io/pypi/v/psf_utils.svg https://img.shields.io/pypi/pyversions/psf_utils.svg
Author:

Ken Kundert

Version:

1.8.1rc2

Released:

2024-04-21

What?

psf_utils is a library that allows you to read data from a Spectre PSF ASCII file. Spectre is a commercial circuit simulator produced by Cadence Design Systems. PSF files contain signals generated by Spectre. This package also contains two programs that are useful in their own right, but also act as demonstrators as to how to use the library. They are list-psf and show-psf. The first lists the available signals in a file, and the other displays them.

Accessing the Results

You can use the PSF class to read ASCII Parameter Storage Format files. When instantiating the class you pass in the path to the file and then the resulting PSF object contains the signals. For example, the following lists the signals present in a ASCII PSF file:

from psf_utils import PSF
from inform import Error, display

kinds = {
    'float double': 'real',
    'float complex': 'complex',
}

try:
    psf = PSF('adc.raw/tran.tran')

    for signal in psf.all_signals():
        kind = signal.type.kind
        kind = kinds.get(kind, kind)
        display(f'{signal.name:<15}  {signal.units:<12}  {kind}')
except Error as e:
    e.terminate()

This example plots the output signal:

from psf_utils import PSF
from inform import Error, display
import matplotlib.pyplot as plt

try:
    psf = PSF('adc.raw/tran.tran')
    sweep = psf.get_sweep()
    out = psf.get_signal('out')

    figure = plt.figure()
    axes = figure.add_subplot(1,1,1)
    axes.plot(sweep.abscissa, out.ordinate, linewidth=2, label=out.name)
    axes.set_title('ADC Output')
    axes.set_xlabel(f'{sweep.name} ({PSF.units_to_unicode(sweep.units)})')
    axes.set_ylabel(f'{out.name} ({PSF.units_to_unicode(out.units)})')
    plt.show()
except Error as e:
    e.terminate()

abscissa and ordinate are NumPy arrays. As such, you can perform computation with them:

out = out_p.ordinate - out_n.ordinate

from numpy import sin
sine = sin(sweep.abscissa)

Reading large ASCII data files is slow, so psf_utils reads the PSF file once, then pickles the data and writes it to disk. On subsequent runs the pickled data is used if the pickle file is newer that the corresponding PSF file.

Things are a bit different for DC operating point results. In this case, sweep is None and the results are scalar quantities:

from psf_utils import PSF, Quantity

psf = PSF('opamp.raw/op.dc')
with Quantity.prefs(map_sf=Quantity.map_sf_to_greek):
    for signal in sorted(psf.all_signals(), key=lambda s: s.name):
        name = f'{signal.access}({signal.name})'
        print(f'{name:>20} = {signal.ordinate}')

Utility Programs

Two utility programs are installed along with the psf_utils library: list-psf and show-psf. The first lists the signals available from a PSF file, and the second displays them. They both employ caching to speed up access to the data. They also cache the name of the PSF file so that it need not be given every time. show-psf also caches its arguments, so if you run it again with no arguments it will simply repeat what it did last time. For example, here is a typical session:

# list the signals in noise PSF file
> list-psf -f resistor.raw/pnoise.pnoise
Using resistor.raw/pnoise.pnoise.
    R1:flicker  R1:total    R2:fn       out
    R1:thermal  R2:rn       R2:total

# list them again, this time in long form
> list-psf -l
Using resistor.raw/pnoise.pnoise.
    R1:flicker  A²/Hz  real  (12042 points)
    R1:thermal  A²/Hz  real  (12042 points)
    R1:total    A²/Hz  real  (12042 points)
    R2:fn       A²/Hz  real  (12042 points)
    R2:rn       A²/Hz  real  (12042 points)
    R2:total    A²/Hz  real  (12042 points)
    out         A/√Hz  real  (12042 points)

# list only those that match R1:* (assumes nonomatch variable is set in shell)
> list-psf -l R1:*
Using resistor.raw/pnoise.pnoise.
    R1:flicker  A²/Hz  real  (12042 points)
    R1:thermal  A²/Hz  real  (12042 points)
    R1:total    A²/Hz  real  (12042 points)

# show a graph containing signals that start with R1:
> show-psf R1:*

# show the thermal noise of R1, and then the total noise minus the flicker noise
> show-psf R1:thermal R1:total-R1:flicker

> show-psf out        # show a graph containing only out

> show-psf            # show out again, exactly as in previous run

> show-psf -M out     # show out again, this time include point markers

> show-psf -P out     # show out again, this time only show point markers

> show-psf -s out.svg out     # send graph of out to svg file

# list signals in a PSF file from a DC operating point file:
> list-psf -f diffamp.raw/tran.dc
Using diffamp.raw/pnoise.pnoise.
    in_n    in_p    out_n   out_p   Vdd     Vdd:p

# show the DC voltages
> show-psf \*
     V(in_n) = 47.678 µV
     V(in_p) = 47.623 µV
    V(out_n) = 876.16 µV
    V(out_p) = 876.16 µV
      V(Vdd) = 2.5 V
    I(Vdd:p) = −10.05 µA

# list signals in transient PSF file
> list-psf -f diffamp.raw/tran.tran
Using diffamp.raw/pnoise.pnoise.
    in_n    in_p    out_n   out_p   Vdd     Vdd:p

# display differential output and differential input
> show-psf out_p-out_n in_p-in_n

Converting to PSF ASCII

psf_utils only supports PSF ASCII files. As an alternative, libpsf is a Python package that can read both ASCII and binary PSF files. Or, you can use the Cadence psf program to convert various types of simulation results files into PSF ASCII format. To use it, simply specify the input and output files:

> psf -i adc.raw/tran.tran -o adc.raw/tran.psfascii
> list-psf -f adc.raw/tran.psfascii

In this example there is nothing special about the ‘psfascii’ suffix, it is simply mnemonic. Rather, the output is in ASCII format because the -b (binary) option is not specified.

psf_utils does not support SST files, which are generated by AMS Designer, Cadence’s mixed-signal simulator. You can recognize SST files in that they come in pairs, and the two files have .dsn and .trn suffixes. In this case, Cadence’s PSF utility cannot help you either. However, you can use the simvisdbutil to convert the data to a CSV file, which would allow you to access the data, though not with psf_utils. For example, the following converts all waveforms contained in ldo.trn into CSV data:

simvisdbutil ldo.trn -csv -timeunits s -output ldo.csv

Examples

Flicker Noise is a simulation script that shows how to write simple Python scripts that run Spectre and use psf_utils to extract and display the desired results.

Releases

Latest development release

Version: 1.8.1rc2
Released: 2024-04-21

1.8 (2024-01-15)

  • Fixed issue with NaN

1.7 (2023-12-13)

  • fixed units on terminal currents

  • add support for inf

  • add support for PZ and STB files

1.6 (2022-09-18)

  • changed --no-cache command line option to --refresh-cache.

1.5 (2021-11-11)

  • Renamed plot-psf to show-psf.

  • Improved support of DC operating points.

  • Suppress access function names when printing members of PSF structures.

  • Correct invalid units produced by Spectre on oppoint files (I, R, C).

1.4 (2021-10-21)

  • Allow signal names to contain backslashes.

1.3 (2021-03-21)

  • Improve support for DC operating points.

1.2 (2021-01-07)

  • Support PSF files that contain DC operating points.

  • Support PSF files where values are given in a group.

1.1 (2021-01-30)

  • Allow, but ignore, properties on traces.

1.0 (2020-11-03)

  • Production release