GeoEco.Matlab.SharedMatlabWorkerProcess

class GeoEco.Matlab.SharedMatlabWorkerProcess

Bases: object

Manages a singleton instance of MatlabWorkerProcess that may be shared by multiple callers.

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.

To avoid dependency hell, MatlabWorkerProcess hosts MATLAB or the MATLAB Runtime in a separate process. Starting and initializing this process can take several seconds. To avoid having to do this over and over again, SharedMatlabWorkerProcess starts and manages a single MatlabWorkerProcess instance that can be used throughout the GeoEco library. Once instantiated, it will run until it is explicitly stopped or until the Python interpreter exits (atexit is used for this.)

If a GeoEco component needs its own private worker process, rather than using the shared one, it can instantiate and use its own instance of MatlabWorkerProcess rather than using SharedMatlabWorkerProcess. An unlimited number of worker processes can be started and run simultaneously. A given worker process may only be used by one thread of the Python interpreter at a time. While a call into a worker process is executing, MatlabWorkerProcess blocks new callers until the current call completes.

Here’s how to use SharedMatlabWorkerProcess:

# Start the MatlabWorkerProcess if it is not already running and get a
# weakref to it.

from GeoEco.Matlab import SharedMatlabWorkerProcess
matlab = SharedMatlabWorkerProcess.GetWorkerProcess()

# Now call methods of the matlab object, e.g.:

a = [1,2,3]
b = matlab.TestParameterType(a)
assert b == a

# Optionally, shut down the shared worker process. If this is not done
# explicitly, it will be done automatically when the Python interpreter
# exits. After the process is shut down, you can call GetWorkerProcess()
# to start it back up again, if desired.

SharedMatlabWorkerProcess.Shutdown()

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.

Methods

`GetWorkerProcess`	Instantiate and start the shared `MatlabWorkerProcess` (if not already instantiated) and return `weakref` to it.
`Shutdown`	Stop and delete the `MatlabWorkerProcess`, if it has been instantiated.