Frontend Web application

The frontend was originally developed as Grails application, a Web framework based on the Groovy programming language. As Groovy runs on the Java Virtual Machine (JVM), this would allow us to integrate the backend Java API directly with the frontend. However, due to its matu- rity and extensive third-party library support, development was restarted using the Ruby on Rails Web framework. Ruby on Rails uses the Model-View-Controller (MVC) architecture pattern and adheres to REST principles when accessing resources. For example, POST is used to create new resources and PUT is used to update existing resources. The wealth of third-party libraries, known as ‘gems’, enabled rapid implementation of layouts, form generation, API communication and background processes.

The frontend has been designed in a manner that does not tightly couple classes to the API. Each stage of the emulation process is represented as a model class, and these classes refer to other

classes representing individual results. Each class representing a stage is required to implement two methods: one for generating a JSON request to send to the API and another to handle the response received. If changes are made to the API, only these two methods are affected. Instances of these classes exist in two states: the first when they are initially created, where they only contain parameters to send to the API, and the second after the API response has been handled, where they contain the parameters and results.

API integration

Any class using API functionality is referred to as being a ‘remotable’ class. A Remotable mod- ule, shown in Listing 4.3, was developed to allow such classes to inherit common characteristics, including fields to store the current status of remote communication with the API. A Remotable- Controlleris also defined, which acts as a generic controller for any remotable class. This con- troller exploits reflection features of the Ruby programming language to make dynamic references to fields and methods named after the current remotable object. For example, views typically rely on the controller to set instance variables containing the objects they display. To assist readabil- ity in the view, these variables will generally share the same name as the class. However, as the RemotableControllerhandles classes with several names, we must set these instance variables using a special method, as shown in Listing 4.4, which allows the variable name to be specified as a string, equal to the singular form of our class name.

module Remote

module Remotable

extend ActiveSupport::Concern included do

field :proc_start_time, type: DateTime field :proc_end_time, type: DateTime field :proc_status, type: String field :proc_message, type: String

validates_inclusion_of :proc_status, in: ["queued", "in_progress", "error", " success"], allow_blank: true

end

def queued?

self.proc_status == "queued"

end

# Remaining status methods removed for listing

end end

def edit

# find object and set instance variable

set_instance_object(instance_constantized.find(params[:id])) # translates to: # @design = Design.find(params[:id]) # @input_screening = InputScreening.find(params[:id]) end private def set_instance_object(object) instance_variable_set("@#{instance_singular}", object) end def instance_singular controller_name.classify.underscore.singularize end def instance_constantized controller_name.classify.constantize end

Listing 4.4: Using reflection to create dynamically named variables in the RemoteController.

Certain stages of the emulation process can take minutes, or even hours to perform on the API. While the number of simulator runs is significantly lower with emulation techniques than traditional UA and SA, hundreds, or even thousands of evaluations are still needed to build a good training design. It is crucial the Web application user is not required to leave their browser open, or have any other resources occupied until the API work is complete. Therefore, the frontend Web application must execute and manage long-running jobs asynchronously.

Delayed::Job3is a database-backed asynchronous queue system for Ruby. With Delayed::Job, any fragment of code can be added to a queue for asynchronous execution. Jobs are executed by one of a user-specified number of daemons, which run as separate processes on a system. Integration with Delayed::Job is implemented by the frontend in a generic manner. When creating a remotable resource, RemotableController generates the necessary JSON request, initialises and then enqueues a custom job for the remotable object. This job responds to Delayed::Job events, such as job success or fail, and updates the status fields in the object accordingly. When the job has completed successfully, the handle method in the object is called, which parses the response from the API and stores the results in the object.

While some processes may take several minutes to complete, others will take seconds. In these cases, a user is highly likely to keep their browser open and the frontend must therefore

display appropriate messages to keep the user informed of progress. To prevent users from having to manually refresh, a polling mechanism was implemented, where the client-side JavaScript code will repeatedly check the current status of the job. This utilises features of the Ruby on Rails framework, where instead of requesting the remotable resource as HTML, we request JavaScript. This JavaScript either tells the browser to display an ‘in progress’ message and request the same resource again in two and a half seconds, or to render the result. If the job was unsuccessful, the result will be an error message and an option to try the request again is provided.

Building an emulator

