User Guide

SimLab User Guide is divided into two main sections: 

• Demo Quickstart: a short tutorial introducing the SimLab workflow  

• SimLab Workflow Phases: more specific information on different phases (Design, Monitor, Analyze and Visualize) of the SimLab workflow.

Demo Quickstart

In this tutorial, we'll introduce the SimLab workflow by going through the steps of designing, monitoring and analyzing a simulation campaign. Tutorial has the following steps: 

• Login to SimLab 

• Design a Campaign

• Run Campaign and Monitor Progress

• Analyze Campaign Results 

Login to SimLab  

With your browser, navigate to https://demo.magistersimlab.com and log in with your credentials.

Design a Campaign 

Once logged in, you are taken to the Home in which SimLab greets you welcome. The Home view shortly introduces the logical parts (or phases) of SimLab workflow which are Design, Simulate and Analyze. 

Below the workflow boxes you'll see your simulation campaigns with their statuses. You'll notice in the image below that I've created a couple of example campaigns beforehand, but they have not yet been run.  

Click Design to start the design of a simulation campaign. 

Create a New Campaign

In Step 1 of Design phase, You'll create a new campaign from a campaign template. Satellite Network Simulator 3 (SNS3) and the Aeronautic template is used as an example. 

Click Add new campaign in the upper right corner to open the campaign creation dialog.

Select Campaign template. 

Write aero test as campaign name and Select Aeronautic X.YY.ZZ as the campaign template. Note that the version number of the template might differ from the image below. Campaign templates define basis values for specific simulation use cases and are to be later customized for more specific simulation cases.

After selecting the campaign template, template parameters are visible below the template selection box. Click Create to confirm campaign creation.  

Now you are back at Step 1 of Design phase, with the newly created campaign selected.

Next up is Step 2 (Scenario). In the lower right corner of the screen, Click Scenario to open the simulation scenario view. 

View Scenario 

SNS3 Aeronautic is a simulation use case which supports an example scenario view out of the box. Not all simulators do so, and some may require a dry-run of a simulation after configuring the parameters, as parameter configuration can influence how the scenario looks.

Scenario is shown as a 3D visualization on top of the Earth. From the upper left corner, you can adjust beam transparency and track an entity such as a Satellite or a Gateway. From the upper right corner, you can switch between globe and flap map views and return to the home position of the scenario.

From the lower right corner of the screen (or from the top 1-2-3 navigation), Click Parameters to navigate to Step 3 Parameters.

Edit Parameters

Simulation parameters are divided into different categories based on their purpose. The categories are shown in the top left corner of the table. 

Click Common to view the parameters in that category.

Depending on the type of the parameter, a certain control is used to modify the parameter value(s). The control can be e.g. 

• on-off slider, with option "both" for creating one simulation for true value and one for the false value;

• selection list with checkboxes; and 

• text box 

In case you would select multiple values for a single parameter, all combinations of parameter values are created as separate simulations. From these, you can later select which combinations are to be executed (see section Simulate).

Parameters with a free-form text input incorporate validation to prevent the input of faulty values. Nevertheless, Note that simulation campaign parameter editing is to be done with care. A parameter can have dependencies and misconfiguring it (or the dependent parameters) can cause simulations to fail. 

Let's add a few simulation times. The default simulation duration is +2s. 

Insert values +5s, +8s, +10s and + 15s by clicking Add just below the line which shows +2s simulation time.

Now the campaign aero test is configured to have five (5) simulations with varying simulation durations. 

Click Launch in the bottom right corner of the screen to move to the launch tab.

Run Campaign and Monitor Progress 

In the previous step, a campaign with 5 simulations was configured.  

Click Select to run all simulations and then Run button in the bottom. A confirmation dialog appears. Click Run to confirm.

After confirming, you are automatically routed to the monitor view to see the progress of simulation campaign. Click the row for campaign aero test to expand it. You'll see that the simulations are either in queued, preparing or running state. 

