model.func()

Add different types of functions.

Syntax

model.func().create(<tag>,<type>);

model.func(<tag>).create(<tag>,<type>);

model.func(<tag>).createPlot(<pgtag>)

model.func(<tag>).label(<label>)

model.func(<tag>).model(<mtag>)

model.func(<tag>).set(property,<value>);

model.func(<tag>).set("funcname",<funcname>)

model.func(<tag>).discardData()

model.func(<tag>).importData()

model.func(<tag>).refresh()

model.func(<tag>).image()

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

model.func(<tag>).getType(property);

model.func(<tag>).functionNames()

model.func(<tag>).getAllowedPropertyValues(property);

Description

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, 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>).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-73: 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-74: 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, the space 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.
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.
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.
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.
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	table	If sourcetype is user, specifies whether the data is entered in a local table, read from a file, or taken from a results table.
sourcetype	model \| user	user	Specifies if the data for the function is stored in the model or provided by the user.
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.

Piecewise

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

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

External

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

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