model.material()
Materials and material property groups.
For materials defined on the global level, omit component(<ctag>). from the syntax such as model.component(<ctag>).material().create(<tag>) in the syntax examples below.
Syntax
model.component(<ctag>).material().create(<tag>);
model.component(<ctag>).material().create(<tag>,<type>);
model.component(<ctag>).material(<tag>).info(<itag>);
model.component(<ctag>).material(<tag>).info();
model.component(<ctag>).material(<tag>).insert()
model.component(<ctag>).material(<tag>).label(<label>);
model.component(<ctag>).material(<tag>).materialType(<mattype>)
model.component(<ctag>).material(<tag>).propertyGroup(<mtag>);
model.component(<ctag>).material(<tag>).propertyGroup();
model.component(<ctag>).material(<tag>).prefix(<prefix>);
model.component(<ctag>).material(<tag>).prefix();
model.component(<ctag>).material(<tag>).selection();
model.component(<ctag>).material(<tag>).image();
model.component(<ctag>).material(<tag>).set(<pname>,<expr>);
model.component(<ctag>).material().move(<tag>,<position>);
 
MaterialModel mm = model.component(<ctag>).material(<tag>).propertyGroup().
                 create(<mtag>,<descr>);
mm.addInput(<quantity>);
mm.descr(<pname>,<descr>);
mm.func();
mm.func(<ftag>);
mm.getString(<pname>);
mm.getStringArray(<pname>);
mm.hasParam(<pname>);
mm.info(<itag>);
mm.info();
mm.input();
mm.isOutput(<pname>);
mm.param();
mm.removeInput(<quantity>);
mm.set(<pname>,<expr>);
mm.size(<pname>);
mm.suffix(<suffix>);
mm.suffix();
 
mm.info().create(<itag>,<descr>);
mm.info(<itag>).title(<title>);
mm.info(<itag>).title();
mm.info(<itag>).body(<body>);
mm.info(<itag>).body();
Description
A material is a collection of property groups, where each property group defines a set of material properties, material functions, and model inputs that can be used to define a temperature-dependent material property, for example. A property group usually defines properties used by a particular material model to compute a fundamental quantity. A material property can either be a visible output property or a local parameter. The output property is visible for physics interfaces; local properties are only visible inside the property group. If two property groups define the same output property, the last property group determines the value of the output property. The material function is used by the property group to calculate a property or parameter value as a function of other variables, usually model inputs. The model input is a quantity that the material model recognizes as an input variable (temperature, for example). The actual variable that represents the model input is not known until the model is solved, and it can also be different between physics interfaces.
There are two types of property groups, user-defined and specialized. When a material is created, there is always one default user-defined property group present. To this property group it is possible to add output properties from a predefined list of quantities. These quantities are recognized by all physics interfaces as material properties — for example, thermal conductivity, electric conductivity, and density. The full list is presented in the physics interface for the default property group. The specialized property groups are built in and usually define few output properties that only some physics interfaces can access. These output properties are not necessarily part of the allowed properties for the default property group. An example of such a specialized group is the refractive index material model, which defines the real and imaginary part of the refractive index as output properties. These properties can only be accessed by the Electromagnetic Waves interface.
model.component(<ctag>).material().create(<tag>) creates a new material for the model component with the tag <ctag>.
model.component(<ctag>).material().create(<tag>,"Common") also creates a new material for the model component with the tag <ctag>.
model.component(<ctag>).material().create(<tag>,"Switch") creates a material switch for the model component with the tag <ctag>. You can add materials to the material switch:
model.component(<ctag>).material().create("sw1", "Switch", "");
model.component(<ctag>).material("sw1").feature().create("mat1", "Common", "");
model.component(<ctag>).material("sw1").feature().create("mat2", "Common", "");
model.component(<ctag>).material().create(<tag>,"Link") creates a material link for the model component with the tag <ctag>.
model.component(<ctag>).material().create(<ptag>,"PorousMedia") also creates a new local porous material for the model component with the tag <ctag>. Use model.component(<ctag>).
material(
<ptag>).feature().create(<subtag>, <subfeaturename>, <ctag>); where <subfeaturename> is one of "Fluid", "Pellet", "Solid", or "ImFluid" to add a subfeature to the porous material feature representing a fluid, pellet, solid, or immobile fluid, respectively.
model.component(<ctag>).material().create(<tag>,"External") creates a external material that sets up an interface between a physics feature and functions in an external shared library (a DLL, .so, or .dylib file.). For an external material,
model.component(<ctag>).material(<tag>).set("path",<path to external material file>) sets the path to the external shared library. Also, use model.material(<tag>).set("threadSafe", "off")if the DLL is not thread safe (default is, "on"; that is, the DLL is thread safe).
model.material().create(<tag>,<type>) creates a global material, material switch, or material link.
model.component(<ctag>).material(<tag>).info(<itag>) returns an information item for a material.
model.component(<ctag>).material(<tag>).input() returns the list of model inputs.
For model.component(<ctag>).material(<tag>).insert(), see Inserting Materials.
model.component(<ctag>).material(<tag>).materialType("solid") or model.component(<ctag>).material(<tag>).materialType("nonSolid")sets the material type to a solid or a nonsolid (that is, fluid or liquid) material, respectively.
model.component(<ctag>).material(<tag>).propertyGroup(<mtag>) gets the property group named <mtag> for the material.
model.component(<ctag>).material(<tag>).selection() returns the selection of the material. The selection determines which geometry the material belongs to.
model.component(<ctag>).material(<tag>).set("family",<appearance>) sets the appearance to a family of materials (as strings; "water", for example): air, aluminum, brick, concrete, copper, gold, iron, lead, magnesium, plastic, steel, titanium, water, or custom. With custom, you can set these additional parameters for the appearance:
true | false
phong | cooktorrance | simple
true | false
The color blend, if colornoise is true.
model.component(<ctag>).material().move(<tag>,<position>) moves the material <tag> to the zero-indexed position <position> in the list.
For a material link, model.component(<ctag>).material(<tag>).set("link", <linktag>); creates a material link from a component to the global material with the tag in <linktag>. For example,
model.component("comp1")).material().create("matlnk1", "Link");
model.material("matlnk1").set("link", "mat1");
creates a material link in the component comp1 and then links it to the global material mat1. The material link can also have a selection; for example, model.material("matlnk1").selection().all();.
Importing Materials
You can import materials as global materials and as materials in a component.
To import global materials as mat1, mat2, and mat3 from myfile.xml, for example:
String[][] result = model.material().insert("myfile.xml",
           new String[]{"mat1", "mat2", "mat3"});
