COMSOL 6.2 - model.func()

model.func().create(<tag>,<type>) creates a new function of type <type> with the tag <tag>. The types can be one of the following strings: Analytic, Interpolation, Piecewise, GaussianPulse, Ramp, Rectangle, Step, Triangle, Wave, NormalDistribution, Random, External, MATLAB (requires LiveLink™ for MATLAB®), Elevation, Image, LeastSquares, GaussianProcess (requires the Uncertainty Quantification Module to create and train but not to use a created and trained function), PolynomialChaosExpansion (requires the Uncertainty Quantification Module to create and train but not to use a created and trained function), DNN, and PartialFractionFit. In addition, model.create(<tag>,"FunctionSwitch") creates a function switch. You can add other functions to a function switch:

model.func().create("sw1", "FunctionSwitch");

model.func("sw1").create("int1", "Interpolation");

model.func("sw1").create("an1", "Analytic");

model.func("sw1").create("rn1", "Random");

Use model.func("sw1").set("definecases", true); to instantiate all functions for all cases in a function sweep. By default, not all of them are instantiated.

model.func(<tag>).createPlot(<pgtag>) creates a plot group with the tag pgtag with a plot of the function. The method returns the plot group.

model.func(<tag>).label(<label>) sets a label for the function.

model.func(<tag>).model(<mtag>) sets the model component node of the function.

model.func(<tag>).set(property,<value>) sets the value of a property of the function. See the available properties for each type of function below.

model.func(<tag>).set("funcname",<funcname>) sets the operator name of the function. The default operator name is <tag>.

model.func(<tag>).model() returns the model component node tag.

model.func(<tag>).getType(property) retrieves a value of a function property.

model.func(<tag>).importData() imports the file that the function references into the model. This is possible for interpolation, elevation, and image functions. The importData() method also works for some physics features.

model.func(<tag>).discardData() discards the data imported with importData(). This is possible for interpolation, elevation, and image functions. The discardData() method also works for some physics features.

model.func(<tag>).refresh() reevaluates the file for functions that read files (Elevation, Image, and Interpolation).

Use the model.func(<tag>).image() methods for plotting and exporting images showing plots of the functions. See Plotting and Exporting Images.

model.func(<tag).run() performs optimization or training for functions that need to process their input data before they can be evaluated (Least-Squares Fit, Gaussian Process, Polynomial Chaos Expansion, and DNN).

model.func(<tag>).functionNames() returns an array containing the function names that the function feature defines. Most functions always return an array of length one, but interpolation function features, for example, can define an arbitrary number of function names.

model.func(<tag>).getAllowedPropertyValues(property) returns the set of allowed values for a property if the set is a finite set of strings; otherwise, it returns null.

Function features can have associated problem features. To access the list of problem features for a function feature, use:

model.func(<tag>).problem();

To access a specific problem feature, use:

model.func(<tag>).problem(<problem_tag>);


	For functions on the component level, use the same syntax but add the component level, such as model.component(<ctag>).func().create(<tag>,<type>)


	When using a local table the interpolation function uses the funcname property to set the function name. When the data comes from a file or a result table, the name is specified in the funcs string matrix property. This is necessary because there can be more than one function.

What properties that are available depends on the type of function. The following function types are available:

Analytic

Create an analytic function using a symbolic expression.

Table 2-75: analytic properties.
name	Value	Default	Description
argders	Nx2 String array	{}	(argument, partial derivative) pairs if dermethod is manual.
args	String array	{}	The arguments to the function.
complex	boolean	false	True if the function can produce complex results for real inputs.
dermethod	automatic \| manual	Automatic	Automatic differentiation or manual control over the derivatives.
expr	String	None	The expression defining the function.
funcname	String	The tag name	The name of the function.
periodic	boolean	false	True if the function should be extended to a periodic function.
periodiclower	String	0	The lower limit of the interval that is extended periodically.
periodicupper	String	1	The upper limit of the interval that is extended periodically.
plotargs	N-by-3 array		Contains one row for each function argument. Each row contains the argument name, the lower limit for plotting, and the upper limit for plotting.
plotaxis	boolean array	{}	Contains one value for each function argument. A false value means that the corresponding function argument will be constant when plotting. The constant value is taken from the lower limit value in the plotargs property. Constant arguments do no use an axis in the plot. Up to 3 axes are supported when plotting. Specify using setIndex("plotaxis", false, 2), for example.
argunit	String		A comma-separated list of required units for each argument.
fununit	String		The unit of the function’s result.

Interpolation

Generate an interpolation function. You can use several interpolation and extrapolation methods.

