Scenario - CustomScenarioBuilder

Scenario.CustomScenarioBuilder

A helper class to build optimizable scenarios around a custom task to running on the ELARA platform.

The custom task executes a command inside a dockerized sandbox. It is given some input files as blob data, and produces some output files as blob data. The custom task can run any linux-compatible binary program (which can be provided as one of the input files) inside our default Ubuntu container, or any docker image you upload to ELARA via a blob

Stream.

The outputs of the custom task can be optimized automatically with respect to the inputs using ELARA's standard optimizer. During each optimization iteration, multiple Monte-Carlo "trajectories" can be executed. This means the command will be run numerous times during execution.

A corresponding

Template can be created using .toTemplate().

Example

// Optimize a custom task which uses a user-provided program to transform a JSON file into another JSON file
const my_scenario = new CustomScenarioBuilder("MyScenario")
  .input("my_program", my_program_stream, file => file, true)
  .input("input.json", input_data_stream, data => Utf8Encode(ToJson(data)))
  .output("output.json", blob => FromJson(MyOutputType, Utf8Decode(blob)))
  .shell("./my_program input.json output.json")
  .objective(outputs => outputs["output.json"])
  .optimizeEvery("input.json", "amount", { min: () => Const(0), max: () => Const(100) })

Type parameters

Name	Type
Inputs	extends Record =
Outputs	extends Record =
Results	extends Record =
MultiTrajectory	extends boolean = false

Hierarchy

• Builder

  ↳ CustomScenarioBuilder

CustomScenario

copyScenario

▸ copyScenario(builder):

CustomScenarioBuilder

Inherit all details from a given CustomScenarioBuilder in this scenario. This can be used to create two similar scenarios for comparison (for example, to compare predictions of optimized and unoptimized scenarios).

Type parameters

Name	Type
I	extends Record
O	extends Record
R	extends Record
T	extends boolean

Parameters

Name	Type	Description
builder	CustomScenarioBuilder	the CustomScenarioBuilder to copy from

Returns

CustomScenarioBuilder

---

dataDir

▸ dataDir(dir):

CustomScenarioBuilder

Provide the directory where the input and output data is located.

This directory is a docker "volume mount" - if this directory already exists in the image, files inside will not be visible inside the container. If necessary, copy files into the data directory from elsewhere in the image via a

shell command.

Note: the directory is also set as the current working directory before the task command is executed.

Parameters

Name	Type	Description
dir	string	the directory to mount the data inside the docker container

Returns

CustomScenarioBuilder

Example

// Optimize a custom task which uses a user-provided program to transform a JSON file into another JSON file
const my_scenario = new CustomScenarioBuilder("MyScearnio")
  .dataDir("/my/custom/dir")
  .input("my_program", my_program_stream, file => file, true)
  .input("input.json", input_data_stream, data => Utf8Encode(ToJson(data)))
  .output("output.json", blob => FromJson(MyOutputType, Utf8Decode(blob)))
  .shell("./my_program input.json output.json")
  .objective(outputs => outputs["output.json"])
  .optimizeEvery("input.json", "amount", { min: () => Const(0), max: () => Const(100) })

---

dockerImage

▸ dockerImage(stream):

CustomScenarioBuilder

Provide a user-defined docker image to execute the custom task. The docker image is provided via a blob

Stream, containing an OCI container in a .tar, .tar.gz, .tar.bz2 file format as generated by docker via docker image save ... or similar methods.

If no docker image is provided, then an Ubuntu LTS image is used by default. If no command is provided the image's default command is used.

Parameters

Name	Type	Description
stream	Stream	the stream containing the docker image

Returns

CustomScenarioBuilder

Example

// Create a custom task which uses a user-provided docker image to transform a JSON file into another JSON file
const my_scenario = new CustomScenarioBuilder("MyScenario")
  .dockerImage(my_docker_image_stream)
  .input("input.json", input_data_stream, data => Utf8Encode(ToJson(data)))
  .output("output.json", blob => FromJson(MyOutputType, Utf8Decode(blob)))
  .objective(outputs => outputs["output.json"])
  .optimizeEvery("input.json", "amount", { min: () => Const(0), max: () => Const(100) })