The Web application groups emulation stages into a project which represents the training and validation of a single output emulator. A project belongs to a user, and access control only allows the project to be viewed or modified by its owner. An emulation project is initially created by specifying a service URL, after which the frontend will issue a GetProcessIdentifiers request to the API. The user can then select a model to emulate from the resulting list of identifiers of compatible processes. Upon selection of a model, the frontend sends a GetProcessDescription request to retrieve the list of inputs and outputs. These are used to create a simulator specification — a model of the input and output descriptions. The remainder of this section will describe each stage of the frontend, illustrated by training and validating an emulator for the ‘SimpleSimulator’ model.

Figure 4.2: Updating input descriptions in the simulator specification.

where the user is required to select, for each input, whether the the value can be given as a range or fixed value. A range will be used to build designs for input screening, emulator training and validation, while fixed values will only be used to evaluate the simulator. If provided by the process description, additional input metadata, such as units of measure, is presented to the user.

Figure 4.3: Fixing an inactive input from the screening results view.

Once the simulator specification is complete, a user can perform screening to help identify inactive inputs. Inactive inputs can be excluded from the training design, thus reducing emulator complexity. Elementary effects values calculated by the API are added to an interactive plot, which allows adjustment to the level of zoom and visibility of inputs. After the user has identified inactive inputs, they can set an input to have a fixed value by clicking the point, as seen in Figure 4.3. Once set to a fixed value, the input will only be used to evaluate the simulator, and will not form part of the training design.

When specifying the size of the design to create for emulator training, a sensible default value is automatically set by the Web application, equal to the number of inputs multiplied by 15. To enable the emulator to be trained and validated multiple times without having to re-evaluate the simulator, the generated design points will be split between training and validation stages. The multiplication factor of 15 is to cover 10 times the number of inputs for training points, and 5 times the number of inputs for validation points. For example, if we have a simulator with 20 inputs, the default design size is 300, with 200 of those points used for training the emulator and 100 for validation. After a design has been generated by the API, histograms of the resulting points for each input are displayed, as shown in Figure 4.4. These histograms can help to ensure points

Figure 4.4: Histogram of the design points for input with identifier ‘Rainfall’.

in the generated design cover input space evenly. If so, the bars for each histogram bin will be the same height. A user may wish to generate a larger design if the space is insufficiently covered.

Once a satisfactory design has been generated, the simulator can be evaluated. Depending on the size of the design, this will typically take longer than other stages, proving an effective demonstration of the benefits provided by the asynchronous job mechanism. Upon completion, histograms of the resulting values for each output are available. Using these histograms, a user can check whether the specified input ranges are producing sensible simulator outputs.

As the frontend and API currently only support single output emulation, a user must select which output they wish to emulate. Figure 4.5 shows emulator training parameter setting, with the ‘FinalYield’ output selected to emulate. Other parameters can be set, including the size of the design used for training, whether to apply normalisation, a choice of mean and covariance functions, a length scale multiplier, and whether to include nugget variance for numerical stability or to model simulator randomness. Once training has completed, optimised parameters are re- turned to the user. It is possible to export the emulator at this stage, using the format discussed in Section 4.3.1, but validation should be performed first to ensure the trained emulator accurately represents the simulator.

Validation is performed by evaluating the emulator against the remainder of the design after training, and comparing the results with the corresponding simulator evaluation results. As both the training and validation designs are evaluated before the emulator training stage, validation does not require simulator evaluation, thus drastically reducing the time to perform validation on the API. A wide array of validation metrics are provided, most of which are displayed using interactive plots.

Figure 4.6: Standard score plot for the ‘SimpleSimulator’ example emulator.

The standard score plot can help determine whether the emulator is over or under confident. Figure 4.6 shows a standard score plot generated for the ‘SimpleSimulator’ example, and has the majority of scores between the two blue lines, indicating an under-confident emulator. Typically, a good emulator has 95% of scores between these lines. Figure 4.7 shows a mean residual histogram and QQ plot, for the purpose of checking the distribution of emulator errors. The visualisations

Figure 4.7: Histogram and QQ plot of mean residuals for the ‘SimpleSimulator’ example emulator.

provided at this stage are for diagnostic purposes — they help to inform the user if the emulator is not a good fit to the model, but also the reasons why it is not a good fit. If the results are unsatisfactory, a user can return to the training stage, adjust parameters, and train the emulator again. If the results are still unsatisfactory, a user can try increasing the size of the design, or fix certain inputs to provide emulator stability.

While the frontend provides a variety of visualisations to assist the user, advanced users may wish to perform additional data analysis. Results from the majority of the stages, including de- signs, runs, training, and validation can be exported in formats suitable for subsequent importing into MATLAB and R, and also a JSON object for use in other programming languages.