Creating structural models

The data and properties of each structural model are defined through a set of definitions in a .m script. These properties are stored in struct data structures. The following structs must be defined and provided as input to the ONSAS function in this order:

  1. materials
  2. elements
  3. boundaryConds
  4. initialConds
  5. mesh
  6. numericalMethod
  7. otherParams

Each struct has its own fields with specific names, used to store each corresponding property or information. Each field is obtained or assiged using structName.fieldName. A description of each struct and its fields follows at next.

The materials struct

The materials struct contains the information of the material behavior considered for each element.


This is a cell array with the string-names of the material models used, the options for these names are:

  • 'linearElastic': for linear behaviour in small strains and displacements. The scalar parameters of this model are $p_1=E$ the Young modulus and $p_2=\nu$ the Poisson's ratio.
  • 'SVK': for a Saint-Venant-Kirchhoff material where the parameters $p_1$ and $p_2$ are the Lamé parameters and $\textbf{E}$ is the Green-Lagrange strain tensor, with the strain-energy density function given by

\[\Psi( \textbf{E} ) = \frac{p_1}{2} tr(\textbf{E})^2 + p_2 tr(\textbf{E}^2) \quad p_1 = \frac{ E \nu }{ (1+\nu) (1-2\nu) } \quad p_2 = \frac{ E }{ 2 (1+\nu) }\]

  • 'NHC': for a Neo-Hookean compressible material


A cell structure with vectors with the material properties of each material used in the model. The $i$-th entry of the cell, contains a vector like this:

\[[ p_1 \dots p_{n_P} ]\]

where $n_P$ is the number of parameters of the constitutive model and $\mathbf{p}$ is the vector of constitutive parameters.


This is a cell with the scalar values of the densities of the materials used in the model.

The elements struct

The elements struct contains the information about the type of finite elements used and their corresponding parameters.


cell structure with the string-names of the elements used: node, truss, frame, triangle or tetrahedron. Other auxiliar types such as edge are also available


cell structure with auxiliar params information, required for some element types:

  • triangle vector with parameters, the first parameter is an integer indicating if plane stress (1) or plane strain (2) case is considered.


cell structure with the information of the geometry of the element.

1D elements

For truss or frame elements a vector with the cross-section properties is required:

\[[ crossSectionType, \,\, crossSectionParam_{1}, \,\,\dots,\,\, crossSectionParam_{n}]\]

with $n$ being the number of parameters of the cross section type, and crossSectionType a paramter setting the type of cross section. As follow:

  1. general sections areas and inertias are provided
  2. rectangular sections: thicknesses $t_y$ and $t_z$ are provided
  3. circular sections: diameter is provided.

See the crossSectionProps.m function for more details.

For edge elements the thickness is expected (for 2D load computations).

2D elements

For 2D elements such as triangle the thickness is expected to be introduced. The elementtype

The boundaryConds struct


cell containing the coordinates system for the loads applied in each BC, each entry should be a 'global' string or a 'local', or an empty array if no load is applied in that BC setting [].


cell with the inline function definitions of load factors of the loads applied of an empty array.


cell with the (row) vector of the components of the load case

\[[ f_x, \, m_x, \, f_y, \, m_y, \, f_z, \, m_z ]\]

where $f_i$ are the components of forces and $m_i$ are the moments. Both forces or moments are considered per unit of length in the case of truss/frame/edge elements, or per unit of area in the case of triangle.


cell with filenames of .m function file provided by the user that can be used to apply other forces.


cell with vectors of the local degrees of freedom imposed (integers from 1 to 6)


cell with vectors of the values of displacements imposed.


cell with vectors of the local degrees of freedom with springs (integers from 1 to 6)


cell with vectors of the values of the springs stiffnesses.

The initialConds struct

It initial conditions are homogeneous, then an empty struct should be defined initialConds = struct() ;.


matrix to set the value of displacements at the time step $t$=0. [default: []]


matrix to prescribe the value of velocities at the time step $t$=0. [default: []]

The mesh struct

The mesh struct contains the finite element mesh information.


matrix with the coordinates of all the nodes of the mesh. The $i$-th row contains the three coordinates of the node $i$: $[x_i , \, y_i ,\, z_i]$,


cell array with the elements and node-connectivity information. The $\{i,1\}$ entry contains the vector with the MEBI (Material, Element, boundaryConds and initialConds) indexes and the nodes of the $i$-th element. The structure of the vector at each entry of the cell is:

\[ [ materialInd, \, elementInd, \, boundaryCondInd, \, initialCondInd, \, node_1 \dots node_{n} ]\]

where the five indexes are natural numbers and $n$ is the number of nodes required by the type of element. If noproperty is assigned the $0$ index can be used, for instance, nodes used to introduced loads should be defined with materialIndex = 0.

The analysisSettings struct

This struct contains the parameters required to apply the numerical method for the resolution of the nonlinear equations:

  • methodName: string with the name of the method used: 'newtonRaphson','arcLength','newmark','alphaHHT'.
  • stopTolDeltau: float with tolerance for convergence in relative norm of displacements increment
  • stopTolForces: float with tolerance for convergence in relative norm of residual loads
  • stopTolIts: integer with maximum number of iterations per time step
  • deltaT: time step
  • finalTime: final time of simulation
  • incremArcLen: with of cylinder for arcLength method
  • deltaNM: delta parameter of newmark method
  • alphaNM: alpha parameter of newmark method
  • alphaHHT: alpha parameter of alpha-HHT method
  • solverLang: parameter setting the programming language of the solver: Octave (default) or C++ (binaries required).

another additional optional parameters are:

  • nodalDispDamping: scalar value of linear external viscous damping for the displacements degrees of freedom [default: 0]
  • iniMatUs: a matrix with initial solutions for each time step.

The otherParams struct

  • problemName: string with the name of the problem, to be used in outputs.
  • plotsFormat: strint indicating the format of the output. Use 'vtk' for vtk output.
  • controlDofs: matrix with information of the degrees of freedom to compute and control. Each row should contain this form: [ node localdof ].
  • storeBoolean: boolean to store the results of the current iteration such as the displacements, tangent matrices, normal forces and stresses. [default: 1]