Exporting Physical Properties to MATLAB

MATLAB is a numeric computing environment that can be used to analyze many chemical products and processes. Cranium and Synapse can generate MATLAB script files that contain the physical property values needed for these analyses. We call these files MKS MATLAB Properties Files.

For example, the plot to the right was generated by MATLAB from a property file containing vapor pressure data and estimates for isobutyl acetate. The file was generated by Cranium, loaded and run in MATLAB, and then plotted using MATLAB functions. (You can also download the properties file from a link in the Examples Section below.)

MKS MATLAB Property File

MKS uses five Library Objects, detailed below, to exchange information with other programming languages. These MKS Library Object classes are arranged in the following hierarchy:

application - request - entity - property - datum

(More information about MKS MATLAB Classes are shown below. You can also click here to download a ZIP file containing these class definitions.)

An MKS MATLAB Properties File contains instantiations of these objects. (The application object is used to generate the file and is thus not included in the file's contents.) For example, the file shown below, contains physical property data and estimates for levulinic acid, a chemical that is being researched as a potential platform chemical for a large range of biobased products. Some of the key parts of the file are described below.

Lines 006 through 011: The top-level MKSRequest object is created and its attributes are assigned. The request object will be used as a container to store entity objects.

Lines 014 through 016: The first, and only in this example, MKSEntity object is created.

Lines 019 through 023: The first of many MKSProperty objects are created and its attributes assigned. Note that on line 020, the property's status is assigned a value of "Active". This means the property object contains data values.

Lines 052 through 056: The MKSProperty object for the critical temperature is created and its attributes assigned. Note that on line 053, the property's status is assigned a value of "Estimated". This means the property object contains values that were calculated using Cranium's or Synapse's estimation techniques.

Lines 058 through 063: An MKSDatum object is created to hold the value for the chemical's estimated critical temperature of 722.24 K (lines 059 and 060). Note that each datum object also contains values for a reference and a comment.

MKS MATLAB Properties File
Generating Property Files Using the MKS Online Structure Editor

To generate an MKS MATLAB Properties File for a desired chemical, begin by drawing the chemical's structure in the editor to the right. (Press the editor's demo button to view a short video explaining the editor's operation.)

Once you have drawn your structure, press the 'Generate' button. The webpage packages the structure into a JSON request and sends the request to a WebServer Edition of Cranium running in the cloud. Cranium then estimates about 30 physical properties, packages these estimates into a JSON response, and sends the response back to this webpage for display.

For temperature dependent properties, Cranium selects a range of temperatures between the melting point and boiling point or the boiling point and the critical temperature as appropriate.

Your browser does not support the HTML canvas tag

Use the 'download' button the text header below to save a MATLAB model file. If you need to process a number of chemicals, you might want to download the Basic Edition of Cranium or Synapse. Both applications provide more functionality than that found on this webpage. (For example, click here to view documentation on the MATLAB export dialog.)

Please contact us if you encounter any problems or have any comments or suggestions.

Exported MATLAB File

To run this properties file within MATLAB you will need to have the MKS MATLAB classes definitions. You can click here to download a ZIP file containing these class definitions.

To experiment with this new properties file, you might want to follow the procedure described in Example 03, the New Chemical Structure Property Estimates example. Just subsitute this new, downloaded file for the levulinic acid properties file.

Generating Property Files Using Synapse or Cranium

Both the Basic and Professional Editions of Cranium or Synapse can generate MKS MATLAB Properties Files. (Click here to download a free copy of the Basic Edition of Cranium.)

Once the application is started, open a knowledge base containing the chemicals whose physical properties you wish to export into MATLAB. Once the knowledge base is open, click the left mouse button on the File menu's Export Values command as show in the image to the right.

The application will activate the KB Export Dialog. This dialog lists the various formats into which Cranium and Synapse can write physical property values.

1
Select the MATLAB MKS Classes Format from the dialog's Output File Format list.
2
Press the dialog's Export button. The application will active the MATLAB Properties File Creation dialog.
1
Press the dialog's Browse button and enter the desired name of the output file. Note that MATLAB filenames may not contain spaces.
2
Select one or more chemicals from the list of Chemical Entities. In this example we selected one chemical: isobutyl acetate.
3
Select one or more properties from the list of Properties. In this example we selected only one property: vapor pressure.
4
In additon to the properties file, MATLAB needs the class definition files for the MKS Library Objects. (See the Class Definitions below for details.) You many uncheck this option if you already have copies of the class definition files.
5
Select the status values for the properties being exported. You can select to export data values, estimated values, and newly estimated values. At least one of these status values must be selected.
6
Finally, press the dialog's Export button. The application will estimate the selected physical properties for each of the selected chemicals. These estimates will then be formatted and written into the selected MKS MATLAB Properties file.
Examples
Important: Before you run the code for the following examples, you must load the MKS MATLAB class definitions. Click here to download a ZIP file containing all MKS class definition files or see the Class Definitions section below for the links to download individual files files.
Example 01: Vapor Pressure, Estimates and Data vs Temperature

For this example, we used the Professional Edition of Cranium to retrieve data and generate estimates of the vapor pressure for isobutyl acetate. Estimates were generated at a selection of temperatures between the chemical's melting point and boiling point. Cranium's Export File command, see below, was used to create the MKS MATLAB properties file.

Once you have loaded the class definitions, you can load and run the "VaporPressures.m" properties file listed to the right. Executing the file will create an MKSRequest object, assigned to the 'mksReq' variable, that contains the file's entities, properties, and data.

Finally load the "XYPlotProp.m" file to the right, and run the command shown, to generate the XY graph shown to the right.

Steps to Run the Vapor Pressure Example
Step Description Task
1 Download and load MKS Class definitions (zip file) download
2 Download and Run the vapor pressures properties file download
3 Download the XYPlotProp.m script file download
4 Run: XYPlotProp(mksReq, "Vapor Pressure, Liquid - f(T)")
Example 02: Boiling Point, Estimates vs Data Example

For this example, we used the Professional Edition of Cranium to compare boiling point estimates against experimental data for 1,483 chemicals. Cranium's Export File command, see below, was used to create the MKS MATLAB properties file.

Once you have loaded the class definitions, you can load and run the "BoilingPoints.m" properties file listed to the right. Executing the file will create an MKSRequest object, assigned to the 'mksReq' variable, that contains the file's entities, properties, and data.

Finally load the "XYPlotEsts.m" file to the right, and run the command shown, to generate the XY graph shown to the right.

Steps to Run the Boiling Points Example
Step Description Task
1 Download and load MKS Class definitions (zip file) download
2 Download and Run the boiling points properties file download
3 Download the XYPlotEsts.m script file download
4 Run: XYPlotEsts(mksReq, "Boiling Point")
Example 03: New Chemical Structure Property Estimates

For this example, we used the MKS Online Structure Editor, see below, and the WebServer Edition of Cranium to generate estimated properties for levulinic acid, a biobased molecule currently being investigated as a new platform chemical.

Once you have loaded the class definitions, you can load and run the "LevulinicAcid.m" properties file listed below. Executing the file will create an MKSRequest object, assigned to the 'mksReq' variable, that contains the file's entity, properties, and data.

Finally load the "TabulateProps.m" file, and run the command shown, to generate a table of those physical properties estimated by Cranium.

Steps to Run the Structure Editor Example
Step Description Task
1 Download and load MKS Class definitions (zip file) download
2 Download and Run the levulinic acid properties file download
3 Download the TabulateProps.m script file download
4 Run: TabulateProps(mksReq)
MKS MATLAB Class Definitions
The five MKS MATLAB Classes, and an additional MKSBase base class, are documented in this section. You can download each class definition file using the links in each section or click here to download a ZIP file containing all files.
MKSApplication Class (download)
a top-level class used to parse input into an MKSRequest object. Currently, the only type of input that can be parsed is an MKS formatted JSON object. (See lines 019 through 033.) This JSON object can be:
  • a string (lines 037 to 042)
  • read from a file (lines 045 to 051)
  • retrieved from an online query (lines 054 to 064).
MKSApplication Class Definition
MKSRequest Class (download)

a top-level class used to contain, organize, and manage entities, e.g., chemicals, mixtures, or references.

  • The class's entities attribute (line 011) stores an array of entity instances.
  • The class's processor, fileName, version, date, and type attributes (lines 012 through 016) store information about the source of the contained physical properties.
  • The processJson method (lines 022 through 043) is used to parse a JSON structure for attribute values.
MKSRequest Class Definition
MKSEntity Class (download)

a class used to store and manipulate information on the basic entities exported by Cranium and Synapse. These entities include chemicals, mixtures, techniques, and references.

  • props (line 011) is an array containing MKSProperty objects.
  • identifier (line 012) is a string containing the entity's name.
  • entityType (line 013) is a string indicating the entity's type. The attribute can have values of "Chemical", "Mixture", or "Reference".
  • The processJson method (lines 020 through 038) is used to parse a JSON structure for attribute values.
MKSEntity Class Definition
MKSProperty Class (download)

a class used to store information about an exported physical property.

  • The data attribute stores an array of MKSDatum objects.
  • The component attribute is used for storing certain types of mixture data.
  • The dataType is currently not used.
  • The status attribute can be "Active" or "Estimated" indicating whether the values within the data array are experimental values or estimated values.
  • The processJson method (lines 020 through 038) is used to parse a JSON structure for attribute values.
MKSProperty Class Definition
MKSDatum Class (download)

a large class used to store final physical property data and estimates. This single class is used for all property types: constant properties; temperature dependent properties; temperature and pressure depdendent properties; and mixture properties.

  • The valueAccuracy, value, and valueUnits attributes (lines 009 through 011) store the physical property value, accuracy, and units of measure. All valid datum objects will have a value for the value attribute.
  • The tempAccuracy, tempValue, and tempUnits attributes (lines 013 through 015) store the temperature's value, accuracy, and units of measure. Only data whose property is temperature dependent will have values for these attributes.
  • The presAccuracy, presValue, and presUnits attributes (lines 017 through 019) store the pressure's value, accuracy, and units of measure. Only data whose property is pressure dependent will have values for these attributes.
  • The xAccuracies, xValues, and xUnits attributes (lines 021 through 023) store the composition's value, accuracy, and units of measure. Only data whose property is composition dependent will have values for these attributes.
  • The errorString attribute (line 025) stores any error messages that are generated during the processing of an MKSDatum object.
  • The reference and comments attributes (lines 026 through 027) store information on the source of the datum.
  • The processJson method (lines 034 through 065) is used to parse a JSON structure for attribute values.
MKSDatum Class Definition
MKSBase Class (download)

a class from which all other MKS classes inherit. The MKS Base class is used to provide some basic functions for parsing values extracted from JSON structures.

  • The MKSBase class does not contain any attributes.
  • The getJsonDbl function (lines 011 through 021) retrieves a field value from a JSON structure as a string and then parses that string into a double.
  • The getJsonStr function (lines 024 through 033) retrieves a field value from a JSON structure as a string.
  • The getJsonDArray function (lines 036 through 046) retrieves a field value from a JSON structure as a string and then parses that string into an array of numbers.
MKSBase Class Definition
How It Works

The above structure editor converts the input molecular structure into a molfile string. This string is then combined with a request for a MATLAB model file and sent to a version of Cranium, WebServer Edition running on a Microsoft Azure virtual machine. Cranium processes the molfile, extracting substructures for group contribution techniques, and estimates the physical properties needed for the input file. The resulting input file is then sent back to this webpage for display.

Click here to learn more about how you can use Cranium Web Server to distribute your company's physical property data, estimates, and knowledge throughout your organization or contact us for further details.