Mercurial > pytave
changeset 159:a323f9fae46b
doc: Reformat INSTALL and README in Markdown
* INSTALL.md, README.md: Rename and reformat using Markdown syntax.
* Makefile.am (EXTRA_DIST): Include INSTALL.md and README.md in the list.
* configure.ac: Call automake with --foreign.
| author | Mike Miller <mtmiller@octave.org> |
|---|---|
| date | Tue, 05 Apr 2016 21:00:58 -0700 |
| parents | 572fc724e117 |
| children | eab5c6026303 |
| files | INSTALL INSTALL.md Makefile.am README README.md configure.ac |
| diffstat | 6 files changed, 293 insertions(+), 289 deletions(-) [+] |
line wrap: on
line diff
--- a/INSTALL Tue Apr 05 17:38:29 2016 -0700 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,91 +0,0 @@ -Building instructions -===================== - -Pytave is built using GNU autotools. - -Use the configure script to detect Octave and Boost::Python paths. - -Run `./configure --help' for more info. - -Dependencies -============ - -Configuring: - a shell capable of running `configure' - -Building: - GNU make - -Linked and tested with: - Python 2.7 - Boost::Python 1.58 - Octave 4.1 (development version) - -Bootstrapping from Mercurial -============================ - - 1. `hg clone https://bitbucket.org/mtmiller/pytave' - - 2. `autoreconf --install' - -Building -======== - - 1. `./configure' - or - `./configure --prefix=/directory/where/you/want/the/module/file' - - 2. Type `make' to build the extension module. - - 3. To copy the pytave dynamic library to the prefix, type - `make install' - -Running from build directory -============================ - -Pytave is made up of three parts. The `pytave' package, the -`pytave/pytave' module and the `pytave/_pytave' extension. When the -user uses `import pytave', the pytave package __init__ script loads -both the module and the extension. It is important that they both can -be found. - - 1. Follow the build instructions to compile the extension. - - 2. Start the Python interpreter with a Python path set to a path - containing `_pytave.so' and the `package' directory. A common way - to do this with the bash shell is to execute this command: - `PYTHONPATH=.libs:package python'. - - 3. In the interpreter you can now access Octave through Python: - - import numpy - import pytave - pytave.feval(1, "cos", 0) - b = pytave.addpath(".") - pytave.feval(1, "testfile", 42) - -(Observe that there is no testfile.m file in the distribution. You -could create one for yourself.) - -Running test suite in build directory -===================================== - - 1. Run `make check' - -There are known errors in the test suite. - -Creating a source dist -====================== - - 1. Run `make distcheck' - -Hint about foreign systems -========================== - -If you are running on a system incapable of executing the configure -scripts (e.g. a Microsoft Windows system), you may want to try -installing the `MinGW' and `MSYS' packages, and build everything -inside that environment. This isn't for the faint of hearted though, -since you need/want to build Octave too. It is probably easier than -trying to build without configure scripts, that's all. There are no -guarantees that it will build at all, it has not been tested.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/INSTALL.md Tue Apr 05 21:00:58 2016 -0700 @@ -0,0 +1,97 @@ +Pytave Building Instructions +============================ + +Pytave is built using GNU autotools. + +Use the configure script to detect Octave and Boost::Python paths. + +Run `./configure --help` for more info. + +Dependencies +------------ + +Configuring: + + * a shell capable of running `configure` + +Building: + + * GNU make + +Linked and tested with: + + * Python 2.7 + * Boost::Python 1.58 + * Octave 4.1 (development version) + +Bootstrapping from Mercurial +---------------------------- + + 1. `hg clone https://bitbucket.org/mtmiller/pytave` + + 2. `autoreconf --install` + +Building +-------- + + 1. `./configure` + + or + + `./configure --prefix=/directory/where/you/want/the/module/file` + + 2. Run `make` to build the extension module + + 3. To copy the pytave dynamic library to the prefix, run + `make install` + +Running from build directory +---------------------------- + +Pytave is made up of three parts. The `pytave` package, the +`pytave/pytave` module and the `pytave/_pytave` extension. When the user +uses `import pytave`, the pytave package `__init__` script loads both +the module and the extension. It is important that they both can be +found. + + 1. Follow the build instructions to compile the extension. + + 2. Start the Python interpreter with a Python path set to a path + containing `_pytave.so` and the `package` directory. A common way + to do this with the bash shell is to execute this command: + + PYTHONPATH=.libs:package python + + 3. In the interpreter you can now access Octave through Python: + + import numpy + import pytave + pytave.feval(1, "cos", 0) + b = pytave.addpath(".") + pytave.feval(1, "testfile", 42) + +Note that there is no `testfile.m` file in the distribution. This is +simply a demonstration of how to execute an arbitrary Octave m-file. + +Running test suite in build directory +------------------------------------- + + 1. Run `make check` + +There are known errors in the test suite. + +Creating a source dist +---------------------- + + 1. Run `make distcheck` + +Hint about foreign systems +-------------------------- + +If you are running on a system incapable of executing the configure +scripts (e.g. a Microsoft Windows system), you may want to try +installing the MinGW and MSYS packages, and build everything inside that +environment. This isn't for the faint of heart though, since you +need/want to build Octave too. It is probably easier than trying to +build without configure scripts, that's all. There are no guarantees +that it will build at all, it has not been tested.
--- a/Makefile.am Tue Apr 05 17:38:29 2016 -0700 +++ b/Makefile.am Tue Apr 05 21:00:58 2016 -0700 @@ -29,6 +29,10 @@ octave_to_python.cc \ python_to_octave.cc +DOC_FILES = \ + INSTALL.md \ + README.md + OCT_FILES = \ py.oct @@ -45,7 +49,7 @@ test/exceptions.py \ test/test.py -EXTRA_DIST = $(PY_FILES) +EXTRA_DIST = $(DOC_FILES) $(PY_FILES) EXTRA_libdir = $(PYTAVE_MODULE_INSTALL_PATH) EXTRA_lib_LTLIBRARIES = _pytave.la
--- a/README Tue Apr 05 17:38:29 2016 -0700 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,196 +0,0 @@ --*- coding:utf-8 -*- - -Pytave README - -For installation instructions specific for Pytave, please see the -INSTALL file. - -Contents of this document -========================= - -1. What is Pytave? -2. Gotchas -3. Pytave and multi-threading -4. Python/Octave cheat sheet - -What is Pytave? -*************** - -Pytave enables Python scripts to use existing m-files (Octave/Matlab -scripts) for numerical calculations. The Octave language interpreter -is embedded as a module to Python. - -Example use -=========== - -Calling Octave code in the interactive Python interpreter: - ->>> import pytave ->>> pytave.feval(1, "cos", 0) -(1.0,) - -Goals -===== - -Pytave strives to uphold these points - - * Good out of the box experience - - * Good-natured implicit type conversions, no strange PyApple -> - octave_orange -> PyBanana chains - -Features -======== - -A short list of what Pytave is capable of - - * Implicit type conversions between Python and Octave. Supports all - Numeric integer, real double (and possibly real float) matrices - - * Architecture independent - no assumption on endian type or integer - sizes - - * Supports cell <-> list and struct <-> dict conversions. - -Project homepage -================ - -https://bitbucket.org/mtmiller/pytave - -Using/hacking -============= - -You need the Mercurial version control software (hg). Clone the repo -with: - - $ hg clone https://bitbucket.org/mtmiller/pytave - - You will now have a directory called `pytave' with source code for -the module. Read the INSTALL file for building instructions. - -Gotchas -******* - -Unfortunately, the implicit conversion is not bijective (there is not -a one-to-one relation between Octave and Python values). Pytave users -should be aware of the following cases. - -Numeric row vectors to Octave matrices -====================================== - -Numeric row vectors are converted to Octave 1xN matrices; returned 1xN -matrices will become 1xN numerical arrays, not row vectors. As an -example, a Numeric array with shape == (3,) will become (1, 3) when -converted back and forth. - -Octave cells to Python lists -============================ - -Only row cell arrays can be converted to Python lists. - -Python dictionaries to Octave structures -======================================== - -Dictionaries converted to structures must only have string keys. This -is because Octave structures only allow string keys. Keys must also -be valid Octave identifiers. - - As Octave structures are built using cells, simple variables are -upgraded to cells when a dictionary is converted. A dictionary - -{"name": "Pytave"} - -thus will become - -ans = -{ - name = Pytave -} - -in Octave. In this listing, Octave is hiding the fact that the value -is wrapped in a cell. Converted back, cells are converted to Python -lists. The re-converted Python dictionary will read - -{"name": ["Pytave"]} - -which is natural effect because of the way Octave handles structures. - - The list values in dictionaries to be converted must be of equal -length. All restrictions demanded by the Octave `struct' built-in -applies. - -Pytave and multi-threading -************************** - -Pytave does not handle reentrant calls. It is not thread-safe, and -you cannot make several Pytave calls in parallel. There are no safety -harnesses in Pytave (unlike e.g. PySqlite), and Pytave will not stop -you if you try to make concurrent calls. The behavior is undefined. -It is not possible to run several calculations in parallel. - - That being said, it is possible to do other things while one Pytave -call is running. Pytave is aware of the Global Interpreter Lock. The -lock will be released while the Octave interpreter is running, -allowing you to have other Python threads to run in parallel with the -one Octave call. - -Python/Octave cheat sheet -************************* - -Octave and Python share some syntax elements, which unfortunately -makes it harder to distinguish between the languages. Here are some -examples in both languages, showing how to build related constructs. - -Create a 2x3 matrix -=================== - -octave:1> [1, 1, 1; 2, 2, 2] -python>>> array([[1, 1, 1], [2, 2, 2]]) - -Create a 3x2 matrix -=================== - -octave:1> [1, 1; 2, 2; 3, 3] -python>>> array([[1, 1], [2, 2], [3, 3]]) - -Create a 1x3 matrix -=================== - -octave:1> [1, 1, 1] -python>>> array([[1, 1, 1]]) - -Create a row vector -=================== - -Not applicable to Octave. -python>>> array([1, 1, 1]) - -Note: Python row vectors will be converted to Octave 1xN matrices. - -Create a 3x1 matrix -=================== - -octave:1> [1; 2; 3] -python>>> array([[1], [2], [3]]) - -Create a 1x1 structure/dictionary -================================= - -octave:1> struct("x", 1, "y", 2) -python>>> {"x": 1, "y": 2} - -Create a 1x2 structure array/dictionary containing lists of length 2 -==================================================================== - -octave:1> struct("firstname", {"David", "Håkan"}, ... - "lastname", {"Grundberg", "Fors Nilsson"}) -python>>> {"firstname": ["David", "Håkan"], \ - "lastname": ["Grundberg", "Fors Nilsson"]} - -Create a 1x3 cell array/list -============================ - -octave:1> {"foo", "bar", "baz"} -python>>> ["foo", "bar", "baz"] - -EOF.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/README.md Tue Apr 05 21:00:58 2016 -0700 @@ -0,0 +1,190 @@ +Pytave README +============= + +For installation instructions specific for Pytave, please see the +[INSTALL.md]() file. + +Contents of this document +------------------------- + + 1. What is Pytave? + 2. Gotchas + 3. Pytave and multi-threading + 4. Python/Octave cheat sheet + +What is Pytave? +=============== + +Pytave enables Python scripts to use existing m-files (Octave/Matlab +scripts) for numerical calculations. The Octave language interpreter is +embedded as a module to Python. + +Example use +----------- + +Calling Octave code in the interactive Python interpreter: + + >>> import pytave + >>> pytave.feval(1, "cos", 0) + (1.0,) + +Goals +----- + +Pytave strives to uphold these points + + * Good out of the box experience + * Good-natured implicit type conversions, no strange PyApple -> + octave_orange -> PyBanana chains + +Features +-------- + +A short list of what Pytave is capable of + + * Implicit type conversions between Python and Octave. Supports all + NumPy integer and floating point matrices + * Architecture independent - no assumption on endian type or integer + sizes + * Supports cell <-> list and struct <-> dict conversions. + +Project homepage +---------------- + +[https://bitbucket.org/mtmiller/pytave]() + +Using/hacking +------------- + +You need the Mercurial version control software (hg). Clone the repo +with: + + $ hg clone https://bitbucket.org/mtmiller/pytave + +You will now have a directory called `pytave` with source code for the +module. Read the [INSTALL.md]() file for building instructions. + +Gotchas +======= + +Unfortunately, the implicit conversion is not bijective (there is not a +one-to-one relation between Octave and Python values). Pytave users +should be aware of the following cases. + +Numeric row vectors to Octave matrices +-------------------------------------- + +Numeric row vectors are converted to Octave 1xN matrices; returned 1xN +matrices will become 1xN numerical arrays, not row vectors. As an +example, a NumPy array with shape == (3,) will become (1, 3) when +converted back and forth. + +Octave cells to Python lists +---------------------------- + +Only row cell arrays can be converted to Python lists. + +Python dictionaries to Octave structures +---------------------------------------- + +Dictionaries converted to structures must only have string keys. This is +because Octave structures only allow string keys. Keys must also be +valid Octave identifiers. + +As Octave structures are built using cells, simple variables are +upgraded to cells when a dictionary is converted. A dictionary + + {"name": "Pytave"} + +thus will become + + ans = + { + name = Pytave + } + +in Octave. In this listing, Octave is hiding the fact that the value is +wrapped in a cell. Converted back, cells are converted to Python lists. +The re-converted Python dictionary will read + + {"name": ["Pytave"]} + +which is natural effect because of the way Octave handles structures. + +The list values in dictionaries to be converted must be of equal length. +All restrictions demanded by the Octave `struct` built-in applies. + +Pytave and multi-threading +========================== + +Pytave does not handle reentrant calls. It is not thread-safe, and you +cannot make several Pytave calls in parallel. There are no safety +harnesses in Pytave (unlike e.g. PySqlite), and Pytave will not stop you +if you try to make concurrent calls. The behavior is undefined. It is +not possible to run several calculations in parallel. + +That being said, it is possible to do other things while one Pytave call +is running. Pytave is aware of the Global Interpreter Lock. The lock +will be released while the Octave interpreter is running, allowing you +to have other Python threads to run in parallel with the one Octave +call. + +Python/Octave cheat sheet +========================= + +Octave and Python share some syntax elements, which unfortunately makes +it harder to distinguish between the languages. Here are some examples +in both languages, showing how to build related constructs. + +Create a 2x3 matrix +------------------- + + octave:1> [1, 1, 1; 2, 2, 2] + python>>> array([[1, 1, 1], [2, 2, 2]]) + +Create a 3x2 matrix +------------------- + + octave:1> [1, 1; 2, 2; 3, 3] + python>>> array([[1, 1], [2, 2], [3, 3]]) + +Create a 1x3 matrix +------------------- + + octave:1> [1, 1, 1] + python>>> array([[1, 1, 1]]) + +Create a row vector +------------------- + +Not applicable to Octave. + + python>>> array([1, 1, 1]) + +Note: Python row vectors will be converted to Octave 1xN matrices. + +Create a 3x1 matrix +------------------- + + octave:1> [1; 2; 3] + python>>> array([[1], [2], [3]]) + +Create a 1x1 structure/dictionary +--------------------------------- + + octave:1> struct("x", 1, "y", 2) + python>>> {"x": 1, "y": 2} + +Create a 1x2 structure array/dictionary containing lists of length 2 +-------------------------------------------------------------------- + + octave:1> struct("firstname", {"David", "Håkan"}, ... + "lastname", {"Grundberg", "Fors Nilsson"}) + python>>> {"firstname": ["David", "Håkan"], \ + "lastname": ["Grundberg", "Fors Nilsson"]} + +Create a 1x3 cell array/list +---------------------------- + + octave:1> {"foo", "bar", "baz"} + python>>> ["foo", "bar", "baz"]