Commit e611864f authored by Sean Leavey's avatar Sean Leavey

Merge branch 'develop'

parents 214d8c30 7b31812b
Pipeline #35843 passed with stages
in 5 minutes
# Autogenerated version file
circuit/_version.py
zero/_version.py
# Autogenerated API documentation
docs/api
......
......@@ -38,6 +38,7 @@ stages:
- chmod +x fil_static
- cd ..
- export LISO_DIR=$(pwd)/liso
- export LISO_PATH=$LISO_DIR/fil_static
- python --version
- apt update -qy
- apt install --assume-yes python-pip
......
......@@ -16,7 +16,7 @@ test-validation:
python tests/runner.py validation
lint:
pylint --rcfile=.pylintrc circuit
pylint --rcfile=.pylintrc zero
security:
bandit -c=.banditrc -r circuit
bandit -c=.banditrc -r zero
# circuit.py
# Zero
Linear electronic circuit simulator utility. This package provides tools to
simulate transfer functions and noise in linear electronic circuits, SI unit
parsing and formatting and more.
......@@ -8,7 +8,7 @@ It also (somewhat) understands LISO input and output files, and can plot or
re-simulate their contents.
## Documentation
See the [online documentation](https://docs.ligo.org/sean-leavey/circuit/).
See the [online documentation](https://docs.ligo.org/sean-leavey/zero/).
## Program and library
The simulator tries to replicate LISO's operation: a small signal ac analysis.
......@@ -36,31 +36,31 @@ This library contains a `setup.py` file which tells Python how it should be
installed. Installation can be automated using `pip`. Open up a terminal or
command prompt (Windows) and type:
```bash
pip install git+https://git.ligo.org/sean-leavey/circuit.git
pip install git+https://git.ligo.org/sean-leavey/zero.git
```
This installs the library and adds a console script `circuit` which provides
This installs the library and adds a console script `zero` which provides
access to the package's command line utility.
If you want to update the library to a later version after having previously
installed it, run:
```bash
pip install git+https://git.ligo.org/sean-leavey/circuit.git --upgrade
pip install git+https://git.ligo.org/sean-leavey/zero.git --upgrade
```
## Basic usage
There is a basic CLI provided by the program. Open up a terminal and type:
```bash
circuit --help
zero --help
```
for a list of available commands. Run `circuit [command] --help` for more detailed
for a list of available commands. Run `zero [command] --help` for more detailed
help for a particular `[command]`.
### Run LISO files
```bash
circuit liso path/to/liso/file
zero liso path/to/liso/file
```
`circuit.py` can parse both LISO input (`.fil`) and LISO output (`.out`) files.
`Zero` can parse both LISO input (`.fil`) and LISO output (`.out`) files.
The above command will display the results. Some commands are not yet supported
(see `LISO parsing` below).
......@@ -69,29 +69,29 @@ To force a file to be parsed as either an input or an output file, specify the
`--force-input` or `--force-output` flags.
### Comparing results to LISO
A comparison between `circuit.py`'s native result and that of LISO can be made
with `circuit liso-compare path/to/liso/file`. Note that any operations that
A comparison between `Zero`'s native result and that of LISO can be made
with `zero liso-compare path/to/liso/file`. Note that any operations that
involve running LISO (e.g. `liso-compare`) require the LISO binary to be set
using the `LISO_DIR` environment variable.
LISO can also be run by `circuit.py` directly, using the `circuit liso-external`
LISO can also be run by `Zero` directly, using the `zero liso-external`
command. To allow LISO to plot its own results, instead of plotting the results
in `circuit.py`, specify the `--liso-plot` flag.
in `Zero`, specify the `--liso-plot` flag.
### As a library
`circuit.py` can also be included as a library within other Python code. For
`Zero` can also be included as a library within other Python code. For
examples of how to build simulation scripts with Python, see the `examples`
directory.
## Tests
The script in `/tests/runner.py` can be run to automatically test `circuit.py`.
The script in `/tests/runner.py` can be run to automatically test `Zero`.
There are various tests which compare the results of simulations to LISO; these
can be run with `runner.py validation`. To run all tests, call `runner.py` with
the `all` argument.
## Limitations
See the documentation for LISO [input](https://docs.ligo.org/sean-leavey/circuit/liso/input.html#known-incompatibilities)
and [output](https://docs.ligo.org/sean-leavey/circuit/liso/output.html#known-incompatibilities)
See the documentation for LISO [input](https://docs.ligo.org/sean-leavey/zero/liso/input.html#known-incompatibilities)
and [output](https://docs.ligo.org/sean-leavey/zero/liso/output.html#known-incompatibilities)
parsing.
### Op-amp library
......@@ -123,7 +123,7 @@ A LISO op-amp library parser may be added at a later date.
## Contributing
Bug reports and feature requests are always welcome, as are contributions to the
code. Please use the project's [issue tracker](https://git.ligo.org/sean-leavey/circuit/issues).
code. Please use the project's [issue tracker](https://git.ligo.org/sean-leavey/zero/issues).
## Future ideas
- Return plot objects to allow user to modify them
......@@ -153,10 +153,9 @@ code. Please use the project's [issue tracker](https://git.ligo.org/sean-leavey/
thereby allowing nonlinear components like diodes to be modelled)
## Credits
Sean Leavey
<sean.leavey@ligo.org>
Sean Leavey
<sean.leavey@ligo.org>
Invaluable insight into LISO's workings provided by Gerhard Heinzel.
The author is grateful for additional contributions by:
- Sebastian Steinlechner
The author is grateful for additional contributions by Sebastian Steinlechner.
This diff is collapsed.
# analyses
from .ac import AcSignalAnalysis, AcNoiseAnalysis
\ No newline at end of file
This diff is collapsed.
......@@ -51,7 +51,7 @@ clean:
.PHONY: apidoc
apidoc:
sphinx-apidoc -o api -e ../circuit
sphinx-apidoc -o api -e ../zero
.PHONY: html
html: apidoc
......
......@@ -9,7 +9,7 @@
<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 195)">
<title>%3</title>
<polygon fill="white" stroke="none" points="-4,21 -4,-195 237,-195 237,21 -4,21"/>
<text text-anchor="middle" x="116.5" y="10.4" font-family="Helvetica,sans-Serif" font-size="8.00">Made with graphviz and circuit.py</text>
<text text-anchor="middle" x="116.5" y="10.4" font-family="Helvetica,sans-Serif" font-size="8.00">Made with graphviz and Zero</text>
<!-- c1 -->
<g id="node1" class="node"><title>c1</title>
<polygon fill="YellowGreen" stroke="black" points="61.9702,-101.596 34.9702,-83.5965 61.9702,-65.5965 88.9702,-83.5965 61.9702,-101.596"/>
......
.. currentmodule:: circuit.analysis.ac.noise
.. currentmodule:: zero.analysis.ac.noise
#######################
Small AC noise analysis
......
.. currentmodule:: circuit.analysis.ac.signal
.. currentmodule:: zero.analysis.ac.signal
########################
Small AC signal analysis
......
......@@ -3,7 +3,7 @@ Analyses
.. code-block:: python
>>> from circuit.analysis import AcSignalAnalysis, AcNoiseAnalysis
>>> from zero.analysis import AcSignalAnalysis, AcNoiseAnalysis
The circuit can be solved in order to compute transfer functions or noise in a
single run. If both transfer functions *and* noise are required, then these
......
......@@ -4,7 +4,7 @@ The circuit
.. code-block:: python
>>> from circuit import Circuit
>>> from zero import Circuit
====================
What is a 'circuit'?
......
.. include:: /defs.txt
######################
Command line interface
######################
|Zero| provides a command line interface to perform some common tasks, mainly focused on the
running, display and comparison of LISO scripts.
.. hint::
Also see the documentation on :ref:`LISO compatibility <liso/index:LISO Compatibility>`.
====================
Command line options
====================
.. click:: zero.__main__:cli
:prog: zero
:show-nested:
.. include:: /defs.txt
Components
==========
.. code-block:: python
>>> from circuit.components import Resistor, Capacitor, Inductor, OpAmp
>>> from zero.components import Resistor, Capacitor, Inductor, OpAmp
======================
What is a 'component'?
......@@ -34,12 +36,11 @@ produce noise, whereas :class:`resistors <.Resistor>` do (:class:`Johnson noise
Setting a component's value
---------------------------
A passive component's :attr:`~.PassiveComponent.value` may be altered. First, you must have a
reference to the component object:
A passive component's :attr:`~.PassiveComponent.value` may be altered. First, get the component:
.. code:: python
c1 = circuit.get_component("c1")
c1 = circuit["c1"]
You can then set the value using the object's :attr:`~.PassiveComponent.value` attribute:
......@@ -67,6 +68,10 @@ The above value is parsed as ``2.2e-9``, with unit ``F``. The unit is stored alo
part within the object, and the unit will be printed alongside the component's value when it is
displayed.
.. note::
Units are just for display and are not used for any calculations. Be careful when specifying
units which differ from those used internally by |Zero|.
.. toctree::
:maxdepth: 2
......
.. currentmodule:: circuit.components
.. include:: /defs.txt
.. currentmodule:: zero.components
#######
Op-amps
#######
:class:`Op-amps <OpAmp>` in `circuit` take differential inputs and provide a
:class:`Op-amps <OpAmp>` in |Zero| take differential inputs and provide a
single output.
Voltage gain
......
.. currentmodule:: circuit.components
.. currentmodule:: zero.components
##################
Passive components
......
# -*- coding: utf-8 -*-
#
# circuit.py documentation build configuration file, created by
# Zero documentation build configuration file, created by
# sphinx-quickstart on Mon Nov 13 10:13:06 2017.
#
# This file is execfile()d with the current directory set to its
......@@ -22,7 +22,7 @@ from pkg_resources import get_distribution
sys.path.insert(0, os.path.abspath('.'))
import circuit
import zero
# -- General configuration ------------------------------------------------
......@@ -42,7 +42,8 @@ extensions = [
'sphinx.ext.todo',
'sphinx.ext.coverage',
'sphinx.ext.viewcode',
'sphinx.ext.napoleon'
'sphinx.ext.napoleon',
'sphinx_click.ext'
]
# Add any paths that contain templates here, relative to this directory.
......@@ -62,7 +63,7 @@ source_suffix = '.rst'
master_doc = 'index'
# General information about the project.
project = 'circuit.py'
project = 'Zero'
copyright = '2018, Sean Leavey'
author = 'Sean Leavey'
......@@ -71,7 +72,7 @@ author = 'Sean Leavey'
# built documents.
#
# The full version, including alpha/beta/rc tags.
release = get_distribution('circuit').version
release = get_distribution('zero').version
# The short X.Y version.
version = '.'.join(release.split('.')[:3])
......@@ -257,7 +258,7 @@ html_show_sphinx = False
# html_search_scorer = 'scorer.js'
# Output file base name for HTML help builder.
htmlhelp_basename = 'circuitpydoc'
htmlhelp_basename = 'zerodoc'
# -- Options for Intersphinx ----------------------------------------------
......@@ -292,7 +293,7 @@ latex_elements = {
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
(master_doc, 'circuitpy.tex', 'circuit.py Documentation',
(master_doc, 'zero.tex', 'Zero Documentation',
'Sean Leavey', 'manual'),
]
......@@ -334,7 +335,7 @@ latex_documents = [
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
(master_doc, 'circuitpy', 'circuit.py Documentation',
(master_doc, 'zero', 'Zero Documentation',
[author], 1)
]
......@@ -349,8 +350,8 @@ man_pages = [
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
(master_doc, 'circuitpy', 'circuit.py Documentation',
author, 'circuitpy', circuit.DESCRIPTION,
(master_doc, 'zero', 'Zero Documentation',
author, 'zero', zero.DESCRIPTION,
'Miscellaneous'),
]
......
......@@ -18,7 +18,7 @@ Documentation style
Use `NumPy docstring format`_. Language and grammar should follow `Google style`_.
.. _issue tracker: https://git.ligo.org/sean-leavey/circuit/issues
.. _issue tracker: https://git.ligo.org/sean-leavey/zero/issues
.. _PEP 8: https://www.python.org/dev/peps/pep-0008/
.. _NumPy docstring format: https://numpydoc.readthedocs.io/en/latest/example.html
.. _Google style: https://developers.google.com/style/
\ No newline at end of file
.. _Google style: https://developers.google.com/style/
......@@ -4,4 +4,4 @@ Data containers
.. code-block:: python
>>> from circuit.data import TransferFunction, NoiseSpectrum
>>> from zero.data import TransferFunction, NoiseSpectrum
.. role:: raw-html(raw)
:format: html
.. |Zero| replace:: :raw-html:`<strong><em>Zero</em></strong>`
.. include:: /defs.txt
Input file parsing
==================
`circuit.py` is capable of parsing some LISO input files. First, import the LISO input parser:
|Zero| is capable of parsing some LISO input files. First, import the LISO input parser:
.. code:: python
from circuit.liso import LisoInputParser
from zero.liso import LisoInputParser
then create a parser object:
......@@ -23,9 +25,9 @@ To parse a LISO circuit, either call the :meth:`~.LisoParser.parse` method with
r r2 43k nm nout
c c2 47p nm nout
op o1 lt1124 nin nm nout
freq log 1 100k 100
uinput nin 0
uoutput nout:db:deg
""")
......@@ -53,7 +55,7 @@ You can at any time list the circuit's constituent components:
.. code-block:: text
Circuit with 6 components and 5 nodes
1. c1 [in=gnd, out=n1, C=1e-05]
2. c2 [in=nm, out=nout, C=4.7e-11]
3. input [in=gnd, out=nin, Z=default]
......@@ -65,7 +67,7 @@ You can also plot the circuit's node network using Graphviz, if installed:
.. code:: python
from circuit.display import NodeGraph
from zero.display import NodeGraph
NodeGraph(parser.circuit)
.. image:: /_static/liso-input-node-graph.svg
......
......@@ -6,4 +6,4 @@ Quantity formatting tools.
.. code-block:: python
>>> from circuit.format import Quantity
>>> from zero.format import Quantity
Circuit documentation
=====================
.. include:: /defs.txt
|Zero| documentation
====================
.. note::
`Circuit` is still under construction, with the program structure and behaviour **not at all**
stable, including the name. The program, as with this documentation, may be altered in ways that
break existing scripts at any time without notice.
|Zero| is still under construction, with the program structure and behaviour **not** stable.
The program, and this documentation, may be altered in ways that break existing scripts at any
time without notice.
`Circuit` is a linear circuit simulation library and command line tool. It is able to
|Zero| is a linear circuit simulation library and command line tool. It is able to
perform small signal AC analysis on collections of components such as resistors, capacitors,
inductors and op-amps to predict transfer functions and noise.
==============
Why `circuit`?
==============
===========
Why |Zero|?
===========
Given that tools such as `LTspice <http://www.analog.com/en/design-center/design-tools-and-calculators/ltspice-simulator.html>`_
and `Qucs <http://qucs.sourceforge.net/>`_ exist, why use this tool?
......@@ -21,32 +23,32 @@ The answer is: it depends. For simple circuits where precision is not critical,
model non-linear or time-variant effects, then the above tools are potentially useful; however,
whilst manufacturers often provide SPICE models to represent their parts, these often do not
correctly model noise, open loop gain and output impedance. :ref:`LISO <index:LISO>`, upon which
`circuit` is based, was motivated in part by this reason, and instead provided *measured* op-amp
|Zero| is based, was motivated in part by this reason, and instead provided *measured* op-amp
data as part of its library, which became incredibly useful to its users.
===================
What `circuit` does
===================
================
What |Zero| does
================
`circuit` can perform small signal analyses on circuits containing linear components. It is
|Zero| can perform small signal analyses on circuits containing linear components. It is
inherently ac, and as such can compute frequency responses between nodes or components and
noise spectral densities at nodes. Inputs and outputs can be specified in terms of voltage or
current (except noise, which, for the time being can only be computed as a voltage).
==========================
What `circuit` does not do
What |Zero| does not do
==========================
`circuit` linearises the circuit before performing an analysis, and as such distorsion, saturation
|Zero| linearises the circuit before performing an analysis, and as such distorsion, saturation
or intermodulation that would occur in the real circuit is not considered. It also assumes that the
circuit's components' operating points are around zero, and so non-linear components which can be
operated in a linear regime such as transistors cannot be simulated, nor the effect of dc offsets
on op-amps. One exception to this is the :class:`op-amp <.OpAmp>`, which is available in `circuit`
on op-amps. One exception to this is the :class:`op-amp <.OpAmp>`, which is available in |Zero|
but only as a linearised component; as such, limits to the op-amp's input or output swing are
not able to be simulated in the standard analysis.
It is in principle possible to linearise non-linear components as a first step before performing an
ac analysis (i.e. to compute a non-zero operating point); this is not yet possible with `circuit`
ac analysis (i.e. to compute a non-zero operating point); this is not yet possible with |Zero|
but may be available in the future. For those wishing to simulate circuits containing non-linear
components, try a variety of SPICE (e.g. `LTspice <http://www.analog.com/en/design-center/design-tools-and-calculators/ltspice-simulator.html>`_)
or `Qucs <http://qucs.sourceforge.net/>`_.
......@@ -55,7 +57,7 @@ or `Qucs <http://qucs.sourceforge.net/>`_.
LISO
====
`Circuit` is based on `LISO <https://wiki.projekt.uni-hannover.de/aei-geo-q/start/software/liso>`_
|Zero| is based on `LISO <https://wiki.projekt.uni-hannover.de/aei-geo-q/start/software/liso>`_
by Gerhard Heinzel. It (mostly) understands LISO circuit mode input files, meaning that it
can be used in place of LISO to simulate circuit signals. It also understands LISO output
files, allowing results previously computed with LISO to be plotted, and for LISO results
......@@ -76,5 +78,6 @@ Contents
format/index
examples/index
liso/index
cli/index
API reference <api/modules>
contributing/index
LISO compatibility module
=========================
.. include:: /defs.txt
`circuit` somewhat understands `LISO <https://wiki.projekt.uni-hannover.de/aei-geo-q/start/software/liso>`_
LISO compatibility
==================
|Zero| somewhat understands `LISO <https://wiki.projekt.uni-hannover.de/aei-geo-q/start/software/liso>`_
input and output files. It is also capable of running a locally available LISO binary
and then plotting its results.
......
.. include:: /defs.txt
LISO input file parsing
=======================
......@@ -7,7 +9,7 @@ Known incompatibilities
Outputs
~~~~~~~
`circuit` does not support the `deg+` or `deg-` output coordinates. Please use `deg` instead.
|Zero| does not support the `deg+` or `deg-` output coordinates. Please use `deg` instead.
It also throws an error when a LISO script's `ioutput` or `uoutput` commands contain only a
phase coordinate, e.g.:
......@@ -15,9 +17,9 @@ phase coordinate, e.g.:
uoutput nout:deg
Such outputs could in principle be handled by `circuit`, but it would add complexity to the
Such outputs could in principle be handled by |Zero|, but it would add complexity to the
:class:`Solution` and :class:`Series` classes that is not worth the effort given how rare
this type of output is. In order to use such scripts with `circuit`, simply add a magnitude
this type of output is. In order to use such scripts with |Zero|, simply add a magnitude
unit, e.g.
.. code-block:: text
......@@ -27,8 +29,8 @@ unit, e.g.
Root mode
~~~~~~~~~
`circuit` does not support LISO's root mode, meaning that the fitting tools provided in LISO for
transfer functions and noise spectra are not replicated. It is suggested to instead use `circuit`
|Zero| does not support LISO's root mode, meaning that the fitting tools provided in LISO for
transfer functions and noise spectra are not replicated. It is suggested to instead use |Zero|
with a Python optimisation library such as `scipy.optimize <https://docs.scipy.org/doc/scipy/reference/optimize.html>`_.
Note that it is very important for circuit transfer function and noise fitting to use a well-suited
optimiser, particularly one that can fit in log space. LISO's fitting library performs very well for
......@@ -58,7 +60,7 @@ Op-amp library
~~~~~~~~~~~~~~
LISO's op-amp library format is not supported, but the full LISO library is bundled
in `circuit`'s native format.
in |Zero|'s native format.
The op-amp library is implemented in a different format to that of LISO,
primarily for logistical reasons: Python contains a convenient :class:`~configparser.ConfigParser`
......@@ -95,7 +97,7 @@ LISO Perl commands
~~~~~~~~~~~~~~~~~~
Commands used for running LISO in a loop with :code:`pfil` are not supported. Instead you
can use `circuit` as part of a Python script to run either LISO or native `circuit`
can use |Zero| as part of a Python script to run either LISO or native |Zero|
simulations in a loop.
Differences in behaviour
......@@ -104,7 +106,7 @@ Differences in behaviour
Command order
~~~~~~~~~~~~~
In LISO, the output must be specified *after* the components. In `circuit`, order is
In LISO, the output must be specified *after* the components. In |Zero|, order is
irrelevant.
`Noisy` command
......@@ -128,7 +130,7 @@ error is displayed:
*** Error: No noisy components! (Try 'noisy all')
In `circuit`, the :code:`noisy` command does not need to be present as by default, even in LISO,
In |Zero|, the :code:`noisy` command does not need to be present as by default, even in LISO,
the noise sources that contribute to the :code:`sum` output always includes those specified in
the output itself. The :code:`noisy` command is available merely to add additional noise sources
to the :code:`sum` that are not explicitly plotted.
......@@ -141,8 +143,8 @@ String lengths
~~~~~~~~~~~~~~
LISO has a limit of 16 for most strings (component names, op-amp types, node names, etc.). In
`circuit` the limit is effectively arbitrary.
|Zero| the limit is effectively arbitrary.
.. hint::
In the case of *mutual inductance* commands, the name is entirely ignored. This is used in
LISO only for fitting routines, which are not part of `circuit`.
LISO only for fitting routines, which are not part of |Zero|.
......@@ -3,7 +3,7 @@ Solutions
.. code-block:: python
>>> from circuit.solution import Solution
>>> from zero.solution import Solution
The :class:`.Solution` class provides a mechanism for storing, displaying and saving
the output of an :ref:`analysis <analyses/index:Analyses>`.
......@@ -5,7 +5,7 @@ used."""
import sys
import os
from circuit.liso import LisoInputParser
from zero.liso import LisoInputParser
if __name__ == "__main__":
# parse liso filename, if present
......@@ -21,4 +21,6 @@ if __name__ == "__main__":
parser = LisoInputParser()
parser.parse(path=filename)
# simulate and show results
parser.show(print_equations=True, print_matrix=True)
solution = parser.solution()
solution.plot()
solution.show()
......@@ -4,7 +4,7 @@ the results. If no file is specified, "liso1.out" is used."""
import sys
import os
from circuit.liso import LisoOutputParser