# SLiCAP basic tutorial¶

date: 2019-01-02, author(s): anton, category: SLiCAP_tutorial, tag(s): SLiCAP Tutorial.

## Abstract¶

Basic SLiCAP tutorial “my first RC network”, that demonstrates some basic functions of SLiCAP.

## Contents¶

- You can download the (.zip) archive of this tutorial. In this tutorial we will create its content step-by-step (latest SLiCAP version only).

## Install SLiCAP¶

- Download the install script installSLiCAP.p and save it in your downloads folder.
- Sart MATLAB and navigate to this download folder.
- Type
`installSLiCAP()`

in the MATLAB Command Window and follow the instructions. - After SLiCAP has been installed, type “
**Help**” (with capital “**H**”) in the MATLAB Command Window. This should open the html help file in the MATLAB browser. - Read the Introduction so you know what you can expect from SLiCAP!

## Install and configure LTspice for schematic capture¶

If you want to use LTspice as schematic capture program you also need to install and/or configure LTspice as schematic capture program for SLiCAP. To this end you need to:

Install the latest version of LTspice

Start LTspice

On the menu bar click

`Tools > Control Panel`

. This will bring up the LTspice control panel:On this control panel select the

`Netlist Options`

tab and select the options as shown below:Then select the

`Sym. & Lib. Search Paths`

tab and enter the full path to the “LTspice” subdirectory of your SLiCAP install path. This directory contains all the SLiCAP symbol definitions (*.asy files) for LTspice:Then select the

`Drafting Options`

tab and change the font size and deselect the “Bold” checkbox as shown below. If you want, you can also select different colors for your schematics.

## Create a project directory and a project m-file¶

In this first tutorial, we will create a SLiCAP project to evaluate, design and plot the behavior of a simple RC network. In this example we will use LTspice for creating the schematic of the network.

Create a directory that will contain all the files of a SLiCAP project. During this tutorial we will expect that this project directory is:

`~/DATA/SLiCAP/Tutorial/myFirstProject`

.Navigate in MATLAB to this directory and create an m-file

`myFirstRCproject.m`

with the following contents:clear all; % this will clear the work space initProject('myFirstRCproject', mfilename('fullpath')); % this will initialize the project stophtml(); % this properly closes the project html index page

Run this m-file. The result is shown in the MATLAB workspace:

SLiCAP created a subdirectory structure for your project. The

`html`

tree will contain all html output of the project. The file`index.html`

is the project’s main index file.The

`rst`

tree contains restructured text files and configuration and style files for python sphinx documentation package. We will not use these files in this tutorial.SLiCAP also creates two files that contain project information for MATLAB (

`slicap.p`

) and the Symbolic Math Toolbox MuPAD (`slicap.mu`

).

## Draw the circuit in LTspice¶

Knowledge of drawing circuits with LTspice is assumed.

Open LTspice and select

`File > New Schematic`

from the menu bar. Place a component on the schematic by clicking the AND gate symbol on the tool bar or by pressing the “F2” key (default Hot Keys setting). This will bring up the`Select Component Symbol`

menu. On this menu select the directory with the SLiCAP symbols from`Top Directory`

drop-down select box, as shown below:All SLiCAP symbol names start with “SL”!

Place an independent voltage source “SLV”, a resistor “SLR” and a capacitor “SLC” and create the circuit depicted below:

Please note:

- The node of interconnection of the resistor and the capacitor is labeled as
`out`

. Later we need to refer to this node. SLiCAP will name the voltage at this node`V_out`

. - A default ground symbol (node
`0`

) has been used. - The use of the spice directive
`.param`

: it defines symbolic or numeric values of parameters.

- The node of interconnection of the resistor and the capacitor is labeled as
Save the circuit

`myFirstRCnetwork.asc`

in the project directory.If you want to display the circuit on a SLiCAP output html page, you need to create an image file of it that can be rendered by a browser. A

`.png`

file is a good candidate. You can generate a PNG from a screen dump with a graphic file editor (Paint, Gimp, Photoshop, etc.). Here we assume that the graphic file`myFirstRCnetwork_asc.png`

has been saved in the project directory. It is shown above.

## Create the netlist¶

SLiCAP can create a netlist from within the MATLAB working environment. To this end MATLAB will run the LTspice netlister in batch mode.

If automatic generation of the netlist fails, please check the following:

- The library configuration in LTspice should be set as described in the section above
- The location of the LTspice executable in the file
`LTspiceNetlist.m`

in the`MATLAB`

