structuralBC

(To be removed) Specify boundary conditions for structural model

structuralBC will be removed. Use edgeBC and faceBC instead. (since R2023a) For more information on updating your code, see Version History.

Syntax

structuralBC(structuralmodel,RegionType,RegionID,"Constraint",Cval)

structuralBC(structuralmodel,RegionType,RegionID,"Displacement",Dval)

structuralBC(structuralmodel,RegionType,RegionID,"XDisplacement",XDval,"YDisplacement",YDval,"ZDisplacement",ZDval)

structuralBC(structuralmodel,RegionType,RegionID,"RDisplacement",RDval,"ZDisplacement",ZDval)

structuralBC(structuralmodel,RegionType,RegionID,"XDisplacement",XDval,Name,Value)

structuralBC(structuralmodel,RegionType,RegionID,"Constraint","multipoint")

structuralBC(___,"Reference",Coords)

structuralBC(___,"Reference",Coords,"Radius",R)

structuralBC(___,"Label",labeltext)

structuralBC(___,"Vectorized","on")

bc = structuralBC(___)

Description

Standard Boundary Constraints and Displacements

structuralBC(structuralmodel,RegionType,RegionID,"Constraint",Cval) specifies one of the standard structural boundary constraints. Here, Cval can be "fixed", "free", "roller", or "symmetric". The default value is "free".

Avoid using "symmetric" for transient and modal analysis, since the symmetric constraint can prevent the participation of some structural modes.

structuralBC(structuralmodel,RegionType,RegionID,"Displacement",Dval) enforces displacement on the boundary of type RegionType with RegionID ID numbers.

structuralBC(structuralmodel,RegionType,RegionID,"XDisplacement",XDval,"YDisplacement",YDval,"ZDisplacement",ZDval) specifies the x-, y-, and z-components of the enforced displacement.

structuralBC does not require you to specify all three components. Depending on your structural analysis problem, you can specify one or more components by picking the corresponding arguments and omitting others.

structuralBC(structuralmodel,RegionType,RegionID,"RDisplacement",RDval,"ZDisplacement",ZDval) specifies the r- and z-components of the enforced displacement for an axisymmetric model. The radial component (r-component) must be zero on the axis of rotation.

structuralBC does not require you to specify both components.

Harmonic, Rectangular, Triangular, and Trapezoidal Displacement Pulses

structuralBC(structuralmodel,RegionType,RegionID,"XDisplacement",XDval,Name,Value)specifies the form and duration of the time-varying value of the x-component of the enforced displacement. You can also specify the form and duration of the other components of the displacement as follows:

• structuralBC(...,"YDisplacement",YDval,Name,Value) for the y-component.

• structuralBC(...,"ZDisplacement",ZDval,Name,Value) for the z-component. Use this syntax for a 3-D or axisymmetric model.

• structuralBC(...,"RDisplacement",RDval,Name,Value) for the radial component in an axisymmetric model.

Multipoint Constraint

structuralBC(structuralmodel,RegionType,RegionID,"Constraint","multipoint") sets the multipoint constraint using all degrees of freedom on the combination of geometric regions specified by RegionType and RegionID. The reference location for the constraint is the geometric center of all nodes on the combination of all specified geometric regions.

This syntax is required if you intend to use results obtained with the model order reduction technique in the Simscape™ Multibody™ Reduced Order Flexible Solid block. Simscape models expect the connections at all joints to have six degrees of freedom, while Partial Differential Equation Toolbox™ uses two or three degrees of freedom at each node. Setting a multipoint constraint ensures that all nodes and all degrees of freedom for the specified geometric regions have a rigid constraint with the geometric center of all specified geometric regions altogether as the reference point. The reference location has six degrees of freedom.

For better performance, specify geometric regions with a minimal number of nodes. For example, use a set of edges instead of using a face, and a set of vertices instead of using an edge.

structuralBC(___,"Reference",Coords) specifies the reference point for the multipoint constraint instead of using the geometric center of all specified regions as a reference point.

Use this syntax with the input arguments from the previous syntax.

structuralBC(___,"Reference",Coords,"Radius",R) restricts the region for multipoint constraint to nodes within the circle (for a 2-D geometry) or sphere (for a 3-D geometry) of radius R around the reference point.

Sparse Linear Models for Use with Control System Toolbox

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

Vectorized Evaluation for Function Handles

