structuralBoundaryLoad

(To be removed) Specify boundary loads for structural model

structuralBoundaryLoad will be removed. Use faceLoad, edgeLoad, and vertexLoad instead. (since R2023a) For more information on updating your code, see Version History.

Syntax

structuralBoundaryLoad(structuralmodel,RegionType,RegionID,"SurfaceTraction",STval,"Pressure",Pval,"TranslationalStiffness",TSval)

structuralBoundaryLoad(structuralmodel,"Vertex",VertexID,"Force",Fval)

structuralBoundaryLoad(___,"Vectorized","on")

structuralBoundaryLoad(___,"Pressure",Pval,Name,Value)

structuralBoundaryLoad(structuralmodel,"Vertex",VertexID,"Force",Fval,Name,Value)

structuralBoundaryLoad(___,"Label",labeltext)

boundaryLoad = structuralBoundaryLoad(___)

Description

structuralBoundaryLoad(structuralmodel,RegionType,RegionID,"SurfaceTraction",STval,"Pressure",Pval,"TranslationalStiffness",TSval) specifies the surface traction, pressure, and translational stiffness on the boundary of type RegionType with RegionID ID numbers.

• Surface traction is determined as distributed normal and tangential forces acting on a boundary, resolved along the global Cartesian coordinate system.

• Pressure must be specified in the direction that is normal to the boundary. A positive pressure value acts into the boundary (for example, compression). A negative pressure value acts away from the boundary (for example, suction).

• Translational stiffness is a distributed spring stiffness for each translational direction. Translational stiffness is used to model an elastic foundation.

structuralBoundaryLoad does not require you to specify all three boundary loads. Depending on your structural analysis problem, you can specify one or more boundary loads by picking the corresponding arguments and omitting others. You can specify translational stiffness for any structural model. To specify pressure or surface traction, structuralmodel must be a static, transient, or frequency response model. Structural models for modal analysis cannot have pressure or surface traction.

The default boundary load is a stress-free boundary condition.

structuralBoundaryLoad(structuralmodel,"Vertex",VertexID,"Force",Fval) specifies concentrated force at a vertex with the VertexID number. You can specify force only if structuralmodel is a static, transient, or frequency response model. Structural models for modal analysis cannot have concentrated force.

structuralBoundaryLoad(___,"Vectorized","on") uses vectorized function evaluation when you pass a function handle as an argument. If your function handle computes in a vectorized fashion, then using this argument saves time. See Vectorization. For details on this evaluation, see Nonconstant Boundary Conditions.

Use this syntax with any of the input arguments from previous syntaxes.

structuralBoundaryLoad(___,"Pressure",Pval,Name,Value) lets you specify the form and duration of a nonconstant pressure pulse and harmonic excitation for a transient structural model without creating a function handle. When using this syntax, you must specify the model, region type and region ID, and pressure. Surface traction and translational stiffness are optional arguments. This syntax does not work for static, modal analysis, and frequency response models.

structuralBoundaryLoad(structuralmodel,"Vertex",VertexID,"Force",Fval,Name,Value) lets you specify the form and duration of a nonconstant concentrated force and harmonic excitation for a transient structural model without creating a function handle.

structuralBoundaryLoad(___,"Label",labeltext) adds a label for the structural boundary load to be used by the linearizeInput function. This function lets you pass boundary loads to the linearize function that extracts sparse linear models for use with Control System Toolbox™.

boundaryLoad = structuralBoundaryLoad(___) returns the boundary load object.

Examples

Apply Fixed Boundaries and Specify Surface Traction

Apply fixed boundaries and traction on two ends of a bimetallic cable.

Create a structural model.

structuralModel = createpde("structural","static-solid");

Create nested cylinders to model a bimetallic cable.

gm = multicylinder([0.01,0.015],0.05);

Assign the geometry to the structural model and plot the geometry.

structuralModel.Geometry = gm;
pdegplot(structuralModel,"CellLabels","on", ...
                         "FaceLabels","on", ...
                         "FaceAlpha",0.4)

For each metal, specify Young's modulus and Poisson's ratio.

structuralProperties(structuralModel,"Cell",1,"YoungsModulus",110E9, ...
                                              "PoissonsRatio",0.28);