To import the same materials to the component comp1:
String[][] result = model.component("comp1").material().insert("myfile.xml",
           new String[]{"mat1", "mat2", "mat3"});
The insert method inserts materials from an MPH- or XML-file into the material list and returns the result of the operation as a double string array of length 3. The first array contains the messages from insert operation, the second array contains paths to the inserted objects, and the third array contains paths to the inserted references. An inserted reference is an object that an inserted object refers to and is not necessarily contained by any of the inserted objects. There can only be inserted references when importing from an MPH-file. The first parameter is the filename, and the second is the tags of the materials to insert. For protected MPH-files, you can supply a password as an optional third parameter.
See Materials in The COMSOL File Formats chapter for information about the XML-file format for materials that you can import and export.
Property Groups
The following syntax examples describe the methods available for property groups added to a material (not available for material switches or material links).
mm = model.component(<ctag>).material(<tag>).propertyGroup().create(<tag>,<descr>) creates a new property group and stores it in the variable mm.
To define a method to set an output property of a material, use the following syntax (in this example you specify a density for the basic property group def):
model.compoenent(<ctag>).material("mat1").propertyGroup("def").
set("density", String[] arg);
where arg is the string value to be defined. For a list of available physical property names (such as density), see Table 2-90.
mm.addInput(<quantity>) adds a new model input to the property group of the given quantity.
mm.descr(<pname>,<descr>) adds the description <descr> to the local material property with the name <pname>.
mm.func(<ftag>) returns the function object named <ftag>. For information about how to add and modify functions, see model.func().
mm.getString(<pname>) returns the string value of the given parameter. If it is a vector or matrix quantity, the first value is returned.
mm.getStringArray(<pname>) returns the string array value of the given parameter. Matrix values are returned in a column-wise order.
mm.hasParam(<pname>) returns true if the parameter is defined by the property group.
mm.info(<itag>) returns the information object for the property group.
mm.isOutput(<pname>) returns true if the given local material parameter is an output property. For user-defined property groups the method returns true for all predefined material properties known to all physics interfaces. For the specialized property groups, it can also return true for other properties.
mm.param() returns a list of all parameters stored in the property group.
mm.removeInput(<quantity>) removes the given quantity from the list of model inputs.
mm.set(<pname>,<expr>) sets the expression for the given property. The expression can use local names for the properties, parameters, and model inputs. For vector and matrix properties, the expression can be string arrays of varying size. Isotropic matrices only require one element or a string, diagonal matrices require three elements, and so forth. Vectors always require three elements.
mm.size(<pname>) returns the size of the stored parameter, which usually is 1-by-1, 3-by-1, or 3-by-3, but other sizes are supported.
model.component(<ctag>).material(<tag>).propertyGroup() returns a list of all property groups in the material.
model.component(<ctag>).material(<tag>).propertyGroup(<tag>).info().create(<tag>,<descr>) creates a new information object that can contain detailed information about this property group. This could, for example, be used by the Material Library to define the Phase/Condition and Orientation/Condition fields.
mm.info(<itag>).title(<title>) sets the title of the information object.
mm.info(<itag>).title() returns the title.
mm.info(<itag>).body(<body>) sets the body text of the information object.
mm.info(<itag>).body() returns the body text.
The term material model is sometimes used instead of property group in some contexts. The graphical user interface uses the term property group.
See Also
model.func(), model.physics()