---

exec

▸ exec(command, ...args):

CustomScenarioBuilder

Provide the command used to execute the custom task with raw arguemnts. This command will be executed in a sandbox. As the command is not be interpretted by any shell, it is not necessary to quote the arguments (e.g. filenames containing spaces, etc).

Parameters

Name	Type	Description
command	string	the filename of the program to be executed
...args	string[]	the command-line arguments given to the program

Returns

CustomScenarioBuilder

Example

// Create a custom task which uses a user-provided program to transform a JSON file into another JSON file
const my_scenario = new CustomScenarioBuilder("MyScearnio")
  .input("my_program", my_program_stream, file => file, true)
  .input("input data.json", input_data_stream, data => Utf8Encode(ToJson(data)))
  .output("output data.json", blob => FromJson(MyOutputType, Utf8Decode(blob)))
  .exec("./my_program", "input data.json", "output data.json")
  .objective("output data.json")
  .optimizeEvery("input data.json", "amount", { min: () => Const(0), max: () => Const(100) }) 

---

input

▸ input(filename, stream, toBlob?, executable?):

CustomScenarioBuilder<Inputs & { [K in string]: T }, Outputs, Results, MultiTrajectory>

Add an input to the custom task. A file with the provided filename is created from the data stored in a blob

Stream before the custom task command is launched.

Note that the input could be a linux-compatible program to execute.

Type parameters

Name	Type
Name	extends string
T	extends EastType

Parameters

Name	Type	Default value	Description
filename	Name	undefined	the filename of the input
stream	Stream	undefined	a blob stream contain the data to place in the file
toBlob?	(input: Variable) => EastFunction	undefined	an optional function to create an Expression to serialize the input data into a raw file (blob)
executable	boolean	false	set to true if the file is an executable program (default false)

Returns

CustomScenarioBuilder<Inputs & { [K in string]: T }, Outputs, Results, MultiTrajectory>

Example

// Optimize a custom task which uses a user-provided program to transform a JSON file into another JSON file
const my_scenario = new CustomScenarioBuilder("MyScearnio")
  .input("my_program", my_program_stream, file => file, true)
  .input("input.json", input_data_stream, data => Utf8Encode(ToJson(data)))
  .output("output.json", blob => FromJson(FloatType, Utf8Decode(blob)))
  .shell("./my_program input.json output.json")
  .objective(outputs => outputs["output.json"])
  .optimizeEvery("input.json", "amount", { min: () => Const(0), max: () => Const(100) })

---

optimizationAlgorithm

▸ optimizationAlgorithm(algorithm):

CustomScenarioBuilder

Set the optimzation algorithm to employ to search the parameter space.

Parameters

Name	Type	Description
algorithm	OptimizationAlgorithm	the algorithm to apply (default = "gradient_free")

Returns

CustomScenarioBuilder

Example

// Optimize a custom task which uses a user-provided program to transform a JSON file into another JSON file
const my_scenario = new CustomScenarioBuilder("MyScenario")
  .input("my_program", my_program_stream, file => file, true)
  .input("input.json", input_data_stream, data => Utf8Encode(ToJson(data)))
  .output("output.json", blob => FromJson(MyOutputType, Utf8Decode(blob)))
  .shell("./my_program input.json output.json")
  .objective(outputs => outputs["output.json"])
  .optimizeEvery("input.json", "amount", { min: () => Const(0), max: () => Const(100) })
  .optimizationAlgorithm("random_search")

---

optimizationTrajectories

▸ optimizationTrajectories(n_trajectories):

CustomScenarioBuilder

Set the number of Monte-Carlo trajectories to be performed during optimization.

Parameters

Name	Type	Description
n_trajectories	number	the number of Monte-Carlo trajectories (default 20)

Returns

CustomScenarioBuilder

Remarks

More trajectories will give greater certainty that the optimized recommendations are robust to any randomness in the scenario simulation, but will incur a greater computational cost. To help determine if sufficient trajectories are used for optimization, a "validation" set is also produced - for best result there should be a high degree of correlation between the target objective and the validation objective.

