1. Getting Started¶

This guide is intended for MATLAB users who want to exploit the features of the Python Anesthesia Simulator.
It explains how to set up your environment, instantiate a Patient object from MATLAB, and connect it to Simulink.

1.1. Prerequisites¶

MATLAB R2024b or later
Simulink toolbox
Python 3.12 (recommended: use a virtual environment)
The Python Anesthesia Simulator package installed (pip install . inside the cloned repository)

1.2. Configure the Python Environment¶

1.2.1. Create a virtual environment (recommended)¶

python -m venv your_environment

1.2.2. Activate the environment¶

Windows

your_environment\Scripts\activate

macOS / Linux

source your_environment/bin/activate

1.2.3. Install the simulator package¶

pip install .

1.3. Set Python Interpreter in MATLAB¶

Tell MATLAB to use your virtual environment’s Python interpreter:

% Windows example
pyenv('Version', 'C:\path\to\your_environment\Scripts\python.exe');

% macOS/Linux example
% pyenv('Version', '/Users/your_username/your_environment/bin/python');

1.4. Basic MATLAB Usage Example¶

% Import the simulator module
simulator = py.importlib.import_module('python_anesthesia_simulator.simulator');

% Define patient parameters
age = 18; height = 170; weight = 60; sex = 0; % 0=female, 1=male
sampling_time = 1;

% Create a Patient object
George = simulator.Patient([age, height, weight, sex], ts=sampling_time);

Once instantiated, you can call methods on the Python Patient object directly from MATLAB.

1.5. Using the Simulator in Simulink¶

Simulink can directly interact with Python objects through MATLAB wrapper functions.
This section shows how to integrate the simulator for real-time co-simulation.

1.5.1. Step 1 – Create `callPython.m`¶

Save this function in your MATLAB path:

function [bis, co, map, tol, nmb] = callPython(u_p,u_r,u_n,u_a,age,height,weight,sex,sampling_time)
% callPython  Interface between Simulink and the Python Anesthesia Simulator.
%
%   [bis, co, map, tol, nmb] = callPython(u_p,u_r,u_n,u_a,age,height,weight,sex,sampling_time)
%   performs one simulation step of the Python patient model.
%
%   Inputs:
%       u_p  - Propofol infusion rate [mg/s]
%       u_r  - Remifentanil infusion rate [µg/s]
%       u_n  - Noradrenaline infusion rate [µg/s]
%       u_a  - Atracurium infusion rate [mg/s]
%       age, height, weight, sex - patient parameters
%       sampling_time - simulation sampling period [s]
%
%   Outputs:
%       bis - Bispectral Index
%       co  - Cardiac Output
%       map - Mean Arterial Pressure
%       tol - Tolerance to laryngoscopy
%       nmb - Neuromuscular Blockade level
%
%   Notes:
%       - Requires a configured Python environment via pyenv.
%       - Works only in Simulink **Normal** mode (not Accelerator or codegen).

    persistent simulator George

    % Initialize Python environment and patient once
    if isempty(simulator)
        simulator = py.importlib.import_module('python_anesthesia_simulator.simulator');
        George = simulator.Patient([age, height, weight, sex], ts=sampling_time);
    end

    % Run one simulation step
    simulation_tuple = George.one_step( ...
        u_propo=u_p, ...
        u_remi=u_r, ...
        u_nore=u_n, ...
        u_atra=u_a);

    % Convert Python outputs to MATLAB doubles
    simulation_cell = cell(simulation_tuple);
    bis = double(simulation_cell{1});
    co  = double(simulation_cell{2});
    map = double(simulation_cell{3});
    tol = double(simulation_cell{4});
    nmb = double(simulation_cell{5});
end

1.5.2. Step 2 – Create `PythonStep.m` (Simulink wrapper)¶

This function is called from within your Simulink MATLAB Function block.

function [bis, co, map, tol, nmb] = PythonStep(u_p,u_r,u_n,u_a,age,height,weight,sex,sampling_time)
% PythonStep  Simulink-compatible wrapper for Python anesthesia simulator
%
% This function acts as a bridge between Simulink and the Python patient model.
% It calls the `callPython` function at each simulation step.
%
% The outputs correspond to patient physiological variables:
% BIS, cardiac output, mean arterial pressure, tolerance to laryngoscopy, and NMB.

    coder.extrinsic('callPython')

    % Default values for Simulink codegen compatibility
    bis = 0; 
    co = 0;
    map = 0;
    tol = 0;
    nmb = 0;

    % Call Python through the MATLAB wrapper
    [bis, co, map, tol, nmb] = callPython(u_p,u_r,u_n,u_a,age,height,weight,sex,sampling_time);
end

1.5.3. Step 3 – Configure Simulink¶

Add a MATLAB Function Block to your Simulink model.
Replace its code with the content of PythonStep.m.
Add the Inputs and Outputs:
- Inputs: u_p, u_r, u_n, u_a, age, height, weight, sex, sampling_time
- Outputs: bis, co, map, tol, nmb
Connect your infusion control signals and monitoring scopes as needed.
Open Simulation Settings → Solver:
- Simulation mode: Normal
- Fixed-step size: equal to your sampling_time
Ensure pyenv is correctly configured before running the model.

1.5.4. Step 4 – Resetting the Python Environment¶

To clear the persistent simulator and reload the Python module:

clear callPython

This ensures that the Patient object is reinitialized on the next simulation.