Table 2-76: interpolation properties.
name	Value	Default	Description
defineinv	on \| off	off	If source is set to table: Whether to define the inverse function.
definerandom	on \| off	off	Whether to define a random function.
defvars	boolean	false	If source is file and defvars is set to true, the spatial coordinate variables are used as default arguments to the function if no arguments are supplied in a call to it.
dseparator	point \| comma	point	Decimal separator in interpolation data file, when source is set to file.
extrap	none \| const \| interior \| linear \| value	const	The extrapolation method.
extrapvalue	double	0	The extrapolation value if extrap is set to value.
filename	String		The file that contains the data if source is set to file.
frame	String	spatial	Frame used for defining the spatial coordinates if defvars is set to true.
funcinvname	String		If source is table and defineinv is on: The name of the inverse function.
funcname	String	The tag name	The name of the function if source is table or function.
funcs	String matrix		Used source is file; the first column contains function names and the second column contains the positions in the file where the corresponding function is defined.
interp	neighbor \| linear \| piecewisecubic \| cubicspline	piecewisecubic	The interpolation method.
leftend	double	0	The left end of the range for the random function, if randomrange = manual.
modelres	String		If sourcetype is model, specifies the model resource that contains the interpolation data
nargs	integer (1-3)	1	The number of function arguments if struct is spreadsheet or source is resultTable.
primfunname	String		Define a primitive function with the name give as primfunname.
randomname	String		Define a primitive function with the name give as primfunname.
randomnargs	integer	1	The number of arguments for the random function.
randomrange	automatic\|manual	automatic	Whether to define a range for the random function.
reinterp	boolean	false	If true, reinterpolate interpolation data on computational mesh. Available if defvars is true and frame is set to mesh.
reinterporder	positive integer	1	Lagrange shape function order for reinterpolation, if reinterp is set to true.
resultTable	String		The tag of the result table to use (tbl1, for example).
rightend	double	1	The right end of the range for the random function, if randomrange = manual.
points	positive integer	1000	The number of uniform sampling points, if sampling is set to uniform.
sampling	automatic \| uniform		Sampling type: automatic (uniform with 1000 sampling points) or uniform.
scaledata	auto \| on \| off	auto	Apply scaling of data if the bounding box of the interpolation points has a bad aspect ratio (auto), always apply the scaling (on), or turn off scaling altogether (off).
source	table \| file \| resultTable \| function	table	If sourcetype is user, specifies whether the data is entered in a local table, read from a file, taken from a results table, or is based on another function.
sourcetype	model \| user	user	Specifies if the data for the function is stored in the model or provided by the user.
scrfun	String		Name (tag) of the function used as source when source is set to function.
scrfunname	String		Function name of the function used as source when source is set to function.
struct	grid \| sectionwise \| spreadsheet	spreadsheet	The data format if source is set to file.
table	Nx2 String array	Empty	Contains the point/value pairs if source is set to table.
argunit	String		A comma-separated list of required units for each argument.
fununit	String		The unit of the function’s result.
argtrans	none \| logarithmic	none	No or logarithmic transformation of the argument.
valtrans	none \| logarithmic	none	No or logarithmic transformation of the function.

Piecewise

Generate a piecewise interpolation function, which is created by splicing together several functions, each defined on one interval.

Table 2-77: piecewise properties.
name	Value	Default	Description
arg	String	x	The argument to the function.
extrap	const \| interior \| none \| periodic \| value	const	The extrapolation method.
extrapvalue	double	0	The extrapolation value if extrap is value.
funcname	String	The tag name	The name of the function.
pieces	N-by-3 String array	Empty	(left, right, expression) for each interval.
smooth	none \| cont \| contd1 \| contd2	none	The type of smoothing.
smoothzone	double	0.1	The relative size of the smoothing zone if smoothing is enabled.
argunit	String		A comma-separated list of required units for each argument.
fununit	String		The unit of the function’s result.

GaussianPulse

Generate a Gaussian pulse function. This function is the common bell-shaped curve (Gaussian function).

Table 2-78: Gaussian pulse Properties.
name	Value	Default	Description
baseline	double	0	The baseline for the function.
funcname	String	The tag name	The name of the function.
integralvalue	double	1	The integral value, when normalization is set to integral.
location	String	0	Where the pulse peaks.
peakvalue	double	1	The peak value, when normalization is set to peak.
sigma	String	1	The standard deviation of the underlying normal distribution.
normalization	integral \| peak	integral	The normalization method to use.

Ramp

Generate a ramp function.