structuralProperties(structuralModel,"Cell",2,"YoungsModulus",210E9, ...
                                              "PoissonsRatio",0.3);

Specify that faces 1 and 4 are fixed boundaries.

structuralBC(structuralModel,"Face",[1,4],"Constraint","fixed")

ans = 
  StructuralBC with properties:

                RegionType: 'Face'
                  RegionID: [1 4]
                Vectorized: 'off'

   Boundary Constraints and Enforced Displacements
              Displacement: []
             XDisplacement: []
             YDisplacement: []
             ZDisplacement: []
                Constraint: "fixed"
                    Radius: []
                 Reference: []
                     Label: []

   Boundary Loads
                     Force: []
           SurfaceTraction: []
                  Pressure: []
    TranslationalStiffness: []
                     Label: []

Specify the surface traction for faces 2 and 5.

structuralBoundaryLoad(structuralModel, ...
                          "Face",[2,5], ...
                          "SurfaceTraction",[0;0;100])

ans = 
  StructuralBC with properties:

                RegionType: 'Face'
                  RegionID: [2 5]
                Vectorized: 'off'

   Boundary Constraints and Enforced Displacements
              Displacement: []
             XDisplacement: []
             YDisplacement: []
             ZDisplacement: []
                Constraint: []
                    Radius: []
                 Reference: []
                     Label: []

   Boundary Loads
                     Force: []
           SurfaceTraction: [3×1 double]
                  Pressure: []
    TranslationalStiffness: []
                     Label: []

Input Arguments

structuralmodel — Structural model

StructuralModel object

Structural model, specified as a StructuralModel object. The model contains the geometry, mesh, structural properties of the material, body loads, boundary loads, and boundary conditions.

Example: structuralmodel = createpde("structural","transient-solid")

RegionType — Geometric region type

"Edge" for a 2-D model | "Face" for a 3-D model

Geometric region type, specified as "Edge" for a 2-D model or "Face" for a 3-D model.

Example: structuralBoundaryLoad(structuralmodel,"Face",[2,5],"SurfaceTraction",[0,0,100])

Data Types: char | string

RegionID — Geometric region ID

positive integer | vector of positive integers

Geometric region ID, specified as a positive integer or vector of positive integers. Find the region IDs by using pdegplot.

Example: structuralBoundaryLoad(structuralmodel,"Face",[2,5],"SurfaceTraction",[0,0,100])

Data Types: double

VertexID — Vertex ID

positive integer | vector of positive integers

Vertex ID, specified as a positive integer or vector of positive integers. Find the vertex IDs using pdegplot.

Example: structuralBoundaryLoad(structuralmodel,"Vertex",6,"Force",[0;10^4;0])

Data Types: double

STval — Distributed normal and tangential forces on boundary

numeric vector | function handle

Distributed normal and tangential forces on the boundary, resolved along the global Cartesian coordinate system, specified as a numeric vector or function handle. A numeric vector must contain two elements for a 2-D model and three elements for a 3-D model.

The 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 must correspond to the surface traction vector at the boundary coordinates provided by the solver. In case of a transient or frequency response analysis, STval also can be a function of time or frequency, respectively. For details, see More About.

Example: structuralBoundaryLoad(structuralmodel,"Face",[2,5],"SurfaceTraction",[0;0;100])

Data Types: double | function_handle

Pval — Pressure normal to boundary

number | function handle

Pressure normal to the boundary, specified as a number or function handle. A positive-value pressure acts into the boundary (for example, compression), while a negative-value pressure acts away from the boundary (for example, suction).

If you specify Pval as a function handle, the function must return a row vector where each column corresponds to the value of pressure at the boundary coordinates provided by the solver. In case of a transient structural model, Pval also can be a function of time. In case of a frequency response structural model, Pval can be a function of frequency (when specified as a function handle) or a constant pressure with the same magnitude for a broad frequency spectrum. For details, see More About.

Example: structuralBoundaryLoad(structuralmodel,"Face",[2,5],"Pressure",10^5)

Data Types: double | function_handle

TSval — Distributed spring stiffness

numeric vector | function handle

