MATLAB Wrapper

Pre-compiled Binaries

Release versions of the MATLAB wrapper can be downloaded from MATLAB for your architecture, or from the development snapshots at MATLAB. Whichever one you pick, make sure all the files come from the same place.

Warning

For users on Mac OSX 10.10+, you should use the release binaries from MATLAB/10.10+/MATLAB for your architecture, or from the development snapshots at MATLAB/10.10+/MATLAB.

Download the +CoolProp.7z file and extract it using the 7-zip program. Make sure that when you expand it, there are no +CoolProp intermediate folders generated. Place the mex file that is appropriate to the version of MATLAB in the directory that contains the directory +CoolProp. You can determine what version of matlab you have by running the command computer('arch') at the MATLAB command prompt. Depending on the output, you will need to download one of the following mex files:

  • computer('arch') yields win32: CoolPropMATLAB_wrap.mexw32
  • computer('arch') yields win64: CoolPropMATLAB_wrap.mexw64
  • computer('arch') yields glnxa64: CoolPropMATLAB_wrap.mexa64
  • computer('arch') yields maci64: CoolPropMATLAB_wrap.mexmaci64

Also, download the SwigRef.m and CoolPropsetup.m files.

When you are finished, you should have a folder layout like:

main
 |- SwigRef.m
 |- CoolPropsetup.m
 |- CoolPropMATLAB_wrap.mexw64
 |- +CoolProp
    |- AbstractState.m
    |- DmassHmass_INPUTS.m
    |- ...

Then you need to add the main that contains the +CoolProp folder to the path in MATLAB. This command adds the folder main that contains CoolProp files to the MATLAB path:

addpath('/home/USERNAME/Some_folder/main')

Usage

To calculate the normal boiling temperature of water at one atmosphere:

>> CoolProp.PropsSI('T','P',101325,'Q',0,'Water')

Faster Properties

The interface for CoolProp for MATLAB is quite slow due to the internal structure of MATLAB that is not amenable for easy wrapping of C++ code. For that reason it can be advantageous to call the low-level interface through the DLL (shared library on linux and OSX) and obtain a few properties at a time. There is an example below that demonstrates how to do this. It mirrors the code that is used to call these functions from C++ as seen in the low-level interface. This method of retrieving properties is almost as fast as C++, and much faster than using the SWIG-based wrappers.

User-Compiled Binaries

Pre-generated wrapper code

For windows users, you can almost certainly use the pre-compiled binaries described above. For some other platforms (OSX and linux primarily), there are various problems that make the use of the precompiled binaries impossible. So you would need to build it yourself on your computer to make sure that everything works properly.

Until support for MATLAB makes it into the master branch of SWIG, using swig for users (though documented below), will not be very straightforward. For that reason, a zip file has been generated with the MATLAB interface code already packaged. You will simply need to download the 7z archive, extract it, use CMake to generate a makefile, and build.

The pre-generated versions of the MATLAB wrapper source code can be downloaded from MATLAB for your architecture, or from the development snapshots at MATLAB. You want the file swigged_MATLAB_src.7z. Once you have downloaded this file, you should run these steps at the command line:

# Change this path to be the root directory for MATLAB if needed
export MATLAB_ROOT=/package/matlab/R2014a
7z x swigged_MATLAB_src.7z
cd coolprop/build
cmake .. -DCOOLPROP_MATLAB_SWIGAUTOGENERATED=ON
cmake --build .

You should end up with a folder layout like described above within the coolprop/build directory.

Swig+Matlab

