In the MATLAB environment, a SPACAR Light simulation is performed with the spacarlight()
command. The command requires at least four input arguments (a fifth is optional). If fewer are supplied, warnings and a visualization can appear to help in completing the input. The results of a successful simulation are returned in a structure (the first and only output argument).
Typical usage:
out = spacarlight(nodes, elements, nprops, eprops); %default use out = spacarlight(nodes, elements, nprops, eprops, opt); %use with optional input arguments
Input arguments:
nodes
: node positions elements
: element connectivity nprops
: node propertieseprops
: element propertiesopt
: optional input Output argument:
out
: simulation results
nodes
is an n_{n}×3 matrix for defining the positions of the nodes. Each row represents a node (there are n_{n} nodes). The row number determines the number a node gets. The first column contains the x
coordinate of the node position, the second column the y
coordinate, and the third column the z
coordinate.
elements
is an n_{e}×2 matrix for defining elements. Each row represents an element (there are n_{e} elements). The row number determines the number an element gets. Each element connects two nodes. The first column contains the number of the node that the element is connected to on one side, the second column the node number that the element is connected to on the other side.
nprops
is a structure array for assigning properties to nodes, such as boundary conditions, applied loads, and inertia. The usage is nprops(i).field = value;
to assign property field
with value value
to node i
. The following list contains an overview of all possible fields.
Boundary conditions:
Field  Value  Description 

fix  true  Fix both the position and orientation of the node. 
fix_pos  true  Fix the position of the node. 
fix_orien  true  Fix the orientation of the node. 
fix_x  true  Fix only the x position of the node. 
fix_y  true  Fix only the y position of the node. 
fix_z  true  Fix only the z position of the node. 
Inertia:
Field  Value  Description 

mass  double  Point mass (in unit kg) assigned to node. 
mominertia  1×6 vector  Moment of inertia (in unit kgm^{2}) applied to node ([I_{xx} I_{xy} I_{xz} I_{yy} I_{yz} I_{zz}] ). Note the tensor components are needed, so I_{xy} , I_{xz} and I_{yz} represent the negative of the products of inertia. 
Prescribed input displacement:
Field  Value  Description 

displ_x  double  Prescribed displacement (in unit m) in x direction. Value is the target x coordinate of the node position (in global frame). 
displ_y  double  Prescribed displacement (in unit m) in y direction. Value is the target y coordinate of the node position (in global frame). 
displ_z  double  Prescribed displacement (in unit m) in z direction. Value is the target z coordinate of the node position (in global frame). 
displ_initial_x  double  Prescribed initial^{*} displacement (in unit m) in x direction. Value is the target x coordinate of the node position (in global frame). 
displ_initial_y  double  Prescribed initial^{*} displacement (in unit m) in y direction. Value is the target y coordinate of the node position (in global frame). 
displ_initial_z  double  Prescribed initial^{*} displacement (in unit m) in z direction. Value is the target z coordinate of the node position (in global frame). 
Prescribed rotation:
Field  Value  Description 

rot  1×4 vector  Prescribed rotation. Values represent the target orientation of the node in 3D space, according to the axisangle notation. The first value represents the rotation angle (in radians) and the second to fourth values the normalized axis of rotation, all with respect to the global frame. Note that this input complete defines and constrains the orientation of the node, i.e. no other simultaneous rotations of the node are possible. 
rot_initial  1×4 vector  Prescribed initial^{*} rotation. Values represent the target orientation of the node in 3D space, according to the axisangle notation. The first value represents the rotation angle (in radians) and the second to fourth values the normalized axis of rotation, all with respect to the global frame. Note that this input complete defines and constrains the orientation of the node, i.e. no other simultaneous rotations of the node are possible. 
Applied loads:
Field  Value  Description 

force  1×3 vector  Force applied to node. Values represent the force components (in unit N) in the x , y , and z direction. 
force_initial  1×3 vector  Initial^{*} force applied to node. Values represent the force components (in unit N) in the x , y , and z direction. 
moment  1×3 vector  Moment applied to node. Values represent the moment components (in unit Nm) about the x , y , and z axes. 
moment_initial  1×3 vector  Initial^{*} moment applied to node. Values represent the moment components (in unit Nm) about the x , y , and z axes. 
Statespace representation:
Field  Value  Description 

transfer_in  'force_x '  Force input in x direction on node for statespace equations. See opt.transfer . 
'force_y '  Force input in y direction on node for statespace equations. See opt.transfer . 

'force_z '  Force input in z direction on node for statespace equations. See opt.transfer . 

transfer_out  'displ_x '  Displacement output in x direction on node for statespace equations. See opt.transfer . 
'displ_y '  Displacement output in y direction on node for statespace equations. See opt.transfer . 

