The External Material node () sets up an interface between a physics feature and functions in an external shared library. In addition, it contains most of the functionality of a standard Material node, letting you add arbitrary material properties and property groups. Some aspects of a material can be handled by an external library, while others are defined internally in property groups.

To add an external material to a user-defined material library, right-click the External Material node and choose Add to User-Defined Library ().

The Settings window for the External Materials node contains the following sections:

Use this section to define a library for the Windows® operating system. Enter a Library path and name (the complete network path), or click Browse to locate a library to import. The library must be a DLL (native dynamic library) file.

Use this section to define a library for the Linux® operating system. Enter a Library path and name (the complete network path), or click Browse to locate a library to import. The library must be a .so (native dynamic library) file.

Use this section to define a library for the macOS operating system. Enter a Library path and name (the complete network path), or click Browse to locate a library to import. The library must be a .dylib (native dynamic library) file.

If the external material DLL is not thread safe, clear the Thread safe check box. If the DLL is thread safe, several threads can make calls to the DLL at the same time. By clearing the Thread safe check box, you prevent the DLL from being used by more than one thread at the same time.

Select the appropriate Interface type matching your library. The default is None; other options may vary between COMSOL installations. The following types are preinstalled:

If the chosen external library contains initialization and cleanup functions and the interface type allows it, select Call init() and Call cleanup() as appropriate.

If allowed for the chosen interface type and external library, select the Pass arguments as complex check box to use complex rather than double as the base type in all numeric array arguments to the external functions.

If required by the chosen interface type, specify a State base name for each state array that must be stored at each evaluation point and provide a corresponding array size under Number of states. Actual state variables are created by adding the <matname>.state. namespace as a prefix and appending a state index to the given base names. For example, if for a material with name extmat1 you request a state array of length 2 with State base name p, the state values can be accessed during and after a solution as extmat1.state.p1 and extmat1.state.p2.

If the external library’s functions are implemented so as to return error details, select Return error details and specify a Maximum error message length. A preallocated string of the specified length will then be passed as output argument to all functions.

The Required input quantities, Output quantities, and Model states tables provide an overview of the interface, including which quantities are passed to and from calling physics features, which states are declared, and which component variables are defined by the material feature. Note that all variables are defined in the material’s namespace. To directly access, for example, the first axial component of a second Piola-Kirchhoff stress output outside the scope of an External Material node with the name extmat1, use the variable name extmat1.output.S11.

Components of the Required input quantities are normally defined by a physics feature calling the external material. When using an external material in equation-based modeling, you can set the inputs up manually by defining the required input components (in the material’s namespace) as global variables. For example, if external material extmat1 requires the temperature T as input, define a global variable called extmat1.input.T.

Use the Init column in the Model states table to specify initial values for all internal states used by the external function. This includes both specific states required by the chosen Interface type and numbered states added by this feature.

The Material Properties section of an external material is identical to the same section in a common Material feature. See The Settings Window for Material for more information.

The Material Contents section of an external material is very similar to the same section in a common Material feature (see The Settings Window for Material for more information). The only real difference is that the table shows not only defined output properties and properties required by some physics feature, but also parameters required as input to the external material functions. Depending on the selected Interface type, these may appear either as individually named parameters or as a single generic, arbitrary-length parameter array. In the latter case, any particular external library typically requires a specific set of properties in a certain order to be specified as an array inside curly brackets. For example, two required parameters can be specified as {2e11,0.33}

The table also shows a row for Extra library function string arguments, whose value is expected to be an array of single-quoted strings. These strings are stored in a property group in the same way as other parameters. They are passed to the external library’s functions as separate string arguments.

The Appearance section of an external material is identical to the same section in a common Material feature. See The Settings Window for Material for more information.