GeoEco.Matlab.MatlabWorkerProcess

class GeoEco.Matlab.MatlabWorkerProcess(timeout=30.0, idle=60.0)

Bases: object

Allows GeoEco functions implemented in MATLAB to be called as Python functions, with MATLAB hosted in a separate process.

Certain functions in GeoEco are implemented in MATLAB code. In order for these functions to run, either MATLAB R2024b or the MATLAB Runtime R2024b must be installed. The MATLAB Runtime is free and may be downloaded from https://www.mathworks.com/help/compiler/install-the-matlab-runtime.html. Please follow the installation instructions carefully. Version R2024b must be used; other versions will not work. MATLAB Runtime allows multiple versions can be installed at the same time.

MATLAB is large and complex program that utilizes a lot of third-party programming libraries (.so files on Linux and .DLL files on Windows). Other large and complex programs such as ArcGIS may utilize some of the same libraries. Loading both MATLAB and ArcGIS into the same process can result in a situation known as dependency hell, in which one program requires version A of a third-party library but the other program requires version B, but both versions cannot be loaded into the same process at the same time. When these version conflicts occur, the first program may run successfully but the second one may fail. MatlabWorkerProcess solves this problem by loading MATLAB in a separate process. Because GeoEco often involves utilizing ArcGIS, we recommend accessing GeoEco’s MATLAB functions with MatlabWorkerProcess rather than MatlabFunctions. which loads them into the caller’s process.

Note

Because starting MATLAB or MATLAB Runtime can take several seconds, most parts of the GeoEco package use SharedMatlabWorkerProcess to share a single instance of MatlabWorkerProcess, to avoid having to start the worker process over and over again. If you are implementing a GeoEco component, consider using SharedMatlabWorkerProcess.

To use MatlabWorkerProcess, you must first instantiate it, then call the GeoEco MATLAB functions of interest as methods of that instance. The first time you call a method, a worker process will be created and MATLAB will be loaded inside it. Your call will then be proxied to that process. Because starting MATLAB can take several seconds, the process will then be kept alive in anticipation of you making another call. When you are done, call Stop() to stop the worker process. For example:

from GeoEco.Matlab import MatlabWorkerProcess
matlab = MatlabWorkerProcess()
try:
    a = [1,2,3]
    b = matlab.TestParameterType(a)
    assert b == a
    ...
finally:
    matlab.Stop()

In the example above, the TestParameterType function simply accepts one argument and returns it back to the caller. We use it in GeoEco’s automated tests to verify that we can exchange different data types with MATLAB properly.

Note

GeoEco’s MATLAB functions are part of GeoEco’s internal API and are not recommended for external callers. Because of this, we do not formally document them. But you can find them in GeoEco’s source code repository, or by unzipping the .ctf file found inside GeoEco’s Python package directory and digging around in the resulting directory structure.

MatlabWorkerProcess supports the Python context manager protocol, which allows you to use The with statement to ensure Stop() is called automatically when your block exits:

from GeoEco.Matlab import MatlabWorkerProcess
with MatlabWorkerProcess() as matlab:
    a = [1,2,3]
    b = matlab.TestParameterType(a)
    assert b == a
    ...

Warning

If you do not use The with statement or manually call Stop(), the worker process will remain running until your main process exits. During this time, it will remain idle but it may occupy a not-insignificant amount of RAM. Also, the worker process is not stopped automatically when the MatlabWorkerProcess instance is deleted. You must use The with statement or Stop() to stop the worker process.

Although the MATLAB function is executed in another process, the call into the MatlabWorkerProcess instance method representing it blocks until it is complete. Currently, there is no way to execute MATLAB functions asynchronously with MatlabWorkerProcess.

Requires: MATLAB Runtime R2024b (which can be freely downloaded from https://www.mathworks.com/products/compiler/matlab-runtime.html) or the full version of MATLAB R2024b.

Parameters:

timeout (float, optional) – Number of seconds to wait for MATLAB to start before assuming it has failed. Must be greater than 0.0.
idle (float, optional) – Number of seconds to the worker process should wait after completing the execution of a MATLAB function to be commanded to execute another function. If it does not receive a new command after this idle time, it will shut down to save memory. If a new command is issued after it is shut down, it will be restared automatically. Minimum value꞉ 0.0.

Returns:

MatlabWorkerProcess instance.

Return type:

MatlabWorkerProcess

Methods

Stop

Stops the MATLAB worker process.