Distributed spring stiffness for each translational direction used to model elastic foundation, specified as a numeric vector or function handle. A numeric vector must contain two elements for a 2-D model and three elements for a 3-D model. The custom 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 this matrix corresponds to the stiffness vector at the boundary coordinates provided by the solver. In case of a transient or frequency response analysis, TSval also can be a function of time or frequency, respectively. For details, see More About.

Example: structuralBoundaryLoad(structuralmodel,"Edge",[2,5],"TranslationalStiffness",[0;5500])

Data Types: double | function_handle

Fval — Concentrated force

numeric vector | function handle

Concentrated force at a vertex, specified as a numeric vector or function handle. Use a function handle to specify concentrated force that depends time or frequency. For details, see More About.

Example: structuralBoundaryLoad(structuralmodel,"Vertex",5,"Force",[0;0;10])

Data Types: double | function_handle

labeltext — Label for structural boundary load

character vector | string

Label for the structural boundary load, specified as a character vector or a string.

Data Types: char | string

Name-Value Arguments

Example: structuralBoundaryLoad(structuralmodel,"Face",[2,5],"Pressure",10^5,"RiseTime",0.5,"FallTime",0.5,"EndTime",3)

Use one or more of the name-value pair arguments to specify the form and duration of the pressure or concentrated force pulse and harmonic excitation for a transient structural model only. Specify the pressure or force value using the Pval or Fval argument, respectively.

You can model rectangular, triangular, and trapezoidal pressure or concentrated force pulses. If the start time is 0, you can omit specifying it.

• For a rectangular pulse, specify the start and end times.

• For a triangular pulse, specify the start time and any two of the following times: rise time, fall time, and end time. You also can specify all three times, but they must be consistent.

• For a trapezoidal pulse, specify all four times.

You can model a harmonic pressure or concentrated force load by specifying its frequency and initial phase. If the initial phase is 0, you can omit specifying it.

Rectangular, Triangular, or Trapezoidal Pulse

StartTime — Start time for pressure or concentrated force load

nonnegative number

Start time for pressure or concentrated force load, specified as a nonnegative number. Specify this argument only for transient structural models.

Example: structuralBoundaryLoad(structuralmodel,"Face",[2,5],"Pressure",10^5,"StartTime",1,"EndTime",3)

Data Types: double

EndTime — End time for pressure or concentrated force load

nonnegative number

End time for pressure or concentrated force load, specified as a nonnegative number equal or greater than the start time value. Specify this argument only for transient structural models.

Example: structuralBoundaryLoad(structuralmodel,"Face",[2,5],"Pressure",10^5,"StartTime",1,"EndTime",3)

Data Types: double

RiseTime — Rise time for pressure or concentrated force load

nonnegative number

Rise time for pressure or concentrated force load, specified as a nonnegative number. Specify this argument only for transient structural models.

Example: structuralBoundaryLoad(structuralmodel,"Face",[2,5],"Pressure",10^5,"RiseTime",0.5,"FallTime",0.5,"EndTime",3)

Data Types: double

FallTime — Fall time for pressure or concentrated force load

nonnegative number

Fall time for pressure or concentrated force load, specified as a nonnegative number. Specify this argument only for transient structural models.

Example: structuralBoundaryLoad(structuralmodel,"Face",[2,5],"Pressure",10^5,"RiseTime",0.5,"FallTime",0.5,"EndTime",3)

Data Types: double

Harmonic Pressure or Force

Frequency — Frequency of sinusoidal pressure or concentrated force

positive number

Frequency of sinusoidal pressure or concentrated force, specified as a positive number, in radians per unit of time. Specify this argument only for transient structural models.

Example: structuralBoundaryLoad(structuralmodel,"Face",[2,5],"Pressure",10^5,"Frequency",25)

Data Types: double

Phase — Phase of sinusoidal pressure or concentrated force

nonnegative number

Phase of sinusoidal pressure or concentrated force, specified as a nonnegative number, in radians. Specify this argument only for transient structural models.

Example: structuralBoundaryLoad(structuralmodel,"Face",[2,5],"Pressure",10^5,"Frequency",25,"Phase",pi/6)

Data Types: double

Output Arguments

boundaryLoad — Handle to boundary load

