MATLAB Launcher

The MATLAB launcher integrates with a shared MATLAB Engine session instead of spawning matlab.exe directly. This allows the Python launcher to reconnect if MATLAB restarts and gives the experimenter control through a small UI.

Prerequisites

MATLAB R2020b or newer with the matlabengine Python package installed in the environment that runs run_launcher.py. Install via pip:
pip install openscope-experimental-launcher[matlab]
or, if you only need the engine package:
```
pip install matlabengine
```
The launcher package on the MATLAB path so helper utilities (for example
slap2_launcher) are available. A simple approach during development is:
```
addpath('C:/BonsaiDataPredictiveProcessing/openscope-experimental-launcher/src/openscope_experimental_launcher/launchers')
```

Preparing MATLAB

Before starting the Python launcher, share the MATLAB engine and open the SLAP2 control UI:

slap2_launcher('slap2_launcher')

The engine name is configurable through the matlab_engine_name parameter. When the shared session is ready, the MATLAB UI shows Waiting for Python launcher.

Parameter Summary

Most workflows only need a handful of parameters:

matlab_engine_name (string): Name of the shared engine. Defaults to "slap2_launcher".
matlab_entrypoint / matlab_function (string): MATLAB function to call. matlab_function is accepted for legacy parameter files; matlab_entrypoint is preferred. Defaults to "slap2_launcher" when omitted.
matlab_entrypoint_args (list): Positional arguments forwarded to the MATLAB function. When the entry point is slap2_launcher, the Python launcher automatically prepends "execute" (which tells MATLAB to start the acquisition flow) and then injects the session folder, so most SLAP2 workflows can omit this field. The "execute" branch inside slap2_launcher always runs the bundled slap2 acquisition function; there is no configuration knob for swapping to a different MATLAB function.
script_parameters (object): Arbitrary name/value pairs appended after matlab_entrypoint_args. Use this block to pass rig paths or other configuration (for example, {"rig_description_path": "{rig_param:rig_description_path}"}).
matlab_entrypoint_kwargs (object): Additional name/value pairs appended after script_parameters. These are rarely needed now that script_parameters handles rig-specific values.
matlab_entrypoint_nargout (int): Number of outputs expected from the MATLAB function (default 0).
matlab_engine_connect_timeout_sec (float): How long to wait for the shared engine to appear (default 120).
matlab_engine_connect_poll_interval_sec (float): Polling interval while waiting for the engine (default 1 second).
matlab_cancel_timeout_sec (float): Maximum time to wait for MATLAB to acknowledge a cancellation request.
matlab_keep_engine_alive (bool): Whether to leave the engine running after the launcher exits. Defaults to true so MATLAB stays available between runs.

Note

Session folder injection and resume signalling are automatic. Legacy keys such as matlab_pass_session_folder, matlab_session_folder_position, matlab_enable_resume, and matlab_resume_keyword are still accepted for backward compatibility but should be omitted from new parameter files. If MATLAB crashes or the SLAP2 UI is closed, the Python launcher now stays alive, logs the failure, and keeps trying to reconnect so you can relaunch MATLAB and re-share the engine without restarting Python.

Manual / MATLAB-only Workflows

When no Python launcher is attached, you can still run SLAP2 directly from the shared-engine UI: select a session folder and rig description using the buttons on the window, then press Start SLAP2 acquisition. The UI enables the button automatically once both selections are valid and runs the bundled slap2 function end-to-end. This is useful for exploratory sessions where the standardized metadata pipeline is unnecessary.

Local Smoke Test

A ready-to-run parameter file is provided at params/matlab_local_test_params.json. It exercises the shared engine flow using sample_matlab_entrypoint.m which writes a heartbeat file inside the session folder. The same file demonstrates script_parameters to forward rig_description_path so SLAP2 immediately knows which rig to load.

In MATLAB:

addpath('C:/BonsaiDataPredictiveProcessing/openscope-experimental-launcher/src/openscope_experimental_launcher/launchers')
slap2_launcher('slap2_launcher')

In Python:

python run_launcher.py --param_file params/matlab_local_test_params.json

The MATLAB UI exposes Resume SLAP2 acquisition (same control as the start button) and End SLAP2 acquisition buttons. Resume mode is triggered automatically when the Python launcher reconnects to a shared engine after a failure and ensures operators explicitly confirm that MATLAB should continue.

Crash Recovery Flow

If the MATLAB UI closes or the engine drops mid-run, Python logs that it is waiting for the operator to resume and repeatedly attempts to reconnect. To resume safely:

Relaunch MATLAB if needed and run slap2_launcher('slap2_launcher') so the shared UI window opens again (or re-share the engine name configured in your params file).
Confirm the rig description and session folder selections. The primary button now reads Resume SLAP2 acquisition, indicating SLAP2 will be relaunched.
Press Resume SLAP2 acquisition to re-run slap2. This step is required even if the prior run had already reached the completion prompt, because the microscope hardware must be restarted.
After the re-run finishes, press End SLAP2 acquisition so Python can leave the uiwait loop and finish post-acquisition modules.

Python keeps polling for the shared engine throughout this process and only proceeds once the operator presses End. This guarantees that every resume performs a full SLAP2 restart before metadata is finalized.

Troubleshooting

No module named ``matlab.engine`` – ensure pip install matlabengine
was run inside the same Python environment used for the launcher.
Engine connection times out – verify the MATLAB session called
slap2_launcher('engine_name') and that the name matches

matlab_engine_name in the parameter file.
Logs appear only after completion – MATLAB buffers stdout while the UI uiwait is active. Use the heartbeat file or MATLAB diary to monitor progress during long acquisitions.