API

PreProcessingStep

Functions to prepare data for surrogatization.

A PreProcessingStep can be created given some method. Once created, a PreprocessingStep is callable over a given data structure.

Optionally, users can also provide a configuration for the step. This configuration will modify the behavior of the method being performed over the specified data structure. If no configuration is needed, then PreProcessingStep can be called with only one argument for method.

Examples

# define method
squared_magnitude = abs2

# create step
squared_magnitude_step = PreprocessingStep(squared_magnitude)

# perform step on `X`
squared_magnitude_step(X)

MinMaxNorm(lb, ub)

Constructs a MinMaxNorm transform with given bounds and default scale = (0.0, 1.0)

MinMaxNorm(lb, ub, scale)

Constructs a MinMaxNorm transform with given bounds and scale.

MinMaxNorm(ed::ExperimentData, sym::Symbol, scale = (0.0, 1.0)) Constructs a MinMaxNorm transform that operates on ExperimentData ed for the field given by sym with default scale = (0.0, 1.0)

Arguments

• ed::ExperimentData: The ExperimentData object that MinMaxNorm should be applied on
• sym::Symbol: The field of ExperimentData on which MinMaxNorm would be defined
• scale::Tuple: The scale for the MinMaxNorm, defaulted to (0.0, 1.0)

ZScore(mu, sigma)

Constructs a ZScore transform with given mean and standard deviation

ZScore(ed::ExperimentData, sym::Symbol)

Constructs a ZScore transform that operates on ExperimentData ed for the field given by sym

Arguments

• ed::ExperimentData: The ExperimentData object that MinMaxNorm should be applied on
• sym::Symbol: The field of ExperimentData on which MinMaxNorm would be defined

FilterContinuousValues

Allows user to filter constant i.e. non-changing continuous fields from ExperimentData. It supports providing an arbitrary number of field symbols to filter.

Defining a filter using FilterContinuousValues :

Example

filter_ = FilterContinuousValues(:states)
chain = PreProcessingChain(filter_)
filtered_ed = chain(ed)

# With multiple symbols
filter_ = FilterContinuousValues(:states, :controls, :observables)
chain = PreProcessingChain(filter_)
filtered_ed = chain(ed)

CustomTransform

Allows to use custom functions for PreProcessing

CustomTransform can be used to input custom preprocessing functions as a step to the PreProcessingChain

CustomTransform(f, sym)

Arguments

- `f::Function` : custom preprocessing function.
- `sym::Symbol` :  symbol on which `f` is applied.

Example

f(x) = sin(x)
transform = CustomTransform(f, :controls)
chain = PreProcessingChain(transform)

f(x) = cos(x)
transform = CustomTransform(f, :controls)
min_max = MinMaxNorm(:states, (-1.0, 1.0))
chain = PreProcessingChain(transform, min_max)

FilterFields(ed, sym, filter_labels::Vector{String})

Apply filtering based on filter_labels. Drops features given in filter_labels from the field.

Arguments

• ed::ExperimentData: The ExperimentData object that FilterFields should be applied on
• sym::Symbol: The field of ExperimentData on which FilterFields would be defined
• filter_labels::Vector{String}: The list of labels of the features that need to be dropped.

FilterFields(ed, sym, filter_idxs::Vector{Int})

Apply filtering based on filter_idxs. Drops features given in filter_idxs from the field.

Arguments

• ed::ExperimentData: The ExperimentData object that FilterFields should be applied on
• sym::Symbol: The field of ExperimentData on which FilterFields would be defined
• filter_idxs::Vector{Int}: The list of indices of the features that need to be dropped.

PreProcessingChain

Sequence of transformations to prepare data for surrogatization.

A PreProcessingChain can be created from any collection of AbstractTransformation objects. The transformation can be a defined transformation such as MinMaxNorm or ZScore, or a CustomTransform that allows to apply user defined functions for a given field in ExperimentData object. Calling the PreProcessingChain on ExperimentData returns a new preprocessed ExperimentData object with given transformations applied on the respective fields.

Defining a PreProcessingChain:

Examples

# define a MinMaxNorm 
lb, ub = get_lb(ed, :states), get_ub(ed, :states)
step1 = MinMaxNorm(lb, ub, (-1.0, 1.0))

lb, ub = get_lb(ed, :ps), get_ub(ed, :ps)
step2 = MinMaxNorm(lb, ub, (0.0, 1.0))

# construct the chain 
preprocess_chain = PreprocessingChain(step1, step2)

# Add a custom function to `PreProcessingChain` through `CustomTransform`
f(x) = sin(pi*x)
step3 = CustomTransform(f, :controls)

custom_preprocess_chain = PreprocessingChain(step1, step2, step3)

(c::PreProcessingChain)(ed::ExperimentData)

Calling PreProcessingChain on ExperimentData object returns a new ExperimentData object with the given transformations applied to the corresponding fields.

Examples

lb, ub = get_lb(ed, :states), get_ub(ed, :states)
step1 = MinMaxNorm(lb, ub, (-1.0, 1.0))

preprocess_chain = PreprocessingChain(step1)

preprocessed_ed = preprocess_chain(ed)

train_valid_split(ed::ExperimentData; train_ratio=0.8, validation_ratio=1 - train_ratio)

Given a dataset, split it into a training set and validation set, following a train_ratio and validation_ratio respectively.

PortConfig(; solve_with = :states,
             solve_for = :states,
             autonomous = true,
             paramterized = true)
PortConfig(solve_for, [autonomous = true], [parameterized = true])

Define a standard configuration for the ports used to train surrogates

Models and Surrogates in JuliaSimSurrogates follow a common API which looks like

model(u, x, p, t)

PortConfig constructs a standard port configuration for setting up ports for the (u, x, p, t) arguments, as well as for the ground truth.

Keyword Arguments

• solve_with: Controls the field used to populate the u argument. (Defaults to :states)
• solve_for: Controls the field used to populate the ground truth port. (Defaults to :states)
• autonomous::Bool: Indicate whether the problem is autonomous; ie whether it has inputs. (Defaults to true)
• parameterized::Bool: Indicate whether the problem has parameters. (Defaults to true)