# Work with specifications

Working with specifications is a powerful feature of SLiCAP. Specifications can be read from and stored to CSV files. Editing of the CSV file with a spreadsheet program or a text editor is possible but not preferred.

SLiCAP output displayed on this manual page, is generated with the script: `specifications.py`, imported by `Manual.py`.

     1#!/usr/bin/env python3
     2# -*- coding: utf-8 -*-
     3
     4"""
     5specifications.py: SLiCAP scripts for the HTML help file
     6"""
     7import SLiCAP as sl
     8import sympy as sp
     9
    10###############################################################################
    11# Work with specifications
    12###############################################################################

## Create specifications with specItem objects

The preferred way of working is to create SLiCAP `specItem` objects. Detailed information about specItems can be found in the specItem().

The example below shows how to create a list with specifications. In this example we will define four specifications for a transimpedance amplifier:

1. The typical value of the signal source capacitance in F; this is considered an ‘interface’ specification

2. The target value of the peak input current; this is considered an ‘interface’ specification

3. The target value of the peak output voltage; this is considered a ‘interface’ specification

4. The target value of its -3dB bandwidth; this is considered a ‘performance’ specification

5. The target value of its (unweighted) RMS output noise; this is considered a ‘performance’ specification

The designer is free to define any type of specification. In reports, SLiCAP places specifications of the same type in one table.

Below an example of working with specifications.

    14# Tip: Define parameter values at the top of the file, this makes it easy to
    15#      modify them later.
    16
    17Cs = 10e-12
    18Ip = 20e-6
    19Vp = 4
    20Bf = 5e4
    21Vn = 10e-6
    22
    23specs = []
    24specs.append(sl.specItem("C_s",
    25                         description = "Typical value of the source capacitance",
    26                         value       = Cs,
    27                         units       = "F",
    28                         specType    = "Interface"))
    29specs.append(sl.specItem("I_p",
    30                         description = "Peak-peak input current",
    31                         value       = Ip,
    32                         units       = "A",
    33                         specType    = "Interface"))
    34specs.append(sl.specItem("V_p",
    35                         description = "Peak-peak output voltage",
    36                         value       = Vp,
    37                         units       = "V",
    38                         specType    = "Interface"))
    39specs.append(sl.specItem("B_f",
    40                         description = "Target value -3dB bandwidth in Hz",
    41                         value       = Bf,
    42                         units       = "Hz",
    43                         specType    = "Performance"))
    44specs.append(sl.specItem("V_n",
    45                         description = "Maximum unweighted RMS output noise voltage",
    46                         value       = Vn,
    47                         units       = "V",
    48                         specType    = "Performance"))

Note

You can only assign a single value or expression to a parameter. A list of values is not supported because this would conflict with assigning parameter values to circuit parameters.

## Save specifications in CSV files

The specifications can be stored in a CSV file with specs2csv(). The specifications are stored in the `sl.ini.csv_path` folder. By default this is the `csv/` folder in the project directory.

    50# Save specs to 'csv/specs.csv'
    51sl.specs2csv(specs, "specs.csv")

## Import specifications from CSV files

The can be imported from this file with csv2specs()).

The example below shows how to store them in a csv file and import them from this file.

    53# Importing a list with specItems from 'csv/specs.csv'
    54specs = sl.csv2specs("specs.csv")

## Display specifications in the console

The script below prints the name, the value and the units of the interface specifications:

    56# Convert the speccification list to a dictionary for easy addressing
    57spec_dict = sl.specs2dict(specs)
    58
    59# Print name, value and units of 'interface specifications'
    60for name in spec_dict.keys():
    61    if spec_dict[name].specType.lower() == "interface":
    62        value = spec_dict[name].value
    63        units = spec_dict[name].units
    64        print(name, sp.N(value, 3), units)

The output shows:

    C_s 1.00e-11 F
    I_p 2.00e-5 A
    V_p 4.00 V
    B_f 5.00e+4 Hz
    V_n 1.00e-5 V

## Assign specified parameters to circuit parameters

Specifications can be assigned to circuit parameters using specs2circuit(). Circuit parameters that have the same name as a specItem() will then obtain the value of that specItem().

Create a SLiCAP circuit object from a schematic file or a netlist:

    68# Create a circuit object
    69cir = sl.makeCircuit("kicad/Transimpedance/Transimpedance.kicad_sch", imgWidth=350)

Below the netlist file created with the above script. It shows the expressions and parameters associated with circuit elements.

    "Transimpedance"
    C1 in 0 C value={C_s} vinit=0
    I1 0 in I value={I_s} noise={2*q*I_D} dc={-I_D} dcvar={sigma_ID^2}
    N1 out 0 in 0 N
    R1 in out R value={R_t} noisetemp={T} noiseflow=0 dcvar={sigma_R^2} dcvarlot=0
    .end

Below the `.svg` image file created with the above script.

The script lines below assign the specifications to circuit parameters and shows the results in the console.

    71# Assign the specifications to circuit parameters
    72sl.specs2circuit(specs, cir)
    73
    74# Print name and value of circuit parameters
    75print("\nCircuit parameter definitions")
    76for name in cir.parDefs.keys():
    77    print(name, sp.N(cir.parDefs[name], 3))
    78# Print the contents of the list with parameters that have no definition:
    79if len(cir.params):
    80    print("\nParameters that have no definition:\n")
    81    for param in cir.params:
    82        print(param)
    83else:
    84    print("\nFound no parameters without definition")

The output below, shows the circuit parameters. The parameter definitions include SLiCAP built-in parameter definitions; see Work with parameters.

    Circuit parameter definitions
    T 300.
    q 1.60e-19
    C_s 1.00e-11
    I_p 2.00e-5
    V_p 4.00
    B_f 5.00e+4
    V_n 1.00e-5

    Parameters that have no definition:

    R_t
    sigma_ID
    sigma_R
    I_D

## Display tables with specifications in LaTeX documents and on HTML pages

With the aid of the report module Creating reports, tables with specifications can be displayed on HTML pages or in LaTeX documents.

Below the script for generating the rst snippets for this help file.

    86# Generate RST snippets for the Help file
    87rst = sl.RSTformatter()
    88
    89rst.specs(specs, specType="Performance",
    90          caption="Performance specification").save("table-specs-performance")
    91rst.specs(specs, specType="Interface",
    92          caption="Interface specification").save("table-specs-interface")

Below the tables generated with this script.

Table 2 Performance specification
Name | Description | value | units
--- | --- | --- | ---
\(B_{f}\) | Target value -3dB bandwidth in Hz | \(5.0 \cdot 10^{4}\) | Hz
\(V_{n}\) | Maximum unweighted RMS output noise voltage | \(1.0 \cdot 10^{-5}\) | V

Table 3 Interface specification
Name | Description | value | units
--- | --- | --- | ---
\(C_{s}\) | Typical value of the source capacitance | \(1.0 \cdot 10^{-11}\) | F
\(I_{p}\) | Peak-peak input current | \(2.0 \cdot 10^{-5}\) | A
\(V_{p}\) | Peak-peak output voltage | \(4\) | V