DSL-Python interfaces and type mapping

Interface

An interface implements a mapping between DSL functions to Python API functions

Implicit interface

use numpy.exp
b = 1 [m]
a = exp(b)

In this case the called Python API function "understands" the type of b at run time: whether it is a scalar or vector (iterable) type, the units and the data type (dtype).

Another example, this function cuts a surface along the (y, z) plane:

atoms_tab = ((x: ...), (y: ...), (z: ...), (symbols: ...))
cut(a): a where x > 0
atoms_tab_positive_x = cut(atoms_tab)

Since atoms_t is a Table and the operation is defined for it there is no need of an explicit interface.

Explicit interface

The explicit interface:

1. adapts the type using type mapping for all parameters;
2. performs dimensionality check and converts the units (if needed) for all parameters;
3. calls the Python API function and collects the returned value;
4. adapts the type and units of returned value and returns the adapted value

struct = Structure from file 'myatoms.yaml'
cut(a): a where x > 0
atoms_tab_positive_x = cut(atoms_tab)

In this case an interface is necessary that transforms the DSL Structure either to DSL Table (see example above) or to Python ASE Atoms.

Type mapping

The mapping between typed metamodel classes and nominal Python type must be unique / unambiguous:

Metamodel class	Nominal Python type	Other Python types
Number	pint.Quantity	int, float, complex; numpy.int_, numpy.float_, numpy.complex_; numpy.int64, numpy.float64, numpy.complex128, ...
Bool	bool	numpy.bool_
String	str	numpy.str_
Null	NoneType
Tuple	tuple	list
Table	pandas.DataFrame	dict
Series	pandas.Series
FloatArray	pint_pandas.pint_array.PintArray	list
Array	numpy.ndarray	list
Structure	ase.Atoms
Calculator	ase.Calculator
Property	dict
Dummy	None

Objects of other (non-typed) metamodel classes might have variable types but strictly one of these types. For example, FunctionCall instances may have any of the listed types. A Comparison object has bool type with scalar parameters but the type of Array, i.e. numpy.ndarray (with dtype=numpy.bool_) with iterable parameters.