Example

// Optimize a custom task which uses a user-provided program to transform a JSON file into another JSON file
const my_scenario = new CustomScenarioBuilder("MyScenario")
  .input("my_program", my_program_stream, file => file, true)
  .input("input.json", input_data_stream, data => Utf8Encode(ToJson(data)))
  .output("output.json", blob => FromJson(MyOutputType, Utf8Decode(blob)))
  .shell("./my_program input.json output.json")
  .objective(outputs => outputs["output.json"])
  .optimizeEvery("input.json", "amount", { min: () => Const(0), max: () => Const(100) })
  .optimizationTrajectories(100)

---

output

▸ output(filename, fromBlob?, result?):

CustomScenarioBuilder<Inputs, Outputs & { [K in string]: BlobType }, Results & { [K in string]: BlobType }, MultiTrajectory>

Add an output to the custom task. A file with the provided filename is expected to exist after the custom task command is completed. The output data is then copied to a

Stream.

Type parameters

Name	Type
Name	extends string

Parameters

Name	Type	Description
filename	Name	the filename of the output
fromBlob?	undefined	an optional function to create an Expression to deserialize (or parse) the output data from a raw file (blob)
result?	true	whether this file is written to a datastream (default true)

Returns

CustomScenarioBuilder<Inputs, Outputs & { [K in string]: BlobType }, Results & { [K in string]: BlobType }, MultiTrajectory>

Example

// Optimize a custom task which uses a user-provided program to transform a JSON file into another JSON file
const my_scenario = new CustomScenarioBuilder("MyScearnio")
  .input("my_program", my_program_stream, file => file, true)
  .input("input.json", input_data_stream, data => Utf8Encode(ToJson(data)))
  .output("output.json", blob => FromJson(MyOutputType, Utf8Decode(blob)))
  .result("field_a", outputs => GetField(outputs["output_data.json"], "a"))
  .shell("./my_program input.json output.json")
  .objective(outputs => GetField(outputs["output.json"], "b"))
  .optimizeEvery("input.json", "amount", { min: () => Const(0), max: () => Const(100) })

---

result

▸ result(name, result):

CustomScenarioBuilder<Inputs, Outputs, Results & { [K in string]: ReturnType["type"] }, MultiTrajectory>

Add a result to the (optimized) custom task which is computed from the output files.

Type parameters

Name	Type
Name	extends string
F	extends (output: { [K in string | number | symbol]: Variable }) => EastFunction

Parameters

Name	Type
name	Name
result	F

Returns

CustomScenarioBuilder<Inputs, Outputs, Results & { [K in string]: ReturnType["type"] }, MultiTrajectory>

Example

// Optimize a custom task which uses a user-provided program to transform a JSON file into another JSON file
const my_scenario = new CustomScenarioBuilder("MyScearnio")
  .input("my_program", my_program_stream, file => file, true)
  .input("input.json", input_data_stream, data => Utf8Encode(ToJson(data)))
  .output("output.json", blob => FromJson(MyOutputType, Utf8Decode(blob)))
  .shell("./my_program input.json output.json")
  .objective(outputs => outputs["output.json"])
  .optimizeEvery("input.json", "amount", { min: () => Const(0), max: () => Const(100) })

---

resultStreams

▸ resultStreams(): MultiTrajectory extends false ? { [K in string | number | symbol]: Stream } : { [K in string | number | symbol]: Stream<ArrayType> }

Fetch the result streams of the custom task. This returns a record of data streams; by default the keys are the paths of the output files, but other results can be computed via

result.

The data returned is from the first trajectory of the optimized scenario.

Returns

MultiTrajectory extends false ? { [K in string | number | symbol]: Stream } : { [K in string | number | symbol]: Stream<ArrayType> }

Example