As of version 5 of CoolProp, the MATLAB wrapper has been greatly improved in capabilities thanks to the work of the SWIG team. The MATLAB wrapper will now automatically include complete wrappers of the high-level and low-level code, bringing it in line with the other SWIG-based wrappers (scilab, C#, octave, etc).

The bad part of this is that swig+matlab support has not been integrated into the main codebase of swig (as of October 2014). Thus it is necessary to compile (or obtain) swig+matlab.

The code below assumes that the swig-matlab-bin folder sits in the build directory.

Precompiled

You can download the pre-compiled nightly versions from MATLAB.

Do-it-yourself (masochistic)

On linux and OSX, you can simply run the script dev/scripts/build_swig_matlab.py which will check out the code for swig, obtain PCRE, and build the correct architecture’s binary. The resulting code will reside in the folder dev/scripts/swig-matlab/swig-matlab-bin.

For windows, its pretty much the same story, except that swig has to be cross-compiled from a linux (debian-based OS are good) host. Install all the mingw packages in Synaptic, and then run the build script like:

python build_swig_matlab.py --windows

which should hopefully yield the binaries in dev/scripts/swig-matlab/swig-matlab-bin.

Common Requirements

Compilation of the MATLAB wrapper requires a few common wrapper pre-requisites

Linux

Install MATLAB using installer downloaded from www.mathworks.com. As of version R2014a, only 64-bit MATLAB is available

OSX

Install MATLAB using installer downloaded from www.mathworks.com. As of version R2014a, only 64-bit MATLAB is available

Windows

Install MATLAB using installer downloaded from www.mathworks.com. As of version R2014a, both of 32-bit and 64-bit MATLAB are available

Build

Linux and OSX

Once the dependencies are installed, you can run the builder and tests using:

# Check out the sources for CoolProp
git clone https://github.com/CoolProp/CoolProp --recursive
# Move into the folder you just created
cd CoolProp
# Make a build folder
mkdir build && cd build
# Copy the swig-matlab-bin folder here (fix path as necessary) (see above for Swig discussion)
cp ../../dev/scripts/swig-matlab/swig-matlab-bin .
# Set an environmental variable that points to your MATLAB installation for use in CMake (adjust if needed)
export MATLAB_ROOT=/usr/local/MATLAB/R2014a # or /Applications/MATLAB_R2014a.app
# Build the makefile using CMake with the path hacked to use our swig
PATH=swig-matlab-bin/bin:%{PATH} cmake .. -DCOOLPROP_MATLAB_MODULE=ON -DSWIG_DIR=swig-matlab-bin/bin
# Make the MEX files (by default files will be generated in folder install_root/MATLAB relative to CMakeLists.txt file)
# Setting the SWIG_LIB explictly is dangerous, but for now it doesn't seem there is a better solution
SWIG_LIB=swig-matlab-bin/share/swig/3.0.3 make install

Windows (32-bit and 64-bit)

You need to just slightly modify the building procedure:

# Check out the sources for CoolProp
git clone https://github.com/CoolProp/CoolProp --recursive
# Move into the folder you just created
cd CoolProp
# Make a build folder
mkdir build && cd build
# Copy the swig-matlab-bin folder here (fix path as necessary) (see above for Swig discussion)
cp ../../dev/scripts/swig-matlab/swig-matlab-bin .
# Set an environmental variable that points to your MATLAB installation for use in CMake (adjust if needed)
set "MATLAB_ROOT=c:\Program Files\MATLAB\R2014a"
# Build the makefile using CMake with the path hacked to use our swig
set "PATH=swig-matlab-bin\bin:%{PATH}" && cmake .. -DCOOLPROP_MATLAB_MODULE=ON -DSWIG_DIR=swig-matlab-bin\bin
# Make the MEX files (by default files will be generated in folder install_root/MATLAB relative to CMakeLists.txt file)
# Setting the SWIG_LIB explictly is dangerous, but for now it doesn't seem there is a better solution
set "SWIG_LIB=swig-matlab-bin\share\swig\3.0.3" && make install

Example Code

disp([num2str('**************** INFORMATION ***************')]);
disp([num2str('This example was auto-generated by the language-agnostic dev/scripts/example_generator.py script written by Ian Bell')]);
disp([num2str('CoolProp version:'), ' ', num2str(CoolProp.get_global_param_string('version'))]);
disp([num2str('CoolProp gitrevision:'), ' ', num2str(CoolProp.get_global_param_string('gitrevision'))]);
disp([num2str('CoolProp Fluids:'), ' ', num2str(CoolProp.get_global_param_string('FluidsList'))]);
% See http://www.coolprop.org/coolprop/HighLevelAPI.html#table-of-string-inputs-to-propssi-function for a list of inputs to high-level interface;
disp([num2str('*********** HIGH LEVEL INTERFACE *****************')]);
disp([num2str('Critical temperature of water:'), ' ', num2str(CoolProp.Props1SI('Water', 'Tcrit')), ' ', num2str('K')]);
disp([num2str('Boiling temperature of water at 101325 Pa:'), ' ', num2str(CoolProp.PropsSI('T', 'P', 101325, 'Q', 0, 'Water')), ' ', num2str('K')]);
disp([num2str('Phase of water at 101325 Pa and 300 K:'), ' ', num2str(CoolProp.PhaseSI('P', 101325, 'T', 300, 'Water'))]);
disp([num2str('c_p of water at 101325 Pa and 300 K:'), ' ', num2str(CoolProp.PropsSI('C', 'P', 101325, 'T', 300, 'Water')), ' ', num2str('J/kg/K')]);
disp([num2str('c_p of water (using derivatives) at 101325 Pa and 300 K:'), ' ', num2str(CoolProp.PropsSI('d(H)/d(T)|P', 'P', 101325, 'T', 300, 'Water')), ' ', num2str('J/kg/K')]);
disp([num2str('*********** HUMID AIR PROPERTIES *****************')]);
disp([num2str('Humidity ratio of 50% rel. hum. air at 300 K, 101325 Pa:'), ' ', num2str(CoolProp.HAPropsSI('W', 'T', 300, 'P', 101325, 'R', 0.5)), ' ', num2str('kg_w/kg_da')]);
disp([num2str('Relative humidity from last calculation:'), ' ', num2str(CoolProp.HAPropsSI('R', 'T', 300, 'P', 101325, 'W', CoolProp.HAPropsSI('W', 'T', 300, 'P', 101325, 'R', 0.5))), ' ', num2str('(fractional)')]);
disp([num2str('*********** INCOMPRESSIBLE FLUID AND BRINES *****************')]);
disp([num2str('Density of 50% (mass) ethylene glycol/water at 300 K, 101325 Pa:'), ' ', num2str(CoolProp.PropsSI('D', 'T', 300, 'P', 101325, 'INCOMP::MEG-50%')), ' ', num2str('kg/m^3')]);
disp([num2str('Viscosity of Therminol D12 at 350 K, 101325 Pa:'), ' ', num2str(CoolProp.PropsSI('V', 'T', 350, 'P', 101325, 'INCOMP::TD12')), ' ', num2str('Pa-s')]);
% If you don't have REFPROP installed, disable the following lines;
disp([num2str('*********** REFPROP *****************')]);
disp([num2str('REFPROP version:'), ' ', num2str(CoolProp.get_global_param_string('REFPROP_version'))]);
disp([num2str('Critical temperature of water:'), ' ', num2str(CoolProp.Props1SI('REFPROP::Water', 'Tcrit')), ' ', num2str('K')]);
disp([num2str('Boiling temperature of water at 101325 Pa:'), ' ', num2str(CoolProp.PropsSI('T', 'P', 101325, 'Q', 0, 'REFPROP::Water')), ' ', num2str('K')]);
disp([num2str('c_p of water at 101325 Pa and 300 K:'), ' ', num2str(CoolProp.PropsSI('C', 'P', 101325, 'T', 300, 'REFPROP::Water')), ' ', num2str('J/kg/K')]);
disp([num2str('*********** TABULAR BACKENDS *****************')]);
TAB = CoolProp.AbstractState.factory('BICUBIC&HEOS', 'R245fa');
TAB.update(CoolProp.PT_INPUTS, 101325, 300);
disp([num2str('Mass density of refrigerant R245fa at 300 K, 101325 Pa:'), ' ', num2str(TAB.rhomass()), ' ', num2str('kg/m^3')]);
disp([num2str('*********** SATURATION DERIVATIVES (LOW-LEVEL INTERFACE) ***************')]);
AS_SAT = CoolProp.AbstractState.factory('HEOS', 'R245fa');
AS_SAT.update(CoolProp.PQ_INPUTS, 101325, 0);
disp([num2str('First saturation derivative:'), ' ', num2str(AS_SAT.first_saturation_deriv(CoolProp.iP, CoolProp.iT)), ' ', num2str('Pa/K')]);
disp([num2str('*********** LOW-LEVEL INTERFACE *****************')]);
AS = CoolProp.AbstractState.factory('HEOS', 'Water&Ethanol');
z = CoolProp.DoubleVector(); z.push_back(0.5); z.push_back(0.5);;
AS.set_mole_fractions(z);
AS.update(CoolProp.PQ_INPUTS, 101325, 1);
disp([num2str('Normal boiling point temperature of water and ethanol:'), ' ', num2str(AS.T()), ' ', num2str('K')]);
% If you don't have REFPROP installed, disable the following block;
disp([num2str('*********** LOW-LEVEL INTERFACE (REFPROP) *****************')]);
AS2 = CoolProp.AbstractState.factory('REFPROP', 'Methane&Ethane');
z2 = CoolProp.DoubleVector(); z2.push_back(0.2); z2.push_back(0.8);;
AS2.set_mole_fractions(z2);
AS2.update(CoolProp.QT_INPUTS, 1, 120);
disp([num2str('Vapor molar density:'), ' ', num2str(AS2.keyed_output(CoolProp.iDmolar)), ' ', num2str('mol/m^3')]);

Example Code Output


                            < M A T L A B (R) >
                  Copyright 1984-2014 The MathWorks, Inc.
                     R2014a (8.3.0.532) 64-bit (maci64)
                             February 11, 2014


	Home Use License - for personal use only.  Not for government,
	academic, commercial, and other organizational use.
 
To get started, type one of these: helpwin, helpdesk, or demo.
For product information, visit www.mathworks.com.
 
Running Example
**************** INFORMATION ***************
This example was auto-generated by the language-agnostic dev/scripts/example_generator.py script written by Ian Bell
CoolProp version: 6.1.0
CoolProp gitrevision: 7864c2614ce5a0ef972386ee7f39859f0d3f8038
CoolProp Fluids: 1-Butene,Acetone,Air,Ammonia,Argon,Benzene,CarbonDioxide,CarbonMonoxide,CarbonylSulfide,cis-2-Butene,CycloHexane,Cyclopentane,CycloPropane,D4,D5,D6,Deuterium,Dichloroethane,DiethylEther,DimethylCarbonate,DimethylEther,Ethane,Ethanol,EthylBenzene,Ethylene,EthyleneOxide,Fluorine,HeavyWater,Helium,HFE143m,Hydrogen,HydrogenChloride,HydrogenSulfide,IsoButane,IsoButene,Isohexane,Isopentane,Krypton,m-Xylene,MD2M,MD3M,MD4M,MDM,Methane,Methanol,MethylLinoleate,MethylLinolenate,MethylOleate,MethylPalmitate,MethylStearate,MM,n-Butane,n-Decane,n-Dodecane,n-Heptane,n-Hexane,n-Nonane,n-Octane,n-Pentane,n-Propane,n-Undecane,Neon,Neopentane,Nitrogen,NitrousOxide,Novec649,o-Xylene,OrthoDeuterium,OrthoHydrogen,Oxygen,p-Xylene,ParaDeuterium,ParaHydrogen,Propylene,Propyne,R11,R113,R114,R115,R116,R12,R123,R1233zd(E),R1234yf,R1234ze(E),R1234ze(Z),R124,R125,R13,R134a,R13I1,R14,R141b,R142b,R143a,R152A,R161,R21,R218,R22,R227EA,R23,R236EA,R236FA,R245ca,R245fa,R32,R365MFC,R40,R404A,R407C,R41,R410A,R507A,RC318,SES36,SulfurDioxide,SulfurHexafluoride,Toluene,trans-2-Butene,Water,Xenon
*********** HIGH LEVEL INTERFACE *****************
Critical temperature of water: 647.096 K
Boiling temperature of water at 101325 Pa: 373.1243 K
Phase of water at 101325 Pa and 300 K: liquid
c_p of water at 101325 Pa and 300 K: 4180.6358 J/kg/K
c_p of water (using derivatives) at 101325 Pa and 300 K: 4180.6358 J/kg/K
*********** HUMID AIR PROPERTIES *****************
Humidity ratio of 50% rel. hum. air at 300 K, 101325 Pa: 0.011096 kg_w/kg_da
Relative humidity from last calculation: 0.5 (fractional)
*********** INCOMPRESSIBLE FLUID AND BRINES *****************
Density of 50% (mass) ethylene glycol/water at 300 K, 101325 Pa: 1061.1793 kg/m^3
Viscosity of Therminol D12 at 350 K, 101325 Pa: 0.00052288 Pa-s
*********** REFPROP *****************
REFPROP version: 9.1.1.10
Critical temperature of water: 647.096 K
Boiling temperature of water at 101325 Pa: 373.1243 K
c_p of water at 101325 Pa and 300 K: 4180.6358 J/kg/K
*********** TABULAR BACKENDS *****************
Mass density of refrigerant R245fa at 300 K, 101325 Pa: 5.6481 kg/m^3
*********** SATURATION DERIVATIVES (LOW-LEVEL INTERFACE) ***************
First saturation derivative: 4058.5198 Pa/K
*********** LOW-LEVEL INTERFACE *****************
Normal boiling point temperature of water and ethanol: 357.273 K
*********** LOW-LEVEL INTERFACE (REFPROP) *****************
Vapor molar density: 0.44147 mol/m^3
.
Done Example
__________

Calling Low-Level interface through DLL

%% Calling low-level interface from MATLAB through shared library (DLL)
%%
%% Originally developed by Edo Macchi, modified by Ian Bell
%% 
%% December 2015

path_to_lib = '/work/CoolProp/libs/shared'; %specify path to coolprop shared library
path_to_include= '/work/CoolProp/include'; %specify path to coolprop's include folder

% Loading shared library
if ~libisloaded('coolprop') %checking whether library is already loaded
    addpath(path_to_lib)
    addpath(path_to_include)
    libname = 'libCoolProp' % OSX and linux
    if ispc
        libname = 'CoolProp'
    end
    loadlibrary(libname,'CoolPropLib.h','includepath',path_to_include,'alias','coolprop'); % loading library with alias coolprop
    disp('loaded CoolProp shared library.')
    disp('loaded these functions: ')
    libfunctions coolprop
end

buffer_size = 1000;
ierr = 0;
b = (1:1:buffer_size);
herr= char(b);

%Selecting backend and fluid
backend = 'BICUBIC&HEOS';
fluid = 'Water';
[handle, sh] = calllib('coolprop','AbstractState_factory',backend,fluid,ierr,herr,buffer_size);

length=100000;
input1 = linspace(700000.0,1500000.0,length)';
input2 = linspace(2.8e6,3.0e6,length);
[input_pair,sip] = calllib('coolprop','get_input_pair_index','HmassP_INPUTS');

tic;

%Creating input and output pointers
input1Ptr = libpointer('doublePtr',input1);
input2Ptr = libpointer('doublePtr',input2);
TPtr = libpointer('doublePtr',zeros(length,1));
pPtr = libpointer('doublePtr',zeros(length,1));
rhomolarPtr = libpointer('doublePtr',zeros(length,1));
hmolarPtr = libpointer('doublePtr',zeros(length,1));
smolarPtr = libpointer('doublePtr',zeros(length,1));

calllib('coolprop','AbstractState_update_and_common_out',handle,input_pair,input1Ptr,input2Ptr,length,TPtr,pPtr,rhomolarPtr,hmolarPtr,smolarPtr,ierr,herr,buffer_size);

dt = toc;

T=get(TPtr,'Value');
p=get(pPtr,'Value');
rhomolar=get(rhomolarPtr,'Value');
hmolar=get(hmolarPtr,'Value');
smolar=get(smolarPtr,'Value');

fprintf('%d us/call\n', (dt*1e6/length));

outputs=zeros(5,1);
%Choosing parameters to compute
[outputs(1,1), so1] = calllib('coolprop','get_param_index','T');
[outputs(2,1), so2] = calllib('coolprop','get_param_index','P');
[outputs(3,1), so3] = calllib('coolprop','get_param_index','Dmolar');
[outputs(4,1), so4] = calllib('coolprop','get_param_index','Hmolar');
[outputs(5,1), so5] = calllib('coolprop','get_param_index','Smolar');

%Creating ouput pointers
out1Ptr = libpointer('doublePtr',zeros(length,1));
out2Ptr = libpointer('doublePtr',zeros(length,1));
out3Ptr = libpointer('doublePtr',zeros(length,1));
out4Ptr = libpointer('doublePtr',zeros(length,1));
out5Ptr = libpointer('doublePtr',zeros(length,1));

tic;

calllib('coolprop','AbstractState_update_and_5_out',handle,input_pair,input1Ptr,input2Ptr,length,outputs,out1Ptr,out2Ptr,out3Ptr,out4Ptr,out5Ptr,ierr,herr,buffer_size);

dt=toc;

%Saving computed values to array
out1=get(out1Ptr,'Value');
out2=get(out2Ptr,'Value');
out3=get(out3Ptr,'Value');
out4=get(out4Ptr,'Value');
out5=get(out5Ptr,'Value');

fprintf('%d us/call\n', (dt*1e6/length));