As cloud resources are being prepared for the simulation run, there can be a delay of around five minutes before the simulations start to run.

Progress of individual simulations is tracked by progress bars. In addition to the progress of simulation run, there are preparation and finalizing steps for each simulation. 

Note that at this stage, it would be possible to cancel the campaign or simulation by clicking the control on the right side of the table row.  

Once the campaign has completed, you can utilize the automatic plotting feature to plot all results of the campaign with one click. On the right side of the screen on the campaign aero test row, click the analytics icon to auto-plot the results. 

You are routed to the Analyze view, where the final phase of SimLab workflow, i.e., analysis of simulation statistics, takes place. Let's continue from there in the next section.

Analyze Campaign Results

The Analyze phase of SimLab workflow entails detailed analysis of simulation statistics (Analyze) as well as visual representation of simulations (Visualization). You can add and remove individual statistics from the view, and clear to view altogether. Note that in the demo version of SimLab, you cannot save the view.

Modifying Statistics

Click the Pen icon on any of the statistics figures to modify figure properties, such as x and y axis titles, legend text and result color.

If you want to hide result(s) from a figure, Click on the corresponding result in the figure legend. Click again to show the hidden result. In the figure below, the results for simulations 3, 4 and 5 are hidden from the first figure.

Adding and Removing Statistics

From the bottom of the view, you can add more statistics to the view. It's possible to add statistic figures from other campaigns as well. 

Click the Graph icon (leftmost button) to open the Add Statistics dialog. Then select a campaign, simulation and result of your choosing to be added to the view. 

In the image below, the newly added statistic is shown in the bottom on the left side.

Remove a figure by clicking the trashcan in the upper right corner of the figure. Clear the view by clicking the trashcan button at the bottom of the view. After deletion of all statistics, the view is empty: 

Visualize a simulation

Click Visualize on the navigation panel to the left. This opens a Campaign and simulation selection. Select aero test and simulation number 5 to open the 3D visualization for viewing. 

To start the run of visualization and view airplane statistics let's do a couple of small adjustments: 

• adjust the slider in the lower left corner of the 3D view to have around 0.2x speed 

• select an airplane by double clicking 

• zoom away a bit (adjust as you see fit)

• from the cog menu on the left side of the screen, you may change beam transparency and enable tracked airplane path

• click on the play button in the lower left corner 

As a result, you'll likely see a similar view as the image below

Also note that by holding the left mouse button and moving the cursor around, you can rotate the view: 

This concludes the tutorial. Thanks for participating! 

SimLab Workflow Steps in Detail 

Below, the main features of SimLab are outlined per workflow phase.

Design 

Step 1: Campaign

• Campaign table shows the name, creation date, simulator, state and data packet related to the campaign, and also whether the campaign is currently selected or not.

• Design of a new campaign is based on a campaign template, which corresponds to a use case, or on a previously existing campaign

• Campaign templates have version numbers. In addition to bug fixes, newer versions may provide additional parameters to customize and more statistics to view as results 

• A previously run campaign cannot be re-run. Instead, one needs to create a new campaign based on the existing one. 

• Click a campaign row to show the parameters of the campaign

• Campaign name can be modified from the Pen icon 

• Campaign can be deleted from the trash can icon

• One can proceed to steps 2 and 3 only if a campaign is selected

Step 2: Scenario

• The view shows a 3D visualization of the simulation scenario.

• Upper left corner cog enables beam transparency setting and selecting a node (Satellite, Gateway) for tracking and zooming into 

• Upper right corner globe button switches between 3D and 2D map types, Home button returns the view to default and circled question mark shows the 3D view controls

Step 3: Parameters

• For the time being, parameters don't have detailed explanations (tooltips or similar). Therefore, the user of SimLab needs to be familiar enough with the simulator in use (and computer network system simulation in general) in order to configure parameters accordingly. 

