> ## Documentation Index
> Fetch the complete documentation index at: https://docs.poelis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MATLAB setup - Python SDK

> Call the Poelis Python SDK from MATLAB

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](/python-sdk/matlab-usage).

## 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

<Steps>
  <Step title="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 theme={null}
    matlab.addons.toolbox.installToolbox('PoelisToolbox-1.0.8.mltbx');
    ```
  </Step>

  <Step title="Create a Python environment and install poelis-sdk">
    <Tabs>
      <Tab title="macOS and Linux">
        ```bash theme={null}
        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
        ```
      </Tab>

      <Tab title="Windows">
        ```bash theme={null}
        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
        ```
      </Tab>
    </Tabs>

    Keep the full path printed by `which python` or `where python`. MATLAB needs that path in the next step.
  </Step>

  <Step title="Point MATLAB at that Python environment">
    <Tabs>
      <Tab title="macOS and Linux">
        ```matlab theme={null}
        pyenv('Version', '/full/path/to/.venv/bin/python');
        pyenv
        ```
      </Tab>

      <Tab title="Windows">
        ```matlab theme={null}
        pyenv('Version', 'E:\full\path\to\.venv\Scripts\python.exe');
        pyenv
        ```

        `where python` prints the path to paste into `Version`.
      </Tab>
    </Tabs>

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

    ```matlab theme={null}
    terminate(pyenv)
    pyenv('Version', '/full/path/to/.venv/bin/python');
    ```
  </Step>

  <Step title="Verify the setup">
    ```matlab theme={null}
    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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Update an existing setup

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

<Steps>
  <Step title="Install the new MATLAB toolbox">
    Install the new `PoelisToolbox-<version>.mltbx` file:

    ```matlab theme={null}
    matlab.addons.toolbox.installToolbox('PoelisToolbox-1.0.8.mltbx');
    ```

    If MATLAB asks you to restart after the toolbox update, restart before the next step.
  </Step>

  <Step title="Upgrade the Python SDK">
    Activate the same Python environment MATLAB uses, then upgrade the package.

    <Tabs>
      <Tab title="macOS and Linux">
        ```bash theme={null}
        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
        ```
      </Tab>

      <Tab title="Windows">
        ```bash theme={null}
        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
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Restart MATLAB's Python session">
    ```matlab theme={null}
    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.
  </Step>

  <Step title="Verify the update">
    ```matlab theme={null}
    poelis_sdk.checkInstallation();
    mod = py.importlib.import_module('poelis_sdk');
    char(py.builtins.getattr(mod, '__version__'))
    ```
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="MATLAB loads the wrong Python package">
    Check the file path MATLAB imported:

    ```matlab theme={null}
    char(py.builtins.getattr(mod, '__file__'))
    ```

    The path should sit inside the virtual environment you configured in `pyenv`.
  </Accordion>

  <Accordion title="You switched Python environments">
    Run `terminate(pyenv)` before `pyenv('Version', ...)` again. MATLAB keeps the previous interpreter until that session ends.
  </Accordion>

  <Accordion title="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)`.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>