StructuralBC object

Handle to boundary load, returned as a StructuralBC object. See StructuralBC Properties.

More About

Specifying Nonconstant Parameters of a Structural Model

Use a function handle to specify the following structural parameters when they depend on space and, depending of the type of structural analysis, either time or frequency:

• 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 example, use function handles to specify the pressure load, x-component of the enforced displacement, and the initial displacement for this model.

structuralBoundaryLoad(model,"Face",12, ...
                             "Pressure",@myfunPressure)
structuralBC(model,"Face",2, ...
                   "XDisplacement",@myfunBC)
structuralIC(model,"Face",12, ...
                   "Displacement",@myfunIC)

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

function structuralVal = myfun(location,state)

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

function structuralVal = myfun(location)

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 the initial displacement or initial velocity).

• location — A structure containing these fields:

  • location.x — The x-coordinate of the point or points

  • location.y — The y-coordinate of the point or points

  • location.z — For a 3-D or an axisymmetric geometry, the z-coordinate of the point or points

  • location.r — For an axisymmetric geometry, the r-coordinate of the point or points

  Furthermore, for boundary conditions, the solver passes these 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 — For a 3-D or an axisymmetric geometry, z-component of the normal vector at the evaluation point or points

  • location.nr — For an axisymmetric geometry, r-component of the normal vector at the evaluation point or points

• state — A structure containing these fields for dynamic structural problems:

  • state.time contains the time at evaluation points.

  • state.frequency contains the frequency at evaluation points.

  state.time and state.frequency are scalars.

Boundary constraints and loads get these data from the solver:

• location.x, location.y, location.z, location.r

• location.nx, location.ny, location.nz, location.nr

• state.time or state.frequency (depending of the type of structural analysis)

Initial conditions get these data from the solver:

• location.x, location.y, location.z, location.r

• Subdomain ID

If a parameter represents a vector value, such as surface traction, spring stiffness, force, or displacement, 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.

If a parameter represents a scalar value, such as pressure or a displacement component, 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 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.

Additional Arguments in Functions for Nonconstant Structural 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:

structuralVal = ...
@(location,state) myfunWithAdditionalArgs(location,state,arg1,arg2...)
structuralBC(model,"Face",2,"XDisplacement",structuralVal)

structuralVal = ...
@(location) myfunWithAdditionalArgs(location,arg1,arg2...)
structuralIC(model,"Face",2,"Displacement",structuralVal)

Version History

Introduced in R2017b

R2025a: To be removed

structuralBoundaryLoad will be removed. Use faceLoad, edgeLoad, and vertexLoad instead.

For example, you can specify the surface traction for particular faces as follows.

gm = multicylinder([0.01,0.015],0.05);
model = femodel(AnalysisType="structuralStatic", ...
                Geometry=gm);
model.FaceLoad([2 5]) = faceLoad(SurfaceTraction=[0 0 100]);

The unified finite element model workflow defines the type of a problem and all of its parameters as the properties of an femodel object. This object enables you to specify physical parameters for structural, thermal, and electromagnetic types of analyses. The solver in the unified workflow uses only the parameters (properties) appropriate for the current analysis type while ignoring all other properties. If you switch the analysis type by setting the AnalysisType property of the model, the solver uses the appropriate set of properties corresponding to the new analysis type.

For more help migrating your existing code that uses StructuralModel to the unified finite element workflow, see Migration from Domain-Specific to Unified Workflow.

R2021b: Label to extract sparse linear models for use with Control System Toolbox

Now you can add a label for structural boundary loads to be used by the linearizeInput function. This function lets you pass structural boundary loads to the linearize function that extracts sparse linear models for use with Control System Toolbox.

R2019b: Concentrated boundary loads at arbitrary locations on geometry surfaces

You can now use addVertex to create new vertices at any points on boundaries of a 2-D or 3-D geometry represented by a DiscreteGeometry object. Then set concentrated boundary loads at these vertices.

R2019a: Concentrated force at a vertex

You can now specify concentrated force at a vertex.

R2018a: Time-dependent boundary loads

You can now specify time-dependent boundary loads by using function handles or specify the form and duration of the pressure pulse and the frequency and phase of sinusoidal pressure.