Linear model of the tagger microscope preamplifier circuit in Matlab
                      Richard Jones and Igor Senderovich
                       last modified: December 16, 2013

Synopsis
---------
1) Compile the model to Matlab m files from source mpp files.  The model of
the full preamplifier is contained in the source file equations.mpp which is
the one assumed in the next step.  Other mpp files exist in the directory
for studying other auxilliary circuits that are decoupled from the preamp
signal path.

	$ ./mpp.pl equations.mpp

2) Start Matlab and from the prompt in the Command Window type the following
command.  It runs a series of tests of the validity of the model, and prints
out a report summarizing the behavior of the circuit at a standard set of
signal frequencies.

      >> runmodel

3) Edit equations.mpp in the section where the dc levels are defined (search
for the string "dc bias levels") and modify the external dc set points, then
repeat the two steps above to see the effect of your changes.

4) To explore the model in greater detail, use the runmodel script as a
starting point for how to use the various software components.


Source files ending with .mpp
------------------------------
A Matlab script or function ends with the single-letter .m suffix called
by Matlab programmers a "m-file".  The m-files that implement the circuit
model contain a mix of model definition code and code that implements the
linear algebra algorithm for solving it.  This mixture makes reading and
modifying the model m-files difficult and error-prone for large models.
For this reason, the model definition part has been abstracted out into
"proto-m-files" that are interpreted by a custom preprocessor written in
perl called mpp (mpp.pl) and converted into m-files.  Files that end with
.mpp are not directly executable by Matlab, but must first be converted to
.m files by running them through mpp, as illustrated in the synopsis above.


File inventory
---------------
runmodel.m	- top-level script that runs the model and prints out
		  an assortment of (possibly) interesting results;
equations.mpp 	- the main source file for the model;
equations.m	- function automatically generated from equations.mpp;
varnames.m	- function automatically generated the last time mpp.pl
		  was run, must be regenerated each time a model is used;
calibrate.m	- sets the internal dc set points for the circuit, must be
		  called once when the model is loaded, or when any of the
                  external dc set points are changed, automatically called
		  by the runmodel script;
transistor_model.m - function that describes the non-linear behavior of the
		  transitors in the model, used by calibrate.m to determine
		  the operating point of the transistors around which their
		  ac behavior can be linearized;
check_transistor.m - evaluates the operating point of a transistor within
		  the model, and runs a series of checks on its validity,
		  printing a report with detected errors highlighted in red;
cprintf.m	- a printf function for Matlab that includes capability to
		  change the color of text displayed in the output window,
		  needed by check_transistor.m;
pulsefft.m	- function implementing a pulse-response model of the
		  preamplifier, with parameterized input waveform defined 
		  by adjustable parameters located near the top of the file,
		  and an argument specifying at what point in the circut
		  the response pulse shape should be measured;
showpulse.m	- function that generates a graph of results from pulsefft.m;
showabs.m	- function that generates a graph of a selected output from
		  the model on a log-log plot of that output amplitude vs
		  frequency;
showarg.m	- function similar to showabs.m, but showing the phase of
		  the selected output vs log(frequency);
stiffener.mpp	- auxilliary source file modeling a possible bias voltage
		  stiffening circuit that might be added to the board;
stiffener.m	- m-file generated from stiffener.mpp;
calib_stiff.m   - counterpart function to calibrate.m, for the stiffener
		  model;
showstiff.m	- a quick script to run the stiffener model and produce
		  a meaningful plot of its dc behavior.