subdirectory in the SLiCAP install path must be set correctly. You can edit`LTspiceNetlist.m`

and change the location as desired.

We will now create an m-file that will generate the netlist, check the circuit and display the circuit, its netlist, its elements and its parameter definitions on a web page.

Create an m-file

`myFirstRCnetwork.m`

in the project directory:fileName = 'myFirstRCnetwork'; % file name without extension assigned to the variable: "fileName" makeNetlist(fileName); % This will create a netlist running LTspice in batch mode

If the above script does not work, you have to create a `.cir`

file from the LTspice schematics manually. The way to do this is described below.

### Manual creation of the netlist¶

Manual creation of the netlist from an LTspice schematic should be done as follows:

Open the schematic of the circuit in LTspice (this is a

`.asc`

file)Select View > SPICE Netlist (Alt V –> Shift N). This will display the netlist in a pop-up window:

In this pop-up window click the right mouse button and select ‘Edit as Independent Netlist’. This will bring up a pop-up window to save this netlist as a .cir file. The name of this file is automatically generated by LTspice. Do not alter this name, just save the file and it will open it in LTspice.

After you saved the file LTspice will display its contents. You now need to insert a title for the circuit above the first line. If you use spaces in the circuit title, place it between double quotes ‘”’ (as shown). Do not start the title with ‘*’; it will be ignored by the SLiCAP netlist parser. Please read the manual netlist syntax section for a detailed description of the SLiCAP netlist syntax.

Save the netlist.

If automatic netlist generation did not work, you need to remove the instruction (change it into comment) in

`myFirstRCnetwork.m`

:fileName = 'myFirstRCnetwork'; % file name without extension assigned to the variable: "fileName" %makeNetlist(fileName); % Uncomment if netlist generation from within the MATLAB environment % yields no errors, otherwise create the netlist file manually!

## Check and display the circuit in SLiCAP¶

We will now check the circuit and display the circuit, its netlist, its elements and its parameter definitions on a web page.

Edit

`myFirstRCnetwork.m`

that you created in the previous step:fileName = 'myFirstRCnetwork'; % file name without extension assigned to the variable: "fileName" %makeNetlist(fileName); % Uncomment this line if netlist generation from within the MATLAB environment % yields no errors, otherwise create the netlist file manually! checkCircuit(fileName); % This check the netlist and creates the MNA equation of the circuit htmlPage('Circuit data'); % This creates a web page with the circuit data head2html('Circuit diagram'); % Places a header (level 2) on the web page img2html([fileName, '_asc.png'], 369); % This places the picture of the circuit on the web page (width=369px) netlist2html(fileName); % This places the netlist on the web page elementData2html(); % This places all the properties of all the network elements on the web page params2html(); % This lists the symbolic and numeric values of all network parameters on the web page % % Here, we will insert instructions later % stophtml(); % This closes the active html page

Update the project file to execute

`myFirstRCnetwork.m`

. The project file`myFirstRCproject.m`

is updated to:clear all; % this will clear the work space initProject('myFirstRCproject', mfilename('fullpath')); % this will initialize the project myFirstRCnetwork(); % this executes the m-file: "myFirstRCnetwork.m" stophtml(); % this properly closes the project html index page

Run the project file by typing “myFirstRCproject()” in the MATLAB Command Window.

Below an overview of the files generated after running the project:

- The index.html page is the project’s index page. It links to circuit index pages that have links to the output pages generated for each circuit. Here the only circuit index page is:
- myFirstRCnetwork_index.html that comprises the links to:
- myFirstRCnetwork_log.html , a log page that was generated during the checking of the circuit. This page contains error messages and debug information.
- myFirstRCnetwork_Circuit data.html, the page with circuit data that was generated through the execution of
`myFirstRCproject.m`

. - Other pages that are generated by running the complete tutorial.

- myFirstRCnetwork_index.html that comprises the links to:

Please note: numeric parameter values are obtained through recursive substitution of all parameter definitions in expressions in the element of parameter definition.

- The index.html page is the project’s index page. It links to circuit index pages that have links to the output pages generated for each circuit. Here the only circuit index page is:

## Obtain the MNA equation and display it on an html page¶

We will now obtain the MNA (Modified Nodal Analysis) matrix equation and display it on an html page.

We will insert a few instructions above the

`stophtml()`

instruction in the`myFirstRCnetwork.m`

