Using Circuit Macros

1 Introduction

It may seem very odd (and there again :-) that my choice of graphics package is a text-based command language, as opposed to these fancy GUI pointey and clickey things, occasionally known as CAD packages. Some of this background is covered in why I run GNU packages. Other reasons for the aversion to point and click things is that your hand is constantly reaching for the rodent…

And who of you have never had the frustration of attempting to get things to line-up, snapgrids and large cursors notwithstanding?

Again, unless you have a fairly fancy and expensive package, with a decent digitizer tablet, using element templates (op-amps, inductors) etc is difficult. Also I find myself constantly grouping and ungrouping things in order to move them or copy them etc. All this falls away with the Circuit Macros, written by Dwight Aplevich. The up-to-date version can be found at https://ctan.org/pkg/circuit-macros I have been using Circuit Macros exclusively for all graphics since 1999, I think it was version 4.something. A quarter of a century…… Thank you Dwight!

As a simple example, try a point-and-click solution to placing the bottom 100kΩ resistor exactly centrally! (BTW, my recommended point-and-click CAD is still xfig(), but I simply don’t use it.) (Click on picture for Code, and Browser Back)

Figure 1: A simple Precision Rectifier

The Circuit Macros are based on a mixture of the m4 macro language and the standard pic language. pic being one of the “little languages” like eqn and tbl for pictures, equations and tables which were extensions of troff, the original Unix Document Typesetting language, written by a completely unknown author by the name of Brian Kernighan, who wrote nothing else of Note, excepting the middle key of the Piano.

As the figures are drawn using a powerful programming language, all standard programming features exist—Dwight Aplevich has some stunning examples using for loops, subfunctions etc.

For plebs like me though, the macro’s are put together so well that the learning curve is particularly easy, without getting too fancy!

As a simple example of the use of a for loop, consider a simple ground plane:

Figure 2: A quarter-wavelength monopole on a groundplane.

2 Some of my Creations :-)

As an example of what can be done, I have processed all of my Electronics I (second year) lecture notes and present them by chapter. My Electromagnetics (third year), High Frequency Techniques (= Antennas) (fourth year) and several other miscellaneous things from various CPD courses that I run.

Electronics 1, in second year:

Electromagnetics, in third year:

High Frequency Techniques, in fourth year:

Miscellaneous: Miscellaneous Figures

3 Quickstart

This is so much easier now :-) My absolute recommendation is to use m4 piped to dpic -g piped out as TikZ specials that pdflatex understands and converts to a standalone .pdf graphics file.

That file is then processed through dvisvgm to get a .svg file for web viewing. No pstricks, no Postscript, no png, no gif, no font mismatches, no colour trickery, Just Perfection.

1. apt install circuit-macros dpic dvisvgm xpdf will ensure that the basics are there.
2. After installation, M4PATH needs to be set to include the Circuit Macros macros, as well as the local libraries. On my machine, I have added:

   export M4PATH=/usr/share/circuit-macros:~/apps/cct/mylibs

   to my ~/.bashrc file. In my local library, I have liborth.m4: Orthographic Projection library (for Electromagnetics)

3. The executable is simply cct, a shell script that does the heavy lifting, with far fewer dependencies than in the past.

   cct, m4path,

   open terminal to edit, run and xpdf the file.

   vimrc newdoc cct pdflatex R

   Tutorial Simple file first just pic, then smallest cct, then more advanced. Direction stuff first... (L1.start, Here) xy stuff.

   Manuals pic, gpic dpic CircuitMacros.

   ArcMAcros inputfig[0]filenameCaption

   Download for Linux; As root: cd /usr/local;tar zx cm.tgz; less /usr/local/doc/cct/README

4. Download for MsLoss
5. Hit the Readme’s :-) In the MsLoss case, I have extracted just pic and just m4 out of the usual bundled packages. (All 32-bit apps, hence needing DPMI, ie 9x or NT, ME or whatever the next name is for an MsLoss (Operating) System.)

4 Standard installation

As root, change dir to "/usr/local" and unpack the archive there using tar -zxf cm.tgz

Ensure that /usr/local/bin is in your path (It should be!!) for the scripts cct, ccteg, cctgif.

Set an environment variable in ~/.bashrc with export M4PATH=/usr/local/lib/cct

Check that m4 and gpic are installed (which).

You’re done.

Read the docs in the /usr/local/doc/cct (I have also included the classic PIC manual by Brian Kernighan) (and converted them to pdf too, just in case)

5 MsLoss installation

Since MsLoss has no sense of lib and bin, choose a suitable installation directory, (eg /apps/cct) and unzip the archive. Move the batch files cct.bat ccteg.bat cctgif.bat to somewhere on your path. Set the environment variable M4PATH to wherever your libs are.

6 My Customizations/Useful Tips

In the initial stages of laying out a new circuit (or any figure, I now use “Circuit Macros” for pretty much every graphical thing I need), it is useful to have an easy preview method. Since this entails a latex run, and I cannot pass a file name as a variable, I adopt a rigid filename. All new circuits are called ccteg.m4, and I use a little script ccteg to process it. I leave xdvi running in another screen so that it updates in real time. In the Dos world, similar batch files can be written. MikTeX provides YAP as the previewer, which can show the tpic specials.

