Nonconstant Parameters of Finite Element Model

Specify nonconstant parameters of a finite element model by using a function handle.

Nonconstant Parameters for Structural, Thermal, and Electromagnetics Analysis

For structural mechanics problems, these nonconstant parameters can depend on space and, depending on the type of structural analysis, either time or frequency:

Young's modulus, Poisson's ratio, shear modulus, and mass density (can depend on space only)
Surface traction on the boundary
Pressure normal to the boundary
Concentrated force at a vertex
Distributed spring stiffness for each translational direction used to model elastic foundation
Enforced displacement and its components
Initial displacement and velocity (can depend on space only)

For thermal problems, these nonconstant parameters can depend on space, temperature, and time:

Thermal conductivity of the material
Mass density of the material
Specific heat of the material
Internal heat source
Temperature on the boundary
Heat flux through the boundary
Convection coefficient on the boundary
Initial temperature (can depend on space only)

For electromagnetic problems, these nonconstant parameters can depend on space:

Relative permittivity of the material
Relative permeability of the material
Conductivity of the material
Charge density as source
Current density as source
Magnetization
Voltage on the boundary
Magnetic potential on the boundary
Electric field on the boundary
Magnetic field on the boundary
Surface current density on the boundary
Initial flux density or initial magnetic potential for a nonlinear magnetostatic problem

For harmonic electromagnetic problems, these parameters can also depend on frequency:

Relative permittivity of the material
Relative permeability of the material
Conductivity of the material

For nonlinear magnetostatic analysis, these parameters can also depend on the magnetic potential, its gradients, and the norm of the magnetic flux density:

Relative permeability of the material
Current density as source
Magnetization
Initial flux density or initial magnetic potential. If a relative permeability, current density, or magnetization depend on the magnetic potential or its gradients, then initial conditions must not depend on the magnetic flux density.

Function Form

For all parameters, except the initial temperature, displacement, and velocity, the function must be of the form:

function val = myfun(location,state)

For the initial temperature, displacement, and velocity, the function must be of the form:

function val = myfun(location)

`location` and `state` Input Arguments

The solver computes and populates the data in the location and state structure arrays and passes this data to your function. You can define your function so that its output depends on this data. You can use any names instead of location and state, but the function must have exactly two arguments (or one argument if the function specifies initial conditions).

location — A structure containing these fields:
- location.x — x-coordinate of the point or points
- location.y — y-coordinate of the point or points
- location.z — z-coordinate of the point or points
Furthermore, for boundary conditions, the solver passes this data in the location structure:
- location.nx — x-component of the normal vector at the evaluation point or points
- location.ny — y-component of the normal vector at the evaluation point or points
- location.nz — z-component of the normal vector at the evaluation point or points
state — A structure containing these fields for transient or nonlinear problems:
- state.u — Solution at the corresponding points of the location structure
- state.ux — Estimates of the x-component of solution gradients at the corresponding points of the location structure
- state.uy — Estimates of the y-component of solution gradients at the corresponding points of the location structure
- state.uz — Estimates of the z-component of solution gradients at the corresponding points of the location structure
- state.time — Time at evaluation points
- state.frequency — Frequency at evaluation points
- state.NormFluxDensity — Norm of the magnetic flux density at evaluation points (for a nonlinear magnetostatic problem only)

To save time in function handle evaluation, location can contain multiple evaluation points. When you use a unified femodel workflow, function handles for nonconstant parameters must support computing in a vectorized fashion. For details about vectorized computations, see Vectorization. For example, specify the nonconstant pressure load on a geometry face.

val = @(location,state) 10^5*ones(size(location.x))
model.FaceLoad(2) = faceLoad(Pressure=val)

Additional Arguments in Functions for Nonconstant Parameters

To use additional arguments in your function, wrap your function (that takes additional arguments) with an anonymous function that takes only the location and state arguments. For example:

val = ...
@(location,state) myfunWithAdditionalArgs(location,state,arg1,arg2...)
model.EdgeBC(1) = edgeBC(Temperature=val)

val = @(location) myfunWithAdditionalArgs(location,arg1,arg2...)
model.FaceIC = faceIC(Displacement=val)

Data and Output Sizes: Structural Mechanics

Boundary constraints and loads get this data from the solver:

location.x, location.y, location.z
location.nx, location.ny, location.nz
state.time or state.frequency (depending of the type of analysis)

Structural material properties (Young's modulus, Poisson's ratio, and shear modulus) and initial conditions get this data from the solver:

location.x, location.y, location.z
Subdomain ID

If a parameter represents a vector value, such as surface traction, spring stiffness, force, displacement, or velocity, your function must return a two-row matrix for a 2-D model and a three-row matrix for a 3-D model. Each column of the matrix corresponds to the parameter value (a vector) at the boundary coordinates provided by the solver.

Note

For vector values of Young's modulus, Poisson's ratio, and shear modulus, your function must return a three-row matrix for both 2-D and 3-D models.

