Getting Started

Installation

schemdraw can be installed from pip using

pip install schemdraw

or to include optional matplotlib backend dependencies:

pip install schemdraw[matplotlib]

To allow the SVG drawing Backends to render math expressions, install the optional ziamath dependency with:

pip install schemdraw[svgmath]

Alternatively, schemdraw can be installed directly by downloading the source and running

python setup.py install

Schemdraw requires Python 3.7+. Python 3.8+ is recommended for its walrus operator (:=) that allows a more compact notation of defining schematics.

Overview

The schemdraw module allows for drawing circuit elements. schemdraw.elements contains Basic Circuit Elements pre-defined for use in a drawing. A common import structure is:

import schemdraw
import schemdraw.elements as elm

Schemdraw uses two main classes for creating circuit diagrams: schemdraw.elements.Element and schemdraw.Drawing. Element instances are created and added to a Drawing to make a complete schematic diagram. All the different circuit elements subclass schemdraw.elements.Element and have methods for defining the element’s parameters and location within the drawing. Individual elements can be viewed using the Jupyter representation of the element object:

elm.Resistor().label('R1')
../_images/start_1_0.svg

To make a complete circuit diagram, a schemdraw.Drawing is created and schemdraw.elements.Element are added to it:

d = schemdraw.Drawing()
d.add(elm.Resistor())
d.add(elm.Capacitor())
d.add(elm.Diode())
d.draw()
../_images/start_2_0.svg

The += operator can also be used as shorthand notation to add elements to the drawing. This code is equivalent to the above:

d = schemdraw.Drawing()
d += elm.Resistor()
d += elm.Capacitor()
d += elm.Diode()
d.draw()

Element properties can be set using a chained method interface (new in version 0.9), for example:

d = schemdraw.Drawing()
d += elm.Resistor().label('100KΩ')
d += elm.Capacitor().down().label('0.1μF', loc='bottom')
d += elm.Line().left()
d += elm.Ground()
d += elm.SourceV().up().label('10V')
d.draw()
../_images/start_3_0.svg

Methods up, down, left, right specify the drawing direction, and label adds text to the element. If not specified, elements reuse the same direction from the previous element, and begin where the previous element ended.

For full details of placing and stylizing elements, see Adding circuit elements. and the schemdraw.elements.Element. In general, parameters that control what is drawn are passed to the element itself, and parameters that control how things are drawn are set using chained Element methods. For example, to make a polarized Capacitor, pass polar=True as an argument to Capacitor, but to change the Capacitor’s color, use the .color() method: elm.Capacitor(polar=True).color(‘red’).

Calling d.draw() assembles the drawing. In Jupyter, this will show the schematic inline as the cell output. If run as a script, the schematic will display in the interactive matplotlib window.

When saving, the image type is determined from the extension. Options include svg, eps, png, pdf, and jpg. A vector format, such as svg is recommended for best results.

d.save('basic_rc.svg')

Usage Modes

Jupyter Notebooks

Using a Jupyter Notebook in inline mode is recommended for the easy interactive creation of circuit diagrams. If your schematics pop up in an external window, set Matplotlib to inline mode before importing schemdraw:

%matplotlib inline

For best results when viewing circuits in the notebook, use a vector figure format, such as svg before importing schemdraw:

%config InlineBackend.figure_format = 'svg'

Python Scripts

Code in a .py file can be run to generate figures, and by default, calling d.draw() will display a GUI window for viewing the schematic. Add the show=False option to d.draw() to suppress the window from appearing.

Rather than saving the schematic image to a file, the raw image data as a bytes array can be obtained by calling .get_imagedata() with the desired image format. This can be useful for integrating schemdraw into an existing GUI or web application.

from schemdraw import Drawing

drawing = Drawing()
...
image_bytes = drawing.get_imagedata('svg')

Server Side

When running on a server, sometimes there is no display available. The code may attempt to open the GUI preview window and fail. In these cases, try setting the Matplotlib backend to a non-gui option. Before importing schemdraw, add these lines to use the Agg backend which does not have a GUI. Then get the drawing using d.get_imagedata(), or d.save() rather than d.draw().

import matplotlib
matplotlib.use('Agg') # Set the backend here

Alternatively, use the SVG backend (see below).

Backends

By default, all schematics are drawn on a Matplotlib axis. Starting in version 0.9, schematics can also be drawn on a new experimental SVG image backend. Similar to Matplotlib’s backend behavior, the SVG backend can be used for all drawings by calling:

schemdraw.use('svg')

Unlike Matplotlib, the backend can be changed at any time. Alternatively, the backend can be set at the time of drawing:

drawing.draw(backend='svg')

Reasons to choose the SVG backend include:

  • No Matplotlib or Numpy dependency required.

  • Speed. The SVG backend draws 4-10x faster than Matplotlib, depending on the circuit complexity.

Reasons to use Matplotlib backend:

  • To customize the schematic after drawing it by using other Matplotlib functionality.

  • To render directly in other, non-SVG, image formats

Searchable SVGs

By default, the Matplotlib backend renders text labels as primative lines and arcs rather than text elements. This has the downside that SVG editors, such as Inkscape, cannot perform textual searches on the SVGs. The upside is that there is no dependence on installed fonts on the hosts that open the SVGs.

To configure Matplotlib to render labels as SVG text elements:

import matplotlib
matplotlib.rcParams['svg.fonttype'] = 'none'

The SVG backend can produce searchable-text SVGs by setting:

schemdraw.settextmode('text')

or it can render text as SVG paths (the default if ziamath is installed), allowing for complete Latex math support, by setting:

schemdraw.settextmode('path')