structuralBC(___,"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.

Structural Boundary Condition Object

bc = structuralBC(___) returns the structural boundary condition object using any of the input arguments from previous syntaxes.

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

"Vertex" | "Edge" | "Face" (for a 3-D model only)

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

You cannot use the following geometric region types if you specify the "roller" or "symmetric" value for the boundary constraint Cval:

• "Edge" for a 3-D model

• "Vertex" for a 2-D or 3-D model

Example: structuralBC(structuralmodel,"Face",[2,5],"XDisplacement",0.1)

Data Types: char | string

RegionID — Geometric region ID

vector of positive integers

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

Example: structuralBC(structuralmodel,"Face",[2,5],"XDisplacement",0.01)

Data Types: double

Displacement

Dval — Enforced displacement

numeric vector | function handle

Enforced displacement, specified as a numeric vector or function handle. A numeric vector must contain two elements for a 2-D model (including axisymmetric models) 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 an enforced displacement vector at the boundary coordinates provided by the solver. In case of a transient or frequency response analysis, Dval also can be a function of time or frequency, respectively. For details, see More About.

Note that when you specify Dval for an axisymmetric model, the radial displacement on the axis of rotation must always be zero.

Example: structuralBC(structuralmodel,"Face",[2,5],"Displacement",[0;0;0.01])

Data Types: double | function_handle

XDval — x-component of enforced displacement

number | function handle

x-component of enforced displacement, specified as a number or function handle. The function must return a row vector. Each element of this vector corresponds to the x-component value of the enforced displacement at the boundary coordinates provided by the solver. In case of a transient or frequency response analysis, XDval also can be a function of time or frequency, respectively. For details, see More About.

Example: structuralBC(structuralmodel,"Face",[2,5],"XDisplacement",0.01)

Data Types: double | function_handle

YDval — y-component of enforced displacement

number | function handle

y-component of enforced displacement, specified as a number or function handle. The function must return a row vector. Each element of this vector corresponds to the y-component value of the enforced displacement at the boundary coordinates provided by the solver. In case of a transient or frequency response analysis, YDval also can be a function of time or frequency, respectively. For details, see More About.

Example: structuralBC(structuralmodel,"Face",[2,5],"YDisplacement",0.01)

Data Types: double | function_handle

ZDval — z-component of enforced displacement

number | function handle

z-component of enforced displacement, specified as a number or function handle. The function must return a row vector. Each element of this vector corresponds to the z-component value of the enforced displacement at the boundary coordinates provided by the solver. For a transient or frequency response analysis, ZDval also can be a function of time or frequency, respectively. For details, see More About.

You can specify ZDval for a 3-D or axisymmetric model.

Example: structuralBC(structuralmodel,"Face",[2,5],"ZDisplacement",0.01)

Data Types: double | function_handle

RDval — r-component of enforced displacement

number | function handle

r-component of enforced displacement, specified as a number or function handle. The function must return a row vector. Each element of this vector corresponds to the r-component value of the enforced displacement at the boundary coordinates provided by the solver. For a transient or frequency response analysis, RDval also can be a function of time or frequency, respectively. For details, see More About.

You can specify RDval only for an axisymmetric model. RDval must be zero on the axis of rotation.

Example: structuralBC(structuralmodel,"Face",[2,5],"RDisplacement",0.01)

Data Types: double | function_handle

Cval — Standard structural boundary constraints

"free" (default) | "fixed" | "roller" | "symmetric" | "multipoint"

Standard structural boundary constraints, specified as "free","fixed","roller", "symmetric", or "multipoint".

You cannot use the "roller" and "symmetric" values with the following geometric region types:

• "Edge" for a 3-D model

• "Vertex" for a 2-D or 3-D model

Example: structuralBC(structuralmodel,"Face",[2,5],"Constraint","fixed")

Data Types: char | string

Coords — Reference point location for multipoint constraint

2-by-1 numeric vector | 3-by-1 numeric vector

Reference point location for the multipoint constraint, specified as a 2-by-1 (for a 2-D geometry) or 3-by-1 (for a 3-D geometry) numeric vector.

Example: structuralBC(structuralmodel,"Vertex",[1,3,5:10],"Constraint","multipoint","Reference",[0;0;1])

Data Types: double

R — Radius of circle (for 2-D geometry) or sphere (for 3-D geometry) around reference point location for multipoint constraint

positive number

Radius of a circle (for a 2-D geometry) or a sphere (for a 3-D geometry) around the reference point location for the multipoint constraint, specified as a positive number.

Example: structuralBC(structuralmodel,"Vertex",[1,3,5:10],"Constraint","multipoint","Reference",[0;0;1],"Radius",0.2)

Data Types: double

labeltext — Label for structural boundary condition

character vector | string

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

Data Types: char | string

Name-Value Arguments

Example: structuralBC(structuralmodel,"Face",[2,5],"XDisplacement",0.01,"RiseTime",0.5,"FallTime",0.5,"EndTime",3)

Use one or more name-value pair arguments to specify the form and duration of the time-varying value of a component of displacement. Specify the displacement value using one of the following arguments: XDval, YDval, ZDval, or RDval. You cannot use these name-value pair arguments to specify more than one time-varying component or to specify the Dval value.

You can model rectangular, triangular, and trapezoidal displacement pulses. If the start time is 0, you do not need to specify 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 displacement by specifying its frequency and initial phase. If the initial phase is 0, you do not need to specify it.

Rectangular, Triangular, or Trapezoidal Pulse

StartTime — Start time for displacement component

0 (default) | positive number

Start time for the displacement component, specified as 0 or a positive number. Specify this argument only for transient structural models.

Example: structuralBC(structuralmodel,"Face",[2,5],"XDisplacement",0.01,"StartTime",1,"EndTime",3)

Data Types: double

EndTime — End time for displacement component

positive number

End time for the displacement component, specified as a positive number equal or greater than the start time value. Specify this argument only for transient structural models.

Example: structuralBC(structuralmodel,"Face",[2,5],"XDisplacement",0.01,"StartTime",1,"EndTime",3)

Data Types: double

RiseTime — Rise time for displacement component

positive number

Rise time for the displacement component, specified as a positive number. Specify this argument only for transient structural models.

Example: structuralBC(structuralmodel,"Face",[2,5],"XDisplacement",0.01,"RiseTime",0.5,"FallTime",0.5,"EndTime",3)

Data Types: double

FallTime — Fall time for displacement component

positive number

Fall time for the displacement component, specified as a positive number. Specify this argument only for transient structural models.

Example: structuralBC(structuralmodel,"Face",[2,5],"XDisplacement",0.01,"RiseTime",0.5,"FallTime",0.5,"EndTime",3)

Data Types: double

Harmonic Displacement

Frequency — Frequency of sinusoidal displacement component

positive number

Frequency of a sinusoidal displacement component value, specified as a positive number in radians per unit of time. Specify this argument only for transient structural models.

Example: structuralBC(structuralmodel,"Face","XDisplacement",0.01,"Frequency",25)

Data Types: double

Phase — Frequency of sinusoidal displacement component

0 (default) | positive number

Phase of a sinusoidal displacement component value, specified as a positive number in radians. Specify this argument only for transient structural models.

Example: structuralBC(structuralmodel,"Face",[2,5],"XDisplacement",0.01,"Frequency",25,"Phase",pi/6)

Data Types: double

Output Arguments

bc — Handle to boundary condition

StructuralBC object

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

More About

Degrees of Freedom (DoFs)

In Partial Differential Equation Toolbox, each node of a 2-D or 3-D geometry has two or three degrees of freedom (DoFs), respectively. DoFs correspond to translational displacements. If the number of mesh points in a model is NumNodes, then the toolbox assigns the IDs to the degrees of freedom as follows:

• Numbers from 1 to NumNodes correspond to an x-displacement at each node.

• Numbers from NumNodes+1 to 2*NumNodes correspond to a y-displacement at each node.

• Numbers from 2*NumNodes+1 to 3*NumNodes correspond to a z-displacement at each node of a 3-D geometry.

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)