Table 2-79: Ramp Properties.
name	Value	Default	Description
baseline	double	0	The baseline for the function.
cutoffactive	boolean	false	If true, then the ramp ends when it reaches the cutoff value.
cutoff	double	1	If cutoffactive is true, the level where the ramp ends.
funcname	String	The tag name	The name of the function.
location	String	0	Where the ramp starts.
slope	String	1	The slope of the ramp.
ncontder	1 or 2	2	The number of continuous derivatives if smoothing is enabled.
smoothzonecutoffactive	boolean	false	Smooth the transition where the ramp ends at the cutoff?
smoothzonelocactive	boolean	false	Smooth the transition where the ramp starts?
smoothzonecutoff	double	0.1	The relative size of the smoothing zone for the cutoff, if smoothing is enabled.
smoothzoneloc	double	0.1	The relative size of the smoothing zone where the ramp starts, if smoothing is enabled.

Rectangle

Generate a rectangle-shaped function.

Table 2-80: Rectangle properties.
name	Value	Default	Description
amplitude	double	1	The amplitude for the function.
baseline	double	0	The baseline for the function.
funcname	String	The tag name	The name of the function.
lower	String	-0.5	Where the high zone begins.
ncontder	1 or 2	2	The number of continuous derivatives if smoothing is enabled.
smooth	boolean	true	Smooth the transitions?
smoothzone	String	0.1	The size of the smoothing zone on both sides of the transitions.
upper	String	0.5	Where the high zone ends.

Step

Generate a step function.

Table 2-81: Step properties.
name	Value	Default	Description
baseline	double	0	The baseline for the function.
from	String	0	The value to the left of the location.
funcname	String	The tag name	The name of the function.
location	String	0	Where the step is located.
ncontder	1 or 2	2	The number of continuous derivatives if smoothing is enabled.
smooth	boolean	true	Smooth the transition?
smoothzone	String	0.1	The size of the smoothing zone on both sides of location.
to	String	1	The value to the right of the location.

Triangle

Generate a triangle-shaped function.

Table 2-82: triangle properties.
name	Value	Default	Description
amplitude	double	1	The amplitude for the function.
baseline	double	0	The baseline for the function.
funcname	String	The tag name	The name of the function.
lower	String	-0.5	Where the high zone begins.
ncontder	1 or 2	2	The number of continuous derivatives if smoothing is enabled.
smooth	boolean	true	Smooth the transitions?
smoothzone	String	0.1	Size of smoothing zone on both sides of the transitions.
upper	String	0.5	Where the high zone ends.

Wave

Use a wave function to generate a wave-shaped function (waveform). The wave shape can be a sawtooth, sine wave, square wave, or triangle wave.

Table 2-83: wave properties.
name	Value	Default	Description
amplitude	String	1	The amplitude for the function.
baseline	String	0	The baseline for the function.
dutycycle	String	0.5	The duty cycle of the function (a value between 0 and 1). Available for Square functions (as the fraction of a period that the function has the high value) and for Triangle functions (as the fraction of a period that the function is rising).
funcname	String	The tag name	The name of the function.
ncontder	1 or 2	2	The number of continuous derivatives if smoothing is enabled.
period	String	2*pi	The period.
phase	String	0	The phase.
smooth	boolean	true	Smooth the transitions? (Only used for wave forms with discontinuous function values or derivatives.)
smoothzone	String	0.1	The size of smoothing zone on both sides of the transitions.
type	sawtooth \| sine \| square \| triangle	sine	The type of waveform.

NormalDistribution

Generate a normal distribution function.

Table 2-84: Normal Distribution properties.
name	Value	Default	Description
cumfuncname	String	The tag name + _cum	The name of the cumulative function.
funcname	String	The tag name	The name of the function.
invcumfuncname	String	The tag name + _cum_inv	The name of the quantile function.
mean	double	0	The mean of the function.
nargs	positive integer	1	The number of arguments to the random function.
randomname	String	rn_ + the tag name	The name of the random function.
seed	positive integer		A seed for the random function.
seedactive	boolean	false	Use a custom random seed?
sigma	double	1	The standard deviation of the function.

Random

Generate a random function. The random function can have a uniform or normal distribution.

Table 2-85: random properties.
name	Value	Default	Description
funcname	String	The tag name	The name of the function.
mean	String	0	The average value.
nargs	integer	1	The number of arguments.
normalsigma	String	1	The standard deviation if type is Normal.
seed	String	Unique for each random function	Random seed, if seedtype is set to manual.
seedactive	boolean	false	If true, the random seed will be used.
seedtype	manual \| currenttime	manual	The random seed type, if seedactive is true.
type	uniform \| normal	uniform	The distribution type.
uniformrange	String	1	The range if type is Uniform.

External

Generate an external function that interfaces to other external functions written in the C language.

Table 2-86: External properties.
name	Value	Default	Description
ders	Nx3 string array		(function name, argument, partial derivative) triplets.
funcs	String array		The functions defined by the library.
init	String		The string that is sent to the library when the function feature is initialized.
path	String		The path to the shared library that defines the functions.

