README

   1 oscopy -- An interactive program to view electrical results
   2
   3 This is oscopy, a kind of oscilloscope in python, to view 2D electrical
   4 simulation or measurement results.
   5 It is designed to easily add new input data file formats and new types of plots.
   6
   7 Features highlight:
   8   * Post-processing: math expressions, fft, diffs
   9   * View, examine: multiple windows, cursors
  10   * Data import: gnucap
  11   * Data export: gnucap, pictures
  12   * Scripting
  13
  14 Dependencies:
  15   * Python
  16   * Numpy
  17   * Matplotlib
  18
  19 To run the program, just do ./oscopy.
  20
  21 To get any info on available commands, type 'help'.
  22
  23 EXAMPLE:
  24 -------
  25 cd demo
  26 gnetlist -g spice-sdb -s -o demo.net demo.sch
  27 gnucap -b demo.net
  28 cd ..
  29 ./oscopy -b demo/demo.oscopy
  30
  31 MATH WITH SIGNALS:
  32 ------------------
  33 Support for mathematic with signals is implemented. Supported functions:
  34 trig, sqrt, log...
  35 Support for (i)fft: fft(v1) + fft(v2) is possible, but please avoid
  36 things like ifft(fft(v1) + fft(v2))
  37 First order diff is supported: diff(v1) or diff(v1, 1)
  38 Access to X axis data is provided through Time and Freq, e.g. sin(Time(vsqu)*1e6)
  39
  40 EXTENDING OSCOPY:
  41 -----------------
  42 New data file format can be added by deriving Reader and
  43 redefining the function readsigs(), which fills the list
  44 of signals self.sigs and return a dict of signals.
  45 During execution, Reader.read() check the validity
  46 of the provided path, and then call readsigs().
  47
  48 New graph mode can be added by deriving Graph and redefining
  49 the function set_axes() which if called by plot(), or eventually
  50 redefining plot(). See FFTGraph.py for example.
  51 NOTE : Figure.set_mode() has to be updated when new mode are added !
  52
  53 Vocabular:
  54 A figure is CREATEd or DESTROYed, a graph is ADDed to a figure or DELETEd and a signal is INSERTed or REMOVEd from a graph.
  55
  56 Template for new import format:
  57 ---
  58 import Signal
  59 import Readers
  60
  61 class xxxReader(Readers.Reader.Reader):
  62       def readsigs(self):
  63           #[...] read the signals data from file and for each signal:
  64               #create signal:
  65               # Reference signal, or X axis
  66               sref = Signal("name_ref", self, "unit_ref")
  67               sref.set_pts([with X data from file as a list or numpy.array])
  68               # Signal, or Y axis
  69               s = Signal("name_sig", self, "unit_sig")
  70               s.set_pts([with data from file as a list or numpy.array])
  71               # Assign reference to signal
  72               s.set_ref(sref)
  73           #fill self.slist
  74               self.slist.append(s)
  75               sigs["name_ref"] = s
  76           #and return a dict of sigs where key is signal name
  77           return sigs
  78
  79       def detect(self, fn):
  80           # return True if file fn can be read using this Reader
  81 ---
  82 When a importing a signal, first detect is called.
  83 If format is supported, read() and subsequent update() will call readsigs()
  84
  85 Template for new export format:
  86 ---
  87 import Signal
  88 import Writers
  89
  90 class xxxWriter(Writers.Writer.Writer):
  91       def getfmtname(self):
  92       ... return a string containing the name of the format
  93
  94       def fmtcheck(self, sigs):
  95       ... return True if format can be use to write dict of signals sigs
  96
  97       def writesigs(self, sigs)
  98       ... write signals to file
  99 ---
 100 When an export command is issued, the format name is compared to the
 101 one provided by the class, and then the signals are passed to the class
 102 to check whether it can write them properly, e.g. if they have the same
 103 abscisse. If eveyrthing is fine, writesigs() is called.
 104 Options passed by user can be found in self.opts.
 105
 106 Template for new graphs:
 107 ---
 108 import Graphs
 109 import Signal
 110
 111 class xxxGraph(Graphs.Graph.Graph):
 112       def plot():
 113       ... define the plot function, using signals in self.sigs
 114 ---
 115
 116 A SCHEME:
 117 ---------
 118
 119    READER -- SIGNAL+        + FIGURE +-- GRAPH +-- SIGNAL
 120           \- SIGNAL+        |        |         +-- SIGNAL
 121    READER -- SIGNAL+        |        |
 122                    |        |        +-- GRAPH +-- SIGNAL
 123                    |        |                  +-- SIGNAL
 124                    |        + FIGURE ...
 125                    |        ...
 126                    |        |
 127                    +- CMDS -+
 128