// Optimize a custom task which uses a user-provided program to transform a JSON file into another JSON file
const my_scenario = new CustomScenarioBuilder("MyScenario")
  .input("my_program", my_program_stream, file => file, true)
  .input("input.json", input_data_stream, data => Utf8Encode(ToJson(data)))
  .output("output.json", blob => FromJson(MyOutputType, Utf8Decode(blob)))
  .shell("./my_program input.json output.json")
  .logStdErr(true)
  .objective(outputs => outputs["output.json"])
  .optimizeEvery("input.json", "amount", { min: () => Const(0), max: () => Const(100) })

// Get the decoded output data stream
const output_stream = my_scenario.outputStreams()["output.json"]

---

shell

▸ shell(command):

CustomScenarioBuilder

Provide the command used to execute the custom task in shell. This command will be executed by the linux bash shell in a sandboxed docker environment.

Parameters

Name	Type	Description
command	string	the command to be executed

Returns

CustomScenarioBuilder

Example

// Optimize a custom task which uses a user-provided program to transform a JSON file into another JSON file
const my_scenario = new CustomScenarioBuilder("MyScearnio")
  .input("my_program", my_program_stream, file => file, true)
  .input("input.json", input_data_stream, data => Utf8Encode(ToJson(data)))
  .output("output.json", blob => FromJson(MyOutputType, Utf8Decode(blob)))
  .shell("./my_program input.json output.json")
  .objective(outputs => outputs["output.json"])
  .optimizeEvery("input.json", "amount", { min: () => Const(0), max: () => Const(100) })

---

simulationTrajectories

▸ simulationTrajectories(n_trajectories):

CustomScenarioBuilder

Set the number of Monte-Carlo trajectories to be performed during simulation.

Parameters

Name	Type	Description
n_trajectories	null	the number of Monte-Carlo trajectories, or null for single trajectory (default null)

Returns

CustomScenarioBuilder

Remarks

More trajectories will give greater statistical certainty in the results, but will incur a greater computational cost.

Example

// Optimize a custom task which uses a user-provided program to transform a JSON file into another JSON file
const my_scenario = new CustomScenarioBuilder("MyScenario")
  .input("my_program", my_program_stream, file => file, true)
  .input("input.json", input_data_stream, data => Utf8Encode(ToJson(data)))
  .output("output.json", blob => FromJson(MyOutputType, Utf8Decode(blob)))
  .shell("./my_program input.json output.json")
  .objective(outputs => outputs["output.json"])
  .optimizeEvery("input.json", "amount", { min: () => Const(0), max: () => Const(100) })
  .simulationTrajectories(100);

Other

objective

▸ objective(objective):

CustomScenarioBuilder

Define a contribution to the objective function to be optimized (maximised), by computing a float

Parameters

Name	Type
objective	(value: { [K in string | number | symbol]: Variable }) => EastFunction

Returns

CustomScenarioBuilder

Remarks

optimization will use the sum of all objective values in the case that multiple are defined

Example

// Optimize a custom task which uses a user-provided program to transform a JSON file into another JSON file
const my_scenario = new CustomScenarioBuilder("MyScenario")
  .input("my_program", my_program_stream, file => file, true)
  .input("input.json", input_data_stream, data => Utf8Encode(ToJson(data)))
  .output("output.json", blob => FromJson(FloatType, Utf8Decode(blob)))
  .shell("./my_program input.json output.json")
  .objective(outputs => outputs["output.json"])
  .optimizeEvery("input.json", "amount", { min: () => Const(0), max: () => Const(100) })

Scenario

distributed

▸ distributed(is_distributed):

CustomScenarioBuilder

Set the calculations to be performed in a distributed way, accross multiple tasks and able to take advantage of multiple worker nodes in parallel (instead of the default in-process, single-task method).

Parameters

Name	Type	Description
is_distributed	boolean	true if the calculations should be performed distributed

Returns

CustomScenarioBuilder

Remarks

Distributed simulations are faster for demanding simulations with many trajectories, but orchestration overheads may make it slower for simple simulations.

---

optimizationAtol

▸ optimizationAtol(atol):

CustomScenarioBuilder

Set the absolute tolerance required to trigger convergence detection. Set to 0 if absolute convergence detection is not desired.

Parameters

Name	Type	Description
atol	number	the absolute tolerance required for convergence (default = 0.0)

Returns