An external function is a function defined in a shared library written by the user. The shared library must define the following three functions with C linkage:

•

int init(const char *str) is called when the function is initialized with the string from the field. It returns a nonzero value in case of success and zero in case of failure. This function might be called several times; it is always called before solving a model that uses the function.

•

int eval(const char *func, int nArgs, const double **inReal, const double **inImag, int blockSize, double *outReal, double *outImag) is called for elementwise evaluation of the function func called with nArgs arguments of length blockSize. The array inReal contains the real parts of the arguments; it has length nArgs, and each element has length blockSize.

If the arguments are all-real, then inImag is null; otherwise it contains the imaginary parts of the arguments. If the function evaluation is successful, 1 is returned if it resulted in an all-real array and 2 is returned if it resulted in a complex array. The function should return 0 in case of error. In case of a real result, the function values should be written to the array outReal. In case of a complex result, the real parts of the function should be written to outReal and the imaginary parts to outImag. The outReal and outImag arrays both have length blockSize. All matrices are allocated and deallocated by COMSOL.

•

const char *getLastError() returns the last error that has occurred. A null or empty string is returned if no error has occurred. Calling init() or eval() must set the last error string to "" or null. All memory allocation of this string is handled by the shared library. There is no localization of the error messages.

If you are using Microsoft Visual Studio to compile your library, you can declare the functions as __declspec(dllexport) to export them from the DLL.

An example of a library that defines a function called extsinc that computes the sinc function (sin(x)/x):

#define EXPORT __declspec(dllexport)

#else

#define EXPORT

#endif

static const char *error = NULL;

EXPORT int init(const char *str) {

return 1;

}

EXPORT const char * getLastError() {

return error;

}