'displ_z '  Displacement output in z direction on node for statespace equations. See opt.transfer . 

'veloc_x '  Velocity output in x direction on node for statespace equations. See opt.transfer . 

'veloc_y '  Velocity output in y direction on node for statespace equations. See opt.transfer . 

'veloc_z '  Velocity output in z direction on node for statespace equations. See opt.transfer . 
*) Regarding the initial forces, moments, displacements and rotations:
Normal use is to apply a load using the force
or moment
property. In a simulation, this load value is applied in linearly increasing steps, starting from zero and reaching the userspecified value at the last step. The simulation results are returned per load step. The default number of steps that are used is 10; it can be changed with the opt.loadsteps
property.
The initial loads (force_initial
and moment_initial
) are applied in full value at the first load step and remain constant. When both an initial load and a standard load are present, their sum is applied to the system. This means that then
The same holds for prescribing standard displacement (displ_{x,y,z}
), initial displacement (displ_initial_{x,y,z}
), standard rotation (rot
) and initial rotation (rot_initial
).
eprops
is a structure array for assigning properties to elements, such as dimensions, material constants, flexibility, and visual appearance. Properties are created in sets, such that the same set of properties can be assigned to multiple elements.
The usage is eprops(i).field = value;
to assign property field
with value value
to set i
. The following list contains an overview of all possible fields.
Field  Value  Description 

elems (required)  1×n vector  Numbers of elements to which the properties apply. 
flex  1×n vector  Flexibility. Values represent beam deformation modes that are to be considered flexible (1: elongation, 2: torsion: 3 and 4: outofplane bending, 5 and 6: inplane bending). For example: [2 5 6] allows flexibility in torsion and inplane bending. 
nbeams  integer  Number of beam elements used in the simulation. If omitted, the default value 1 is used. 
cw  true  Enable the effective increase in torsional stiffness due to constrained warping at the nodes of the element. 
Material constants:
Field  Value  Description 

emod ^{*1}  double  Young's modulus (in unit Pa). 
smod ^{*1}  double  Shear modulus (in unit Pa). 
dens ^{*1}  double  Density (in unit kg/m^{3}). 
Geometry and dimensions:
Field  Value  Description 

cshape ^{*1,2}  'rect '  Rectangular crosssectional shape. Requires dim and orien field. 
'circ '  Circular crosssectional shape. Requires dim field. 

dim  1×2 vector  For cshape='rect ': width and thickness (in unit m) of crosssection. 
double  For cshape='circ ': diameter (in unit m) of crosssection. 

orien  1×3 vector  Orientation of the crosssection. Values represent a vector in the 'widthdirection' of the element. 
Visual appearance (these properties only affect the visualization, not the simulation):
Field  Value  Description 

color  1×3 vector  Color of element. Values represent rgb color values between 0 and 1, or between 0 and 255. If any of the values specified are larger than 1, the 0255 map is used. Otherwise, the 01 map is used. 
string  Color of element. String is name from the color table below.  
double  Color of element. Value is index from the color table below.  
opacity  double  Opacity of element. Value between 0 (transparent) and 1 (opaque). 
hide  true  Hide element in visualization (note that it is still included in the simulation!). 
Color table:
Index  Name  RGB values  Color 

1  'blue '  162, 195, 214  
2  'grey '  198, 198, 198  
3  'darkblue '  0, 124, 176  
4  'darkgrey '  112, 112, 112  
5  'green '  128, 194, 143  
6  'darkgreen '  90, 137, 101 
*1: These properties are required when flexibility (flex
) is enabled.
*2: These properties are required when a density value (dens
) is provided.
opt
is a structure array for specifying optional input. The usage is opt.field = value;
to assign value value
to property field
. The following list contains an overview of all possible fields.
Field  Value  Description 

