Mercurial > pytave
annotate README @ 33:1d7bab3bc745 task
Documentation
| author | David Grundberg <individ@acc.umu.se> |
|---|---|
| date | Tue, 05 May 2009 20:57:54 +0200 |
| parents | 6d75691c5c07 |
| children | 313932d566c9 |
| rev | line source |
|---|---|
| 33 | 1 -*- coding:utf-8 -*- |
|
0
4da14cce0890
First launchpad.net check in.
David Grundberg <c04dgg@cs.umu.se>
parents:
diff
changeset
|
2 |
| 33 | 3 Pytave README |
| 4 | |
| 5 For installation instructions specific for Pytave, please see the | |
| 6 INSTALL file. | |
|
0
4da14cce0890
First launchpad.net check in.
David Grundberg <c04dgg@cs.umu.se>
parents:
diff
changeset
|
7 |
| 33 | 8 Contents of this document |
| 9 ========================= | |
|
0
4da14cce0890
First launchpad.net check in.
David Grundberg <c04dgg@cs.umu.se>
parents:
diff
changeset
|
10 |
| 33 | 11 1. What is Pytave? |
| 12 2. Gotchas | |
| 13 3. Pytave and multi-threading | |
| 14 4. Python/Octave cheat sheet | |
|
0
4da14cce0890
First launchpad.net check in.
David Grundberg <c04dgg@cs.umu.se>
parents:
diff
changeset
|
15 |
| 33 | 16 What is Pytave? |
| 17 *************** | |
|
0
4da14cce0890
First launchpad.net check in.
David Grundberg <c04dgg@cs.umu.se>
parents:
diff
changeset
|
18 |
| 33 | 19 Pytave enables Python scripts to use existing m-files (Octave/Matlab |
| 20 scripts) for numerical calculations. The Octave language interpreter | |
| 21 is embedded as a module to Python. | |
| 22 | |
| 23 Example use | |
| 24 =========== | |
| 25 | |
| 26 Calling Octave code in the interactive Python interpreter: | |
|
0
4da14cce0890
First launchpad.net check in.
David Grundberg <c04dgg@cs.umu.se>
parents:
diff
changeset
|
27 |
| 33 | 28 >>> import pytave |
| 29 >>> pytave.feval(1, "cos", 0) | |
| 30 (1.0,) | |
| 31 | |
| 32 Goals | |
| 33 ===== | |
|
0
4da14cce0890
First launchpad.net check in.
David Grundberg <c04dgg@cs.umu.se>
parents:
diff
changeset
|
34 |
| 33 | 35 Pytave strives to uphold these points |
|
4
e84a2afb3342
Bootstrapping instructions
David Grundberg <individ@acc.umu.se>
parents:
0
diff
changeset
|
36 |
| 33 | 37 * Good out of the box experience |
|
4
e84a2afb3342
Bootstrapping instructions
David Grundberg <individ@acc.umu.se>
parents:
0
diff
changeset
|
38 |
| 33 | 39 * Good-natured implicit type conversions, no strange PyApple -> |
| 40 octave_orange -> PyBanana chains | |
|
4
e84a2afb3342
Bootstrapping instructions
David Grundberg <individ@acc.umu.se>
parents:
0
diff
changeset
|
41 |
| 33 | 42 Features |
| 43 ======== | |
|
0
4da14cce0890
First launchpad.net check in.
David Grundberg <c04dgg@cs.umu.se>
parents:
diff
changeset
|
44 |
| 33 | 45 A short list of what Pytave is capable of |
|
0
4da14cce0890
First launchpad.net check in.
David Grundberg <c04dgg@cs.umu.se>
parents:
diff
changeset
|
46 |
| 33 | 47 * Implicit type conversions between Python and Octave. Supports all |
| 48 Numeric integer, real double (and possibly real float) matrices | |
|
0
4da14cce0890
First launchpad.net check in.
David Grundberg <c04dgg@cs.umu.se>
parents:
diff
changeset
|
49 |
| 33 | 50 * Architecture independent - no assumption on endian type or integer |
| 51 sizes | |
|
0
4da14cce0890
First launchpad.net check in.
David Grundberg <c04dgg@cs.umu.se>
parents:
diff
changeset
|
52 |
| 33 | 53 * Supports cell <-> list and struct <-> dict conversions. |
|
0
4da14cce0890
First launchpad.net check in.
David Grundberg <c04dgg@cs.umu.se>
parents:
diff
changeset
|
54 |
| 33 | 55 Project homepage |
| 56 ================ | |
|
0
4da14cce0890
First launchpad.net check in.
David Grundberg <c04dgg@cs.umu.se>
parents:
diff
changeset
|
57 |
| 33 | 58 https://launchpad.net/pytave |
| 59 | |
| 60 Using/hacking | |
| 61 ============= | |
|
0
4da14cce0890
First launchpad.net check in.
David Grundberg <c04dgg@cs.umu.se>
parents:
diff
changeset
|
62 |
| 33 | 63 You need the Bazaar version control software (bzr). Branch from trunk |
| 64 with: | |
|
0
4da14cce0890
First launchpad.net check in.
David Grundberg <c04dgg@cs.umu.se>
parents:
diff
changeset
|
65 |
| 33 | 66 $ bzr branch lp:pytave |
|
0
4da14cce0890
First launchpad.net check in.
David Grundberg <c04dgg@cs.umu.se>
parents:
diff
changeset
|
67 |
| 33 | 68 You will now have a directory called `pytave' with source code for |
| 69 the module. Read the INSTALL file for building instructions. | |
|
0
4da14cce0890
First launchpad.net check in.
David Grundberg <c04dgg@cs.umu.se>
parents:
diff
changeset
|
70 |
| 33 | 71 Gotchas |
| 72 ******* | |
|
0
4da14cce0890
First launchpad.net check in.
David Grundberg <c04dgg@cs.umu.se>
parents:
diff
changeset
|
73 |
| 33 | 74 Unfortunately, the implicit conversion is not bijective (there is not |
| 75 a one-to-one relation between Octave and Python values). Pytave users | |
| 76 should be aware of the following cases. | |
|
0
4da14cce0890
First launchpad.net check in.
David Grundberg <c04dgg@cs.umu.se>
parents:
diff
changeset
|
77 |
| 33 | 78 Numeric row vectors to Octave matrices |
| 79 ====================================== | |
|
0
4da14cce0890
First launchpad.net check in.
David Grundberg <c04dgg@cs.umu.se>
parents:
diff
changeset
|
80 |
| 33 | 81 Numeric row vectors are converted to Octave 1xN matrices; returned 1xN |
| 82 matrices will become 1xN numerical arrays, not row vectors. As an | |
| 83 example, a Numeric array with shape == (3,) will become (1, 3) when | |
| 84 converted back and forth. | |
|
0
4da14cce0890
First launchpad.net check in.
David Grundberg <c04dgg@cs.umu.se>
parents:
diff
changeset
|
85 |
| 33 | 86 Octave cells to Python lists |
|
0
4da14cce0890
First launchpad.net check in.
David Grundberg <c04dgg@cs.umu.se>
parents:
diff
changeset
|
87 ============================ |
|
4da14cce0890
First launchpad.net check in.
David Grundberg <c04dgg@cs.umu.se>
parents:
diff
changeset
|
88 |
| 33 | 89 Only row cell arrays can be converted to Python lists. |
| 90 | |
| 91 Python dictionaries to Octave structures | |
| 92 ======================================== | |
| 93 | |
| 94 Dictionaries converted to structures must only have string keys. This | |
| 95 is because Octave structures only allow string keys. Keys must also | |
| 96 be valid Octave identifiers. | |
| 97 | |
| 98 As Octave structures are built using cells, simple variables are | |
| 99 upgraded to cells when a dictionary is converted. A dictionary | |
|
0
4da14cce0890
First launchpad.net check in.
David Grundberg <c04dgg@cs.umu.se>
parents:
diff
changeset
|
100 |
| 33 | 101 {"name": "Pytave"} |
| 102 | |
| 103 thus will become | |
|
0
4da14cce0890
First launchpad.net check in.
David Grundberg <c04dgg@cs.umu.se>
parents:
diff
changeset
|
104 |
| 33 | 105 ans = |
| 106 { | |
| 107 name = Pytave | |
| 108 } | |
| 109 | |
| 110 in Octave. In this listing, Octave is hiding the fact that the value | |
| 111 is wrapped in a cell. Converted back, cells are converted to Python | |
| 112 lists. The re-converted Python dictionary will read | |
|
0
4da14cce0890
First launchpad.net check in.
David Grundberg <c04dgg@cs.umu.se>
parents:
diff
changeset
|
113 |
| 33 | 114 {"name": ["Pytave"]} |
| 115 | |
| 116 which is natural effect because of the way Octave handles structures. | |
| 117 | |
| 118 The list values in dictionaries to be converted must be of equal | |
| 119 length. All restrictions demanded by the Octave `struct' built-in | |
| 120 applies. | |
| 121 | |
| 122 Pytave and multi-threading | |
| 123 ************************** | |
|
0
4da14cce0890
First launchpad.net check in.
David Grundberg <c04dgg@cs.umu.se>
parents:
diff
changeset
|
124 |
| 33 | 125 Pytave does not handle reentrant calls. It is not thread-safe, and |
| 126 you cannot make several Pytave calls in parallel. There are no safety | |
| 127 harnesses in Pytave (unlike e.g. PySqlite), and Pytave will not stop | |
| 128 you if you try to make concurrent calls. The behavior is undefined. | |
| 129 It is not possible to run several calculations in parallel. | |
|
0
4da14cce0890
First launchpad.net check in.
David Grundberg <c04dgg@cs.umu.se>
parents:
diff
changeset
|
130 |
| 33 | 131 That being said, it is possible to do other things while one Pytave |
| 132 call is running. Pytave is aware of the Global Interpreter Lock. The | |
| 133 lock will be released while the Octave interpreter is running, | |
| 134 allowing you to have other Python threads to run in parallel with the | |
| 135 one Octave call. | |
|
0
4da14cce0890
First launchpad.net check in.
David Grundberg <c04dgg@cs.umu.se>
parents:
diff
changeset
|
136 |
| 33 | 137 Python/Octave cheat sheet |
| 138 ************************* | |
|
0
4da14cce0890
First launchpad.net check in.
David Grundberg <c04dgg@cs.umu.se>
parents:
diff
changeset
|
139 |
| 33 | 140 Octave and Python share some syntax elements, which unfortunately |
| 141 makes it harder to distinguish between the languages. Here are some | |
| 142 examples in both languages, showing how to build related constructs. | |
| 143 | |
| 144 Create a 2x3 matrix | |
| 145 =================== | |
| 146 | |
| 147 octave:1> [1, 1, 1; 2, 2, 2] | |
| 148 python>>> array([[1, 1, 1], [2, 2, 2]]) | |
| 149 | |
| 150 Create a 3x2 matrix | |
| 151 =================== | |
|
0
4da14cce0890
First launchpad.net check in.
David Grundberg <c04dgg@cs.umu.se>
parents:
diff
changeset
|
152 |
| 33 | 153 octave:1> [1, 1; 2, 2; 3, 3] |
| 154 python>>> array([[1, 1], [2, 2], [3, 3]]) | |
| 155 | |
| 156 Create a 1x3 matrix | |
| 157 =================== | |
|
0
4da14cce0890
First launchpad.net check in.
David Grundberg <c04dgg@cs.umu.se>
parents:
diff
changeset
|
158 |
| 33 | 159 octave:1> [1, 1, 1] |
| 160 python>>> array([[1, 1, 1]]) | |
|
0
4da14cce0890
First launchpad.net check in.
David Grundberg <c04dgg@cs.umu.se>
parents:
diff
changeset
|
161 |
| 33 | 162 Create a row vector |
| 163 =================== | |
| 164 | |
| 165 Not applicable to Octave. | |
| 166 python>>> array([1, 1, 1]) | |
|
0
4da14cce0890
First launchpad.net check in.
David Grundberg <c04dgg@cs.umu.se>
parents:
diff
changeset
|
167 |
| 33 | 168 Note: Python row vectors will be converted to Octave 1xN matrices. |
|
0
4da14cce0890
First launchpad.net check in.
David Grundberg <c04dgg@cs.umu.se>
parents:
diff
changeset
|
169 |
| 33 | 170 Create a 3x1 matrix |
| 171 =================== | |
|
0
4da14cce0890
First launchpad.net check in.
David Grundberg <c04dgg@cs.umu.se>
parents:
diff
changeset
|
172 |
| 33 | 173 octave:1> [1; 2; 3] |
| 174 python>>> array([[1], [2], [3]]) | |
|
0
4da14cce0890
First launchpad.net check in.
David Grundberg <c04dgg@cs.umu.se>
parents:
diff
changeset
|
175 |
| 33 | 176 Create a 1x1 structure/dictionary |
| 177 ================================= | |
| 178 | |
| 179 octave:1> struct("x", 1, "y", 2) | |
| 180 python>>> {"x": 1, "y": 2} | |
|
0
4da14cce0890
First launchpad.net check in.
David Grundberg <c04dgg@cs.umu.se>
parents:
diff
changeset
|
181 |
| 33 | 182 Create a 1x2 structure array/dictionary containing lists of length 2 |
| 183 ==================================================================== | |
| 184 | |
| 185 octave:1> struct("firstname", {"David", "Håkan"}, ... | |
| 186 "lastname", {"Grundberg", "Fors Nilsson"}) | |
| 187 python>>> {"firstname": ["David", "Håkan"], \ | |
| 188 "lastname": ["Grundberg", "Fors Nilsson"]} | |
|
0
4da14cce0890
First launchpad.net check in.
David Grundberg <c04dgg@cs.umu.se>
parents:
diff
changeset
|
189 |
| 33 | 190 Create a 1x3 cell array/list |
| 191 ============================ | |
| 192 | |
| 193 octave:1> {"foo", "bar", "baz"} | |
| 194 python>>> ["foo", "bar", "baz"] | |
| 195 | |
| 196 EOF. |