Skip to main content

Define a custom scenario

In this tutorial you will:

  • Create a data source with a default value,
  • Build a custom scenario that executes a shell script based on input data, and
  • Read the results of the custom scenario.

This lesson will assume that you have an empty project and asset which you can to deploy to a workspace named 08_02_02_define_a_custom_scenario with the following command:

edk template deploy -ycw 08_02_02_define_a_custom_scenario

Note that this lesson is very similar to the

one for custom tasks. Basically, replace CustomTaskBuilder with CustomScenarioBuilder (and set a default value to the data source). Without optimization or Monte Carlo, custom scenarios and custom tasks are extremely similar (custom scenarios are strictly more powerful). In the next lesson you will have the opportunity to add optimization to this scenario.

Create the datasource

In this case we are going to use our custom scenario to do some simple mathematics. The input will be a floating-point number. Initially, our project will have just this datasource.

import { FloatType, SourceBuilder, Template } from "@elaraai/core"

const my_source = new SourceBuilder("My Source")
    .value({ value: 2 });

export default Template(my_source);

Build the custom scenario

A custom scenario is built by the CustomScenarioBuilder class. You start by giving a scenario a name, and providing the inputs. This scenario will have just one input, from the datasource above.

The .input method

const custom_scenario = new CustomScenarioBuilder("Quadratic")
    .input(
        "input.txt", // filename
        my_source.outputStream(), // datastream
        false, // executable
        float => Utf8Encode(Print(float)), // toBlob
    )

A custom scenario can execute one of:

  • a shell script (bash, on Ubuntu LTS)
  • a native linux program (on Ubuntu LTS)
  • a user-provided docker image

In this lesson we will look at the simplest option – a shell script. We will use bash builtin functions and cat to perform some simple mathematics. Our goal is to perform the following function:

f(x) = x * (x - 10)

Our input is in a file called input.txt. We can use the cat program to read that file. We can use $(( ... )) syntax to perform mathematical expressions in bash, and pipe the output to a file. One way to do calculate the formula above is using the awk command-line tool via this bash script:

awk '{x=$1; printf "%.14f\n", x * (10 - x)}' input.txt > output.txt

The awk program parses simple C-like expressions and produces a result. Understanding awk is not crucial to this lesson; just know that the above reads input.txt and writes the answer to a new file, output.txt. We can pass the above program above as a string to the .shell method on FunctionBuilder. This results in a file called output.txt.

The final thing to do is to instruct the FunctionBuilder to read the output file with the .output method, and parse it back to a floating-point number. Parsing is optional; you can simply return results with a BlobType data type. But in this case the result is numerical and it makes sense to parse it to a float immediately. To do so, we must first convert the blob to a string with Utf8Decode and then parse the string to a float with Parse. Putting it all together results in the following project definition:

import { CustomScenarioBuilder, FloatType, Parse, Print, SourceBuilder, Template, Utf8Decode, Utf8Encode } from "@elaraai/core"

const my_source = new SourceBuilder("My Source")
    .writeable(FloatType);

const custom_scenario = new CustomScenarioBuilder("Quadratic")
    .input(
        "input.txt", // filename
        my_source.outputStream(), // datastream
        float => Utf8Encode(Print(float)), // toBlob
    )
    .shell(`awk '{x=$1; printf "%.14f\n", x * (10 - x)}' input.txt > output.txt`)
    .output(
        "output.txt", // filename
        blob => Parse(FloatType, Utf8Decode(blob)) // fromBlob
    )

export default Template(my_source, custom_scenario);

Running the scenario

Build and deploy the template. Populate the value, for example via:

edk stream replace "Writeable.My Source" --value 2 -w 08_02_02_define_a_custom_scenario

This should inject the value 2 into the function. This should calculate 2 * (10 - 2), or 16. Let's see what result we get:

$ edk stream get Custom.Quadratic.output.txt -w 08_02_02_define_a_custom_scenario

Additional exercises

Try populating the writable data source with some other values and see what results you get.

  • Try to get the largest result possible.
  • At what value of the input do you see the largest output?
  • And what is the maximum output value?

Example Solution

The final solution for this tutorial is available below:

Next Steps

In this tutorial, you created a basic custom scenario. In the

next lesson you will optimize the inputs to maximize the output.

On this page