filename  string  Filename of the data files involved in the SPACAR simulation. If omitted, filenname 'spacar_file' is used. 
silent  true  Activation of 'silent' mode of SPACAR Light. In the silent mode, the input arguments (nodes , elements , nprops , eprops , rls ) are not validated and not checked for errors (improving speed). Also, visualization after simulation is turned off. This feature can be useful when e.g. running a lot of SPACAR Light simulations in an optimization or iteration loop. 
calcbuck  true  Calculation of buckling loads. Multipliers with respect to the combined applied load are returned. It is recommended to only apply a single force or moment to the system. Whenever input displacements or rotations are used, the multipliers are also with respect to the equivalent reaction loads. Note that the loads nprops(i).force and nprops(i).moment are applied in (linearly increasing) steps: they only reach the userspecified value at the last step. The multipliers are calculated with respect to the current load at each of these steps. 
calccompl  false  Disable calculation of compliance matrices of the nodes (may improve calculation time). 
gravity  1×3 vector  Loads due to gravity. Values represent the components of the gravitational acceleration in x , y , and z direction (in unit m/s^{2}). For example: [0 0 9.81] . 
loadsteps  integer  Number of load steps used in the simulation and visualization. If not specified, the default number of 10 load steps is used. For creating smooth plots and visualizations, you may want to increase this number. For optimization purposes, you may want to reduce this number to increase computational speed. For wellconditioned problems, a single load step is still feasible. For illconditioned problems (involving large loads, large prescribed displacements, or buckling ), a larger number of load steps is required for the simulation to converge. 
rls(i).def  1×n vector  Deformation modes of element i that are to be considered released (1: elongation, 2: torsion: 3 and 4: outofplane bending, 5 and 6: inplane bending). For example: opt.rls(1).def = [2 3 4] releases torsion and outofplane bending deformations of element 1. 
showinputonly  true  Only create a visualization of the defined nodes and elements, without running any simulation. Useful for debugging connectivity and inspecting node and element numbering. 
transfer  true  Calculation of statespace equations. Requires specification of at least one input and one output, by means of nprops(i).transfer_in and nprops(i).transfer_out . Cannot be used with applied forces, applied moments, prescribed displacements, and buckling load multipliers. 
1×2 cell  Calculation of statespace equations that include relative damping for all modes of the system. (This value only affects the output in out.statespace ; the eigenfrequency output in out.freq and Spavisual remain undamped.) For example: opt.transfer = {true 0.01} calculates statespace equations with relative damping 0.01. 

customvis  {'modeshape','maximum 20'}  The maximum number of mode shapes, in this case 20, that are shown in the Spavisual window. If omitted, the default value of 10 is used. 
out
is a structure array that contains the simulation results. Most result fields are dependent on the load step. For convenience, the out
structure provides the same load stepdependent data in two ways:
Both ways are detailed below.
1. Data for all load steps combined
In the fields of the out
structure (unless otherwise noted), each column contains data for a certain load step. The following list describes what those columns represent. (The total number of load steps is n_{s}.)
Field  Value  Description of column representation  

stressmax  1×n_{s} vector  Maximum stress in the system (in unit Pa).  
freq  n_{ndof}×n_{s} matrix  Natural frequencies of the system (in unit Hz). Values are sorted from low to high.  
buck  n_{ndof}×n_{s} matrix  Buckling load multipliers of the system. Values are sorted from low to high. Note: load multipliers are only calculated if opt.calcbuck = true . 

node(i)  structure  Results for node i . Subfields are given directly below: 

.p  1×n_{s} vector  Position of node i . Values represent the x , y  and z coordinates (in unit m). 

.r_eulzyx  3×n_{s} matrix  Rotation of node i in Euler angles. Values represent successive rotation (in radians) about the z , y , x axes. 

.r_axang  4×n_{s} matrix  Rotation of node i in axisangle representation. The first value represents the rotation angle (in radians) and the second to fourth values the normalized axis of rotation. 

.r_quat  4×n_{s} matrix  Rotation of node i in quaternions. 

.Freac  3×n_{s} matrix  Reaction forces at node i . Values represent the vector components of the reaction force (in unit N) in x , y , and z direction. Reaction forces only exist for nodes that have fixed boundary conditions or prescribed motion. 

.Mreac  3×n_{s} matrix  Reaction moments at node i . Values represent the vector components of the reaction moment (in unit Nm) in x , y , and z direction. Reaction moments only exist for nodes that have fixed boundary conditions or prescribed motion. 

.CMglob  6×6×n_{s} matrix  Compliance matrix of node i in global frame (fixed frame). This is an array of three dimensions. The load step varies along the third dimension. 

.CMloc  6×6×n_{s} matrix  Compliance matrix of node i in local frame (corotational with node). This is an array of three dimensions. The load step varies along the third dimension. 

statespace  statespace object  Statespace representation of the system. This is only calculated when opt.transfer is used. Requires the ss command in MATLAB (see doc ss ), e.g. from the Control System Toolbox. 

version  string  SPACAR Light version number.  
ndof  integer  Number of degrees of freedom.  
fighandle  figure handle  MATLAB figure handle of Spavisual figure. Useful for custom visualizations, e.g. a custom x axis label: out.fighandle.Children.XLabel.String = 'xlabel '. 
2. Data for a single load step
All of the above fields can also be found as subfields of out.step(i)
. As subfields of step(i)
, they contain only the data for load step i
. For example:
out.node(2).p
is a 3×n_{s} matrix that contains the position of node 2 for all load stepsout.step(3).node(2).p
is a 3×1 vector that contains the position of node 2 for load step 3 only