Python is a very popular programming language now
widely used for data analysis and machine learning.
More than 100,000 Python libraries are available
that provide functions for plotting, numerical
methods, optimization, JSON parsing, and web
scraping.
We used the JSON library to develop a set of Python
classes and methods that can parse JSON files and
strings, exported by Cranium or Synapse, into
Python class instances. These classes make it very
easy to include physical property data and estimates
into your own Python projects.
For example, the Python code to the right used the MKS
Python Classes to process the data contained in a
JSON file into the histogram shown in the image below.
(Click
here
to download the Python code and data files discussed on this
page. Please see the code file for further instructions.)
Example Python Histogram Code
Importing Physical Property Values into Python (File Transfer)
Transferring physical property values from Cranium or Synapse
to a Python project can be easily done by using MKS JSON files.
These files can be generated by either the Basic or Professional
editions. The process takes three steps as shown to the right.
(Note that physical properties can also be transferred in a
dynamic manner by communicating with either a WebServer or
a Component edition of Cranium or Synapse. See
below
for documentation.)
Three Step Process
Compilation:
Cranium or Synapse is used to compile physical
property data and estimates
Export JSON
the Export functionality of these applications is then
used to generate a JSON formatted file containing these
data and estimates
Import:
the MKS Python Classes documented below are used to
parse the JSON source into a collection of Python
class instances.
Compiling Physical Property Data and Estimates
Very often you will need the physical properties of chemicals
and mixtures for your Python project. Our MKS Core Knowledge
Base may contain all the property values you need. If you need
to add new chemicals or new mixtures, you can use either the
Basic or Professional editions of both Cranium and Synapse
to add these values. Both editions enable you to estimate more
than 30 physical properties as functions of temperature,
pressure, and composition. (For example, the image below shows
both data (squares) and estimates (diamonds) for the liquid
density of tetramethylsilane as a function of temperature.
Documentation for adding physical property data and generating
physical property estimates can be found on the following
pages:
Exporting Physical Property Data and Estimates to a JSON File
Detailed documentation on exporting JSON files from Cranium
or Synapse can be found
here.
In summary:
Open the knowledge base containing the physical property
values you wish to transfer to your Python project.
Click
the left mouse button on the application's File menu and
select the Export Values command.
The application will activate the
here.
This dialog can generate input values for many
chemical engineering software programs.
Click the left mouse button on the "MKS JSON
File Format" item in the Output File Format
list. The dialog will display some documentation
about the format in its Format Information and
General Description windows.
Press the dialog's Export button.
The application will activate the
MKS JSON Export Dialog.
This dialog enables select the entities and
properties you wish to export. (Note that MKS JSON
files may contain a maximum of 100 entities.)
Press the Browse button and enter the name
of the export file in the displayed file
selection dialog.
Click the left mouse button on the Entity
Type control and select the "Chemical"
entry. The dialog will display the list of
chemicals in the current knowledge base
and their properties.
Click the left mouse button within the Entities
control on the names of those chemicals whose
properties you wish to export. (Note that MKS JSON
files may contain a maximum of 100 entities.)
Click the left mouse button within the Properties
control on the names of one or more properties whose
values you wish to export.
Select one or more status values from the Status
control. Typically you would select "Active" and/or
"Estimated".
Finally, press the Export button. The application will
compile your selected values and write them into a
JSON formatted file.
An example MKS JSON file is show to the right. The file is
structured around four main MKS objects:
request - entity - property - datum
The request is the overall JSON object which is sent to
and returned from the application. The request contains
one or more entities, e.g., chemicals, mixtures, techniques,
etc. Each entity contains one or more properties. Each
property contains one or more data objects. The use of these
objects within the MKS Python Objects module is discussed
in the next section.
Example MKS JSON Export File
MKS Python Classes
There are five MKS Python classes: 1) a top-level MKSApplication class; 2)
an MKSRequest class; 3) an MKSEntity class; 4) an MKSProperty class; 5)
an MKSDatum class. Together these classes enable you to parse physical
property values retrieved from either Cranium or Synapse into a highly
structured collection of Python instances.
MKSApplication Class
The MKSApplication class is a top-level class which provides
methods that can parse strings and files containing JSON formatted
information. Specifically, the class provides three main methods:
begins the parsing of the input string, which must be a
valid JSON string, into a collection of MKS class
instances.
reads the contents if the input file, which must contain a
valid JSON object, and then begins the parsing of the these
contents into a collection of MKS class instances.
sends the query to the MKS Web API for processing and then
begins the parsing of the returned response into a collection
of MKS class instances.
prints the values of its contained MKS class instances
on the current output window.
The code for the class's definition is shown to
the right.
MKSApplication Class
MKSRequest Class
The MKSRequest class is used to parse an input JSON string into
attribute values a list of MKSEntity instances.
The MKSRequest class's main attributes are:
application:
the instance of the MKSApplication that created this request
processor:
a string detailing the name and version of the MKS
Application, i.e., Cranium or Synapse, that generated this
request's values.
entities:
a list of MKSEntity instances.
date:
a string displaying the date and time at which this
request was processed.
The MKSRequest class provides two main methods:
continues the parsing of the input JSON string started by its
parent MKSApplication instance. This function is almost always
used internally, by an MKSApplication instance, and is thus
seldom used by the user.
prints the values of the MKSRequest's attributes
on the current output window.
The code for the class's definition is shown to
the right.
MKSRequest Class Definition
MKSEntity Class
The MKSEntity class is used to parse an input JSON string into
attribute values a list of MKSProperty instances.
The MKSEntity class's main attributes are:
entity_type:
a string specifying the entity's type, e.g., "Chemical",
"Mixture", "Reference".
identifier:
a string containing the entity's name.
properties:
a list of MKSProperty instances.
The MKSEntity class provides two main methods:
continues the parsing of the input JSON string started by its
parent MKSRequest instance. This function is almost always
used internally, by an MKSRequest instance, and is thus
seldom used by the user.
prints the values of the MKSEntity's attributes
on the current output window.
The code for the class's definition is shown to
the right.
MKSEntity Class Definition
MKSProperty Class
The MKSProperty class is used to parse an input JSON string into
attribute values a list of MKSDatum instances.
The MKSProperty class's main attributes are:
name:
a string containing the property's name.
status:
a string value equal to "Active", "Passive",
"Rejected", "Unknown".
component:
an integer corresponding to the index of a
mixture's component whose property this is.
The MKSProperty class provides two main methods:
continues the parsing of the input JSON string started by its
parent MKSEntity instance. This function is almost always
used internally, by an MKSEntity instance, and is thus
seldom used by the user.
prints the values of the MKSProperty's attributes
on the current output window.
The code for the class's definition is shown to
the right.
MKSProperty Class Definition
MKSDatum Class
The MKSDatum class is a large class used to parse an input
JSON string into many attribute values.
The MKSDatum class's main attributes are:
value:
a number or a string containing the datum's value.
value_accuracy:
a positive number representing the accuracy of the
datum's value.
value_units:
a string containing the units, if any, in which
the datum's value is being reported.
temperature:
a number representing the temperature at which
the datum's value is being reported.
temp_accuracy:
a positive number representing the accuracy of the
datum's temperature value.
temp_units:
a string containing the units in which
the datum's temperature is reported.
pressure:
a number representing the pressure at which
the datum's value is being reported.
pres_accuracy:
a positive number representing the accuracy of the
datum's pressure value.
pres_units:
a string containing the units in which
the datum's pressure is reported.
x_values:
a list of numbers representing the composition of each
mixture component at which the datum's value is being
reported.
x_accuracies:
a list of positive numbers representing the accuracy of
each datum composition value.
x_units:
a string containing the units in which the datum's
composition valuess are reported.
reference:
a string typically containing information about the
source of the datum's value.
comment:
a string typically containing details about the
datum's source and curation.
The MKSDatum class provides the following methods:
continues the parsing of the input JSON string started by its
parent MKSProperty instance. This function is almost always
used internally, by an MKSProperty instance, and is thus
seldom used by the user.
prints the values of the MKSProperty's attributes
on the current output window.
The MKSDatum class also uses several support functions for parsing
numbers and lists of numbers. The code for these support functions
are shown below. The code for the MKSDatum class definition is shown
to the right.
MKSDatum Support Functions
MKSDatum Class Definition
Example: Reading JSON from a File - General Properties
The code below reads the contents of a JSON formatted file containing
a selection of physical property data for several chemicals. The code
then uses the MKS Python Classes to parse these contents into an MKS
Object heirachy and then prints the results, as shown in the figure
to the right.
Example Code - General Properties
JSON File - General Properties
Python Output - General Properties
Example: Reading JSON from a File - Synonyms
The code below reads the contents of a JSON formatted file containing
the names and synonyms of several chemicals. The code then uses the
MKS Python Classes to parse these contents into an MKS Object heirachy
and then prints the results, as shown in the figure to the right.
Example Code - Synonyms
JSON File - Synonyms
Python Output - Synonyms
Importing Physical Property Values into Python (Dynamic Queries)
The MKS Python classes also enable to interact with either the
WebServer or Component edition of Cranium or Synapse. Such an
interaction enables you to create dynamic queries, retrieving
physical property data and estimates as needed in your Python
project. The process takes the three steps as shown to the
right.
(Note that physical properties can also be transferred in a static
manner by using either the Basic or Professional edition of
Cranium or Synapse. See
above
for documentation.)
Three Step Process
Query Preparation:
An MKS JSON Query is a JSON string that contains all the
entities, properties, and data you are requesting from
Cranium or Synapse. See
here
for documentation on how to create MKS JSON Queries.
(Note that an upcomming version of the MKS Python
Classes will make this process more Python-like.)
Process Query
the query is sent to either a WebServer edition, via
a web-based api, or a Component edition, via a COM
interface, for processing.
Query Import:
the MKS Python Classes documented above are used to
parse the JSON response into a collection of Python
class instances.
Example: Querying the MKS Web API - Boiling Points
The code below sends an MKS JSON Query to the MKS Web API for
processing. The query requests both a data value and an estimated
value for the boiling point of 1,2-Dichlorobenzene. Note that the
estimated value is a "New Estimate", i.e., it was generated on
demand when the query was processed.
Once the WebServer edition has processed the query, the response
is parsed using the MKS Python Classes into an MKS Object heirachy.
A printout of these objects is shown in the figure to the right.
Example Code - Boiling Points
Python Output - Boiling Points
Example: Querying the MKS Web API - Structure Entry
The code below sends an MKS JSON Query to the MKS Web API for
processing. The query requests the estimation of several properties
for a new chemical, i.e., a chemical that is not in the current
source knowledge base. Cranium and Synapse can estimate the
properties of this new chemical if they are given its molecular
structure. The query sends this structure to the API as a SMILES
string.
The WebServer edition will convert the SMILES string into a
molecular structure, dissect the structure into groups, and then use
group contribution and equation-based techniques to estimated the
requested physical properties. These values are then packaged into
a JSON string which is sent back to the Python function. The function
uses the MKS Python Classes to parse the JSON string into an MKS
Object heirachy. A printout of these objects is shown in the
figure to the right.
Example Code - SMILES Structure
Python Output - SMILES Structure
Example: Querying the MKS Web API - Mixture Properties
The code below sends an MKS JSON Query to the MKS Web API for
processing. The query requests the estimation of several properties
for a new mixture, i.e., a mixture that is not in the current
source knowledge base. Cranium and Synapse can estimate the
properties of this new mixture if they are given its components,
composition, and state variables. The code prepares an MKS JSON
query containing this information and sends it to the API.
The WebServer edition extract components, compositions, and state
variables from the MKS JSON query and then estimate the requested
physical properties. These estimated values are then packaged into
a JSON string which is sent back to the Python function. The function
uses the MKS Python Classes to parse the JSON string into an MKS
Object heirachy. A printout of these objects is shown in the
figure to the right.
Example Code - Mixture Properties
Python Output - Mixture Properties
Contact Us
Please
contact us
if you have any questions or suggestions about the MKS Python Classes, have questions
about using the these classes within your own code, or have any other
questions about physical properties.