If a parameter represents a scalar value, such as pressure, displacement component, or mass density, your function must return a row vector where each element corresponds to the parameter value (a scalar) at the boundary coordinates provided by the solver.

If boundary conditions depend on state.time or state.frequency, ensure that your function returns a matrix of NaN values of the correct size when state.frequency or state.time are NaN. Solvers check whether a problem is nonlinear or time dependent by passing NaN state values and looking for returned NaN values.

Data and Output Sizes: Heat Transfer

Thermal material properties (thermal conductivity, mass density, and specific heat) and internal heat source get this data from the solver:

location.x, location.y, location.z
Subdomain ID
state.u, state.ux, state.uy, state.uz, state.time

Boundary conditions (temperature on the boundary, heat flux, and convection coefficient) get this data from the solver:

location.x, location.y, location.z
location.nx, location.ny, location.nz
state.u, state.time

Initial temperature gets this data from the solver:

location.x, location.y, location.z
Subdomain ID

For all thermal parameters, except for thermal conductivity, your function must return a row vector thermalVal with the number of columns equal to the number of evaluation points, for example, M = length(location.y).

For thermal conductivity, your function must return a matrix with the number of rows equal to 1, Ndim, Ndim*(Ndim+1)/2, or Ndim*Ndim, where Ndim is 2 for 2-D problems and 3 for 3-D problems. The number of columns must equal the number of evaluation points, for example, M = length(location.y). For details about dimensions of the matrix, see c Coefficient for specifyCoefficients.

If parameters depend on time or temperature, ensure that your function returns a matrix of NaN values of the correct size when state.u or state.time are NaN. Solvers check whether a problem is time dependent by passing NaN state values and looking for returned NaN values.

Data and Output Sizes: Electromagnetics

Relative permittivity, relative permeability, and conductivity get this data from the solver:

location.x, location.y, location.z
state.frequency for a harmonic analysis
state.NormFluxDensity, state.u, state.ux, state.uy, and state.uz for relative permeability in a nonlinear magnetostatic analysis
Subdomain ID

Charge density, current density, magnetization, surface current density on the boundary, electric or magnetic field on the boundary, and initial conditions get this data from the solver:

location.x, location.y, location.z
state.NormFluxDensity, state.u, state.ux, state.uy, state.uz for current density and magnetization in a magnetostatic analysis
Subdomain ID

Voltage or magnetic potential on the boundary get this data from the solver:

location.x, location.y, location.z
location.nx, location.ny, location.nz

If relative permittivity, relative permeability, or conductivity for a harmonic analysis depends on the frequency, ensure that your function returns a matrix of NaN values of the correct size when state.frequency is NaN. Also, if relative permeability, magnetization, or current density for a magnetostatic analysis depends on the magnetic flux density, ensure that your function returns a matrix of NaN values of the correct size when state.NormFluxDensity, state.u, state.ux, state.uy, or state.uz is NaN. Solvers check whether a problem is nonlinear by passing NaN state values and looking for returned NaN values.

When you solve an electrostatic or DC conduction problem, the output returned by the function handle must be of the following size. Here, Np = numel(location.x) is the number of points.

1-by-Np if a function specifies the nonconstant relative permittivity
1-by-Np or Np-by-1 if a function specifies the nonconstant charge density
2-by-Np for a 2-D model and 3-by-Np for a 3-D model if a function specifies the nonconstant surface current density on the boundary

When you solve a magnetostatic problem, the output returned by the function handle must be of the following size. Here, Np = numel(location.x) is the number of points. Note that for a 3-D magnetostatic analysis, state.u, state.ux, state.uy, and state.uz are 3-by-Np, and state.NormFluxDensity is 1-by-Np.

1-by-Np if a function specifies the nonconstant relative permeability or the initial magnetic flux
1-by-Np or Np-by-1 for a 2-D model and 3-by-Np or Np-by-3 for a 3-D model if a function specifies the nonconstant current density
1-by-Np for a 2-D model and 3-by-Np for a 3-D model if a function specifies the nonconstant magnetic potential on the boundary or the initial magnetic potential
2-by-Np for a 2-D model and 3-by-Np for a 3-D model if a function specifies the nonconstant magnetization

When you solve a harmonic problem, the output returned by the function handle must be of the following size. Here, Np = numel(location.x) is the number of points.

1-by-Np if a function specifies the nonconstant relative permittivity, relative permeability, and conductivity
2-by-Np for a 2-D geometry and 3-by-Np for a 3-D geometry if a function specifies the nonconstant electric or magnetic field
2-by-Np or Np-by-2 for a 2-D geometry and 3-by-Np or Np-by-3 for a 3-D geometry if a function specifies the nonconstant current density and the field type is electric
1-by-Np or Np-by-1 for a 2-D geometry and 3-by-Np or Np-by-3 for a 3-D geometry if a function specifies the nonconstant current density and the field type is magnetic