ornl-wasp 4.2.0

Workbench Analysis Sequence Processor 4.2.0

Wasp Python Interfaces (WaspPy)

WaspPy provides a python interface for utilizing WASP's parsing and validation functionality. The primary design consideration is to enable access to data represented in SON, DDI, EDDI, HIT, and HALITE formats.

WaspPy places an emphasis on client convenience and provides overloading of the ".", dot operator. This is intended to allow a client to interact with their input with calls of the following form, doc.subnode1.subnode2, where doc is the object containing the parsed input and subnode* are branches of the parse tree defined in the schema.

WaspPy can be generated by adding the -Dwasp_ENABLE_SWIG=ON flag to the existing usable configuration script, i.e

Requirements

In addition to standard wasp requirements:

• Swig-4.1.1 is additionally required.
• Python-3.8 or later is required in lieu of python 2.7

Code Configuration and Compilation

#!/bin/bash
# Linux bash file example
cmake \
 -D CMAKE_BUILD_TYPE:STRING=RELEASE \
 -D wasp_ENABLE_ALL_PACKAGES:BOOL=ON \
 -D wasp_ENABLE_TESTS:BOOL=ON \
 -D wasp_ENABLE_SWIG=ON \ #Added to build the python wrappers
 -D CMAKE_INSTALL_PREFIX=`pwd`/install \
 -G "Unix Makefiles" \
 ~/wasp

Example

WASP supports structured and definition-driven syntaxes. Structured syntaxes (SON, HIT), do not require an input schema to be brought into memory. Definition-driven syntaxes (DDI, EDDI) require an input schema to construct the hierarchy of the desired parse tree. The following example illustrates how to bring input data into a program data structure using structured and definition-driven syntax.

Problem Description

The following fictional application is a general chemistry code describing salts and property interpolation. Specifically, the input is composed of a collection of salts and series of temperatures at which to query salt density.

The input schema that describes the input hierarchy and parameter constraint is below. A legal input follows and depicts 2 salts, LiF and NaF, and temperatures queries at 1100, 1200, 1300, 1400:

salts {
    % Favorite salt
    salt(LiF) {
        MeltTemp : 1121.2
        MolecularWeight : 25.9394
        BoilTemp : 2512
        Density
        {
            A : 2.37
            B : 5.0e-4
            MinTemp : 1123.6
            MaxTemp : 1367.5
        }
    }
    salt(NaF) {
        MolecularWeight : 41.9882
        MeltTemp : 1268
        BoilTemp : 1978
        Density
        {
            A : 2.76
            B : 6.36e-4
            MinTemp : 1273
            MaxTemp : 1373
        }
    }
}
queries {
    temperatures = [1100 1200 1300 1400]
}

Python program

from wasp import *
import math

class LinearModel:
    ''' _b*x + _c*y = _a '''
    def __init__(self, params):
        self._a = 0.0
        self._b = 1.0
        self._c = 1.0
        self._minT = math.inf
        self._maxT = -math.inf

        for it in params:
            if it.name() == "MinTemp":
                self._maxT = float(it)
            elif it.name() == "MaxTemp":
                self._minT = float(it)
            elif it.name() == "A":
                self._a = float(it)
            elif it.name() == "B":
                self._b = float(it)
            elif it.name() == "C":
                self._c = float(it)

    def get_y(self, x: float) -> "float":
        if self._c == 0.0:
            return math.inf

        return (self._a - (self._b * x)) / self._c

class Salt:
    def __init__(self,params):
        self._name = ""
        self._molew = 0.0
        self._meltT = 0.0
        self._boilT = 0.0
        self._density: LinearModel

        # Loop over salt parameters
        for it in params:
            if it.name() == "id":
                self._name = str(it)
            elif it.name() == "MolecularWeight":
                self._molew = float(it)
            elif it.name() == "MeltTemp":
                self._meltT = float(it)
            elif it.name() == "BoilTemp":
                self._boilT = float(it)
            elif it.name() == "Density":
                self._density = LinearModel(it)

    def density(self,T: float) -> "float":
        return self._density.get_y(T)

if __name__ == '__main__':
    import sys
    schemapath = "path/to/application/schema.sch or schema data"
    input_file = sys.argv[1]
    interpreter = Interpreter(Syntax.SON, schema=schemapath, path=input_file)

    errors = interpreter.errors()
    if errors:
        print ("\n".join(errors))
        sys.exit(1)
    
    document = interpreter.root()

    # Obtain required queries parameter
    queries = document.queries

    # Obtain required salts
    salts = []
    for component in document.salts.salt:
        salts.append(Salt(component))

    # Obtain each salt's melt temperature value
    for v in document.salts.salt.MeltTemp.value:
        # Print salt's id (located at ../../id of value node) and melt temperature
        print ("MeltTemp of", str(v.parent().parent().id), "is", float(v))

    # Obtain query temperatures
    temperatures = []
    for t in queries.temperatures.value:
        temperatures.append(float(t))

    # Evaluate salt density for each temperature
    for s in salts:
        for t in temperatures:
            print ("Salt", s._name, "density at",t, "is", s.density(t))
     