CustomScenarioBuilder

Example

// Optimize a custom task which uses a user-provided program to transform a JSON file into another JSON file
const my_scenario = new CustomScenarioBuilder("MyScenario")
  .input("my_program", my_program_stream, file => file, true)
  .input("input.json", input_data_stream, data => Utf8Encode(ToJson(data)))
  .output("output.json", blob => FromJson(MyOutputType, Utf8Decode(blob)))
  .shell("./my_program input.json output.json")
  .objective(outputs => outputs["output.json"])
  .optimizeEvery("input.json", "amount", { min: () => Const(0), max: () => Const(100) })
  .optimizationAtol(0.1)

---

optimizationInMemory

▸ optimizationInMemory(in_memory):

CustomScenarioBuilder

Set the optimization parameters are to be held in memory (instead of the default out-of-core method).

Parameters

Name	Type	Description
in_memory	boolean	true if the optimization data should be held in memory

Returns

CustomScenarioBuilder

Remarks

In-memory optimization may be faster but requires more RAM.

Example

// Optimize a custom task which uses a user-provided program to transform a JSON file into another JSON file
const my_scenario = new CustomScenarioBuilder("MyScenario")
  .input("my_program", my_program_stream, file => file, true)
  .input("input.json", input_data_stream, data => Utf8Encode(ToJson(data)))
  .output("output.json", blob => FromJson(MyOutputType, Utf8Decode(blob)))
  .shell("./my_program input.json output.json")
  .objective(outputs => outputs["output.json"])
  .optimizeEvery("input.json", "amount", { min: () => Const(0), max: () => Const(100) })
  .optimizationInMemory(true)

---

optimizationMaxIterations

▸ optimizationMaxIterations(max_iterations):

CustomScenarioBuilder

Set the maximum number of optimization iterations to complete.

Parameters

Name	Type	Description
max_iterations	number	the maximum number of optimization iterations (default 1000)

Returns

CustomScenarioBuilder

Example

// Optimize a custom task which uses a user-provided program to transform a JSON file into another JSON file
const my_scenario = new CustomScenarioBuilder("MyScenario")
  .input("my_program", my_program_stream, file => file, true)
  .input("input.json", input_data_stream, data => Utf8Encode(ToJson(data)))
  .output("output.json", blob => FromJson(MyOutputType, Utf8Decode(blob)))
  .shell("./my_program input.json output.json")
  .objective(outputs => outputs["output.json"])
  .optimizeEvery("input.json", "amount", { min: () => Const(0), max: () => Const(100) })
  .optimizationMaxIteration(100)

---

optimizationMinIterations

▸ optimizationMinIterations(min_iterations):

CustomScenarioBuilder

Set the minimum number of iterations to complete before detecting for convergence

Parameters

Name	Type	Description
min_iterations	number	the minimum number of iterations to complete before detecting for convergence (default 0)

Returns

CustomScenarioBuilder

Example

// Optimize a custom task which uses a user-provided program to transform a JSON file into another JSON file
const my_scenario = new CustomScenarioBuilder("MyScenario")
  .input("my_program", my_program_stream, file => file, true)
  .input("input.json", input_data_stream, data => Utf8Encode(ToJson(data)))
  .output("output.json", blob => FromJson(MyOutputType, Utf8Decode(blob)))
  .shell("./my_program input.json output.json")
  .objective(outputs => outputs["output.json"])
  .optimizeEvery("input.json", "amount", { min: () => Const(0), max: () => Const(100) })
  .optimizationMinIterations(50)

---

optimizationRtol

▸ optimizationRtol(rtol):

CustomScenarioBuilder

Set the relative tolerance required to trigger convergence detection. Set to 0 if relative convergence detection is not desired.

Parameters

Name	Type	Description
rtol	number	the relative tolerance required for convergence (default = 1.0e-3)

Returns

CustomScenarioBuilder

Example

