Generate HTML reports

Writing design documentation is often something that needs to be done after the design work has been finished. By then, all kinds of information needs to be collected and structured in a document, while in many cases new projects are already taking most of the time. This undesirable but almost always inevitable practice can be prevented if the design work goes hand in hand with generation of the design documents. SLiCAP supports this with the generation of web-based design documentation in which figures, tables, expressions and ASCII files can be updated while running SLiCAP-MATLAB scripts. In this way, presentations and documentation can be kept up to date with the actual status of the design.

HTML site structure

The structure of the project web site that can be generated with SLiCAP will be discussed below.

Main Index.html

Initialization of a project generates an index.html file in the html subdirectory. This file will hold the main table of contents of your project. Each time you check a circuit netlist that resides in the project directory, a list entry will be generated in this index file.

Below the preferred way of working if you have SLiCAP-MATLAB installed in /home/myName/SLiCAP/ and your work needs to be stored in the project directory /home/myName/myProject/. The script below should be executed in this project directory.

% move to the project directory (here: '/home/myName/SLiCAP/')
cd /home/myName/SLiCAP/
% Clear the MATLAB and the symbolic toolbox environment
clear all;
%
% Initialize a project (here: 'myProject') in this directory
initProject(myProject', mfilename);
%
% Here you can put your SLiCAP-MATLAB instructions
% ...
%
% Close the index.html file properly
stophtml();

Circuit index file

Each time you check a circuit as described in: ‘Check the netlist and build the matrices’, the following will happen (assume the name of the netlist file is circuitName.cir:

  • A file circuitName_index.html will be created. This file will hold the table of contents of the html pages for this circuit.
  • A file circuitName_log.html will be created and a link to this file will be created in the circuitName_index.html file.
  • A link to the circuitName_index.html file will be created in the main index.html file that was created at the initialization of the project.

A good practice is to start a new active html page after checking the circuit, this prevents output to be writen to index files which would mess up the table of contents.

Start a new html page

A new html page can be created by evoking the command htmlPage(< pageTitle >), in which pageTitle is the title of the new page (character string). The following will occur:

  1. The current active html page will be closed with the correct html tags.
  2. A html page with the file name: < circuitName >_< pageTitle >.html in which circuitName is the name of the circuit will be created.
  3. It makes this new page the active html page
  4. It places a top-level page heading (H1) with pageTitle on this page

The return value of htmlPage('pageTitle') is the character string:

<h1>pageTitle</h1>

The example below shows the initialization of SLiCAP, the checking of myCircuit and the generation of a page for the netlist. In this example we assume that a project has been created and the working directory is the project directory.

clear all
slicap()
makeNetlist('myCircuit')
numberOfErrors = checkCircuit('myCircuit');
htmlPage('Netlist');
netlist2html('myCircuit');
htmlPage('AlmostEmpty');
text2html('This page is almost empty!');
stophtml();

The stophtml() instruction closes the last active html page and the index page for this circuit with the correct html tags.

Headings

Sub headings (level 2 and level 3) can be placed on the active html page.

H2

The function head2html(< level2heading >) places the character string level2heading in H2 format on the active html page.

head2html('Schematics of the circuit');

H3

The function head3html(< level3heading >) places the character string level3heading in H3 format on the active html page.

head3html('Schematics of the sub circuit myOpamp');

List element data

The function elementData2html() displays all the data of the elements of the expanded netlist in a table on the active html page.

elementData2html();

List parameter data

The function params2html() displays the symbolic and the numeric values of all parameters in your circuit.

params2html();

Include ASCII file

You can include an ASCII file with or without html tags and with or without LaTeX, literally in your active HTML page.

file2html('myTextFile.ascii');

In-line LaTeX expressions should be placed between single dollar characters: $ < myLaTeXexpression > $. Displayed LaTeX expressions should be placed between double dollar characters: $$ < myLaTeXexpression > $$.

Include netlist

You can include a netlist file on the active html page. Line breaks of the input file will be copied to the html file. You should not include the netlist file extension in the file name.

netlist2html('myCircuit');

Include MATLAB script

A MATLAB script file can be converted into a html page using the function:

script2html(< MATLABmFile >)

In which MATLABmFile is the name of the MATLAB script file (excluding the file extension .m) that resides in the project directory. This function generates a html file with the name < circuitName >_< MATLABmFile >.html, and places a link on the < < circuitName >_index.html page. It does not change the name of the active html page. LaTeX in the MATLAB script file will not be typeset. The script is displayed in the browser as in the MATLAB editor.

Assume the MATLAB script file hfAnalysis.m with the contents given below and the circuit netlist myCircuit.cir are both stored in the project directory. The script below then creates an html file myCircuit_hfAnalysis.m.html in the project directory.

clear all;
slicap()
numberOfErrors = checkCircuit('myCircuit');
script2html('hfAnalysis');

Include images and plots

Images from files

You can include images into your html file by using the function:

img2html( < figureFileName >, < widthInPixels >);

The width of the image is scaled to widthInPixels (the aspect ratio will be maintained). The graphic file should reside in the work/html/SLiCAP-MATLAB/figures/ directory.

MATLAB figures

Plots generated by MATLAB can be placed on the active html page by using the function:

fig2html(< MATLABfigureObject >, < fileName >, < widthInPixels >)
  1. MATLABfigureObject is a MATLAB figure as it has been generated with one of the SLiCAP plot functions
  2. fileName is the name of the graphic file in which the figure will be stored, including a html compatible extension. The figure file will be stored in the work/html/SLiCAP-MATLAB/figures/ directory.
  3. widthInPixels sets the width of the figure in the html page. The aspect ratio will be maintained.
img2html('myCircuit.svg', 600);

The variable myFig in the example below is a MATLAB figure object containing the step response of a circuit. It will be displayed on an HTML page and included in the html/figures/ subdirectory of the project.

fig2html(myFig, 'stepResponse.svg', 600);

The function returns the MuPAD boolean TRUE if the file is found, else FALSE.

Include tables from CSV files

Comma Separated Values files can be displayed as a table on the active HTML page using the function csv2html.m. The CSV file may comprise LaTeX expressions. The example below shows how a CSV file transimpedanceSpec.csv with specifications of a transimpedance amplifier is displayed on the active html page.

csv2html('transimpedanceSpec') % File extension is '.csv' and should not be included

The file transimpedanceSpec.csv has been listed below.

symbol,description,value,units
$C_{s}$,Sensor capacitance,10...20,pF
$I_{D}$,Sensor dark current,20...50,nA
$I_{peak}$,Peak signal current of sensor,20,$\mathrm{\mu A}$
$\left( \frac{dI}{dt} \right)_{max}$,Max rate of change sensor current,100,A/s
$R_{\ell}$,Load resistance,1 $\cdots \infty$, $\mathrm{k \Omega}$
$C_{\ell}$,Load capacitance,0...100,pF
$V_{\ell}$,Peak signal voltage across load,2,V
$V_{onoise}$,Maximum RMS noise voltage across load,100,$\mathrm{\mu V}$
$V_{off}$,Maximum offset voltage across load,10,mV
$B_{f}$,MFM -3dB cut-off frequency of transimpedance gain,1,MHz
$\delta$,Maximum of absolute static (gain) inaccuracy,2,%

The displayed result (depends on the CSS file):

symbol description value units
\(C_{s}\) Sensor capacitance 10…20 pF
\(I_{D}\) Sensor dark current 20…50 nA
\(I_{peak}\) Peak signal current of sensor 20 \(\mathrm{\mu A}\)
\(\left( \frac{dI}{dt} \right)_{max}\) Max rate of change sensor current 100 A/s
\(R_{\ell}\) Load resistance 1 \(\cdots \infty\) \(\mathrm{k \Omega}\)
\(C_{\ell}\) Load capacitance 0…100 pF
\(V_{\ell}\) Peak signal voltage across load 2 V
\(V_{onoise}\) Maximum RMS noise voltage across load 100 \(\mathrm{\mu V}\)
\(V_{off}\) Maximum offset voltage across load 10 mV
\(B_{f}\) MFM -3dB cut-off frequency of transimpedance gain 1 MHz
\(\delta\) Maximum of absolute static (gain) inaccuracy 2 %

Include Pole-Zero results

The function pz2html.m accepts the result of a single (non stepped) pole-zero analysis with the data type equal to POLES or ZEROS or PZ. It converts these results into html tables on the active html page. See examples for application and displayed results.

dataType('PZ');
stepOff();
pz2html(execute());

Include noise results

The function noise2html.m accepts the result of a single (non stepped) noise analysis and converts it into html tables on the active html page. See examples for application and displayed results.

dataType('noise');
stepOff();
noise2html(execute());

Include results of noise integration

The function noise2htmlInt.m accepts the result of a single (non stepped) noise analysis with integration and converts it into html tables on the active html page. See examples for application and displayed results.

dataType('noise');
stepOff();
noise2htmlInt(doNoiseInt(execute()));

Include text

The function text2html.m can be used to write a text paragraph, including html tags, css code and LaTeX code to the active html page. In-line LaTeX expressions should be placed between single dollars signs $ < latexExpression > $. Displayed LaTeX expressions should be placed between double dollars signs $$ < latexExpression > $$.

The text is placed between html paragraph tags: <p> < text > </p>.

text2html(['The transfer $H(s)$ of a unity-gain, '...
'second-order, low-pass Butterworth filter with '...
'bandwidth $omega_n$, can be written as:']);

It writes this text to the active html page that will display:

The transfer of a unity-gain, second-order, low-pass Butterworth filter with bandwidth \(\omega_{n}\) can be written as:

Include expressions

SLiCAP incorporates functions to write expressions or equations in LaTeX format to the active html page. These LaTeX expressions can be rendered by any browser with the aid of MathJax. The MathJax configuration settings have been included in the html pages. MathJax CDN can be accessed when connected to the Internet. Local installation of MathJax is possible, but not yet documented. The functions for printing expressions to the active HTML page have been described below.

Include an in line expression in LaTeX format

The function expr2html.m can be used for printing an expression to the active html page. The syntax is: expr2html(< expr >)

In which expr is a symbolic expression. This function prints this expression in LaTeX format to the active html page.

syms('s', 'omega_n');
text2html(['The transfer of a unity-gain, '...
'second-order, low-pass Butterworth filter with '...
'bandwidth $omega_n$, can be written as:']);
expr2html(1/(1 + s*sqrt(2)/omega_n + s^2/omega_n^2));

The html output looks like:

The transfer of a unity-gain, second-order, low-pass Butterworth filter with bandwidth \(\omega_n\), can be written as: \(\frac{1}{\frac{s^2}{{\mathrm{\omega}_{n}}^2} + \frac{\sqrt{2}\, s}{\mathrm{\omega}_{n}} + 1}\)

Include a displayed and numbered equation in LaTeX format

The function eqn2html.m prints an equation to the active html page. The syntax for this function is:

eqn2html(< expr1, expr2 >)

In which expr1 and expr2 are symbolic expressions. This function prints the equation expr1=expr2 in LaTeX format to the active html page.

syms H(s) s omega_n H_s;
H_s = 1/(1 + s*sqrt(2)/omega_n + s^2/omega_n^2);
text2html(['The transfer $H(s)$ of a unity-gain, '...
'second-order, low-pass Butterworth filter with '...
'bandwidth $omega_n$, can be written as:']);
eqn2html(H(s), H_s)

The result on the html page will look like:

The transfer \(H(s)\) of a unity-gain, second-order, low-pass Butterworth filter with bandwidth \(\omega_n\), can be written as:

(1)\[ H\left(s\right)=\frac{1}{\frac{s^2}{{\mathrm{\omega}_{n}}^2} + \frac{\sqrt{2}\, s}{\mathrm{\omega}_{n}} + 1}\]

Include the MNA matrix equation in LaTeX format

The function matrices2html.m prints the MNA matrices with headers and comment to the active html page. It accepts the result of an execute() instruction with the data type set to MATRIX as argument. The function returns a copy of the html code written to the active html page.

The example below illustrates:

  1. The initialization of SLiCAP
  2. Checking of the netlist myCircuit.cir
  3. Printing of the matrices for the default gain type VI to an html page with the title ‘Matrix equations’
clear all
slicap
numberOfErrors = checkCircuit('myCircuit');
dataType('matrix');
htmlPage('Matrix equations');
matrices2html(execute());