oct2py - GitLite

KO | EN

gitlite — search

#typescript #llm #golang #go #android #rust #deep-learning #linux #docker #nodejs #windows #awesome-list #pytorch #mcp

oct2py

(★ 271)

Run M Files from Python - GNU Octave to Python bridge

File Explorer

Download Latest Version (.zip)

- - bug_report.yml
  - feature_request.yml
- - codeql.yml
  - enforce-label.yml
  - lock-update.yml
  - pre-commit-autoupdate.yml
  - release.yml
  - tests.yml
  - zizmor.yml
- dependabot.yml
- pull_request_template.md
- zizmor.yml
- __init__.py
- benchmarks.py
- apt.txt
- environment.yml
- postBuild
- start
- - plot.png
  - surf.png
- api.md
- conversions.md
- demo.md
- examples.md
- index.md
- info.md
- installation.md
- notebook.ipynb
- pyinstaller.md
- settings.md
- octavemagic_extension.ipynb
- roundtrip.m
- roundtrip.py
- test_datatypes.m
- test_datatypes.py
- test_nodocstring.m
- mlabwrap.txt
- octavemagic.txt
- ompc.txt
- - __init__.py
  - ipython-COPYING.txt
  - octavemagic.py
- __init__.py
- _pyeval.m
- _version.py
- check.py
- core.py
- demo.py
- dynamic.py
- io.py
- settings.py
- speed_check.py
- thread_check.py
- utils.py
- app.py
- oct2py_app.spec
- test_build.py
- test-opencv.py
- - display.m
  - get.m
  - polynomial.m
  - set.m
- - __init__.py
  - test_octavemagic.py
- __init__.py
- conftest.py
- NoDefaultCtorClass.m
- pyeval_like_error0.m
- pyeval_like_error1.m
- pyeval_like_error2.m
- pyeval_like_error3.m
- roundtrip.m
- script_error.m
- SimpleObj.m
- test_conversions.py
- test_core_branches.py
- test_datatypes.m
- test_dynamic_branches.py
- test_keep_matlab_shapes.py
- test_misc.py
- test_nodocstring.m
- test_numpy.py
- test_octave_script.m
- test_octave_script_argv.m
- test_octavemagic.py
- test_recurse.m
- test_roundtrip.py
- test_settings.py
- test_usage.py
.coveragerc
.git-blame-ignore-revs
.gitattributes
.gitignore
.markdown_link_config.json
.pre-commit-config.yaml
.python-version
.readthedocs.yaml
asv.conf.json
CHANGELOG.md
CITATION.cff
codecov.yml
CONTRIBUTING.md
CONTRIBUTORS.md
justfile
LICENSE.txt
mkdocs.yml
poetry.lock
pyproject.toml
README.md
RELEASE.md

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Oct2Py: Python to GNU Octave Bridge

[![PyPI version](https://badge.fury.io/py/oct2py.png/)](https://badge.fury.io/py/oct2py)
[![codecov](https://codecov.io/github/blink1073/oct2py/coverage.svg?branch=main)](https://codecov.io/github/blink1073/oct2py?branch=main)
[![PyPi Download stats](https://pepy.tech/badge/oct2py)](https://pepy.tech/project/oct2py)
[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/blink1073/oct2py/main?filepath=example/octavemagic_extension.ipynb)

Oct2Py allows you to seamlessly call M-files and Octave functions from Python.
It manages the Octave session for you, sharing data behind the scenes using
MAT files. Usage is as simple as:

```python
>>> import oct2py
>>> oc = oct2py.Oct2Py()
>>> x = oc.zeros(3, 3)
>>> print(x, x.dtype)
[[0. 0. 0.]
 [0. 0. 0.]
 [0. 0. 0.]] float64
```

To run .m function, you need to explicitly add the path to .m file using:

```python
>>> from oct2py import octave
>>> # to add a folder use:
>>> octave.addpath("/path/to/directory")  # doctest: +SKIP
>>> # to add folder with all subfolder in it use:
>>> octave.addpath(octave.genpath("/path/to/directory"))  # doctest: +SKIP
>>> # to run the .m file :
>>> octave.run("fileName.m")  # doctest: +SKIP
```

To get the output of .m file after setting the path, use:

```python
>>> import numpy as np
>>> from oct2py import octave
>>> x = np.array([[1, 2], [3, 4]], dtype=float)
>>> # use nout='max_nout' to automatically choose max possible nout
>>> octave.addpath("./example")  # doctest: +SKIP
>>> out, oclass = octave.roundtrip(x, nout=2)  # doctest: +SKIP
>>> import pprint  # doctest: +SKIP
>>> pprint.pprint([x, x.dtype, out, oclass, out.dtype])  # doctest: +SKIP
[array([[1., 2.],
        [3., 4.]]),
    dtype('float64'),
    array([[1., 2.],
        [3., 4.]]),
    'double',
    dtype('<f8')]
```

If you want to run legacy m-files, do not have MATLAB®, and do not fully
trust a code translator, this is your library.

## Features

- Supports all Octave datatypes and most Python datatypes and Numpy dtypes.
- Provides [OctaveMagic](https://nbviewer.org/github/blink1073/oct2py/blob/main/example/octavemagic_extension.ipynb?create=1) for IPython, including inline plotting in notebooks.
- Supports cell arrays and structs/struct arrays with arbitrary nesting.
- Supports sparse matrices.
- Builds methods on the fly linked to Octave commands (e.g. `zeros` above).
- Thread-safety: each Oct2Py object uses an independent Octave session.
- Can be used as a context manager.
- Supports Unicode characters.
- Supports logging of session commands.
- Optional timeout command parameter to prevent runaway Octave sessions.

## Supported Python and dependency versions

This project follows [SPEC 0](https://scientific-python.org/specs/spec-0000/) for minimum supported Python and dependency versions.

## Installation

You must have GNU Octave installed and in your `PATH` environment variable.
Alternatively, you can set an `OCTAVE_EXECUTABLE` or `OCTAVE` environment
variable that points to `octave` executable itself.

You must have the Numpy and Scipy libraries for Python installed.
See the [installation instructions](https://blink1073.github.io/oct2py/source/installation.html) for more details.

Once the dependencies have been installed, run:

```bash
$ pip install oct2py
```

If using conda, it is available on conda-forge:

```bash
$ conda install -c conda-forge oct2py
```

## Documentation

Documentation is available [online](https://oct2py.readthedocs.io/en/latest/).

For version information, see the [Changelog](https://github.com/blink1073/oct2py/blob/main/CHANGELOG.md).

## JupyterHub with Qt Support

To enable Octave's Qt graphics toolkit in a JupyterHub environment (or any headless server), you need a virtual display. Install the required system packages:

```shell
apt-get install -y octave libglu1 xvfb texinfo fonts-freefont-otf ghostscript
```

Start `Xvfb` before launching JupyterHub (or in a server startup script):

```shell
Xvfb :99 -screen 0 1024x768x24 &
export DISPLAY=:99
```

Then configure oct2py to use the Qt backend in your notebook or script:

```python
from oct2py import octave
octave.eval("graphics_toolkit qt")
```

Alternatively, set `OCTAVE_EXECUTABLE` to run Octave under `xvfb-run`:

```shell
export OCTAVE_EXECUTABLE="xvfb-run octave"
```

For Binder-based deployments, the `binder/` directory in this repository contains an `apt.txt` listing required packages and a `start` script that launches `Xvfb` and exports `DISPLAY` before the Jupyter server starts, enabling Qt graphics out of the box.