script file:% obtain the symbolic MNA matrix equation of the network % % simType('symbolic'); % Set the simulation type to 'symbolic' gainType('vi'); % Set the gain type to 'vi' (calculation of voltages or current using Cramer's rule) dataType('matrix'); % Set the data type to 'matrix', this is the type of output data we want MNA = execute(); % Assign the matrix equation (execution result) to the variable MNA htmlPage('Matrix equations'); % Create a html page to display the matrix equation matrices2html(MNA); % Put the matrix equation on this page

Run the project file again. The matrix equation is displayed on the new html page: myFirstRCnetwork_Matrix equations.html. The instruction

`matrices2html()`

also displays a note above the equation. Just ignore it for now!Please note:

- The names of the dependent variables (node voltages and branch current of current-controlled elements):
- Nodal voltages obtain the name V_<nodeName> and will be displayed as \(V_{<nodeName>}\)
- Branch currents obtain the name I_<vSourceName> and will be displayed as \(I_{<vSourceName>}\)

- The names of the dependent variables (node voltages and branch current of current-controlled elements):
The MATLAB variable MNA now contains the vector with independent variables, the MNA matrix and the vector with dependent variables. The structure of the execution result is described in the html help file. To view this structure insert a the following instructions above the

`stophtml()`

instruction in the`myFirstRCnetwork.m`

script file.htmlPage('Matrix equation variables'); % Create a new html page to display the separate variables of the matrix equation MNA_vars = MNA.results(1); % MNA variables I_v = MNA_vars(1); % Vector with independent variables M = MNA_vars(2); % Matrix D_v = MNA_vars(3); % Vector with independent variables % Display text (including LaTeX) on the active html page. text2html('The vector $I_v$ with the independent variables equals:'); % Display an equation on the active html page. eqn2html(sym('I_v'), I_v); text2html('The matrix $M$ equals:'); eqn2html(sym('M'), M); text2html('The vector $D_v$ with the dependent variables equals:'); eqn2html(sym('D_v'), D_v);

The new variables are shown in the MATLAB workspace and on the new html page myFirstRCnetwork_Matrix equation variables.html.

## Obtain the Laplace Transform of the transfer¶

We will now obtain a symbolic expression for the transfer from the source to the detector. The voltage source V1 will be assigned as signal source and the voltage at node out (with respect to ground) as detector voltage.

We will insert the following instructions above the

`stophtml()`

instruction in the`myFirstRCnetwork.m`

script file:% Obtain the Laplace Transform of the source-to-detector transfer of the network % source('V1'); % The independent source 'V1' is assigned as signal source detector('V_out'); % The voltage between node 'out' and node '0' is assigned as detector voltage gainType('gain'); % The gain from source to load is the desired transfer dataType('laplace'); % The Laplace Transform is the data we need % Note: the simulation type is still 'symbolic', we didn't change it gainLaplace = execute(); % The execution result (structured array) is assigned to the variable 'gainLaplace' % We will unpack the structured array since we only need the expression: gainLaplaceExpr = gainLaplace.results(1); htmlPage('Laplace Transform'); % Create a new html page. head2html('Laplace transform of the gain'); % Put a heading on it text2html('The Laplace Transform of the gain is found as:'); % Put some text on the page syms('V_out', 'V_1'); % Define symbolic variables for the left hand side of the equation eqn2html(V_out/V_1, gainLaplaceExpr); % Place the equation on the page.

Run the project file and open the html page with the Laplace expression.

## Plot the magnitude, phase and delay characteristics¶

Plotting requires numeric analysis. SLiCAP has many built-in plot routines. We will plot the magnitude, the phase and the delay characteristics of the gain.

We will insert the following instructions above the

`stophtml()`

instruction in the`myFirstRCnetwork.m`

script file:% Obtain the numeric Laplace Transform of the source-to-detector transfer of the network % simType('numeric'); % Set the simulation type to numeric. % % Data type is still 'laplace' which is required for plotting frequency characteristics % Source, detector and gain type have already been defined. gainLaplaceNumeric = execute(); % Create MATLAB figure objects, later we will place them on an html page. figMag = plotMag('Magnitude plot of the gain', gainLaplaceNumeric, 10, 1e5, 100); figdBmag = plotdBmag('dB Magnitude plot of the gain', gainLaplaceNumeric, 10, 1e5, 100); figPhase = plotPhase('Phase plot of the gain', gainLaplaceNumeric, 10, 1e5, 100); figDelay = plotDelay('Group delay of the gain', gainLaplaceNumeric, 10, 1e5, 100);

Run the project file and the plots will be displayed.

## Place the plots on an html page¶

You can also include the plots in the html output. By doing so, the plots will not be displayed in the MATLAB work space.

We will insert the following instructions above the

`stophtml()`

instruction in the`myFirstRCnetwork.m`

script file:% Display the plots on an html page % htmlPage('Plots of the gain'); % Create a new html page fig2html(figMag, 'figMag.svg', 800) % save figMag as figMag.svg in the 'html/figures' subdirectory % and place it on the page with a width of 800px fig2html(figdBmag, 'figdBmag.svg', 800) % As above, but now for figdBmag fig2html(figPhase, 'figPhase.svg', 800) % As above, but now for figPhase fig2html(figDelay, 'figDelay.svg', 800) % As above, but now for figDelay

Run the project file and open the html page with the plots.

## Calculate and plot the poles and zeros of the gain¶

SLiCAP can calculate the poles and zeros of a network numerically. Although this is not very exciting for this simple RC network, we will demonstrate the procedure, so you will be able to apply it for more complicated networks.

`stophtml()`

instruction in the`myFirstRCnetwork.m`

script file:% Calculate the DC gain, the poles and the zeros of the gain using data type 'pz', simulation type 'numeric' and gain type 'gain'. % The latter two have already been defined correctly. dataType('pz'); % Define the data type for pole-zero analysis gainPolesZeros = execute(); % Calculate the DC gain, the poles and the zeros listPZ(gainPolesZeros); % Display the results in the MATLAB Command Window htmlPage('Pole-zero analysis'); % Create an html page for displaying the results pz2html(gainPolesZeros); % Display the results on the html page. % Generate the plot: x-axis: -1900...100Hz, y-axis: -1000...1000Hz. figPZ = plotPZ('Pole-zero plot', gainPolesZeros, [-1900, 100], [-1000, 1000]); head2html('Plot'); % Put a heading on the page fig2html(figPZ, 'figPZ.svg', 600);% Place the figure on the html page

Run the project file and open the html page with the DC gain, the poles and the zeros.

If you want the obtain values of the DC gain, the poles and the zeros for further processing, you need to unpack the structured array ‘gainPolesZeros’. The structure of the execution result is described in the html help file.

data type ‘pz’ calculates poles and zeros and cancels poles and zeros that have the same frequency. If you also want to display non-observable poles, use data type ‘pols’ for calculation of the poles and data type ‘zeros’ for calculation of the zeros.

`stophtml()`

instruction in the`myFirstRCnetwork.m`

script file:% Calculate the poles and the zeros of the gain using data type 'poles', simulation type 'numeric' and gain type 'gain'. % The latter two have already been defined correctly. dataType('poles'); % Define the data type for pole analysis gainPoles = execute(); % Calculate the poles htmlPage('Separate pole and zero analysis'); % Create an html page for displaying the results pz2html(gainPoles); % Display the results on the html page. dataType('zeros'); % Define the data type for zero analysis gainZeros = execute(); % Calculate the zeros pz2html(gainZeros); % Display the results on the html page.

Run the project file and open the html page with the poles and the zeros.

## Calculate and plot the unit impulse response of the gain¶

Determination of **symbolic** expressions for the unit impulse response h(t) (Inverse Laplace Transform) and the unit step response a(t), requires symbolic pole-zero analysis. SLiCAP can perform such analysis for relatively simple circuits only (low-order).

`stophtml()`

instruction in the`myFirstRCnetwork.m`

script file:% Calculate the unit impulse response of the gain. simType('symbolic'); % Symbolic simulation dataType('impulse'); % Calculate the unit impulse response of the gain (gain type has already been set) gainImpulse = execute(); % Assign the execution result to the variable 'gainImpulse' gainImpulseExpr = gainImpulse.results(1); % Unpack the execution result and assign the expression to 'gainImpulseExpr' htmlPage('Unit impulse response'); % Start a new html page head2html('Symbolic expression'); % Put a heading on it syms('h(t)'); % Define the left hand side of the equation eqn2html(h(t), gainImpulseExpr); % Write the equation to the html page % generate the plot of h(t) simType('numeric'); % This requires numeric simulation figImpulse = plotTime('Impulse response', execute(), 0, 1e-3, 100); % Make the time-domain plot head2html('Plot'); % Put a heading on the page fig2html(figImpulse, 'figImpulse.svg', 800);% Put the plot on the page

Run the project file and open the html page with the unit impulse response.

## Calculate and plot the unit step response of the gain¶

Determination of **symbolic** expressions for the unit impulse response h(t) (Inverse Laplace Transform) and the unit step response a(t), requires symbolic pole-zero analysis. SLiCAP can perform such analysis for relatively simple circuits only (low-order).

`stophtml()`

instruction in the`myFirstRCnetwork.m`

script file:% Calculate the unit step response of the gain. simType('symbolic'); % Symbolic simulation dataType('step'); % Calculate the unit impulse response of the gain (gain type has already been set) gainStep= execute(); % Assign the execution result to the variable 'gainStep' gainStepExpr = gainStep.results(1); % Unpack the execution result and assign the expression to 'gainStepExpr' htmlPage('Unit step response'); % Start a new html page head2html('Symbolic expression'); % Put a heading on it syms('a(t)'); % Define the left hand side of the equation eqn2html(a(t), gainStepExpr); % Write the equation to the html page % generate the plot of h(t) simType('numeric'); % This requires numeric simulation figStep = plotTime('Step response', execute(), 0, 1e-3, 100); % Make the time-domain plot head2html('Plot'); % Put a heading on the page fig2html(figStep, 'figStep.svg', 800); % Put the plot on the page

Run the project file and open the html page with the unit step response.

## Set up and solve component design equations¶

SLiCAP can be used for deriving and solving design equations for analog circuits. We will demonstrate this for a simple case. We will determine requirements for the component values of this RC network, such that it settles to an accuracy of $n$ bit within \(\tau_s\) seconds. To this end we need to determine the settling error \(\epsilon_s\) versus time and find a solution for \(\epsilon_s=2^{-n}\). The script below calculates the time-dependent relative settling error \(\epsilon_s(t)\). It then calculates the selttling time by solving \(t\) from \(\epsilon_s=2^{-n}\).

`stophtml()`

instruction in the`myFirstRCnetwork.m`

script file:% Calculate the settling error as a function of time. syms('n', 't', 'epsilon_s', 'tau_s'); % Define symbolic variables eps = 1-gainStepExpr; % Calculate the relative settling error taus = solve(eps-2^-n, t); % Calculate the settling time htmlPage('Settling time'); % Start a html page head2html('Settling time to n-bits'); % Put a heading on it % Put some text on the page and write the equations on the page text2html('The relative settling error versus time can be founs as:'); eqn2html(epsilon_s, eps); text2html('The settling time to $n$ bit can be found as the solution of:'); eqn2html(epsilon_s, 2^-n); text2html('This yields:'); eqn2html(tau_s, taus);

We will now express the resistance \(R\) in the capacitance \(C\), and vice versa for a settling time of \(\tau_s\) s to an accuracy of \(n\) bit. We will insert the following instructions above the

`stophtml()`

instruction in the`myFirstRCnetwork.m`

script file:% Derive the design equations for the resistance R and the capacitance C of the network % for settling to n bit within tau_s seconds. syms('R', 'C'); Rsol = solve(taus-tau_s, R); % Symbolic design equation for the resistance Csol = solve(taus-tau_s, C); % Symbolic design equation for the capacitance head2html('Component design equations'); % Put a heading on the page % Put some text on the page and write the equations on the page text2html(['The resistance $R$ can be written as a function of the capacitance ', ... '$C$ and the settling time $\\tau_s$ to $n$ bit:']); eqn2html(R, Rsol); text2html(['The capacitance $C$ can be written as a function of the resistance ', ... '$R$ and the settling time $\\tau_s$ to $n$ bit:']); eqn2html(C, Csol);

We will now determine a numeric value for the resistance \(R\) for \(n=10\), \(C=10\) pF and \(\tau_s=100\) ns. We will insert the following instructions above the

`stophtml()`

instruction in the`myFirstRCnetwork.m`

script file:% Determine the value of the resistance, given the capacitance and the settling time to 10 bit. % Substitute numeric values for C, tau_s and n in the expression for Rsol Rnum = subs(Rsol, [C, tau_s, n], [10e-12, 100e-9, 10]); head2html('Numeric example'); % Put a heading on the page and display text with the result text2html(['For a settling time of 100ns to 10bit, with a capacitance of 10pF, we need a resistance of: ', ... num2str(double(Rnum)), '$\\Omega$']);

Run the project file and open the html page with the design equations.

## Write the script to an html page¶

SLiCAP can write a script to a separate html file.

`stophtml()`

instruction in the`myFirstRCnetwork.m`

script file:% Write the complete script to an html file % This writes the script to an html page and places a link on the circuit's index page. script2html('myFirstRCnetwork');

Run the project and view the complete output index.html.