Metadata-Version: 2.1
Name: psf_utils
Version: 1.3.0
Summary: Cadence PSF file utilities
Home-page: https://psf_utils.readthedocs.io
Author: Ken Kundert
Author-email: psf_utils@nurdletech.com
License: GPLv3+
Download-URL: https://github.com/kenkundert/psf_utils/tarball/master
Description: PSF Utilities - Read Spectre Data Files
        =======================================
        
        .. image:: https://img.shields.io/pypi/v/psf_utils.svg
            :target: https://pypi.python.org/pypi/psf_utils
        
        .. image:: https://img.shields.io/pypi/pyversions/psf_utils.svg
            :target: https://pypi.python.org/pypi/psf_utils/
        
        :Author: Ken Kundert
        :Version: 1.3.0
        :Released: 2021-03-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 *plot-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 a dictionary that containing 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* 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 
        <https://quantiphy.readthedocs.io>`_::
        
            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 *plot-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. *plot-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::
        
            # display 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
        
            # display 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)
        
            # display 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)
        
            # display a graph containing signals that start with R1:
            > plot-psf R1:*
        
            # display the thermal noise of R1, and then the total noise minus the flicker noise
            > plot-psf R1:thermal R1:total-R1:flicker
        
            # display a graph containing only out
            > plot-psf out
        
            > plot-psf            # display out again, exactly as in previous run
        
            > plot-psf -M out     # display out again, this time include point markers
        
            > plot-psf -P out     # display out again, this time only show point markers
        
            > plot-psf -s out.svg out     # send graph of out to svg file
        
            # display 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
        
            # display the DC voltages
            > plot-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
        
            # display 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
            > plot-psf out_p-out_n in_p-in_n
        
        
        Converting to PSF ASCII
        -----------------------
        
        *psf_utils* only supports PSF ASCII files. As an alternative, `libpsf
        <https://pypi.org/project/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 <https://github.com/KenKundert/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.3.0
            | Released: 2021-03-21
        
        **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
        
        **0.7 (2020-09-23)**:
            - Add ability to show individual points
            - Improve the cursor values display
            - Increase precision of both cursor values and axis labels
        
        **0.6 (2020-04-16)**:
            - modest refinements
        
        **0.5 (2020-01-08)**:
            - beta release
        
        **0.4 (2019-09-26)**:
            - Allow glob patterns to be passed to both *list-psf* and *plot-psf*.
        
        **0.3 (2019-09-25)**:
            - Fix import errors in *plot-psf* command.
        
        **0.2 (2019-09-25)**:
            - Fix dependencies.
        
        **0.1 (2019-09-25)**:
            - Initial version
        
Keywords: cadence,spectre,PSF,simulation
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Natural Language :: English
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Topic :: Utilities
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.6
Description-Content-Type: text/x-rst
