full_syntax

# SPACAR Light full syntax

## Overview

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:

1. nodes: node positions
2. elements: element connectivity
3. nprops: node properties
4. eprops: element properties
5. opt: optional input

Output argument:

1. out: simulation results

## Input Arguments

### 1. Node positions

nodes is an nn×3 matrix for defining the positions of the nodes. Each row represents a node (there are nn 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.

### 2. Element connectivity

elements is an ne×2 matrix for defining elements. Each row represents an element (there are ne 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.

### 3. Node properties

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 kgm2) applied to node ([Ixx Ixy Ixz Iyy Iyz Izz]). Note the tensor components are needed, so Ixy, Ixz and Iyz 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 3-D space, according to the axis-angle 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 3-D space, according to the axis-angle 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.

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.

State-space representation:

Field Value Description
transfer_in 'force_x' Force input in x-direction on node for state-space equations. See opt.transfer.
'force_y' Force input in y-direction on node for state-space equations. See opt.transfer.
'force_z' Force input in z-direction on node for state-space equations. See opt.transfer.
transfer_out 'displ_x' Displacement output in x-direction on node for state-space equations. See opt.transfer.
'displ_y' Displacement output in y-direction on node for state-space equations. See opt.transfer.
'displ_z' Displacement output in z-direction on node for state-space equations. See opt.transfer.
'veloc_x' Velocity output in x-direction on node for state-space equations. See opt.transfer.
'veloc_y' Velocity output in y-direction on node for state-space equations. See opt.transfer.
'veloc_z' Velocity output in z-direction on node for state-space 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 user-specified 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

1. the first load step is in fact solely due to the full initial load,
2. the subsequent load steps have the full initial load and a part of the standard load,
3. the last load step is due to both the full initial and full standard load.

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).

### 4. Element properties

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: out-of-plane bending, 5 and 6: in-plane bending). For example: [2 5 6] allows flexibility in torsion and in-plane 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/m3).

Geometry and dimensions:

Field Value Description
cshape*1,2 'rect' Rectangular cross-sectional shape. Requires dim and orien field.
'circ' Circular cross-sectional shape. Requires dim field.
dim 1×2 vector For cshape='rect': width and thickness (in unit m) of cross-section.
double For cshape='circ': diameter (in unit m) of cross-section.
orien 1×3 vector Orientation of the cross-section. Values represent a vector in the 'width-direction' 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 0-255 map is used. Otherwise, the 0-1 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.

### 5. Optional

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 user-specified 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.
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/s2). 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 well-conditioned problems, a single load step is still feasible. For ill-conditioned 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: out-of-plane bending, 5 and 6: in-plane bending). For example: opt.rls(1).def = [2 3 4] releases torsion and out-of-plane 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 state-space 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 state-space 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 state-space equations with relative damping 0.01.

## Output Arguments

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 step-dependent data in two ways:

1. the values of a single result field for all load steps combined
2. the values of all result fields for only a single load step

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 ns.)

Field Value Description of column representation
stressmax 1×ns vector Maximum stress in the system (in unit Pa).
freq nndof×ns matrix Natural frequencies of the system (in unit Hz). Values are sorted from low to high.
buck nndof×ns 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×ns vector Position of node i. Values represent the x-, y- and z-coordinates (in unit m).
.r_eulzyx 3×ns matrix Rotation of node i in Euler angles. Values represent successive rotation (in radians) about the z, y, x axes.
.r_axang 4×ns matrix Rotation of node i in axis-angle representation. The first value represents the rotation angle (in radians) and the second to fourth values the normalized axis of rotation.
.r_quat 4×ns matrix Rotation of node i in quaternions.
.Freac 3×ns 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×ns 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×ns 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×ns matrix Compliance matrix of node i in local frame (co-rotational with node). This is an array of three dimensions. The load step varies along the third dimension.
statespace state-space object State-space representation of the system. This is only calculated when opt.transfer is used.
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 = 'x-label'.

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×ns matrix that contains the position of node 2 for all load steps
• out.step(3).node(2).p is a 3×1 vector that contains the position of node 2 for load step 3 only