// Optimize a custom task which uses a user-provided program to transform a JSON file into another JSON file
const my_scenario = new CustomScenarioBuilder("MyScenario")
  .input("my_program", my_program_stream, file => file, true)
  .input("input.json", input_data_stream, data => Utf8Encode(ToJson(data)))
  .output("output.json", blob => FromJson(MyOutputType, Utf8Decode(blob)))
  .shell("./my_program input.json output.json")
  .objective(outputs => outputs["output.json"])
  .optimizeEvery("input.json", "amount", { min: () => Const(0), max: () => Const(100) })
  .optimizationRtol(0.01)

---

optimizationStream

▸ optimizationStream():

Stream<ArrayType<StructType<{ objective: FloatType ; objectives: ArrayType ; values: DictType }>>>

Return a

Stream detailing the optimzation procedure, where convergence of optimization can be validated.

Returns

Stream<ArrayType<StructType<{ objective: FloatType ; objectives: ArrayType ; values: DictType }>>>

Example

// Optimize a custom task which uses a user-provided program to transform a JSON file into another JSON file
const my_scenario = new CustomScenarioBuilder("MyScenario")
  .input("my_program", my_program_stream, file => file, true)
  .input("input.json", input_data_stream, data => Utf8Encode(ToJson(data)))
  .output("output.json", blob => FromJson(MyOutputType, Utf8Decode(blob)))
  .shell("./my_program input.json output.json")
  .logStdErr(true)
  .objective(outputs => outputs["output.json"])
  .optimizeEvery("input.json", "amount", { min: () => Const(0), max: () => Const(100) })

// Get the optimization stream
const optimization_stream = my_scenario.optimizationStream()

---

optimize

▸ optimize(name, config):

CustomScenarioBuilder

Optimize the value of an input to maximize the output objective.

The optimizer can search for optimal values using one of three different strategies:

1. searching between min and max values (for float/integer/datetime inputs)
2. selecting one of a range containing an array of possible values
3. using a custom transform to construct a value from a search parameter between 0.0 and 1.0

Type parameters

Name	Type
Name	extends string | number | symbol

Parameters

Name	Type	Description
name	Name	the path of the input to optimize
config	Object	the configuration of the optimization
config.max	ValueTypeOf | (inputs: { [K in string | number | symbol]: Variable }) => EastFunction	The maximum value that the optimzer may apply (inclusive)
config.min?	ValueTypeOf | (inputs: { [K in string | number | symbol]: Variable }) => EastFunction	The minimum value that the optimzer may apply (inclusive, default 0)

Returns

CustomScenarioBuilder

Remarks

each optimize added results in significant compute so should be used sparingly

Example

// Optimize a custom task which uses a user-provided program to transform a JSON file into another JSON file
const my_scenario = new CustomScenarioBuilder("MyScenario")
  .input("my_program", my_program_stream, file => file, true)
  .input("input.json", input_data_stream, data => Utf8Encode(ToJson(data)))
  .output("output.json", blob => FromJson(MyOutputType, Utf8Decode(blob)))
  .shell("./my_program input.json output.json")
  .objective(outputs => outputs["output.json"])
  .optimize("input.json", "amount", { min: () => Const(0), max: () => Const(100) })

---

optimizeEvery

▸ optimizeEvery(name, field, config):

CustomScenarioBuilder

Optimize the initial values of a float field inside a tabular (i.e. array of structs) input to maximize the output objective.

The optimizer can search for optimal values using one of three different strategies:

1. searching between min and max values (for float/integer/datetime inputs)
2. selecting one of a range containing an array of possible values
3. using a custom transform to construct a value from a search parameter between 0.0 and 1.0

Type parameters

Name	Type
Name	extends string

Parameters

Name	Type	Description
name	Name	the path of the input to optimize
field	Inputs[Name] extends ArrayType ? keyof any[any]["value"]["value"] : never	-
config	Object	the configuration of the optimization
config.active?	(inputs: { [K in string | number | symbol]: Variable }, value: Inputs[Name] extends ArrayType ? Variable : never, key: Variable) => EastFunction	-
config.max	number | bigint | Date | (inputs: { [K in string | number | symbol]: Variable }, value: Inputs[Name] extends ArrayType ? Variable : never, key: Variable) => EastFunction<IntegerType | FloatType | DateTimeType>	-
config.min?	number | bigint | Date | (inputs: { [K in string | number | symbol]: Variable }, value: Inputs[Name] extends ArrayType ? Variable : never, key: Variable) => EastFunction<IntegerType | FloatType | DateTimeType>	-

