MATLAB Guide

MDSplus has a MATLAB API, allowing you to read, analyze, and write data to and from MDSplus trees using MATLAB.

There are three ways to set up communication between MATLAB and MDSplus:

For Java and Python, the full MDSplus suite must be installed on your computer, plus compatible versions of Java or Python (check MATLAB documentation for compatible Python and OpenJDK). For the mdsthin bridge, only mdsthin needs to be installed. See the section on troubleshooting for more information.

Setup

As long as setup.sh is sourced, the following should work. You can also set MATLABPATH or configure the MatLab search path manually. See the section on troubleshooting for more information.

For more about MATLABPATH, please see the documentation on the MATLAB site: https://www.mathworks.com/help/matlab/matlab_env/what-is-the-matlab-search-path.html https://www.mathworks.com/help/matlab/ref/path.html

Testing

You can access MDSplus from Matlab via Java or Python. Once MATLAB can find the .m files in $MDSPLUS_DIR/matlab you can run these commands to test the Java or Python bridges:

% to test the Java bridge
mdstest(false)

% to test the Python bridge
mdstest(true)

% the mdsthin bridge cannot be tested as the tests rely on local MDSplus
% mdstest(true, true)

Usage

Initializing MDSplus

Java bridge

% Java is the default, but you can force it with:
mdsUsePython(false)

Python bridge

mdsUsePython(true)

mdsthin bridge

mdsUsePython(true, true)

Connecting and Opening Trees

% Connect to a server, in this case 123.456.7.89
mdsconnect('123.456.7.89')

ans = 
    1

% Open "mytree" to shot 42
mdsopen('mytree', 42)

Reading Data

% Assign the value from node with tag name "data_node" into a MATLAB workspace variable named "data_read"
data_read = mdsvalue('\data_node')

% If applicable, issue Tree Command Language (TCL) commands to the MDSplus server through MATLAB
mdsvalue('tcl($)', 'set current mytree 42')

% Close the current tree
mdsclose

% Disconnect from the server
mdsdisconnect

Writing Data

% Write the value of the Matlab workspace variable named "data_read" to the node with the tag name "data_node"
mdsput('\data_node', data_read)

Troubleshooting

Many issues can be explained by compatibility between different versions of software. In all cases, be sure to check both version of the server and the client. See below for other specific issues.

Manually Configuring the MATLAB Search Path

The commands used to read/write data from MDSplus trees are provided as MATLAB script files (.m), which are located in $MDSPLUS_DIR/matlab. You must add this folder to your MATLAB search path using the Set Path option from the File menu or using these commands:

% add $MDSPLUS_DIR/matlab to path
addpath(fullfile(getenv('MDSPLUS_DIR'), 'matlab'))
savepath()

Relevant reference articles from the MATLAB Help Center:

Java Bridge Troubleshooting

For reference, please also see to the MathWorks documentation for using Java with MATLAB as needed.

Java Compatability

Ensure that your version of Java is compatible with MDSplus. Search for “compatible OpenJDK” on the MATLAB website (or try this link).

Java ClassPath

For Personal Computers

Setting the Java class path can be done many ways; see all options in this table.

  • For permanent configuration, we recommend the Static Path.

  • For temporary configuration, using the javaddpath will also work.

  • For either method, you will need the following information:

    • The MDSplus Java classes are located in this folder: $MDSPLUS_DIR/java/classes

    • Java also needs access to the “libJavaMds” library that is in $MDSPLUS_DIR/lib. Use the javalibrarypath.txt file to specify that location. Read more about libraries.

    • To troubleshoot, use the javaclasspath command to make sure that it has $MDSPLUS_DIR/java/classes.

For Computing Clusters

If your organization runs MATLAB from a computing cluster, it will likely have multiple versions of MATLAB, Python, Java, and MDSplus installed. If so, please follow these instructions instead.

  • Place configuration files in your user home directory. For example, on Linux javaclasspath.txt and javalibrarypath.txt can be placed in ~/.matlab/R2024b (where “R2024b” is a version of MATLAB).

  • To override configuration created by your the system administrator, you may need to use the <before> attribute as the first line of the javaclasspath.txt file; this ensures that the directories you specify will be searched first (and likely skipping the directories that the system administrator specified).

  • To test the configuration of MATLAB / MDSplus, run mdstest(0).

Python Bridge Troubleshooting

  • Ensure that MATLAB is using the expected version of Python with:

    >> pyversion()

    version: '3.12'
    executable: '/usr/bin/python3'
    library: 'libpython3.12.so.1.0'
        home: '/usr'
    isloaded: 0

  • Ensure you can import MDSplus from a Python prompt in the same terminal where you are launching MATLAB.

  • Sourcing setup.sh doesn’t always work when using the Python bridge. Depending on how MDSplus was installed, the .pth file might not be present. If it is missing, then one must make sure that the $PYTHONPATH environment variable includes $MDSPLUS_DIR/python.

  • If on a cluster and MATLAB is using the wrong Python version, the user will likely have to use the module command to select a compatible Python before starting MATLAB.

mdsthin Bridge Troubleshooting

  • Ensure you can import mdsthin from a python prompt in the same terminal where you’re launching MATLAB.

  • Follow steps for troubleshooting Python bridge in the previous section.

  • If using mdsthin, the matlab.tgz file must also be installed (it is available on GitHub in the Releases section).

Reading Data: Troubleshooting

Occasionally, the API will return MDSplus status codes. These are usually large numbers indicating that a specific status message applies. Even numbers indicate a failure of some sort (basically the lowest bit is set to false, and that indicates a failure…but this may be too much info)

Example: the large number shown in the following output indicates that a TreeFAILURE condition occurred because the user does not have write permissions on the specified archive.

```
>> mdsvalue('tcl($)', 'set current cmod 1090909009') 
ans =

int32

265392034
```