Volta User Guide
Introduction
What is Volta?
Volta is a software application for designing analog electric circuits on macOS. It offers graphical frontend and backend tools for SPICE-like command-line circuit simulators.
Circuits
There is one window for each circuit design. You can work on multiple circuits at the same time, each in its own window. A circuit window contains four resizable areas as shown in figure 1.
Design Workflow
You typically start designing your circuit in the schematic editor where you assemble and interconnect circuit components. You then repeatedly test and refine your design with the help of circuit simulations. To run circuit simulations, you 'capture' the schematic in a format that the simulator can process. When the simulation is done, depending on the output of the simulator, the results will be displayed graphically in the plotter area at the bottom.
The first three buttons in the toolbar of the window (Plot, Capture and Analyze) are your workflow buttons, where Plot and Analyze do more than their names imply. The Plot button also captures the schematic and runs the simulation. It is the button you will use most frequently. The Analyze button not only feeds the netlist and the analysis commands to the simulator but also plots the simulation results if sufficient data points exist. Use this button if you want to preserve changes that you made to the netlist after the schematic was captured.
The last two toolbar buttons, seen in figure 3, open or close the bottom plotter area and the right hand tools area, respectively.
Ngspice
Volta ships with the free circuit simulator Ngspice. One of the long-term goals of Volta is to wrap all Ngspice capabilities in easy-to-discover and, hopefully, easy-to-use graphical controls. Ideally, everything you can express with a netlist should be configurable in the schematic editor so that even for advanced use cases there is no need to edit netlists. Until this goal is reached you will need to know how to use Ngspice. Please refer to the detailed user manual on the Ngspice documentation page.
Schematic Editor
The schematic editor consists of an overhead component strip (the palette strip), an inspector panel, and a canvas for assembling components.
The Palette Strip
The schematic palette strip is located at the top of the schematic editor and displays a row of schematic elements. It is a convenient component source so that you don't need to deal with the library window for frequently used components. Changes to the contents of the palette strip, however, can only be made in the library window.
To add a copy of an element to the schematic you simply drag it from the palette to the canvas.
The palette in your library may contain many element groups but the schematic palette strip shows only one group at a time. Select the displayed group with the menu button at the top left.
Select "Edit..." to open the library window, where you can make changes.
The palette strip can be hidden (and shown again) with the 'Palette' toolbar button.
The Inspector
The inspector is a panel in the canvas for editing components. With the inspector you can rotate and flip components, change their model and their property values. If a single component is selected, you can also change the component name - as long as the name is not used by another component within the schematic. If multiple components are selected, you can only change the properties that are shared by all components.
The name of the selected component is displayed at the top of the inspector. You can edit the name by clicking and typing. Below are the controls for positioning the label, for rotating, and for flipping (mirroring). Further below is the model chooser where you can select alternative, type-compatible models. Lastly, there is a table of properties and their values. You can start editing a property's value by double-clicking on the field next to the property name.
For circuit components, the properties are SPICE properties. Refer to the Ngspice manual for their description.
The inspector can be hidden and shown again by pressing the "Inspector" toolbar button.
The inspector can be attached to any corner of the canvas.
Connecting Components
You connect two circuit components by dragging a connection line from the connection point (pin) of the first component to the pin of the second component. Each circuit component has at least one pin. Pins are highlighted in red when the mouse pointer is on top. A pin can accommodate only one connection. Use nodes, which have 4 pins, to join connectors. Disconnecting components is also easy: Simply drag the connector away from one of its connection points and let go.
Initially, a connection is a straight line. By dragging points on the linear segments of the connector you can insert joints. To remove a joint you simply drag it back to the (imaginary) line between its neighboring joints (or connection points). Joints are highlighted in green when the mouse pointer is on top.
Zooming
The schematic can be scaled up to twice the standard size. This feature is intended to make working on small, high-resolution displays easier. You can change the zoom factor with the slider in the toolbar (figure 7) or with a pinching gesture on your trackpad.
The Library
The library window is the primary interface to your collection of device models, customized component groups, and subcircuits. You open the library window either through the main menu, Window → Library, or by selecting "Edit..." in the group selection menu of the schematic palette.
Models
Similar to SPICE models, Volta models define classes of schematic elements. Unlike SPICE, Volta models also define classes of non-electrical schematic elements. A Volta model contains the common attributes of the class it defines: A shape, a set of connection points (i.e., pins), and a set of named properties.
All available device models are listed in the "Models" section of the library. Models are grouped by type (resistor, diode, MOSFET, voltmeter, etc.). All models have a name, some also have a vendor ID. The vendor ID serves to further differentiate a model and is especially useful when distributing your customized models to other users. For example, you can use your name or your e-mail address as vendor ID.
Models can be dragged to a palette group or to a schematic, where components with default property values will be inserted.
Subcircuits
The "Subcircuits" section of the library window lists all your subcircuits. A subcircuit item in the library window is a special kind of model that represents a Volta subcircuit document. A Volta subcircuit contains a SPICE subcircuit netlist, either captured from schematic or edited manually, that gets inserted when the schematic, in which the subcircuit is used, is captured.
Unlike models and palette components, subcircuits are not editable within the library window. Double-click a subcircuit item or single-click its link button to open the corresponding subcircuit document. Make your changes and save the document. The library will detect the change and reload automatically without having to restart Volta.
Subcircuits can be dragged to a palette group or to a schematic, where a component will be created.
Palette
The palette contains user-defined groups of circuit components (or other kind of schematic elements). Groups can be added , renamed or removed . Likewise, components can be added to a group, renamed or removed. Group names must be unique and component names must be unique within their groups.
Palette groups can be populated by dragging models or subcircuits into the group. Dragging components from group to group is also possible and creates copies of the dragged components in the target folder.
Library Storage
Except for the built-in models, the items in your library are loaded from and stored to user-accessible files. These files are located under Volta's library root folder, which is organized into sub-folders ("Models", "Palette", "Subcircuits") for the three types of library content. You can share your library content by distributing the files (please observe copyrights). Volta updates the library automatically when files are added to or removed from the above sub-folders.
Local vs. Cloud
The library root folder can be located either on your Mac or on iCloud. You can copy your locally stored library content to iCloud at any time and switch to using the iCloud library. The advantages of using the iCloud library are: having an online backup and automatic synchronization between multiple installations of Volta. The disadvantage is the risk of data loss when synchronizing two libraries which have been modified independently since the last synchronization.
The local library will not be modified while you use the iCloud library. You can switch back to using the local library at any time. It is also possible to copy the library contents from iCloud to local (or from local to iCloud) without switching.
Switching between the two libraries and copying the contents is done via the main menu, under "Volta" → "iCloud library".
The library root folder for local storage is located at "~/Library/Containers/com.kulfx.Volta/Data/Library/Application Support/Volta", where ~ denotes your home folder.
Access from the Library Window
For each type of library content (model, palette, subcircuit) there is a button in the library window, which will reveal the contents of the corresponding library root sub-folder. When using your local library, the buttons look like a folder and the folder contents are presented in Finder. When using the iCloud library, the buttons look like a cloud and the folder contents are presented in Volta's own file view window.
Storage of Custom Models
Custom models, that you create by copying (and modifying) existing models, will be stored in the model library file "CustomModels.volta". This is the only model library file whose contents can be modified from within Volta. Models read from other model library files can not be modified. That's why some models in the library can not be modified and show a lock symbol.
SPICE Model Library Files
In addition to library files in Volta's own file format, Volta can load models from SPICE library (lib) files. The following format is required for lib files:
.MODEL <model name> <model type> +param1=value1 param2=value2 +param3=value3 param4=value4 ...
No space is allowed around the '=' sign. Comment lines starting with an asterisk (*) can be inserted everywhere.
The Netlist Editor
The netlist editor displays the results of the schematic capture. It shows line numbers and colorizes the netlist lines. Other than that, the netlist editor is a simple text editor where you can make modifications to the netlist before running the circuit simulation.
A netlist is basically a line-by-line listing of circuit components together with the nodes the connect to. The netlist also includes analysis commands for the simulator. Please refer to the Ngspice documentation for a detailed description.
Note, that, any modifications you make to the netlist will be overwritten the next time you capture the schematic again.
Circuit Simulations
Simulator
Volta comes with the free circuit simulator Ngspice out of the box. Ngspice is an open-source successor of UC Berkeley's widely-known SPICE 3 simulator. For more information on Ngspice please visit the Ngspice web site. For information on SPICE itself please visit the Wikipedia page.
Running Simulations
You run simulations by pressing either the "Analyze" or the "Plot" button in the toolbar. "Plot" will capture the schematic (and replace the existing netlist) before starting the simulation. "Analyze" uses the existing netlist and does not capture.
The gear wheel icon of the Analyze button animates while the simulation is running. Pressing the button while it animates aborts the simulation.
Volta displays the raw text output of the simulator in the "Simulator" panel.
Plotting Simulation Results
When a simulation finishes, Volta automatically parses the output in order to extract analysis data. If tabular analysis data is present, Volta draws graphs in the plotter area.
The plotter is still very basic. The ordinate (y axis) always shows real values in linear scale. The abscissa (x axis) shows real values in linear or logarithmic (for AC analyses) scale.
The plotter allows switching between multiple graphs through the menu seen in figure 3. The menu is only available if graph data for multiple entities exist.
Working With Subcircuits
Volta supports the concept of subcircuits, which are re-usable partial circuits. In Volta, subcircuits are special circuit documents that can be loaded into the library where they act as device models.
Creating Subcircuits
You can create a Volta subcircuit, either based on a schematic design or from an existing SPICE subcircuit netlist, by following these steps:
- Open the subcircuit editor.
- Enable the subcircuit.
- Give the subcircuit a name.
- Optionally, give it a vendor ID.
- Select the number of external pins.
- Enter the nodes corresponding to the external pins.
- Capture the schematic.
Do not perform the last step (capturing the schematic) if the subcircuit is based on an existing SPICE subcircuit netlist.
In step 5 you choose the pin count for the DIP (dual in-line package) shape of the subcircuit. Only DIP shapes are currently available. There will be more choices in a future version of Volta.
The node assignment in step 6 defines an interface to the node network of the subcircuit. Without this interface the subcircuit will not be accessible for the simulator. Please double-check, that, the node names you are providing actually exist in the netlist. If a pin is not used leave the corresponding node name empty.
Hint: When designing a subcircuit, also create test circuits to verify that the subcircuit works as expected.
Using Subcircuits
Before you can use the subcircuit that you created, you need to place the subcircuit file in the subcircuits storage folder. The library will automatically pick it up from there and add the subcircuit item to the list in "Subcircuits".
You can open the subcircuits storage folder in Finder by pressing the button with the folder icon at the bottom of the "Subcircuits" section of the library window (see figure 2).
Drag the subcircuit item from the list in the library window to your circuit to insert it. You can also add subcircuits to a palette group and access it from the schematic palette strip.
Keyboard Shortcuts
Schematic Editor
| ⌥⌘I | Hides or shows the inspector panel. |
| ⌘A | Selects all components. |
| Backspace | Removes the selected components from the circuit. |
| ⌘← | Rotates the selected components 90° counterclockwise. |
| ⌘→ | Rotates the selected components 90° clockwise. |
| ←, →, ↑, ↓ | Moves the selected components. Larger steps with Shift key (⇧). |
| ⌘- | Flips the selected components horizontally. |
| ⌘| | Flips the selected components vertically. |
Circuit Document
| ⌥⌘P | Captures the circuit, starts a circuit analysis, plots results. |
| ⌥⌘C | Captures the schematic. |
| ⌥⌘A | Starts or stops circuit analysis, plots results. |
General
| ⌘L | Opens or closes the component library window. |