Utilities

Here we can find the documentation for the utility classes and functions implemented in the Combustion Toolbox (CT).

Display subpackage

The display subpackage contains functions and classes designed to assist with visualizing and presenting data. These utilities are useful for generating plots to aid in the analysis and interpretation of results obtained from the CT modules.

PlotConfig

The PlotConfig class provides a set of predefined plot configurations that can be used to customize the appearance of plots generated by the Combustion Toolbox.

Routines

class PlotConfig(varargin)

Bases: handle

Class to store plot configuration data

position

Default figure position [pixels]

Type:

float

innerposition

Set figure inner position [normalized]

Type:

float

outerposition

Set figure outer position [normalized]

Type:

float

linestyle

Set line style for plots

Type:

char

symbolstyle

Set symbol style for plots

Type:

char

linewidth

Set line width for plots

Type:

float

fontsize

Set fontsize

Type:

float

colorpalette

Set Color palette (see brewermap function for more options)

Type:

char

colorpaletteLenght

Set Maximum number of colors to use in the color palette

Type:

float

box

Display axes outline

Type:

char

grid

Display or hide axes grid lines

Type:

char

hold

Retain current plot when adding new plots

Type:

char

axis_x

Set x-axis limits

Type:

char

axis_y

Set y-axis limits

Type:

char

xscale

Set x-axis scale (linear or log)

Type:

char

yscale

Set y-axis scale (linear or log)

Type:

char

xdir

Set x-axis direction (normal or reverse)

Type:

char

ydir

Set y-axis direction (normal or reverse)

Type:

char

title

Set title

Type:

char

label_type

Set label with variable (short), name (medium), or name and variable (long)

Type:

char

labelx

Set x label

Type:

char

labely

Set y label

Type:

char

legend_name

Set legend labels

Type:

char

legend_location

Set legend location

Type:

char

colorline

Default colorline

Type:

float

colorlines

Default colorlines

Type:

float

blue

Default colorline

Type:

float

gray

Default colorline

Type:

float

red

Default colorline

Type:

float

orange

Default colorline

Type:

float

brown

Default colorline

Type:

float

brown2

Default colorline

Type:

float

id_polar1

Axes id for pressure-deflection polar diagrams

Type:

float

id_polar2

Axes id for wave-deflection polar diagrams

Type:

float

id_polar3

Axes id for velocity polar diagrams

Type:

float

PlotConfig(varargin)

Class constructor

axis_x = "'tight'"

Set x-axis limits

axis_y = "'auto'"

Set y-axis limits

blue = '[0.3725, 0.7373, 0.8275]'

Default colorline

box = "'off'"

Display axes outline

brown = '[200, 190, 183]/255'

Default colorline

brown2 = '[72, 55, 55]/255'

Default colorline

colorline = '[44, 137, 160]/255'

Default colorline

colorlines = '[135, 205, 222;                      95, 188, 211;                      44, 137, 160;                      22,  68,  80]/255'

Default colorlines

colorpalette = "'Seaborn'"

Set Color palette (see brewermap function for more options)

colorpaletteLenght = '11'

Set Maximum number of colors to use in the color palette

fontsize = '22'

Set fontsize

gray = '[0.50, 0.50, 0.50]'

Default colorline

grid = "'off'"

Display or hide axes grid lines

hold = "'on'"

Retain current plot when adding new plots

id_polar1 = '1001'

Axes id for pressure-deflection polar diagrams

id_polar2 = '1002'

Axes id for wave-deflection polar diagrams

id_polar3 = '1003'

Axes id for velocity polar diagrams

innerposition = '[0.05 0.05 0.9 0.9]'

Set figure inner position [normalized]

label_type = "'short'"

Set label with variable (short), name (medium), or name and variable (long)

labelx = '[]'

Set x label

labely = '[]'

Set y label

legend_location = "'northeastoutside'"

Set legend location

legend_name = '[]'

Set legend labels

linestyle = "'-'"

Set line style for plots

linewidth = '1.8'

Set line width for plots

orange = '[212, 85, 0]/255'

Default colorline

outerposition = '[0.05 0.05 0.9 0.9]'

Set figure outer position [normalized]

position = None

Default figure position [pixels]

red = '[0.64,0.08,0.18]'

Default colorline

symbolstyle = "'o'"

Set symbol style for plots

title = '[]'

Set title

xdir = "'normal'"

Set x-axis direction (normal or reverse)

xscale = "'linear'"

