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, Elevation, External, Image, Interpolation, GaussianProcess (requires Uncertainty quantification module), LeastSquares, MATLAB (requires LiveLink™ for MATLAB®), Piecewise, GaussianPulse, Ramp, Random, Rectangle, Step, Triangle, and Wave. 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");

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 and Gaussian process).

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.


	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

Generate an analytic function using a symbolic expression.

Table 2-74: 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.
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-75: interpolation properties
name	Value	Default	Description
defineinv	on \| off	off	If source is 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 value.
filename	String		The file that contains the data if source is 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 file.
table	Nx2 String array	Empty	Contains the point/value pairs if the source is table.
argunit	String		A comma-separated list of required units for each argument.
fununit	String		The unit of the function’s result.

LeastSquares

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


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.


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.
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.
lastinternalseed	non-negative integer	1014	Random number seed used for training the function(s). Used when useseed is manual.
lastinternalseedtest	non-negative 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	Nx3 string matrix		Contains one row for each function argument. Each row contains the argument name, the lower limit for plotting, and the upper limit for plotting.
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, unit.

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

Piecewise

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

Table 2-76: 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-77: 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-78: 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.

Random

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

Table 2-79: 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.
seedactive	boolean	false	If true, the random seed will be used.
type	uniform \| normal	Uniform	The distribution type.
uniformrange	String	1	The range if type is Uniform.

Normal Distribution

Generate a normal distribution function.

Table 2-80: 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.

Rectangle

Generate a rectangle-shaped function.

Table 2-81: 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-82: 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-83: 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.

External

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

Table 2-84: 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.

Elevation

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

Table 2-85: 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-86: 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.

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.

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-88: 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.

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.