Skip to content

SBTL media creator


The spline-based table-lookup media creator (SBTL) presents an alternative way to implement a media to that of a full or short Helmholtz two-phase media implementation.


  • The SBTL media is based on coefficient-driven look-up tables, which describe the media properties.
  • It is much faster compared to the Helmholtz approach which calculates (interpolates) the media properties.
  • Increased speed is achieved by fast access to pre-calculated properties defined in the spline coefficient tables.
  • Spline coefficient tables are loaded as external objects at the initialization of a simulation.
  • Evaluation of the splines, function inverses and derivatives are carried out in external C functions for computational speed.


  • Generation of spline-based table-lookup media has to be done in advance and it takes some time.
  • Generation time depends on the data grid density and range, which should be chosen to cover the operating region required by the simulation.
  • A two-phase media takes approximately 30 minutes on a common desktop computer (Intel Core i7 CPU @ 2GHz, 8GB RAM) with a sufficient grid size, and has to be done once for each media of interest.
  • The generated media, depending on range and fidelity, can occupy a large amount of storage space.

Before we start the tutorial🔗

What are we building?

In this application, we will show how to create a two-phase R134a SBTL media, how to implement it into Modelon Impact, and how to run it within a Heat-exchanger example. The resulting calculation time will be compared vs. the short Helmholtz media implementation.


  1. Tutorial requires a desktop Modelon Impact Pro installation.
  2. Basic Python experience.

You will learn how to:

  • Installation
  • Generate & compare SBTL media
  • Import and run in Modelon Impact

Release notes

Click here to see Release notes.


The spline-based table-lookup creator uses a Jupyter notebook for running and generating all relevant data and comparison plots for your media.

External media database installation🔗

Either the CoolProp media database and interface needs to be installed, and REFPROP needs to be installed if you wish to use their database. One or the other can be used as an input for SBTL media creation.


    1. Visit REFPROP 10.0 homepage, download and install the media database into c:\Program Files (x86)\REFPROP\.


    You will need to obtain a valid license to install REFPROP 10.0.

  • "CoolProp"

    1. CoolProp 6.3.0 will be installed automatically as a part of the following notebook installation.


    CoolProp can be installed using python.exe -m pip install CoolProp==6.3.0 to chosen Python installation.

Installation through miniconda🔗

This section can be skipped if you are using the python installation that is included within Modelon Impact.

The following code needs to be run in the miniconda command prompt:

conda config --append channels conda-forge conda install numpy conda install scipy conda install matplotlib conda install ipympl conda install jupyter conda install ipywidgets conda install setuptools conda install -c conda-forge coolprop

Jupyter Notebook installation🔗

The installation of Jupyter is described within JupyterLab: Installation.

  1. Go through all installation steps and make sure the JupyterLab is up and running within C:/Jupyter.

  2. Create SBTL folder within C:\Jupyter.

  3. Go to Modelon Impact installation folder and find a SBTL folder within resources of Modelon Base library (e.g. <modelon_impact_installation_folder>\modelica-dist\Modelon X.X\Resources\Python\SBTL Media Creator\SBTL Media Creator X.X). This folder includes 3 files as shown below.

  1. Copy these files into C:/Jupyter and unpack into a folder with the same name.

  1. Create a media directory: e.g. C:\SBTL_MEDIA and copy there SBTLMediaModelicaPackage folder.

  2. All is now prepared for opening and running the notebook SBTLMediaCreator.ipynb within JupyterLab.

Generate & Compare🔗

The notebook includes a media creation workflow. The workflow includes all major step:

  • loading of media databases (REFPROP, CoolProp)
  • generating media data
  • calculating spline coefficients
  • comparing generated spline vs. original media

Start SBTL workflow🔗

  1. Open SBTLMediaCreator.ipynb within JupyterLab.


When using miniconda, after launching the notebook, the following needs to be run to install the compiled python code

import sys !{sys.executable} -m easy_install "C:\SBTL\SBTL_media_creator-X.X-py3.7.egg"


When using the Modelon Impact installation, the SBTL .egg file needs to be appended to the path with import sys sys.path.append("C:\SBTL\SBTL_media_creator-X.X-py3.7.egg")

  1. Select the first cell and click on the run button (or press Shif+Enter).

Importing Python extensions🔗

Run the import cell, which imports the media creator scripts ('SBTL_media_creator-X.X-py3.7.egg') compiled within an *.egg file and other necessary extensions.


  1. The interactive inputs chapter will create an input widget shown below.


