JSteam Toolbox MEX Interface

To use the JSteam Toolbox the primary interface routine is via the MEX (MATLAB Executable) interface JSteamMEX. This single "function" (actually, a compiled C++ interface to JSteam with the MATLAB API) allows all thermodynamics, system modelling and engineering unit functionality to be called from MATLAB.

Loading JSteam

Before any computations can be done using JSteam, it must first be loaded using the following function call:

>> JSteamMEX('Load');

-------------------------------------------
JSteam Full License

Functionality Enabled:
  - Steam Thermodynamic Functions (IAPWS-IF97)
  - General Thermodynamic Functions (REFPROP)
  - Steam Unit Operations
  - Combustion Unit Operations
  - Organic Rankine Cycle Unit Operations
-------------------------------------------

If you have already installed a license for JSteam, you will see the above. If not, you will see something like the below:

>> JSteamMEX('Load')
Warning: A valid JSteam License could not be found - only steam thermodynamic functions are available.

Warning: To License the JSteam Toolbox, please place your JSteam.lic file in the following directory:
 C:\Program Files\MATLAB\R2022b\bin\win64
The directory should have opened automatically for you. Please Restart MATLAB after copying the license file.

Warning: If you have not received (or requested) a JSteam License file, please email the below MAC address (Physical Address/Host-ID) to
(license email server) to request one.

Note: You can also use the same license file from the JSteam Excel Add In if you are using that.


Physical Address    Transport Name                                            
=================== ==========================================================
XX-XX-XX-XX-XX-XX   \Device\Tcpip_{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}  

If you already have a JSteam license file (e.g. from the Excel Interface or received via email), you can simply copy it to the directory listed (which should already be open in Windows Explorer). If you do not have a license file, then you can email me to request one. The Physical Address table at the bottom of the print out contains the MAC addresses/Host-IDs/Physical addresses of the network adaptors on your computer, and generally the top one is sufficient to send to me to request a license is generated. You could also send all printed out and I can take a guess of the best one to use (i.e. a physical ethernet adaptor is best, or WiFi). The email address will be populated with the address to send the license request to. Once the license is received (typically 24-48hrs), copy it to the directory opened and restart MATLAB to use JSteam Toolbox!

Viewing Help

To avoid exhaustively listing every function contained with the interface in this Wiki, the MEX interface contains top-level built in help documentation, while the Toolbox also comes with the compiled Excel Help File in Examples/JSteam Excel Help.chm which gives detailed information on all functions. To view the MEX interface help use:

>> JSteamMEX('help')

which will print the below (abbreviated) to the MATLAB console:

-------------------------------------------
 JSTEAM MEX INTERFACE HELP
 Built against JSteam v3.26
 (C) Jonathan Currie 2011-2023
 Control Engineering
 https://controlengineering.co.nz

-------------------------------------------
WATER & STEAM FUNCTIONS [IAPWS IF97]
e.g. JSteamMEX('HPT',1,100)
...
-------------------------------------------
PURE FLUID FUNCTIONS [REFPROP]
e.g. JSteamMEX('HcPT','Methane',20,150)
...
-------------------------------------------
AVAILABLE FLUIDS
...
-------------------------------------------
MIXTURE FUNCTIONS [REFPROP]
e.g. JSteamMEX('HmPT',{'nButane',0.5;'nPentane',0.5},20,150)
...
-------------------------------------------
WATER & STEAM UNIT OPERATIONS
...
-------------------------------------------
COMBUSTION UNIT OPERATIONS
...
-------------------------------------------
REFRIGERANT UNIT OPERATIONS
...
-------------------------------------------
USER CUSTOMIZABLE UNITS
...

Thermodynamic & Transport Property Functions

Calling thermodynamic and transport functions is as simple as telling the MEX interface which routine you want to call, and supplying the input arguments. For the naming of routines and arguments, see the Nomenclature Page, and for information on Engineering Units see the unit set documentation.

Some simple scalar examples solving for Specific Enthalpy and Entropy:

% IAPWS-97 Examples
H1 = JSteamMEX('HPT',1,100)
S1 = JSteamMEX('SPT',1,100)

% REFPROP Pure Fluid Examples
H2 = JSteamMEX('HcPT','Methane',10,100)
S2 = JSteamMEX('ScPT','Methane',10,100)

% REFPROP Mixture Examples
H3 = JSteamMEX('HmPT',{'nButane',0.5;'nPentane',0.5},10,100)
S3 = JSteamMEX('SmPT',{'nButane',0.5;'nPentane',0.5},10,100)

In addition to being able to compute scalar quantities, the MEX interface is parallelized to speed up computing sets of quantities. This includes scalar expansion as required.

% Parallelized Thermodynamics - Vector
p = 1;
t = linspace(100,500,10)';
Hv1 = JSteamMEX('HPT',p,t)

% Parallelized Thermodynamics - Matrix
p = linspace(1,10,10)';
t = linspace(100,500,10)';
[P,T] = meshgrid(p,t);
Hv2 = JSteamMEX('HPT',P,T)

Note in rare circumstances the parallel interface can fail depending on the combination of MATLAB/VC++ Runtime/iFort Runtime versions installed. If this happens simply use JSteamMEX in a scalar fashion (for loop(s)) to avoid issues, or update your version of MATLAB.

Unit Operation Functions

All unit operation functions are available via the interface as well, which can be called using the following format:

>> [status,stmH,bfwM,bdM,bdH,duty] = JSteamMEX('UnitOp_Boiler',250,10,410,42,0.01,0.9)

Note that the JSteam MATLAB interface is different to the Excel Interface in that there no optional return arguments, the status is reported first, and the argument order is sometimes different. This has been done to keep the interface in MATLAB as simple as possible.

In order to avoid argument order errors, the user is encouraged to call unit operation functions using the format copied directly from JSteamMEX('help'), such as:

>> [status,airM,Duty,FEff,acidDp,Stack] = JSteamMEX('UnitOp_FuranceM',{Fuel_Mixture},fuelT,airT,airP,airRelHum,minStackT,O2,O2Mode,fuelM)

and assigning values to the names of arguments, rather directly into the function call, as follows:

% Fuel Spec
fluids = {'methane','hydrogen','nitrogen','water','hydrogensulfide'};
fracs = [0.95,0.01,0.02,0.01,0.01];
Fuel = [fluids(:) num2cell(fracs(:))];

% Operating Specs
fuelT = 30;
airT = 30;
airP = 1.01325;
airRelHum = 0.5;
minStackT = 1000;
O2 = 0.1;
O2Mode = 0;
fuelM = 1;

% Solve Unit
[status,airM,Duty,FEff,acidDp,Stack] = JSteamMEX('UnitOp_FurnaceM',Fuel,fuelT,airT,airP,airRelHum,minStackT,O2,O2Mode,fuelM)