# SLiCAP basic tutorial¶

A tutorial that will demonstrate some basic functions of SLiCAP. Use the ‘Page’ drop-down menu for the table of contents.

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

## Install SLiCAP¶

2. Sart MATLAB and navigate to this download folder.
3. Type installSLiCAP() in the MATLAB Command Window and follow the instructions.
4. 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.
5. 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:

1. Install the latest version of LTspice

2. Start LTspice

3. On the menu bar click Tools > Control Panel. This will bring up the LTspice control panel:

4. On this control panel select the Netlist Options tab and select the options as shown below:

5. 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:

6. 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.

1. 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.

2. 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

copy code

3. 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.

The result subdirectory can be used to store SLiCAP results.

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.

1. 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”!

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

1. 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.
2. A default ground symbol (node 0) has been used.
3. The use of the spice directive .param: it defines symbolic or numeric values of parameters.
3. Save the circuit myFirstRCnetwork.asc in the project directory.

4. 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.

## Read and display the circuit in SLiCAP¶

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.

1. 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
% it will be named: <fileName>.cir
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

copy code

2. 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

copy code

3. 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:

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

## 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.

1. 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

copy code

2. 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!

• 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>}$
3. 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);

copy code

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.

1. 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.

copy code

2. 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.

1. 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);

copy code

2. 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.

1. 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

copy code

2. 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.

1. We will insert the following instructions above the 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

copy code

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

3. 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.

4. 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.

5. We will insert the following instructions above the 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.

copy code

6. 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).

1. We will insert the following instructions above the 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

copy code

2. 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).

1. We will insert the following instructions above the 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

copy code

2. 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}$.

1. We will insert the following instructions above the 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);

copy code

2. 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);

copy code

3. 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$']);

copy code

4. 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.

1. We will insert the following instructions above the 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');

copy code

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