English
Log in
English

Top Tips for Using the OnScale MATLAB® Toolbox

By Chloe Allison 22 October 2020

Learning how to use any new tool can be a daunting task. So, we have put together some of our top tips for using the new OnScale MATLAB® toolbox.

Setup

When setting up a model there are a couple of tips we recommend. Firstly, you must always initialize your OnScale account if you wish to run a job on the cloud. However, you only need to do this once. Once you have typed in your OnScale credentials once, you can save your details into a *.mat file to use in future simulations.

MATLAB® toolbox

Example code to save account credentials for future use

Another tip when setting up a model is to change the job name every time you create a new version of the model. When jobs are submitted to the cloud, the date and time is appended to the job name in the format JobName-HHMMSS-YYMMDD (e.g. Mesh_Sweep-095156-071020). However, this can become confusing if you are constantly tweaking the model and re-submitting. To avoid confusion, we recommend creating the job name as a variable at the top of the script.

General Simulation Code

Example code to pass job name as a variable

It is also important to note that models do not need to be setup from scratch in MATLAB®. Any model created in the OnScale user interface (UI) can be run in the toolbox by passing in the input file (*.flxinp) to the Job function.

MATLAB® toolbox

Example code to create job for existing input file

Parameters in existing input files can also be controlled from the toolbox. Any input parameter set in the toolbox will overwrite that parameter in the input file.

MATLAB® toolbox

Example code to overwrite input parameter

Job Submission

A key tip for job submission is to save the job information after submitting every job so that you have access to this data later. This is especially useful if you plan to do post processing on the job in the future. Saving the job information means you can easily download and post process the job without having to go rooting around in the OnScale UI for the job name and ID. Multiple jobs can also be saved into the same file and then imported by choosing either the name of the job or the date it was created.

Example Code

Example code to save job information

The toolbox automatically reports the progress of simulations that are running in the console. However, you can unsubscribe from this so that MATLAB® does not lock and you can continue to do work.

MATLAB® toolbox

Example code to turn off job progress

Download and Post Processing

A common question asked is if the toolbox you can download jobs that have not been run through the toolbox. The answer is yes. To do so, you must go to the OnScale UI to obtain the job name and ID. You can find all jobs by selecting the Job Status button in the Home ribbon. This opens a list of all jobs which you sort by name, date etc. When you find the job, double click on it and it will open a tab which contains the job name and ID.

OnScale UI

Image of job opened in OnScale UI showing job name and ID

 

OnScale

Example code for how to download a job ran via the OnScale UI

If you are only interested in downloading specific files from a job, you can do this by setting a specific file extension before downloading. This is especially useful when running large sweeps.

Example Code

Example code to download specific file types

Sometimes you might encounter the error ‘Unable to download until job is complete.’ This means that the job has finished but the file transfer is not yet completed. For simulations which are generating a lot of files, a good tip if you experience this error is to put a pause before downloading the job to ensure all files are ready.

Pause Script

Example code to pause script

Help

The toolbox contains inbuilt help documentation covering the syntax for all functions as well as how to’s and examples. This can be accessed in multiple ways. Check out this article for more details.

For help on getting started head over to our Help Center.

Debugging

The toolbox has built in error checking to ensure that things are being used the way they are supposed to. There are two types of errors that you may encounter, MATLAB® and OnScale errors. A MATLAB® error will be red and look like the following:

MATLAB® toolbox

Example of MATLAB® error

The error should give an indication of what parameter is incorrect and what the options are. However, if this is not clear, you can click on the error and it will take you to the line of code in the toolbox causing the error. From there, you can debug by putting in a break point at the line causing the error and run the code again.

On occasion you may encounter OnScale errors in the console (if running locally). OnScale errors look like the following:

OnScale

Example of OnScale error

For OnScale errors, check the print file (*.flxprt) to get more information. The file should indicate where the error occurs.

If you submit a job to the cloud and it fails, you will be notified in the console. For example:

If this occurs you can download the print file (*.flxprt)  for further investigation.

MATLAB® toolbox

Example code to download print files

That is our top tips for using the new OnScale MATLAB® toolbox. If you have any questions, please post them on our forum.

If you have not yet downloaded the toolbox get it for free here!

Chloe Allison
Chloe Allison

Chloe Allison is an Application Engineer at OnScale. She received her MA in Electrical and Electronics Engineering from the University of Strathclyde. As part of our engineering team Chloe assists with developing applications, improving our existing software and providing technical support to our customers.