Setting up Force Field X with Matlab.

The instructions below are available in the file "ffx/matlab/SetupFFX.m". Please follow these instructions to configure Java and Force Field X within the Matlab environment.

Loading the Java SDK into Matlab
As of Matlab 2026b, both Matlab and Force Field X support JDK/JRE version 25. Please install JDK 25 from Oracle or from Adopt Open JDK:
Oracle JDK 25
- or -
Adopt Open JDK 25
Matlab can be configured to use this JDK use the 'jenv' command:

jenv("/Library/Java/JavaVirtualMachines/jdk-25.0.3+9/Contents/Home")

To check the current Matlab Java version, first execute a Java command to force loading of the Java Virtual Machine.

java.lang.String('Load Java.')

Check the current JDK version:

version -java
 ans = 'Java 25.0.3+9-LTS with Eclipse Adoptium OpenJDK 64-Bit Server VM mixed mode, emulated-client, sharing'

Adding Force Field X to the Matlab Classpath
Once Matlab is running on JRE/JDK 25, the FFX jar files need to be added to the "static" Matlab classpath as documented here.
The SetupFFX.m script will configure the classpath by running the following commands:

% Add JAR files to "javaclasspath.txt" in the Matlab pref directory.
cd(prefdir)
fid = fopen('javaclasspath.txt','wt');
for n = 1:length(jarfiles)
  file = jarfiles(n);
  if (length(file.name) > 4)
    jar = ffxlib + file.name;
    fprintf(fid, '%s\n', jar);
  end
end
fclose(fid);

Matlab must be restarted for the new static classpath to take effect.

Configure Java Start-Up Options
FFX requires the incubating Vector extensiuons be enabled. This is configured using a Matlab Java start-up options file as documented here.
The SetupFFX.m script will configure the start-up options by running the following comamnds:

% Configure Java Start-Up Options to enable Vector Calculations
startupDir = matlabroot + "/bin/" + computer('arch');
cd(startupDir);
fid = fopen('java.opts','wt');
fprintf(fid, '%s\n', '--add-modules=jdk.incubator.vector');
fclose(fid);

Matlab must be restarted for the new start-up options to take effect.

Running Force Field X Commands

Once Matlab is running on Java v. 25, an example using Force Field X commands is given in the script "ffx/matlab/ForceFieldX.m".
Matlab Java syntax documentation is available here.

import java.util.ArrayList
import ffx.utilities.FFXBinding
import ffx.potential.commands.Energy

% Set the FFX_HOME variable to the root FFX directory.

FFX_HOME = "/Users/mjschnie/Data/ffx-project/forcefieldx";

% Script input Arguments
A = ArrayList;
A.add("-m");
A.add(FFX_HOME + "/examples/dhfr.xyz");

% Create a Binding
binding = FFXBinding;
binding.setVariable("args", A);

% Run the Energy command
command = Energy;
command.setBinding(binding);
command.run();

% Get back the ForceFieldEnergy instance
forceFieldEnergy = command.forceFieldEnergy;
forceFieldEnergy.toString()