Using Custom Scripts to Postprocess Simulation Results

Warning

Custom scripts are still a WIP and the function signature of postprocess might still change!

This tutorial shows how to use custom Python scripts to postprocess simulation results of the ngspice tool.

This feature can be used to extract certain parameters from simulation results. For example, it could be used to calculate the INL, DNL, offset error and gain error of a DAC. An example of this can be seen in sky130_ef_ip__rdac3v_8bit.

For a step-by-step guide on how to set up custom scripts, please see below.

Specifying Custom Scripts in the Datasheet

At present, only the ngspice tool allows postprocessing of the simulation results. Please have a look at its arguments at Supported Tools.

To add a custom script for postprocessing, you simply need to specify the script and script_variables arguments.

    tool:
      ngspice:
        template: voltage_output.sch
        collate: iterations
        format: ascii
        suffix: .data
        variables: [null, vout]
        script: inl.py
        script_variables: [inl]

The script argument defines the name of the Python script that is called for each of the simulation results. The script_variables argument defines the results generated by the script. In this case, the script generates a single variable called dnl. The variables can then be used in the spec or plot section as if they came from the simulation run itself. The script needs to be placed in the scripts folder of CACE.

CACE expects the custom script to provide a function called postprocess. The function signature of postprocess is as follows:

def postprocess(results: dict[str, list], conditions: dict[str, Any]) -> dict[str, list]:

The results argument contains the results of a single simulation run. Since variables: [null, vout] is set in the datasheet, results contains a single key vout with a list of values (results['vout'] = [..., ...]). The conditions argument contains the conditions for this simulation run. For example, it contains a key temperature with the value for this simulation run, e.g. 27 (conditions['temperature'] = 27).

If you collate simulation results based on a condition, then this condition will contain a list of values instead of a single value. For a Monte Carlo simulation that is collated with the iterations condition, conditions['iterations'] contains a list of all the iterations for all collated simulations (conditions['iterations'] = [1, 2, 3...]).

The return value of postprocess is another dictionary that must contain the keys specified in the script_variables argument in the datasheet. In this case {'inl': [..., ...]} is returned, where the list can also contain only a single value.

To get a feel for the data being passed to your script, you can simply print results and conditions and return an empty dictionary. (Note that script_variables in the datasheet must be an empty list as this script does not return any results.)

def postprocess(results: dict[str, list], conditions: dict[str, Any]) -> dict[str, list]:

    print(f'results: {results}')
    print(f'conditions: {conditions}')

    return {}

To notify CACE about any issues, simply raise an exception in your script:

raise Exception('This is an exception')

For a real example, see the contents of inl.py:

def postprocess(results: dict[str, list], conditions: dict[str, Any]) -> dict[str, list]:

    print(f'results: {results}')
    print(f'conditions: {conditions}')
    
    # INL calculation:
    # x is the digital value b7:0 converted to an integer
    # V(x) is the original value in RESULT:  The voltage output of the DAC
    #	under the given set of conditions.
    # ALSB = (Vhigh - Vlow) / 256	(ideal voltage step size per LSB)
    #
    # INL(x) = (RESULT - (x * ALSB + Vlow)) / ALSB	(in units of LSB)
    #
    # NOTE that this DAC is based on 256 steps with the highest step being
    # 1 lsb below Vhigh.
    
    Vhigh = float(conditions['Vhigh'])
    Vlow = float(conditions['Vlow'])
    x = float(conditions['b'])
    
    alsb = (Vhigh - Vlow) / 256
    
    inl = []
    
    # Iterate over MC results
    for vout in results['vout']:
        inl.append((vout - (x * alsb + Vlow)) / alsb)
 
    return {'inl': inl}

For a simulation run the result might look like this in the summary:

  Parameter           Tool          Result         Min Limit   Min Value   Typ Target   Typ Value   Max Limit   Max Value   Status   
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  INL                 ngspice       inl               -2 lsb   0.998 lsb        0 lsb   1.136 lsb       2 lsb   3.995 lsb   Fail ❌