• For certain parameters, there is an on-off slider and an associated checkbox. Three possible values exist: on, off, and both. The last one means that a simulation is defined which has the value as false, and another simulation which has the value as true. 

• All parameters can be reset, or just one parameter at a time. Resetting the values resets them to the default of the use case in question, i.e., the default value of the campaign template the campaign is based on. Note that this may differ for different use cases, for instance a parameter value can be on or off after the reset (the default value of the campaign template). 

• If multiple values are configured for multiple parameters, all possible combinations of parameters are formed. Later in the Launch step of Simulate phase, the user can select which simulations to run for the campaign.

• Care needs to be taken to configure all required parameters properly. Changing the value of a single parameter can also pose the requirement to change the value of multiple other parameters accordingly, for the configuration to make sense. Disabling a parameter may make multiple other parameters obsolete. 

• Some parameters highly influence the outcome of simulation(s), e.g. may enable or disable production of simulation statistics and / or visualization.  

Simulate

• In launch, user selects the simulations (from all possible combinations) which are executed by SimLab. Once the campaign run is started, the same campaign cannot be re-run with different simulations. 

• In Monitor, campaign row is expandable and clicking the campaign row shows the simulations of the campaign. Each simulation has a set of parameters, start time, end time, status and result. Progress bars are shown when the simulation has either running or finalizing status. 

• The result of simulation is either success or failure. The result of a campaign can be either success, failure or partial failure, the last option indicating that not all simulations of the campaign completed successfully.  

• Controls on the right side of the row make possible automatic plotting of campaign and simulation results. Note that some controls may not be available in the demo version. 

• When a simulation campaign is started, a delay of approximately five minutes can occur. This is due to the elastic resources for simulation campaign run being prepared on demand in the background. If a user runs multiple campaigns in a row, the resources are already there and a delay should not be experienced in campaigns other than the first one (and the five minute wait). 

Analyze

• User can save or discard report with the statistics added in the analyze view. 

• Statistics of a simulation are produced only if the parameter Enable statistics was set to true by the user, or the default value for the parameter was true and was not changed by user.

• Statistics can be added one by one, or in batch using statistic figure templates (SFTs) (all or selected simulations of a campaign)

• Statistics from multiple campaigns can be added to the view, but they need to be added one after the other (one dialog for each). 

• Depending on parameter configuration, selection of statistics is available. Some statistics may have infinite values and are thus not presented in figures (NaN or -NaN as text data). 

• A Figure can be customized to some extent. Figure and axis titles (x and y) are customizable as well as the legend text and graph colors. Individual results can be hidden from a figure by clicking the result name in the legend, and hidden results shown by clicking the result name in the legend again.  

• Statistics types of CDF, Scalar and Map are supported for now, and new statistics type(s) are to be supported in later releases. 

• Figures can be removed from the view one by one, or all at once by clicking the delete button at the bottom of the view. 

• Figures are shown in two columns and auto-scale to the screen size, depending on the zoom level (see image below). 

Visualize

• Visualization from one simulation is shown at the time. User selects the campaign and simulation to view.

• Controls of the Visualization 3D view are almost the same as for the scenario view in Design phase.

• Visualization of a simulation is produced only if the parameter Enable visualization was set to true by the user, or the default value for the parameter was true and was not changed by user.

• When a visualization is run, statistics of individual nodes (e.g. airplanes) can be observed in a figure, which is enabled by tracking a certain entity (upper left corner cog settings)

• User can increase the relative size of visualization window by zooming out (see image below).

Settings 

In SimLab settings, you can currently switch between the light (default) and dark color themes. 

You can also configure default statistic figure template (SFT) used per campaign template. The figures are then plotted according to this configuration , when user press 'Analyze' button of a campaign or a simulation row in Monitor view. In Analyze view this configuration is used as default selection in SFT selection lists.

The copyright notice is also shown.