Set x-axis scale (linear or log)

ydir = "'normal'"

Set y-axis direction (normal or reverse)

yscale = "'linear'"

Set y-axis scale (linear or log)

Functions

A collection of functions in the display subpackage.

Routines

getMonitorPositions(varargin)

Routine that gets the position in pixels of the monitor(s) connected to the device using Java (default) or MATLAB’s routines. If no monitor is specified, the position of the main monitor is returned.

Optional Args:

monitor_id (float): Get position in pixels for the given monitor

Returns:

position (float) – Position of the monitor(s)

Examples

• position = get_monitor_positions() returns the position of the main monitor

• position = getMonitorPositions(2) returns the position of the second monitor

• position = getMonitorPositions(1) returns the position of the first monitor

• position = getMonitorPositions(monitor_id) returns the position in pixels of the given monitor

Notes

This function first tries using Java to get the screen size values that do not take into account ui scaling, so it will return the proper screen size values. Otherwise, it gets the screen position using MATLAB’s routines

getMonitorPositionsMATLAB(varargin)

Routine that gets the position in pixels of the monitor(s) connected to the device using MATLAB’s routines. If no monitor is specified, the position of the main monitor is returned.

Optional Args:

monitor_id (float): Get position in pixels for the given monitor

Returns:

position (float) – Position of the monitor(s)

Examples

• position = get_monitor_positions() returns the position of the main monitor

• position = getMonitorPositions(2) returns the position of the second monitor

• position = getMonitorPositions(1) returns the position of the first monitor

• position = getMonitorPositions(monitor_id) returns the position in pixels of the given monitor

getTitle(obj)

Get a title based on the problem type and species involved

Parameters:

obj (Mixture) – Mixture object

Returns:

titlename (char) – Title based on the problem type and species involved

interpreterLabel(property, varargin)

Interpreter label for properties - returns property name

Note

The ‘interpreter_label.m’ routine considers that the properties are in mass basis. This will be fixed in a future patch.

Parameters:

property (char) – Property name

Optional Args:

• type (char): Type of label to return. Can be ‘short’, ‘medium’ or ‘long’ (default: medium)

• FLAG_BASIS (bool): Flag indicating label with basis, e.g., kg or mol (default: true)

• basis (char): Specific basis (default: kg)

Returns:

value (char) – Corresponding name of the property

plotComposition(obj, x_var, x_field, y_field, varargin)

Plot molar fractions againts any variable

Parameters:

• obj (Mixture) – Data of the mixture, conditions, and databases

• x_var (cell) – Properties of the mixture for all the cases

• x_field (char) – Field name for the x-axis data

• y_field (char) – Field name for the y-axis data

Optional Name-Value Pair Args:

• validation (struct): Struct that contains validations with (x_field, y_field)

• nfrec (float): Frequency points to plot validations

• mintol (float): Minimum limit i-axis with the composition of the mixture

• displaySpecies (cell): List of species to plot

• y_var (cell): Get y-axis data from a different mixture

• config (struct): Struct with the configuration for plots

• axis_x (char): Set x-axis limits

• axis_y (char): Set y-axis limits

• xscale (char): Set x-axis scale (linear or log)

• yscale (char): Set y-axis scale (linear or log)

• xdir (char): Set x-axis direction (normal or reverse)

• ydir (char): Set y-axis direction (normal or reverse)

• ax (object): Handle of the axes to plot on

Returns:

Tuple containing

• ax (object): Handle of the axes

• fig (object): Handle of the figure

Examples

• [ax, fig] = plotComposition(mixArray(1), mixArray, ‘equivalenceRatio’, ‘Xi’)

• [ax, fig] = plotComposition(mixArray(1), mixArray, ‘equivalenceRatio’, ‘Xi’, ‘y_var’, mixArray2)

• [ax, fig] = plotComposition(mixArray(1), mixArray, ‘equivalenceRatio’, ‘Xi’, ‘y_var’, mixArray2, ‘validation’, resultsCEA)

• [ax, fig] = plotComposition(mixArray(1), mixArray, ‘equivalenceRatio’, ‘Xi’, ‘y_var’, mixArray2, ‘validation’, resultsCEA, ‘displaySpecies’, displaySpecies)

plotFigure(x_field, x_var, y_field, y_var, varargin)

Plot figure with customizable settings

Note

The ‘interpreterLabel.m’ routine considers that the properties are in mass basis. This will be fixed in a future patch.

Parameters:

• x_field (char) – Field name for the x-axis data

• x_var (cell) – Cell array containing the x-axis data

• y_field (char) – Field name for the y-axis data

• y_var (cell) – Cell array containing the y-axis data

Optional Name-Value Pair Args:

• config (struct): Struct with the configuration for plots

• leg or legend (cell): Cell array of strings containing the legend names

• legend_location (char): Location of the legend

• ax or axes (object): Handle of the axes to plot on

• linestyle (char): Line style

• linewidth (float): Line width

• fontsize (float): Font size

• title (char): Title of the figure

• labelx, xlabel, label_x, or x_label (char): x-axis label

• labely, ylabel, label_y, or ‘y_label (char): y-axis label

• label_type (char): Label type

• xscale (char): Set x-axis scale (linear or log)

• yscale (char): Set y-axis scale (linear or log)

• xdir (char): Set x-axis direction (normal or reverse)

• ydir (char): Set y-axis direction (normal or reverse)

• color (float): Line color [R, G, B]

Returns:

Tuple containing

• ax (object): Handle of the axes

• dline (object): Handle of the plotted line

plotPolar(mixArray1, mixArray2, varargin)

Routine to obtain shock polar plots, namely:

• Plot (pressure, deflection)

• Plot (wave angle, deflection)

• Plot (velocity_x velocity_y)

Parameters:

• mixArray1 (Mixture) – Mixture object with the pre-shock state

• mixArray2 (Mixture) – Mixture object with the post-shock state

Optional Args:

• mix2_case (Mixture): Mixture object with the post-shock state (case 2)

• mix0 (Mixture): Mixture object with the post-shock state (case 0)

Returns:

Tuple containing

• ax1 (object): Handle of the axes with (pressure, deflection)

• ax2 (object): Handle of the axes with (wave angle, deflection)

• ax3 (object): Handle of the axes with (velocity_x velocity_y)

Examples

• [ax1, ax2, ax3] = plotPolar(mixArray1, mixArray2)

• [ax1, ax2, ax3] = plotPolar(mixArray1, mixArray2, mix2_case, mix0)

plotProperties(x_field, x_var, y_field, y_var, varargin)

Plot figure with customizable settings

Parameters:

• x_field (cell) – Cell array containing field names for the x-axis data

• x_var (cell) – Cell array containing the x-axis data

• y_field (cell) – Cell array containing field names for the y-axis data

• y_var (cell) – Cell array containing the y-axis data

Optional Name-Value Pair Args:

• config (plotConfig): object with the plot configuration

• leg or legend (cell): Cell array of strings containing the legend names

• legend_location (char): Location of the legend

• ax or axes (object): Handle of the axes to plot on

• linestyle (char): Line style

• linewidth (float): Line width

• fontsize (float): Font size

• title (char): Title of the figure

• labelx, xlabel, label_x, or x_label (char): x-axis label

• labely, ylabel, label_y, or ‘y_label (char): y-axis label

• label_type (char): Label type

• xscale (char): Set x-axis scale (linear or log)

• yscale (char): Set y-axis scale (linear or log)

• xdir (char): Set x-axis direction (normal or reverse)

• ydir (char): Set y-axis direction (normal or reverse)

• color (float): Line color [R, G, B]

Returns:

mainfigure (obj) – Figure object

setFigure(varargin)

Initialize figure with a standard composition

Optional Args:

• ax (axis): Figure axis

• config (struct): Struct with default plot parameters

Returns:

Tuple containing

• ax (axis): Axis of the standard figure

• config (struct): Struct with default plot parameters

• fig (figure): Standard figure

Example

[ax, config, fig] = setFigure(); [ax, config, fig] = setFigure(ax); [ax, config, fig] = setFigure(config); [ax, config, fig] = setFigure(ax, config);

See also: plot_settings

setLegends(ax, legend_name, varargin)

Set legend to the given axes

Parameters:

• ax (object) – Handle to the axes

• legend_name (cell) – Cell array of char containing the legend names

Optional Name-Value Pairs Args:

• config (struct): Struct containing the configuration parameters for the plots

• obj (object): Handle to the plotted objects (e.g. lines, patches, etc.)

setTitle(ax, varargin)

Set legend to the given axes

species2latex(species, varargin)

Convert species name into LateX format

Parameters:

species (char) – Species name

Optional Args:

FLAG_BURCAT (bool): If true, do not remove Burcat database prefix (default: true)

Returns:

speciesLatex (char) – Species name in LateX format

Examples

• species2latex(‘H2ObLb’)

• species2latex(‘Si2H6_M’)

• species2latex(‘Si2H6_M’, false)

Math subpackage

The math subpackage includes a variety of mathematical functions that are essential for performing numerical calculations.

Routines

computeFirstDerivative(x, y)

Compute first central derivate using a non-uniform grid

Parameters:

• x (float) – Grid values

• y (float) – Values for the corresponding grid

Returns:

dxdy (float) – Value of the first derivate for the given grid and its corresponding values

getOrder(value)

Get order of magnitude of a number in base 10

Parameters:

value (float) – number in base 10

Returns:

order (float) – order of magnitude of a number in base 10

Example

order = getOrder(0.0001)

Optimization subpackage

The optimization subpackage includes algorithms for minimizing or maximizing objective functions, solving constrained and unconstrained optimization problems.

Routines

simplex(A, b, c)

Use simplex method to solve the next linear programming problem:

• min c’x,

• A * x = b,

• x >= 0.

Parameters:

• A (float) – Coefficient matrix for the equality constraints (Ax = b)

• b (float) – Right-hand side vector of the equality constraints

• c (float) – Coefficient vector of the objective function (minimize c’x)

Returns:

x (float) – Optimal solution vector

Example

x = simplex(A, b, c)

simplexCheck(A, b, c)

Use Matlab’s simplex method to solve the next linear programming problem:

• min c’x,

• A * x = b,

• x >= 0.

Parameters:

• A (float) – Coefficient matrix for the equality constraints (Ax = b)

• b (float) – Right-hand side vector of the equality constraints

• c (float) – Coefficient vector of the objective function (minimize c’x)

Returns:

x (float) – Optimal solution vector

Example

x = simplexCheck(A, b, c)

simplexDual(A, b)

Use simplex method to solve the next linear programming problem:

• max(min x) -> max t,

• A * x = b,

• x >= 0.

Parameters:

• A (float) – Coefficient matrix for the equality constraints (A * x = b)

• b (float) – Right-hand side vector of the equality constraints

Returns:

x (float) – Optimal solution vector x_min (float): Minimum value of x

Example

[x, x_min] = simplexDual(A, b)

simplexDualCheck(A_eq, b_eq, c, A_ineq, b_ineq)

Use Matlab’s simplex method to solve the next linear programming problem:

• max(min x) -> max t,

• A * x = b,

• x >= 0.

Parameters:

• A_eq (float) – Coefficient matrix for the equality constraints (A * x = b)

• b_eq (float) – Right-hand side vector of the equality constraints

• c (float) – Coefficient vector of the objective function max t -> min -t

• A_ineq (float) – Coefficient matrix for the inequality constraints (x_j - t >= 0)

• b_ineq (float) – Right-hand side vector of the inequality constraints

Returns:

x (float) – Optimal solution vector x_min (float): Minimum value of x

Example

[x, x_min] = simplexDualCheck(A_eq, b_eq, c, A_ineq, b_ineq)

Extensions subpackage

The extensions subpackage is designed for third-party functions. It includes utilities and tools developed by external contributors that extend the capabilities of the Combustion Toolbox.