EXPORT int eval(const char *func,

int nArgs,

const double **inReal,

const double **inImag,

if (strcmp("extsinc", func) == 0) {

if (nArgs != 1) {

error = "One argument expected";

return 0;

}

for (i = 0; i < blockSize; i++) {

double x = inReal[0][i];

outReal[i] = (x == 0) ? 1 : sin(x) / x;

error = "Unknown function";

return 0;

}

To compile this function into a library, place it in ext.c and proceed as follows depending on platform:


	See https://www.comsol.com/system-requirements for information about supported compiler versions.

•

64-bit Windows with Microsoft Visual Studio:

Start Microsoft Visual Studio > Visual Studio Tools > Visual Studio x64 Win64 Command Prompt (2010) from the Windows Start Menu.

cd to the directory that contains ext.c.

cl /MT /c ext.c

link /OUT:ext.dll /DLL ext.obj

•

64-bit Linux with Intel Compiler:

cd to the directory that contains ext.c.

icc -fPIC -c ext.c

icc -shared -fPIC -Wl,-z -Wl,defs -o ext.so ext.o -ldl

•

64-bit Mac with Intel Compiler:

cd to the directory that contains ext.c.

icc -fPIC -c ext.c

icc -dynamiclib -fPIC -o ext.dylib ext.o

For other compilers, refer to the compiler’s documentation for instructions how to compile and create a shared library.

MATLAB

Declare use of function in MATLAB. This requires the LiveLink™ for MATLAB®.

Table 2-87: MATLAB properties.
name	Value	Default	Description
ders	Nx3 string array		(function name, argument, partial derivative) triplets.
funcs	String array		The functions defined by MATLAB.

Elevation

Generate an elevation function by importing geospatial elevation data from digital elevation models (DEM files).

Table 2-88: Elevation properties.
name	Value	Default	Description
extrap	const \| interior \| linear \| value	const	The extrapolation method.
extrapvalue	double	0	The extrapolation value if extrap is value.
filename	String		The name of the DEM file.
funcname	String	The tag name	The name of the function.
interp	neighbor \| linear	linear	The interpolation method.

Image

Generate an image function from a BMP, GIF, JPEG, PNG, or TIFF file.

Table 2-89: Image properties.
name	Value	Default	Description
argunit	String		The unit of the function arguments.
clipmaxx	double	1000	If clipping is manual: The maximum pixel x-coordinate that is kept.
clipminx	double	0	If clipping is manual: The minimum pixel x-coordinate that is kept.
clipmaxy	double	1000	If clipping is manual: The maximum pixel y-coordinate that is kept.
clipminy	double	0	If clipping is manual: The minimum pixel y-coordinate that is kept.
clipping	none \| manual	none	The clipping method.
extrap	const \| interior \| linear \| value	const	The extrapolation method.
extrapvalue	double	0	The extrapolation value if extrap is value.
fununit	String		The unit of the function value.
filename	String		The name of the DEM file.
flipx	boolean	false	If inplace is false: Whether to flip the image horizontally when mapping it to the xy-plane.
flipy	boolean	false	If inplace is false: Whether to flip the image vertically when mapping it to the xy-plane.
funcname	String	The tag name	The name of the function.
inplace	boolean	false	If true, the image is mapped to the xy-plane without scaling; 1 length unit corresponds to 1 pixel.
interp	neighbor \| linear	linear	The interpolation method.
manualexpr	String	(r+g+b)/3	If scaling is manual: The scaling function expressed in terms of the red (r), green (g), and blue (b) pixel intensities.
scaling	automatic \| manual	automatic	The method used for computing function values from pixel colors.
xmax	double	1	If inplace is false: The maximum x-coordinate of the region to which the image is mapped.
xmin	double	0	If inplace is false: The minimum x-coordinate of the region to which the image is mapped.
ymax	double	1	If inplace is false: The maximum y-coordinate of the region to which the image is mapped.
ymin	double	0	If inplace is false: The minimum y-coordinate of the region to which the image is mapped.

LeastSquares

Create a function based on a least-squares fit of the function’s input data to a parameterized function.

Table 2-90: Least Squares Properties.
name	Value	Default	Description
args	string array	{}	The argument names for the defined function(s), as an array of alternating column names from the input data and argument names. Using the setEntry, getEntryKeys, getEntryKeyIndex methods makes it easier to work with this array.
columnType	string array	{}	Defines the types of columns in the input data, as an array of alternative column names and column types. Valid column types are none, arg, and value. See also the description of the args property.
dseparator	point \| comma	point	Decimal separator in input data file, when source is set to file.
exprs	string array	{}	The expression for the defined function(s), as an array of alternating column names from the input data and expressions. Using the setEntry, getEntryKeys, getEntryKeyIndex methods makes it easier to work with this array.
filecolumns	integer	0	Number of columns in the input data. This property is updated automatically when input data properties are changed.
fileheaders	string array	{}	Custom column names to be displayed in the column settings table. This property is updated automatically when file input data properties are changed. Column header names are taken from the last line in the file that starts with a '%' character. The line is split on " " (double space), tab character, and comma character, and each part is used as one custom column name.
filename	string		The file that contains the data if source is file.
unit	string array	{}	The units for the arguments and function values, as an array of alternating column names from the input data and unit expressions. See also the description of the args property.
pname	String array		Parameter names.
plist	String array		Parameter values.
resultTable	string		The results table that contains the data if source is resultTable.
source	file \| table \| resultTable	file	Specifies whether the data is read from a file, specified in a table, or taken from a results table.
table	Nx2 String array	Empty	Contains the argument/function value pairs if the source is table.
unit	string array	{}	The units for the arguments and function values, as an array of alternating column names from the input data and unit expressions. See also the description of the args property.

GaussianProcess

Generate a Gaussian process regression (Kriging) function. Creating or training a Gaussian process function requires the Uncertainty Quantification Module. Using an already created and trained Gaussian process function does not require the Uncertainty Quantification Module.

Table 2-91: Gaussian Process Properties.
name	Value	Default	Description
args	string array	{}	The argument names for the defined function(s), as an array of alternating column names from the input data and argument names. Using the setEntry, getEntryKeys, getEntryKeyIndex methods makes it easier to work with this array.
columnType	string array	{}	Defines the types of columns in the input data, as an array of alternative column names and column types. Valid column types are none, arg, and value. See also the description of the args property.
covfunction	se \| matern32 \| matern52 \| nn	matern32	Type of covariance function to use in the Gaussian process regression. Use se for Squared exponential, matern32 for Matérn 3/2, matern52 for Matérn 5/2 and nn for Single-layer neural network.
definestddev	boolean	false	If true, the related error estimation function(s) are made available.
descr	string array	{}	The description for each function argument and function value, as an array of alternating function arguments or values and their descriptions. Using the setEntry, getEntryKeys, getEntryKeyIndex methods makes it easier to work with this array.
dseparator	point \| comma	point	Decimal separator in input data file, when source is set to file.
filecolumns	integer	0	Number of columns in the input data. This property is updated automatically when input data properties are changed.
fileheaders	string array	{}	Custom column names to be displayed in the column settings table. This property is updated automatically when file input data properties are changed. Column header names are taken from the last line in the file that starts with a '%' character. The line is split on " " (double space), tab character, and comma character, and each part is used as one custom column name.
filename	string		The file that contains the data if source is file.
fraction	double	0.1	The fraction of input data to set aside for validation of the trained function(s). Used when validation is one of random, fraction, last.
funcs	string array	{}	The names of the defined function(s), as an array of alternating column names from the input data and function names. See also the description of the args property.
ignorenaninf	boolean	false	If true, causes lines in the training data that contain any NaN or Inf values to be ignored. If false, NaN and Inf values are treated as an error.
lastinternalseed	nonnegative integer	1014	Random number seed used for training the function(s). Used when useseed is manual.
lastinternalseedtest	nonnegative integer	108714	Random number seed used for validation of the trained function(s). Used when validation is random and useseedtest is manual.
manualrestarthypergpnumber	positive integer	10	Number of restart points for training. Use more restart points to increase the chance to find the global optimum during training. Used when restarthypergp is manual.
maxmatsize	positive integer	2000	Maximum number of allowed training data points. More data points require more memory and longer training time.
meanfunction	const \| linear \| quadratic	const	Defines the overall trend of the trained function(s).
plotargs	N-by-3 array		Contains one row for each function argument. Each row contains the argument name, the lower limit for plotting, and the upper limit for plotting.
plotaxis	boolean array	{}	Contains one value for each function argument. A false value means that the corresponding function argument will be constant when plotting. The constant value is taken from the lower limit value in the plotargs property. Constant arguments do no use an axis in the plot. Up to 3 axes are supported when plotting. Specify using setIndex("plotaxis", false, 2), for example.
plotfixedvalue	double array	{}	Contains one value for each function argument. For arguments that do not have an axis in the plot (see plotaxis), this property specifies the fixed value to use in the plot.
plotfuncname	string		The name of the function whose value should be plotted.
restarthypergp	automatic \| manual	automatic	Controls how the number of restart points during training is determined. If automatic, the number is calculated from the number of function arguments. If manual, the number is given by the manualrestarthypergpnumber property.
resultTable	string		The results table that contains the data if source is resultTable.
source	file \| resultTable	file	Specifies whether the data is read from a file or taken from a results table.
stddevsuffix	string	_stddev	Function name suffix to add to error estimation functions. Used when definestddev is true.
testerrortable	none \| new \| results table	none	If validation is not none, specifies the table where verification error summary is stored. Use none to not generate the table data. Use new to create a new table for the data. Use a results table tag to store the data in an existing table.
testtable	none \| new \| results table	new	If validation is not none, specifies the table where detailed verification error information is stored. Use none to not generate the table data. Use new to create a new table for the data. Use a results table tag to store the data in an existing table.
unit	string array	{}	The units for the arguments and function values, as an array of alternating column names from the input data and unit expressions. See also the description of the args property.
useseed	manual \| currenttime	manual	Specifies how the random seed for training is determined. If manual, the seed is given by the lastinternalseed property. If currenttime, the seed is computed from the current time when training is started.
useseedtest	manual \| currenttime	manual	Specifies how the random seed for validation is determined. If manual, the seed is given by the lastinternalseedtest property. If currenttime, the seed is computed from the current time when training is started.
validation	none \| random \| fraction \| last \| table	none	Specifies what data to use for validation of the trained function(s). none: No validation is performed. random: Use a random sample of the input data and exclude the corresponding values from the training data. The size of the sample is fraction times the number of input data points. fraction: Use every 1/fraction values from the input data and exclude the corresponding values from the training data. last: Use the last part of the input data and exclude the corresponding values from the training data. The size of the last part is fraction times the number of input data points. table: Use a results table as validation data.
validationtable	string		The results table to take validation data from. Used when validation is table.

Changes in the following properties take effect without retraining the function: definestddev, stddevsuffix, funcs, plotargs, and unit.

The Uncertainty Quantification Module User’s Guide explains the theory behind Gaussian process regression. See Surrogate Models — Gaussian Process.

PolynomialChaosExpansion

Generate a polynomial chaos expansion (PCE) function. Creating or training a PCE function requires the Uncertainty Quantification Module. Using an already created and trained PCE function does not require the Uncertainty Quantification Module.

Table 2-92: Polynomial Chaos Expansion Properties.
name	Value	Default	Description
args	string array	{}	The argument names for the defined function(s), as an array of alternating column names from the input data and argument names. Using the setEntry, getEntryKeys, getEntryKeyIndex methods makes it easier to work with this array.
columnType	string array	{}	Defines the types of columns in the input data, as an array of alternative column names and column types. Valid column types are none, arg, and value. See also the description of the args property.
descr	string array	{}	The description for each function argument and function value, as an array of alternating function arguments or values and their descriptions. Using the setEntry, getEntryKeys, getEntryKeyIndex methods makes it easier to work with this array.
distributionselection	string array	{}	Defines the probability distributions for the function arguments, as an array of alternative column names and distribution types. Valid distribution types are uniform, normal, lognormal, gamma, beta, weibull, and gumbel. See also the description of the args property.
dseparator	point \| comma	point	Decimal separator in input data file, when source is set to file.
filecolumns	integer	0	Number of columns in the input data. This property is updated automatically when input data properties are changed.
fileheaders	string array	{}	Custom column names to be displayed in the column settings table. This property is updated automatically when file input data properties are changed. Column header names are taken from the last line in the file that starts with a '%' character. The line is split on " " (double space), tab character and comma character and each part is used as one custom column name.
filename	string		The file that contains the data if source is file.
fraction	double	0.1	The fraction of input data to set aside for validation of the trained function(s). Used when validation is one of random, fraction, last.
funcs	string array	{}	The names of the defined function(s), as an array of alternating column names from the input data and function names. See also the description of the args property.
ignorenaninf	boolean	false	If true, causes lines in the training data that contain any NaN or Inf values to be ignored. If false, NaN and Inf values are treated as an error.
lastinternalseedtest	nonnegative integer	108714	Random number seed used for validation of the trained function(s). Used when validation is random and useseedtest is manual.
lboundselection	string array	{}	Defines how the lower bounds of the valid range for the function arguments are determined, as an array of alternative column names and CDF (cumulative distribution function) values. Valid CDF values are 0.3, 0.1, 0.01, 0.001, 1e-4, 1e-5, 1e-6, 1e-7, and manual. Not used if distributionselection is uniform or beta. See also the description of the args property.
maxmatsize	positive integer	2000	Maximum number of allowed training data points. More data points require more memory and longer training time.
outofrange	warning \| cancel	warning	Decides how to handle out-of-range and extrapolated training data. If outofrange is cancel, the training is canceled. If outofrange is warning, the training continues, but a warning is added under the function feature. In either case, details about the problematic training data points are logged in the log window.
pcesettings	auto \| manual	automatic	If pcesettings is set to auto, the training will automatically determine the required polynomial degree needed to obtain suitable accuracy. If pcesettings is set to manual, the maximum polynomial degree is determined by the polydegreespce and qnorm settings.
plotargs	N-by-3 array		Contains one row for each function argument. Each row contains the argument name, the lower limit for plotting, and the upper limit for plotting.
plotaxis	boolean array	{}	Contains one value for each function argument. A false value means that the corresponding function argument will be constant when plotting. The constant value is taken from the lower limit value in the plotargs property. Constant arguments do no use an axis in the plot. Up to 3 axes are supported when plotting. Specify using setIndex("plotaxis", false, 2), for example.
plotfixedvalue	double array	{}	Contains one value for each function argument. For arguments that do not have an axis in the plot (see plotaxis), this property specifies the fixed value to use in the plot.
plotfuncname	string		The name of the function whose value should be plotted.
polydegreespce	positive integer	30	The maximum polynomial degree to use when pcesettings is set to manual. See also the Uncertainty Quantification Module User’s Guide.
qnorm	double	0.5	Controls the hyperbolic truncation of polynomial terms used for functions having more than one argument. Only used when pcesettings is set to manual. See also the Uncertainty Quantification Module User’s Guide.
s1selection	string array	{}	Defines the first probability distribution parameter for the function arguments as an array of alternative column names and distribution parameters. Not used if distributionselection is set to uniform. See also the description of the args property.
s2selection	string array	{}	Defines the second probability distribution parameter for the function arguments as an array of alternative column names and distribution parameters. Not used if distributionselection is set to uniform. See also the description of the args property.
source	file \| resultTable	file	Specifies whether the data is read from a file or taken from a results table.
surrogatetol	double	1e-3	The tolerance used when deciding the required polynomial degree of the trained function. See also the Uncertainty Quantification Module User’s Guide.
testerrortable	none \| new \| results table	none	If validation is not none, specifies the table where verification error summary is stored. Use none to not generate the table data. Use new to create a new table for the data. Use a results table tag to store the data in an existing table.
testtable	none \| new \| results table	new	If validation is not none, specifies the table where detailed verification error information is stored. Use none to not generate the table data. Use new to create a new table for the data. Use a results table tag to store the data in an existing table.
uboundselection	string array	{}	Defines the upper bound of the valid input range for the function arguments as an array of alternative column names and upper bounds. Only relevant if distributionselection is set to uniform or beta, or if ucdfselection is set to manual. See also the description of the args property.
ucdfselection	string array	{}	Defines how the upper bounds of the valid range for the function arguments are determined as an array of alternative column names and CDF (cumulative distribution function) values. Valid CDF values are 0.7, 0.9, 0.99, 0.999, 1-1e-4, 1-1e-5, 1-1e-6, 1-1e-7, and manual. Not used if distributionselection is set to uniform or beta. See also the description of the args property.
unit	string array	{}	The units for the arguments and function values, as an array of alternating column names from the input data and unit expressions. See also the description of the args property.
useseedtest	manual \| currenttime	manual	Specifies how the random seed for validation is determined. If manual, the seed is given by the lastinternalseedtest property. If currenttime, the seed is computed from the current time when training is started.
validation	none \| random \| fraction \| last \| table	none	Specifies what data to use for validation of the trained function(s). none: No validation is performed. random: Use a random sample of the input data and exclude the corresponding values from the training data. The size of the sample is fraction times the number of input data points. fraction: Use every 1/fraction values from the input data and exclude the corresponding values from the training data. last: Use the last part of the input data and exclude the corresponding values from the training data. The size of the last part is fraction times the number of input data points. table: Use a results table as validation data.
validationtable	string		The results table to take validation data from. Used when validation is table.

Changes in the following properties take effect without retraining the function: funcs, plotargs, unit.

The Uncertainty Quantification Module User’s Guide explains the theory behind PCE. See Surrogate Models — Polynomial Chaos Expansion.

DNN

Generate a deep neural network (DNN) function. A DNN function provides training and validation using a deep neural network (DNN) for use with surrogate model training, for example. Deep neural networks form a class of machine learning algorithms similar to the artificial neural network and aims to mimic the information processing of the brain.

Table 2-93: Deep Neural Net Properties.
name	Value	Default	Description
activation	array of the following values: tanh \| none \| relu \| elu \| sigmoid	{tanh}	The activation function for the layers.
args	string array	{}	The argument names for the defined function(s), as an array of alternating column names from the input data and argument names. Using the setEntry, getEntryKeys, getEntryKeyIndex methods makes it easier to work with this array.
batchsize	positive integer	512	The batch size for the DNN training.
descr	string array	{}	The description for each function argument and function value, as an array of alternating function arguments or values and their descriptions. Using the setEntry, getEntryKeys, getEntryKeyIndex methods makes it easier to work with this array.
epochs	integer	1000	The number of epochs to train for. In each epoch all input data is processed once.
filename	string		The full filename of the data source, when source is set to file.
fraction	scalar, 0–1	0.1	The validation data fraction.
ignorenaninf	boolean	true	Ignore data points that are NaN or Inf.
layertype	array of dense	{dense}	The type of layer in the DNN.
lr	positive scalar	1e-3	The learning rate for the training.
loss	mse \| mae	mse	The loss function; root-mean-square error or a mean absolute error.
momentum	nonnegative scalar	0	The momentum, if optmethod is set to sgd.
optmethod	adam \| sgd	adam	Training optimization method: Adam or a stochastic gradient descent (SGD) method
outfeatures	array of positive integers	{1}	The number of output features from a layer.
plotargs	N-by-3 array		Contains one row for each function argument. Each row contains the argument name, the lower limit for plotting, and the upper limit for plotting.
plotaxis	boolean array	{}	Contains one value for each function argument. A false value means that the corresponding function argument will be constant when plotting. The constant value is taken from the lower limit value in the plotargs property. Constant arguments do no use an axis in the plot. Up to 3 axes are supported when plotting. Specify using setIndex("plotaxis", false, 2), for example.
plotfixedvalue	double array	{}	Contains one value for each function argument. For arguments that do not have an axis in the plot (see plotaxis), this property specifies the fixed value to use in the plot.
resultTable	result table tag		The result table to use as source, if source is set to resultTable.
rndseed	double	0	The random seed for training, if useseed is set to manual.
rndseedvalidation	double	0	The random seed for validation, if useseedvalidation is set to manual.
source	file \| resultTable	file	Specify whether the data source is read from a file or taken from a results table.
useseed	manual \| currenttime	manual	Specifies how the random seed for training is determined. If manual, the seed is given by the rndseed property. If currenttime, the seed is computed from the current time when training is started.
useseedvalidation	manual \| currenttime	manual	Specifies how the random seed for validation is determined. If manual, the seed is given by the rndseed property. If currenttime, the seed is computed from the current time when training is started.
validation	random \| fraction \| last \| table	random	The validation data: random sample of data values, every N:th data value, last part of data values, or taken from a separate table.
validationtable	table tag (string)		The tag of the table used as validation data, if validation is set to table.
weightdecay	double	0	Nonnegative number to penalize complexity by adding the squares of all the parameters to the loss function.

PartialFractionFit

Create an partial fraction fit function.

Table 2-94: Partial Fraction Fit Properties.
name	Value	Default	Description
asymterm	double	0	Asymptotic term for the poles and residues.
dseparator	point \| comma	point	Decimal separator in the data file, when source is set to file.
funcname	String	The tag name	The name of the function.
source	file \| resultTable	file	Specify whether the data source is read from a file or taken from a results table.
tol	double	1e-3	The tolerance for the partial fraction fit.

Compatibility

For the Wave function, the freq property with a default value of 1 in previous versions of COMSOL Multiphysics has been replaced by period with a default value of 2π in version 6.0.