pyILT2 package API

This package contains object classes and functions to access the Ionic Liquids Database - ILThermo (v2.0) from NIST (Standard Reference Database #147) within Python.

Concept

The pyilt2.query() function uses the requests module to carry out the query on the NIST server. The resulting JSON object is then decoded to a Python dictionary (resDict), which serves as input to create a pyilt2.result object. The result object creates and stores for each hit of the query a pyilt2.reference object, which offers the method pyilt2.reference.get() to acquire the full data (setDict) as a pyilt2.dataset object.

Variables

To handle the "problem" with expressing the physical property in a programmatic sense, there are following module variables accessible:

pyilt2.prop2abr

A dictionary with long description as key and abbreviation as value, like:

{'Activity': 'a',
 'Adiabatic compressibility': 'kS',
 'Apparent enthalpy': 'Hap',
 'Apparent molar heat capacity': 'capm',
 ...}

pyilt2.abr2prop

Obvious the reversed version of prop2abr ;)

pyilt2.properties

Deprecated since version 0.9.8: Use abr2prop instead!

A dictionary where the key is an abbreviation and the value is a list containing the NIST hash and a long description of the respective physical property:

{"a" :     ["xuYB", "Activity"],
 "phi" :   ["GVwU", "Osmotic coefficient"],
 "Xpeq" :  ["DzMB", "Composition at phase equilibrium"],
 "Xeut"  : ["yfBw", "Eutectic composition"],
 ...}

pyilt2.abr2key

This modified dictionary provides the translation between the abbreviation (dict's key) of a physical property and the key (dict's value) as used in the http search request. Because it already happened that the keys have changed, we get those just in time of first usage by a http request. It looks like:

{'Dself': 'wCtj',
 'Dterm': 'LZlp',
 'Dtrac': 'QJLO',
...}

If you don't intend to write your own query() function, there is no need to access this variable.

Classes & Functions

pyilt2.query(comp='', numOfComp=0, year='', author='', keywords='', prop='')

Starts a query on the Ionic Liquids Database from NIST.

Each web form field is represented by a keyword argument. To specify the physical property you have to use the respective abbreviation. The function returns a pyilt2.result object, whether or not the query makes a hit.

Parameters:

• comp (str) -- Chemical formula (case-sensitive), CAS registry number, or name (part or full)
• numOfComp (int) -- Number of mixture components. Default '0' means any number.
• year (str) -- Publication year
• author (str) -- Author's last name
• keywords (str) -- Keyword(s)
• prop -- Physical property by abbreviation. Default '' means unspecified.

Returns:

result object

Return type:

pyilt2.result

Raises:

• pyilt2.propertyError -- if the abbreviation for physical property is invalid
• pyilt2.queryError -- if the database returns an Error on a query

class pyilt2.result(resDict)

Class to store query results.

The result object is created by the pyilt2.query() function. Each hit of the query is represented by a pyilt2.reference object. The build-in function len() returns the number of hits, respectively references stored in the result object. It is iterable, so you can simply iterate over references, like:

# iterate over references
for reference in result:
    ...

# One can also access the individual references as items:
first_reference = result[0]
last_reference = result[-1]

Parameters:resDict (dict) -- decoded JSON object

resDict = None

original JSON object from NIST server decoded to a Python dictionary (example)

class pyilt2.reference(refDict)

Class to store a reference.

The reference objects will be created while initiating pyilt2.result object. It contains just a few meta data. To acquire the full data set, it offers the pyilt2.reference.get() method.

Parameters:refDict (dict) -- part of resDict

numOfComp = None

number of components as integer

listOfComp = None

names of component names as list of strings

setid

NIST setid (hash) as used as input for pyilt2.dataset

ref

Reference as in the result table on the website, like Muster et al. (2018), Muster and Mann (2018) or Muster (2018a).

sref

Short reference, like MusterEtal2018, MusterMann2018 or Muster2018a.

Note

We are very sure about this reference (as derived from ref) is unique within the database. Therefore it can be used as an identifier for a source (publication) over multiple requests, for example as BibTeX reference.

year

year of publication as integer

author

1st author’s last name

prop

physical property

np

Number of data points

get()

Returns the full data according to this reference.

Returns:Dataset object Return type:pyilt2.dataset

class pyilt2.dataset(setid)

Class to request & store the full data set.

The dataset object is created by the pyilt2.reference.get() method.

Parameters:setid (str) -- NIST setid (hash) Raises:pyilt2.setIdError -- if setid is invalid

setid = None

NIST setid (hash) of this data set

setDict = None

original JSON object from NIST server decoded to a Python dictionary (example)

data = None

numpy.ndarray containing the data points

headerList = None

List containing the description for each column of the data set

physProps = None

List containing the physical property for each column of the data set

physUnits = None

List containing the physical units for each column of the data set

phases = None

List containing the phase information (if it make sense) for each column of the data set

shape

Tuple of data array dimensions.

np

Number of data points

listOfComp

List of component names as strings.

numOfComp

Number of components as integer.

write(filename, fmt='%+1.8e', header=None)

Writes the data set to a text file.

Parameters:

• filename (str) -- output file name
• fmt (str) -- str or sequence of strs, (see numpy.savetxt doc)
• header (str) -- String that will be written at the beginning of the file. (default from headerList)

exception pyilt2.queryError(note)

Exception if the database returns an Error on a query.

exception pyilt2.propertyError(prop)

Exception if an invalid abbreviation (for physical property) is defined.

exception pyilt2.setIdError(setid)

Exception if the set NIST setid (hash) is invalid.

Because the NIST web server still returns a HTTP status code 200, even if the set id is invalid (I would expect here a 404er!), this exception class was introduced.