Returns

CustomScenarioBuilder

Remarks

each optimize added results in significant compute so should be used sparingly

Example

// Optimize a custom task which uses a user-provided program to transform a JSON file into another JSON file
const my_scenario = new CustomScenarioBuilder("MyScenario")
  .input("my_program", my_program_stream, file => file, true)
  .input("input.json", input_data_stream, data => Utf8Encode(ToJson(data)))
  .output("output.json", blob => FromJson(MyOutputType, Utf8Decode(blob)))
  .shell("./my_program input.json output.json")
  .objective(outputs => outputs["output.json"])
  .optimizeEvery("input.json", "amount", { min: () => Const(0), max: () => Const(100) })

---

optimizedStreams

▸ optimizedStreams(): { [K in string | number | symbol]: Stream }

Return a record of

Streams containing the automatically optimized values for the custom scenario inputs.

Returns

{ [K in string | number | symbol]: Stream }

Task

env

▸ env(name, value):

CustomScenarioBuilder

Set an environment variable for the custom task. This could be computed from the trajectory number, for example for a random seed.

Parameters

Name	Type	Description
name	string	the name of the environment variable
value	string	the value of the environment variable - either a raw string, or an expression of the trajectory number

Returns

CustomScenarioBuilder

Example

// Optimize a custom task which uses a user-provided program to transform a JSON file into another JSON file
const my_scenario = new CustomScenarioBuilder("MyScenario")
  .input("my_program", my_program_stream, file => file, true)
  .input("input.json", input_data_stream, data => Utf8Encode(ToJson(data)))
  .output("output.json", blob => FromJson(MyOutputType, Utf8Decode(blob)))
  .env("RANDOM_SEED", (trajectory) => Print(Add(1000n, trajectory)))
  .shell("./my_program input.json output.json")
  .objective(outputs => outputs["output.json"])
  .optimizeEvery("input.json", "amount", { min: () => Const(0), max: () => Const(100) })

---

logStdErr

▸ logStdErr(enabled):

CustomScenarioBuilder

Enable or disable logging of stderr from the custom scenario. Note that this will create messages for each trajectory inside each iteration of optimization.

Parameters

Name	Type	Description
enabled	boolean	whether logging is enabled (default false)

Returns

CustomScenarioBuilder

Example

// Optimize a custom task which uses a user-provided program to transform a JSON file into another JSON file
const my_scenario = new CustomScenarioBuilder("MyScenario")
  .input("my_program", my_program_stream, file => file, true)
  .input("input.json", input_data_stream, data => Utf8Encode(ToJson(data)))
  .output("output.json", blob => FromJson(MyOutputType, Utf8Decode(blob)))
  .shell("./my_program input.json output.json")
  .logStdErr(true)
  .objective(outputs => outputs["output.json"])
  .optimizeEvery("input.json", "amount", { min: () => Const(0), max: () => Const(100) })

---

logStdOut

▸ logStdOut(enabled):

CustomScenarioBuilder

Enable or disable logging of stdout from the custom scenario. Note that this will create messages for each trajectory inside each iteration of optimization.

Parameters

Name	Type	Description
enabled	boolean	whether logging is enabled (default true)

Returns

CustomScenarioBuilder

Example

// Optimize a custom task which uses a user-provided program to transform a JSON file into another JSON file
const my_scenario = new CustomScenarioBuilder("MyScenario")
  .input("my_program", my_program_stream, file => file, true)
  .input("input.json", input_data_stream, data => Utf8Encode(ToJson(data)))
  .output("output.json", blob => FromJson(MyOutputType, Utf8Decode(blob)))
  .shell("./my_program input.json output.json")
  .logStdOut(true)
  .objective(outputs => outputs["output.json"])
  .optimizeEvery("input.json", "amount", { min: () => Const(0), max: () => Const(100) })