• Combustion Toolbox’s color palette is obtained from the following repository: Stephen (2021). ColorBrewer: Attractive and Distinctive Colormaps (https://github.com/DrosteEffect/BrewerMap), GitHub. Retrieved December 3, 2021.

• For validations, Combustion Toolbox uses CPU Info from the following repository: Ben Tordoff (2022). CPU Info (https://github.com/BJTor/CPUInfo/releases/tag/v1.3), GitHub. Retrieved March 22, 2022.

• Combustion Toolbox’s splash screen is based on a routine from the following repository: Ben Tordoff (2022). SplashScreen (https://www.mathworks.com/matlabcentral/fileexchange/30508-splashscreen), MATLAB Central File Exchange. Retrieved October 15, 2022.

Other functions and classes

This section includes various other utility functions and classes that don’t fall under the specific subpackages mentioned above. These general-purpose tools support a wide range of tasks within the Combustion Toolbox.

Export

The Export class provides functionalities to export results into different formats.

Routines

class Export(varargin)

Bases: handle

Class to export and save data to different formats (Excel, CSV, and mat)

Export(varargin)

Class constructor

FLAG_PROMT = None

Flag to show promt to save data

compositionUnit = None

Composition unit (kg or mol)

compositionVariable = None

Composition variable (molar fraction)

export(mixArray, varargin)

Export results of reactants (mix1) and products (mix2) into a .xls file

Parameters:

• obj (Export) – Export object

• mixArray (Mixture) – Array of mixture objects

Optional Args:

• mixArray_i (Mixture): Additional arrayy of mixture objects

Examples

• exportResults(Export(), mixArray1)

• exportResults(Export(), mixArray1, mixArray2)

• exportResults(Export(), mixArray1, mixArray2, mixArray3)

filename = None

Filename to save data

format = None

Format to save data (Excel, CSV, or mat)

generateMatrix(mixArray, listSpecies, equivalenceRatio)

Construct a cell with the thermodynamic data of the given mixture

Parameters:

• obj (Export) – Export object

• mixArray (Mixture) – Mixture object

• listSpecies (cell) – List of species

• equivalenceRatio (float) – Vector of equivalence ratio

Returns:

data (cell) – Cell array with the thermodynamic data of the given mixture

Example

data(Export(), mixArray, {‘CH4’, ‘O2’, ‘CO2’, ‘H2O’}, [0.5, 1.0, 1.5])

SystemUtils

The SystemUtils class contains utility functions for system operations, such as identifying the operating system and opening URLs in the default web browser. This class provides convenient methods to interact with the system environment, aiding in the integration and functionality of the Combustion Toolbox.

Routines

class SystemUtils

Bases: handle

SystemUtils - A class containing utility functions for system operations

Examples

• SystemUtils.openWebsite(’https://combustion-toolbox-website.readthedocs.io/’);

• SystemUtils.openWebsite(SystemUtils.url.documentation);

• os = SystemUtils.getOS();

static getOS()

This function returns a char indicating the operating system.

Returns:

os (char) – Operating system

Example

os = SystemUtils.getOS();

static openWebsite(url)

Open website in default web browser

Example

SystemUtils.openWebsite(’https://combustion-toolbox-website.readthedocs.io/’)

url = 'getUrl()'

URLs

static websiteCT()

Open Combustion Toolbox’s website in default web browser

Uncategoized

Uncategorized utility functions and classes that do not fit into any of the specific subpackages are included here.

Routines

checkUpdate(varargin)

Check if there is a new release of the Combustion Toolbox

Optional Args:

fig (object): UIFigure class

Returns:

Tuple containing

• FLAG_UPDATE (bool): FLAG indicating true (false) if there is (not) an update of the Combustion Toolbox

• message (char): Message displayed

Examples

• [FLAG_UPDATE, message] = check_update();

• [FLAG_UPDATE, message] = check_update(UIFigure);

clearCache()

Function to clear the variables stored in the cache

Example

clearCache()

findIndex(LS, species)

Find the index of the species based on the given list (LS)

Parameters:

• LS (cell) – List of species

• species (cell) – Species to find index values

Returns:

index (float) – List with the index of the species based on the given list (LS)

Example

index = findIndex({‘H2O’, ‘CO2’, ‘CH4’}, {‘H2O’, ‘CH4’})

generateID(value)

Generate a deterministic UUID (Universally Unique Identifier) based on the input character array

Parameters:

value (char) – Input character array used to generate the UUID

Returns:

id (char) – UUID generated from the input character array

Example

id = generateID(‘this_is_an_example’)

getAir(FLAG_IDEAL_AIR)

Define the chemical species that compound air and its molar composition

Parameters:

FLAG_IDEAL_AIR (bool) – Flag indicating consider ideal or non-ideal air mixture

Returns:

Tuple containing

• listSpecies (cell): List of species

• moles (float): Array with molar composition

printConvergence(it, itMax, T, STOP, TOL)

Print error of the method if the number of iterations is greater than maximum iterations allowed

Parameters:

• it (float) – Number of iterations executed in the method

• itMax (float) – Maximum nNumber of iterations allowed in the method

• T (float) – Temperature [K]

• STOP (float) – Relative error [-]

• tol (float) – Relative tolerance [-]

timeFunction(f, nFrec, varargin)

Function to compute mean evaluation time of a given function f

Parameters:

• f (function) – Function to be evaluated

• nFrec (float) – Number of evaluations

Returns:

Tuple containing

• tMean (float): Average evaluation time

• tArray (float): Array with the evaluation times

Note: The function needs at least one input

Example

[tMean, tArray] = timeFunction(@Example_TP_scoggins2015, 10)