MATLAB setup - Python SDK

If you already calculate and simulate in MATLAB, you can call the Poelis Python SDK from MATLAB. Point MATLAB at a Python environment where poelis-sdk is installed, then use the Poelis MATLAB Toolbox. That gives you:

Values and metadata from Poelis inside MATLAB, including units
Calculations that stay in MATLAB
Poelis as the source of truth for the engineering data those calculations read

Once setup succeeds, continue with Use Poelis from MATLAB.

How it works

MATLAB talks to Python through pyenv. The Poelis MATLAB Toolbox is a thin wrapper around the Python SDK. Helpers such as poelis_sdk.checkInstallation() and poelis_sdk.PoelisClient(...) live in MATLAB. The requests themselves run in the poelis-sdk package inside your virtual environment.

First-time setup

Install the Poelis MATLAB Toolbox

Download the latest PoelisToolbox-<version>.mltbx release and install it in MATLAB. Double-click the .mltbx file, or run:

matlab.addons.toolbox.installToolbox('PoelisToolbox-1.0.8.mltbx');

Create a Python environment and install poelis-sdk

macOS and Linux
Windows

cd /path/to/your/working-directory
python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
./.venv/bin/python -m pip install -U poelis-sdk
./.venv/bin/python -c "import poelis_sdk; print(poelis_sdk.__version__); print(poelis_sdk.__file__)"
which python

cd /path/to/your/working-directory
python -m venv .venv
.venv\Scripts\activate.bat
pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -U poelis-sdk
.\.venv\Scripts\python.exe -c "import poelis_sdk; print(poelis_sdk.__version__); print(poelis_sdk.__file__)"
where python

Keep the full path printed by which python or where python. MATLAB needs that path in the next step.

Point MATLAB at that Python environment

macOS and Linux
Windows

pyenv('Version', '/full/path/to/.venv/bin/python');
pyenv

pyenv('Version', 'E:\full\path\to\.venv\Scripts\python.exe');
pyenv

where python prints the path to paste into Version.

If MATLAB is already using another interpreter, restart Python first:

terminate(pyenv)
pyenv('Version', '/full/path/to/.venv/bin/python');

Verify the setup

poelis_sdk.checkInstallation();
mod = py.importlib.import_module('poelis_sdk');
char(py.builtins.getattr(mod, '__version__'))
char(py.builtins.getattr(mod, '__file__'))

You should see the installed poelis-sdk version and a file path inside the environment you configured.

Run the sample script

Open try_poelis_matlab.m (src/poelis_matlab/try_poelis_matlab.m). Replace the API key and demo paths with your own, then run the script.

Update an existing setup

A new release usually means a new toolbox file and a newer poelis-sdk.

Install the new MATLAB toolbox

Install the new PoelisToolbox-<version>.mltbx file:

matlab.addons.toolbox.installToolbox('PoelisToolbox-1.0.8.mltbx');

If MATLAB asks you to restart after the toolbox update, restart before the next step.

Upgrade the Python SDK

Activate the same Python environment MATLAB uses, then upgrade the package.

macOS and Linux
Windows

cd /path/to/your/working-directory
python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -U poelis-sdk
which python

cd /path/to/your/working-directory
python -m venv .venv
.venv\Scripts\activate.bat
pip install --upgrade pip
pip install -U poelis-sdk
where python

Restart MATLAB's Python session

terminate(pyenv)

If the Python path stayed the same, MATLAB picks that interpreter up again on the next Python call. If the environment moved, run pyenv('Version', ...) again with the new path.

Verify the update

poelis_sdk.checkInstallation();
mod = py.importlib.import_module('poelis_sdk');
char(py.builtins.getattr(mod, '__version__'))

Troubleshooting

MATLAB loads the wrong Python package

Check the file path MATLAB imported:

char(py.builtins.getattr(mod, '__file__'))

The path should sit inside the virtual environment you configured in pyenv.

You switched Python environments

Run terminate(pyenv) before pyenv('Version', ...) again. MATLAB keeps the previous interpreter until that session ends.

The toolbox is new and Python is old

MATLAB can still load the previous poelis-sdk. Upgrade the package in the environment from pyenv, then terminate(pyenv).

Python is new and the toolbox is old

MATLAB wrapper fixes and examples ship in the toolbox. Install the matching PoelisToolbox-<version>.mltbx as well.

Getting started

Guides

MATLAB

MATLAB setup - Python SDK

How it works

First-time setup

Update an existing setup

Troubleshooting

​How it works

​First-time setup

​Update an existing setup

​Troubleshooting

How it works

First-time setup

Update an existing setup

Troubleshooting