path: root/readme.org

#+TITLE: Readme
* Overview

Extends org-babel capabilities to support spice simulations using
ngspice. Simulations are executed using an interactive ngspice process
running in emacs. The running ngspice process can be used to
manipulate the simulation results directly or spread a simulation into
multiple src blocks.

Spice source blocks are interpreted as circuit descriptions until an
'.end' line is encountered. After that a control part may follow
(surrounded by '.control' and '.endc' lines). If there is no '.end'
line all of the src block is interpreted as a control block!

* Installation

Add ~ob-spice.el~ to your load-path and add ~(spice . t)~ to to your
~org-babel-load-languages~ list.

* Examples
To look at the src block header arguments look at this file in raw
mode. Or load it into your emacs (using eww for example) and turn on
org-mode.
** Load a circuit for later simulation
#+BEGIN_SRC spice :results output
,* RC
r1 1 0 10k
c1 1 0 1p
.IC V(1)=1
.tran 1n 0.1u
.end
#+END_SRC
#+RESULTS:
: Circuit: * rc

** Execute some stuff
#+NAME: ex_1
#+BEGIN_SRC spice :exports both
echo "Hello world"
#+END_SRC
returns
#+RESULTS: ex_1
: Hello world

#+NAME: ex_2
#+BEGIN_SRC spice :exports both
echo "0,1,2,3"
#+END_SRC
returns
#+RESULTS: ex_2
| 0 | 1 | 2 | 3 |

** Plot some voltages and return png
#+BEGIN_SRC spice :var file="/tmp/xzy" :results file
,*RC circuit
r1 1 0 10k
c1 1 0 1p

.IC V(1)=1
.tran 1n 0.1u
.end

.control
run
set gnuplot_terminal=png
gnuplot $file v(1)
.endc
#+END_SRC

#+RESULTS:
[[file:/tmp/xzy.png]]

** Do measurements and return results
#+BEGIN_SRC spice :results value :exports both
,*Time Constant Measurement
r1 1 0 10k
c1 1 0 1p

.IC V(1)=1
.tran 1n 0.1u
.print tran v(1)
.end

.control
run
meas tran value_at_tau find V(1) at=1e-8
meas tran value_at_five_tau find V(1) at=5e-8
echo $&value_at_tau ,$&value_at_five_tau
.endc
#+END_SRC

#+RESULTS:
| 0.36798 | 0.00671732 |

** Write simulation data to file and return file name

A gnuplot block is called on the result of the spice block using the
~:post~ argument. This allows the usage of all gnuplot options instead
of the limited ngspice subset.

#+NAME: plot_stuff
#+BEGIN_SRC gnuplot :var data="whatever" :file "/tmp/ignored.png" :results silent
plot data u 1:2 w l ls 1
#+END_SRC

#+BEGIN_SRC spice :var file="/tmp/xyz" :post plot_stuff[:file /tmp/xyz.png](data=*this*) :results file
,*RC circuit
r1 1 0 10k
c1 1 0 1p
.IC V(1)=1
.tran 1n 0.1u
.end
.control
run
wrdata $file v(1)
.endc
#+END_SRC

#+RESULTS:
[[file:/tmp/xyz.png]]

** Use calculation results of other src blocks as parameters

Parameters calculated in any language can be included as variables.

Using ruby:
#+NAME: dim1_params
#+BEGIN_SRC ruby :exports code
[7.326e-06,1.321e-05,5.4117e-06,2.344e-05,2.4e-06, 100.0]
#+END_SRC
#+RESULTS: dim1_params
| 7.326e-06 | 1.321e-05 | 5.4117e-06 | 2.344e-05 | 2.4e-06 | 100.0 |

Gnuplot code:
#+NAME: dim1_plot
#+BEGIN_SRC gnuplot :var data="x" :file /tmp/ignored.png :results silent :exports code
set terminal pngcairo size 640,300 enhanced
set format y "%.0s%cV"
set format x "%.0s%cs"
set xrange [190e-9:260e-9]
set yrange [-5e-3:11e-3]
set grid
set ytics 5e-3
set xlabel "t"
plot data using 1:2 w l ls 2 t "V_{out}"
#+END_SRC

Circuit description:
#+NAME: dim1
#+BEGIN_SRC spice :session test :var dim=dim1_params :results output :eval never
,* DAC.asc
.model mosp pmos level=8 version=3.3.0 
M1 0 VDD N005 N005 mosp l=$dim[5] w=$dim[4]
M2 VOUT VCTRL N005 N005 mosp l=$dim[5] w=$dim[4]
M4 N003 N002 VDD VDD mosp l=$dim[3] w=$dim[2]
M3 N002 N002 VDD VDD mosp l=$dim[3] w=$dim[2]
M5 N005 N004 N003 N003 mosp l=$dim[3] w=$dim[2]
M6 N004 N004 N002 N002 mosp l=$dim[3] w=$dim[2]
RL VOUT 0 $dim[6]
CL VOUT 0 10p
VDD VDD 0 5
IREF N004 0 7.3u
V1 VBIAS 0 2.5
V2 VCTRL 0 PULSE(0 5 0 1n 1n 200n 420n)
VM VDD N001 0
.tran 1n 300n 190n
.end
#+END_SRC

Evaluated spice block:
#+BEGIN_SRC spice :session test :var file="/tmp/dim1" dim=dim1_params :post dim1_plot[:file /tmp/dim1.png](data=*this*) :results file :noweb yes
<<dim1>>
run
wrdata $file v(vout)
#+END_SRC

#+RESULTS:
[[file:/tmp/dim1.png]]

* Current supported special Flags
  - ~:dir~: Working directory to run the src block in. Default is the
    value of ~default-directory~.
* Variable handling

Variables can either be strings or arrays represented by ~$var~ or
~$var[0]~. Variables in the circuit part are replaced with their value
using a regex search. This supports only positive indexes at the
moment. Variables in the control part are handled by setting their
value in the spice session and letting spice figure out their value on
its own. Vector/Array indexing in /ngspice/ starts with index 1 not 0!
To generate file names a ~$file~ variable can be set and file extensions
can be appended using this notation:
#+NAME: ex_filename
#+BEGIN_SRC spice :var file="result/test1" :results output :exports both
echo $file\.txt
echo $file\.png
#+END_SRC
returns
#+RESULTS: ex_filename
: result/test1.txt
: result/test1.png

* Result type handling

  If RESULT-TYPE equals ~output~ return all outputs, if it equals ~value~
  return only value of last statement.\\
  If the last command was any of ~wrdata~, ~write~ or ~gnuplot~ using
  result-type ~value~ returns the corresponding filename.\\
  To output multiple values as a table use either " ," or "\," as
  separator or quote the whole echo string and use ",".
  #+BEGIN_SRC spice :var x=6.13 :exports both
  echo 1 ,$x ,abc
  #+END_SRC

  #+RESULTS:
  | 1 | 6.13 | abc |

  #+BEGIN_SRC spice :var x=6.13 :exports both
  echo 1\,$x\,abc
  #+END_SRC

  #+RESULTS:
  | 1 | 6.13 | abc |

  #+BEGIN_SRC spice :var x=6.13 :exports both
  echo "1,$x,abc"
  #+END_SRC

  #+RESULTS:
  | 1 | 6.13 | abc |