I have made some minor modifications to the macros, allowing an additional parameter to a diode to denote an LED, modified the op-amp a tad, and added the power-supply connections—students simply don’t power these things up!!! Some of these have been adopted by the author of the macros. (I have reverted to using the original stuff now, as most “important” (to me) suggestions have been adopted by the original author!—try that with Uncle Bill :-)

I have also removed the hardcoded paths in ALL m4 files, and use M4PATH instead. ie I have changed: (in each file)

#ifdef(`HOMELIB_',,`define(`HOMELIB_',`/u/aplevich/lib/')')
ifdef(`HOMELIB_',,`define(`HOMELIB_',`')')

My convention of using .cct and \inputcct actually using the tpic specials is now deprecated: a .cct file is not really shareable with non-L^AT_EX 2є users. (I could say something here, but I’ll be good). So my new cct script produces (via an m4 run, a gpic run, a L^AT_EXrun, a dvips run, two gs runs, within the netpbm suite, we have a call to pnmcrop, pnmmargin, pnmalias, and pnmtopng. Finally a sed call sorts out the correct BoundingBox in the Encapsulated Postscript. :-) an .eps file and a web-able .png file. (Google burnallgifs) This entire procedure is completely transparent to the user, and from the original .m4 picture file, we magically simply get a .eps and a .png in the same directory.

Naturally cct *.m4 processes all figures in the directory. Try that in Doze :-)

The Encapsulated Postscript is inserted with \inputepsraw{fn}{cap} available from my ftp site, the snippet of interest (from the .dtx file) being:

\newcommand{\inputepsraw}[2]%
  {%
    \begin{figure}[!htb]%
      \centering%
      \includegraphics{#1.eps}%
      \caption{#2}%    includes fig num
      \label{fig:#1}%  ie may \ref{fig:#1}
    \end{figure}%
  }

Note that this includes the file at “natural” scaling, ie 10*mm in m4 will be 10mm on the printed page.

The relevant section from the cct.hva Hevea style file is:

% A replacement for \inputeps of the ArcMacro package, for the purpose of
% .png inclusion of the cct macros generated .eps, for Web use.
%
% Alan Robert Clark a.clark@ee.wits.ac.za
% 
% created 10 March 2005.

\renewcommand{\inputepsraw}[3][80]%
  {% Dont use height in HeVeA, but keep interface the same :-)
    \begin{figure*}[!htb]%
        \centering%
 \ahref{cctpng/#2.txt}{%
          \imgsrc{cctpng/#2.png}%
 }
        \caption{#3}%    includes fig num
        \label{fig:#2}%  ie may \ref{fig:#2}
    \end{figure*}%
  }

6.1 Useful Tips:

• Size things in terms of the basic unit dimen_. I tried following the idea of absolute grids as in the author’s first example, but this was not meant as general rule, and it becomes very tedious.

  This convention has also changed. Every new file automatically includes the following standard definitions:

  # Usual defs...
  qrt=dimen_/4
  hlf=dimen_/2
  dim=dimen_
  
  

  This allows mm to be the default when drawing arb things, and dim, hlf, qrt when actually using Circuit Elements.

• Open brackets immediately following a macro! The most common syntax error is resistor (right_) instead of resistor(right_) Its a pain, but you get used to it :-) (m4 Hangover, apparently)
• Define an environment variable M4PATH, and you won’t have to dabble with setting absolute paths in the macro files or the invocation.
• Label appropriate points, and use Here. One of the most useful constructs is to get a nice “Manhattan” line between two points (as opposed to a direct diagonal line, very seldom wanted in a cct diagram) is:

  line to (Op1.Out, Here)
  line to (Here, Op1.Out) 
  

  This is because both Here and Op1.Out have an x and a y component; in the first line, the x component of Op1.Out is used, and in the second line the y component.
• Don’t forget that Here retains its identity until the end of the construct. ie line to (Op1.Out,Here) then to (Here,Op1.Out)would NOT have worked in the above point!
• When debugging, use # at the beggining of lines to comment them out, until you find your glaring error!
• Another very useful construct is to bracket a section of code with curlies {}, which preserves the position of Here. An example is

  line right_ dimen_/2;dot 
  {line down_ dimen_/4;dot; "-10V" ljust_}
  line right_ dimen_/2
  

  where the third line takes off from where the first finished, not from where the second finished.
• If the direction changes and “inconsistencies” in llabel, rlabel,ljust,rjust is confusing, remember that these are always relative to the current direction! Remember the great Turtle Graphics???
• Note that a white fill value obliterates everything underneath. Hence to make an open noded circle put the dot(,,1) as the last entry that writes to location.

6.2 Scripts

The scripts are

6.2.1 ccteg

6.2.2 cct

6.2.3 ccteg.tex

The online version is "https://YingTongDiddleiPo.eie.wits.ac.za/cct.html"

This document was translated from L^AT_EX by H^EV^EA.