When executing the above program and providing the given input you can expect the following output:

MeltTemp of LiF is 1121.2
MeltTemp of NaF is 1268.0
Salt LiF density at 1100.0 is 1.82
Salt LiF density at 1200.0 is 1.77
Salt LiF density at 1300.0 is 1.7200000000000002
Salt LiF density at 1400.0 is 1.67
Salt NaF density at 1100.0 is 2.0603999999999996
Salt NaF density at 1200.0 is 1.9968
Salt NaF density at 1300.0 is 1.9331999999999998
Salt NaF density at 1400.0 is 1.8695999999999997

If an input error is encountered, as defined in the input schema, the program will emit a user-friendly diagnostic and exit. For example, if a MaxTemp value violates the MinTemp value constraint the following diagnostic is emitted.

line:12 column:29 - Validation Error: MaxTemp value "1367.5" is less than or equal to the allowed minimum exclusive value of "1523.6" from "../../MinTemp/value"

Accessors

The dot operator provides the ability to navigate the hierarchy of the parse tree given the name of the subcomponents. When a subcomponent name conflicts with a Python reserved keyword the bracket operator [] can be used.

Syntaxes

The syntax can be specified using the Syntax.X where X is one of HIT, SON, DDI, and EDDI.

For example, the input above is equivalent to the followiing HIT-formatted input and will produce the same out with only changing the one line:

- interpreter = Interpreter(Syntax.SON, schema=schemapath, path=input_file)
+ interpreter = Interpreter(Syntax.HIT, schema=schemapath, path=input_file)
...

[salts]
    # Favorite salt
    [salt]
        id = LiF
        MeltTemp = 1121.2
        MolecularWeight = 25.9394
        BoilTemp = 2512
        [Density]
            A = 2.37
            B = 5.0e-4
            MinTemp = 1123.6
            MaxTemp = 1367.5
        []
    []
    [salt]
        id = NaF
        MolecularWeight = 41.9882
        MeltTemp = 1268
        BoilTemp = 1978
        [Density]
            A = 2.76
            B = 6.36e-4
            MinTemp = 1273
            MaxTemp = 1373
        []
    []
[]
[queries]
    temperatures = '1100 1200 1300 1400'
[]

Input Schema

salts{
    Description = "The collection of salts in the system"
    MinOccurs = 1
    MaxOccurs = 1

    salt{
        MinOccurs = 1
        MaxOccurs = NoLimit
        id{
            MinOccurs = 1
            MaxOccurs = 1
            ValEnums = [LiF NaF CaF2 NH4F NaCl]
        }
        BoilTemp{
            MinOccurs = 1
            MaxOccurs = 1
            value{
                MinOccurs = 1
                MaxOccurs = 1
                ValType   = Real
            } % end value
        } % end BoilTemp

        Density{
            MinOccurs = 1
            MaxOccurs = 1
            A{
                MinOccurs = 0
                MaxOccurs = 1
                value{
                    MinOccurs = 1
                    MaxOccurs = 1
                    ValType   = Real
                } % end value
            } % end A

            B{
                MinOccurs = 0
                MaxOccurs = 1
                value{
                    MinOccurs = 1
                    MaxOccurs = 1
                    ValType   = Real
                    MinValInc = 0
                } % end value
            } % end B

            MaxTemp{
                MinOccurs = 0
                MaxOccurs = 1
                value{
                    MinOccurs = 1
                    MaxOccurs = 1
                    ValType   = Real 
                    MinValExc = "../../MinTemp/value"
                } % end value
            } % end MaxTemp

            MinTemp{
                MinOccurs = 0
                MaxOccurs = 1
                value{
                    MinOccurs = 1
                    MaxOccurs = 1
                    ValType   = Real
                    MinValExc = 0
                } % end value
            } % end MinTemp
        } % end Density

        MeltTemp{
            MinOccurs = 1
            MaxOccurs = 1

            value{
                MinOccurs = 1
                MaxOccurs = 1
                ValType   = Real
                MinValInc = 0
            } % end value
        } % end MeltTemp

        MolecularWeight{
            MinOccurs = 0
            MaxOccurs = 1
            InputDefault = "1.0"
            value{
                MinOccurs = 1
                MaxOccurs = 1
                ValType   = Real
                MinValExc = 0
            } % end value
        } % end MolecularWeight
    } % end salt
} % end salts

queries{
    Description = "Parameters for queries salt properties"
    MinOccurs = 1
    MaxOccurs = 1

    temperatures{
        Description = "Temperatures (C) at which to query density" 
        MinOccurs = 1
        MaxOccurs = 1
        value{
            MinOccurs = 1
            MaxOccurs = NoLimit
            ValType   = Real
            MinValInc = 0
        } % end value
    } % end temperatures
} % end queries