Encoders

In mUQSA portal, encoders are an essential component of the whole workflow. An encoder is a function that transforms input variables from the technical mUQSA format into a format that can be used as input to a simulation code or model, thus a real application. The encoder function ensures that the input variables are properly formatted, within the correct range, and ready to be passed to the simulation code.

mUQSA exposes a few predefined encoders that can be used in a raw form or attached to the scenario in a form of compound, multistep encoder. The provided encoders should be sufficient to satisfy needs of the majority of use-cases, but for the remaining part, UQSA gives also a user possibility to attach custom encoders written in python.

Built-in encoders #

Generic Encoder #

Generic Encoder is simple decoder targeted to encode text input files. It generates the target file based on a provided text template, where it substitutes placeholders provided in a format $INPUT_VAR by a corresponding value of INPUT_VAR parameter defined in UQSA parameters.

Thus, assuming we have defined two sampled parameters int: a and int: b and a static parameter string: s, the template, which puts these variables into JSON text file, may look as follows:

{"first": $a, "second": $b, "third": "$s"}

and then the resulting file after substitution may look as follows:

{"first": 20, "second": 10, "third": "some_string"}

Jinja Encoder #

Jinja is a popular and powerful templating framework. The encoder based on Jinja is suitable to encode textual files in a more sophisticated way than Generic Encoder. With Jinja2 constructs it is possible to apply more complex and non-trivial substitutions.

The example below presents a simple Jinja template for two sampled input parameters a and b that uses Jinja conditional expression to generate final content:

{
    "first": {{a}},
    "second": {{b}},
{% if a > b  %}
    "third": true
{% else %}
    "third": false
{% endif %}
}

The output file may then look as follows:

{
    "first": 20,
    "second": 10,
    "third": true
}

Custom Encoder #

UQSA supports usage of custom python encoders. The custom encoder can be provided as a python file with a class exposing a constructor and encode method of the following signatures:

class CustomEncoder:
    def __init__(self, template_filename, selector, generated_filename)
        pass

    def encode(self, params={}, target_dir='')
        pass

The encode method is called by the EasyVVUQ library and passes a params parameter. params include all sampled data, and it is of a custom encoder’s creator to decide how this data can be transferred into the form suitable for a specific application.

Please look into the EasyVVUQ Encoders Sources to get a closer insight how an encoder can be constructed.

Multiencoders #

Many encoders can be stacked and combined into a single Multiencoder. The order of execution of such stacked encoders is from top to bottom.