Once the widget is configured, manually move to the cell below. If you run the widget cell, it will re-load up the default values.

  1. It is important to update 4 input fields at the top based on the Modelon Impact version and installation path.

    Path to Modelon Base Library🔗

    This line should include path to Modelon Base library from the Modelon Impact installation (e.g. <modelon_impact_installation_folder>\modelica-dist\Modelon X.X).

    Path to Vapor Cycle Library🔗

    This line should include the path to Vapor Cycle library from the Modelon Impact installation (e.g. <modelon_impact_installation_folder>\modelica-dist\VaporCycle X.X).

    Output path directory🔗

    Output path, where the plots generated are stored (e.g. C:\SBTL_MEDIA).

    Path to Modelica media package🔗

    Path to the SBTL Media Modelica template package, where the spline-based table-lookup media will be stored.


    The path should include SBTLMediaModelicaPackage folder name! (e.g. C:\SBTL_MEDIA\SBTLMediaModelicaPackage).


    Paths to libraries are important for the final comparison of the created media and reference (CoolProp or REFPROP).


    Backend controls which media database will be used - REFPROP or COOLPROP.

    Reference state🔗

    It defines which reference state for the specific enthalpy and specific entropy will be used. It is usable with COOLPROP only, since REFPROP reference state is set in the FLD-file.


    The user selects available fluid from drop down list. This media will be generated.

    Interpolation method🔗

    A spline interpolation method with the Cubic interpolation method is strongly recommended for its stability.

    Raw data points🔗

    This field decides how many data points will be generated in the square raw data grid. The recommended range is 600-1000. Higher values lead to better accuracy, but long generation times.

    Enthalpy and Pressure grid size🔗

    The number defines a grid size for the media coefficients. The recommended minimum value is 200. Higher sizes lead to better accuracy but long generation times.

    Boundary conditions🔗

    These input fields include minimum and maximum values for the generated media.

    • p_min - Minimum pressure in Pa
    • p_max - Maximum pressure in Pa
    • h_min - Minimum specific enthalpy in J/kg
    • h_max - Maximum specific enthalpy in J/kg


    This data should be aligned with the tabular data from CoolProp or REFPROP. The ranges will be checked later in the notebook.


    When specifying the grid, a few criteria must be met - The critical point must be within the limits of the grid - The minimum specific enthalpy must be lower than the liquid enthalpy at minimum pressure - The maximum specific enthalpy must be higher than the vapor enthalpy at minimum pressure - If the regtangluar grid expands into the solid region, the values will be extrapolated. This will cause the verification step to fail simulation with REFPROP/COOLPROP, but the medium will still work.

    Reset variables and outputs🔗

    Use this button to re-start the generator and all outputs. This can be also done from the menu Kernel > Restart Kernel and clear all outputs. It is recommended to use this button, when changing e.g. grid, min, max, etc.

  2. Save settings by running the relevant cell.

  3. Finally, run the cells setting up the backend.

The text output should confirm, that the backend has been successfully found.

Data generation🔗

This is the most time consuming part of the media generator. It typically takes 10+ minutes (based on a selected number of points and grid size).

The media backend (CoolProp or REFPROP) is called to get 3 grids:

  • Pressure, Temperature
  • Pressure, Enthalpy
  • Density, Temperature

These are used to compute the following properties:

  • Density
  • Temperature
  • Pressure
  • Specific Enthalpy
  • Specific Entropy
  • Thermal Conductivity
  • Dynamic Viscosity
  • Vapor Quality
  • Specific Heat Capacity at Constant Pressure
  • Specific Heat Capacity at Constant Volume

Follow the instructions provided within the notebook. Each step is described and plots for all important variables.

Find below an example of Temperature vs. Density plot.


Expected execution time for all cells in this section is at least 10 minutes depending on selected grid sizes.

Coefficients generation🔗

This part generates 1D and 2D spline coefficients interpolating all generated media table data.

Editing Modelica package🔗

This cell updates the Modelica package by moving the coefficient files created in the medium package data directory (e.g. C:\SBTL_MEDIA\SBTLMediaModelicaPackage). It then updates the external medium wrapper, the Modelica data file, and the validation experiment model.

Run in a model🔗

This chapter shows how to implement generated spline-based table-lookup media into one of the refrigeration model examples which is part of the Modelon Vapor Cycle Library.

What model to take?🔗

VaporCycle.Experiments.AirConditioning refrigeration cycle is an ideal example for demonstrating the spline-based table-lookup media implementation and advantages. The example uses R-134a 2-phase Helmholtz media. We will replace it with a R134a spline-based table-lookup implementation.


You need to have Modelon Impact Pro installed, including Modelon Library Suite. Contact Modelon sales to get the Pro version.

Loading spline-based table-lookup media package into Modelon Impact🔗

  1. Copy whole C:/SBTL/SBTLMediaModelicaPackage folder in C:/Users/<user_name>/impact/libraries. This will make SBTL package available within Modelon Impact Global Libraries.

  2. Open Modelon Impact.

  3. Create a new workspace called sbtl.

  4. Check that the SBTLMediaModelicaPackage package is available within the Global Libraries.

Running the short Helmholtz implementation model🔗

  1. Duplicate VaporCycle.Experiments.AirConditioning into the workspace.

  2. Run the AirConditioning model and note the simulation time.

  3. The simulation time should be approximately 100sec depending on the used computer.


The simulation time can be found within results simulation log.


Running the table-based model🔗

  1. Duplicate AirConditioning and rename it to AirConditioning_sbtl_R134a. The spline-based table-lookup media will be added into this model.

  2. Select one of the pipes and update medium inside, using Medium choice to SBTLMediaModelicaPackage.R134a.


Start typing SBTLMediaModel... into the box and a filter narrowing down the selection will be used.

  1. Propagate this media into whole model.

  2. Run the model and note the simulation time.

  3. The simulation time should be less than 50sec, meaning that the spline-based table-lookup media model runs ~2 times faster compared to the Helmholtz media!


Download the latest version of the media creator from here.