Mercurial > pytave

comparison README.md @ 425:14b134ffdc24

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Update project docs, delete obsolete docs from legacy project (fixes issue #72) * README.md: Rewrite to describe the current project state. * CONTRIBUTORS.md: New file listing project contributors. * Makefile.am (DOC_FILES): Include CONTRIBUTORS.md, remove INSTALL.md. * AUTHORS, ChangeLog, INSTALL.md, NEWS: Delete.
author Mike Miller <mtmiller@octave.org>
date Fri, 05 May 2017 15:55:41 -0700
parents 809f2c7f76c7
children c8543d9a4bff
comparison
equal deleted inserted replaced
424:9b34c17cb0fb 425:14b134ffdc24
1 Pytave README 1 Octave Python Interface
2 ============= 2 =======================
3 3
4 For installation instructions specific for Pytave, please see the 4 This project is for development of a native Python calling interface for
5 [INSTALL.md](INSTALL.md) file. 5 [GNU Octave](http://www.octave.org).
6
7 Contents of this document
8 -------------------------
9
10 1. What is Pytave?
11 2. Gotchas
12 3. Pytave and multi-threading
13 4. Python/Octave cheat sheet
14
15 What is Pytave?
16 ===============
17
18 Pytave enables Python scripts to use existing m-files (Octave/Matlab
19 scripts) for numerical calculations. The Octave language interpreter is
20 embedded as a module to Python.
21
22 Example use
23 -----------
24
25 Calling Octave code in the interactive Python interpreter:
26
27 >>> import pytave
28 >>> pytave.feval(1, "cos", 0)
29 (1.0,)
30 6
31 Goals 7 Goals
32 ----- 8 -----
33 9
34 Pytave strives to uphold these points 10 The goals of this extension include
35 11
36 * Good out of the box experience 12 * call any loadable Python modules, classes, and functions
37 * Good-natured implicit type conversions, no strange PyApple -> 13 * automatic translation of certain Octave data types into Python
38 octave_orange -> PyBanana chains 14 arguments
15 * hold reference to and performing operations on any Python data type as
16 Octave variables
17 * automatic translation of certain Python data types into Octave return
18 values
19 * be as compatible as possible with Matlab's own Python calling
20 interface
39 21
40 Features 22 Examples
41 -------- 23 --------
42 24
43 A short list of what Pytave is capable of 25 A few examples are listed here to give a brief introduction to how the
26 Python runtime is translated to Octave.
44 27
45 * Implicit type conversions between Python and Octave. Supports all 28 Add a directory to the Python module search path
46 NumPy integer and floating point matrices
47 * Architecture independent - no assumption on endian type or integer
48 sizes
49 * Supports cell <-> list and struct <-> dict conversions.
50 29
51 Project homepage 30 py.sys.path.insert (int32 (0), "/path/to/module");
52 ----------------
53 31
54 [https://bitbucket.org/mtmiller/pytave](https://bitbucket.org/mtmiller/pytave) 32 Use a vectorized NumPy function
55 33
56 Using/hacking 34 x = py.numpy.sqrt (1:10);
57 -------------
58 35
59 You need the Mercurial version control software (hg). Clone the repo 36 Call a function with keyword arguments
60 with:
61 37
62 $ hg clone https://bitbucket.org/mtmiller/pytave 38 a = py.int ("5ba0", pyargs ("base", int32 (16)));
63 39
64 You will now have a directory called `pytave` with source code for the 40 Read an entire text file into a string
65 module. Read the [INSTALL.md](INSTALL.md) file for building instructions.
66 41
67 Gotchas 42 s = py.str ().join (py.open ("/etc/passwd").readlines ());
68 =======
69 43
70 Unfortunately, the implicit conversion is not bijective (there is not a 44 Installation
71 one-to-one relation between Octave and Python values). Pytave users 45 ------------
72 should be aware of the following cases.
73 46
74 Numeric row vectors to Octave matrices 47 There is currently no support for installing this project as an Octave
75 -------------------------------------- 48 package or in a system or user directory for regular use. This is
49 intentional, since the project is still being developed and is not
50 stable enough for actual use yet.
76 51
77 Numeric row vectors are converted to Octave 1xN matrices; returned 1xN 52 What is supported is building and running the project from the build
78 matrices will become 1xN numerical arrays, not row vectors. As an 53 directory. Building requires Octave and Python development libraries and
79 example, a NumPy array with shape == (3,) will become (1, 3) when 54 GNU autotools.
80 converted back and forth.
81 55
82 Octave cells to Python lists 56 1. `hg clone https://bitbucket.org/mtmiller/pytave`
83 ---------------------------- 57 2. `cd pytave`
58 3. `autoreconf -i`
59 4. `./configure`
60 5. `make`
61 6. Run Octave with the build directory added to the load path
84 62
85 Only row cell arrays can be converted to Python lists. 63 Development
64 -----------
86 65
87 Python dictionaries to Octave structures 66 We welcome all contributors, bug reports, test results, and ideas for
88 ---------------------------------------- 67 improvement. Contributions in any of the following forms, in no
68 particular order, are needed and appreciated.
89 69
90 Dictionaries converted to structures must only have string keys. This is 70 * Testing on different operating systems and in different environments
91 because Octave structures only allow string keys. Keys must also be 71 * Testing for full functionality with a variety of Python libraries
92 valid Octave identifiers. 72 * Bug reports detailing problems encountered or unexpected behavior
73 * Code contributions
74 * Documentation in the form of examples, improvements to help texts, or
75 some sort of user manual
93 76
94 As Octave structures are built using cells, simple variables are 77 Other Resources
95 upgraded to cells when a dictionary is converted. A dictionary 78 ---------------
96 79
97 {"name": "Pytave"} 80 Please discuss or ask questions about this project on the Octave
81 [maintainers mailing list](https://lists.gnu.org/mailman/listinfo/octave-maintainers).
98 82
99 thus will become 83 The [wiki page](http://wiki.octave.org/Python_interface) contains more
100 84 examples and ideas about the project.
101 ans =
102 {
103 name = Pytave
104 }
105
106 in Octave. In this listing, Octave is hiding the fact that the value is
107 wrapped in a cell. Converted back, cells are converted to Python lists.
108 The re-converted Python dictionary will read
109
110 {"name": ["Pytave"]}
111
112 which is natural effect because of the way Octave handles structures.
113
114 The list values in dictionaries to be converted must be of equal length.
115 All restrictions demanded by the Octave `struct` built-in applies.
116
117 Pytave and multi-threading
118 ==========================
119
120 Pytave does not handle reentrant calls. It is not thread-safe, and you
121 cannot make several Pytave calls in parallel. There are no safety
122 harnesses in Pytave (unlike e.g. PySqlite), and Pytave will not stop you
123 if you try to make concurrent calls. The behavior is undefined. It is
124 not possible to run several calculations in parallel.
125
126 That being said, it is possible to do other things while one Pytave call
127 is running. Pytave is aware of the Global Interpreter Lock. The lock
128 will be released while the Octave interpreter is running, allowing you
129 to have other Python threads to run in parallel with the one Octave
130 call.
131
132 Python/Octave cheat sheet
133 =========================
134
135 Octave and Python share some syntax elements, which unfortunately makes
136 it harder to distinguish between the languages. Here are some examples
137 in both languages, showing how to build related constructs.
138
139 Create a 2x3 matrix
140 -------------------
141
142 octave:1> [1, 1, 1; 2, 2, 2]
143 python>>> array([[1, 1, 1], [2, 2, 2]])
144
145 Create a 3x2 matrix
146 -------------------
147
148 octave:1> [1, 1; 2, 2; 3, 3]
149 python>>> array([[1, 1], [2, 2], [3, 3]])
150
151 Create a 1x3 matrix
152 -------------------
153
154 octave:1> [1, 1, 1]
155 python>>> array([[1, 1, 1]])
156
157 Create a row vector
158 -------------------
159
160 Not applicable to Octave.
161
162 python>>> array([1, 1, 1])
163
164 Note: Python row vectors will be converted to Octave 1xN matrices.
165
166 Create a 3x1 matrix
167 -------------------
168
169 octave:1> [1; 2; 3]
170 python>>> array([[1], [2], [3]])
171
172 Create a 1x1 structure/dictionary
173 ---------------------------------
174
175 octave:1> struct("x", 1, "y", 2)
176 python>>> {"x": 1, "y": 2}
177
178 Create a 1x2 structure array/dictionary containing lists of length 2
179 --------------------------------------------------------------------
180
181 octave:1> struct("firstname", {"David", "Håkan"}, ...
182 "lastname", {"Grundberg", "Fors Nilsson"})
183 python>>> {"firstname": ["David", "Håkan"], \
184 "lastname": ["Grundberg", "Fors Nilsson"]}
185
186 Create a 1x3 cell array/list
187 ----------------------------
188
189 octave:1> {"foo", "bar", "baz"}
190 python>>> ["foo", "bar", "baz"]