Tips

• Restrain all rigid body motions by specifying as many boundary conditions as needed. If you do not restrain all rigid body motions, the entire geometry can freely rotate or move. The resulting linear system of equations is singular. The system can take a long time to converge, or it might not converge at all. If the system converges, the solution includes a large rigid body motion in addition to deformation.

Version History

Introduced in R2017b

R2025a: To be removed

structuralBC will be removed. Use edgeBC and faceBC instead.

For example, you can specify particular faces as fixed boundaries.

gm = multicylinder([0.01,0.015],0.05);
model = femodel(AnalysisType="structuralStatic", ...
                Geometry=gm);
model.FaceBC([1 4]) = faceBC(Constraint="fixed");

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 conditions to be used by the linearizeInput function. This function lets you pass structural boundary conditions to the linearize function that extracts sparse linear models for use with Control System Toolbox.

R2020a: Axisymmetric analysis

You can now specify an enforced displacement for a structural axisymmetric model.

R2019b: Concentrated boundary constraints 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 constraints at these vertices.

R2019b: Multipoint Constraint

You can now set a multipoint constraint, which ensures that all nodes and all degrees of freedom have a rigid constraint with the geometric center of all specified geometric regions together as the reference point. The reference location has six degrees of freedom.

R2019a: Boundary constraints on edges and vertices

You can now specify an enforced displacement and the 'free' and 'fixed' boundary constraints on vertices and edges for both 2-D and 3-D models. The previous versions of this function let you specify the displacement and boundary constraints values only on edges for 2-D models and faces on 3-D models.

R2018a: Time-dependent boundary conditions

You can now specify time-dependent boundary conditions by using function handles or specify the form and duration of x-, y-, or z-component of the enforced displacement and the frequency and phase of sinusoidal displacement.