====== 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:
- ''nodes'': node positions
- ''elements'': element connectivity
- ''nprops'': node properties
- ''eprops'': element properties
- ''opt'': optional input
Output argument:
- ''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:**
{{tablelayout?colwidth="100px,100px,-"}}
^ 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:**
{{tablelayout?colwidth="100px,100px,-"}}
^ Field ^ Value ^ Description ^
| ''mass'' | double | Point mass (in unit kg) assigned to node. |
| ''mominertia'' | 1x6 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:**
{{tablelayout?colwidth="140px,80px,-"}}
^ 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:**
{{tablelayout?colwidth="110px,100px,-"}}
^ Field ^ Value ^ Description ^
| ''rot'' | 1x4 vector | Prescribed rotation. Values represent the target orientation of the node in 3-D space, according to the [[https://en.wikipedia.org/wiki/Rotation_formalisms_in_three_dimensions#Euler_axis_and_angle_.28rotation_vector.29|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'' | 1x4 vector | Prescribed initial* rotation. Values represent the target orientation of the node in 3-D space, according to the [[https://en.wikipedia.org/wiki/Rotation_formalisms_in_three_dimensions#Euler_axis_and_angle_.28rotation_vector.29|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. |
**Applied loads:**
{{tablelayout?colwidth="140px,100px,-"}}
^ Field ^ Value ^ Description ^
| ''force'' | 1x3 vector | Force applied to node. Values represent the force components (in unit N) in the ''x''-, ''y''-, and ''z''-direction. |
| ''force_initial'' | 1x3 vector | Initial* force applied to node. Values represent the force components (in unit N) in the ''x''-, ''y''-, and ''z''-direction. |
| ''moment'' | 1x3 vector | Moment applied to node. Values represent the moment components (in unit Nm) about the ''x''-, ''y''-, and ''z''-axes. |
| ''moment_initial'' | 1x3 vector | Initial* moment applied to node. Values represent the moment components (in unit Nm) about the ''x''-, ''y''-, and ''z''-axes. |
**State-space representation:**
{{tablelayout?colwidth="120px,100px,-"}}
^ 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
- the first load step is in fact solely due to the full initial load,
- the subsequent load steps have the full initial load and a part of the standard load,
- 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.
{{tablelayout?colwidth="100px,100px,-"}}
^ 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**:
{{tablelayout?colwidth="100px,100px,-"}}
^ 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**:
{{tablelayout?colwidth="100px,100px,-"}}
^ 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'' | 1x2 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'' | 1x3 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):
{{tablelayout?colwidth="100px,100px,-"}}
^ Field ^ Value ^ Description ^
| ''color'' | 1x3 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.
{{tablelayout?colwidth="160px,240px,-"}}
^ 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 (may improve calculation time).|
| ''gravity'' | 1x3 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. |
| ''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. |
| ''spavisual'' | ''false'' | Do not show the Spavisual window after a simulation. |
| ''rigidstress'' | ''true'' | Consider the stress in rigid elements when computing the maximum Von Mises stress in ''opt.stressmax''. By default, this option is false and stress in rigid elements is ignored. |
| ''stressperelement'' | ''true'' | Compute the maximum Von Mises stress per element, stored in ''out.step(i).element(j).stressmax'' for element ''j'' at step ''i''. |
===== 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:
-the values of a //single// result field for //all// load steps combined
-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.)
{{tablelayout?colwidth="-,140px,140px,-"}}
^ Field ^^ Value ^ Description of column representation ^
| ''stressmax'' || 1×ns vector | Maximum stress in the system (in unit Pa). By default, only nonrigid elements are considered. See ''opt.rigidstress''. |
| ''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 [[https://en.wikipedia.org/wiki/Rotation_formalisms_in_three_dimensions#Euler_rotations|Euler angles]]. Values represent successive rotation (in radians) about the ''z'', ''y'', ''x'' axes. |
| | ''.r_axang'' | 4×ns matrix| Rotation of node ''i'' in [[https://en.wikipedia.org/wiki/Rotation_formalisms_in_three_dimensions#Euler_axis_and_angle_.28rotation_vector.29|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 [[https://en.wikipedia.org/wiki/Rotation_formalisms_in_three_dimensions#Quaternions|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'' | 6x6×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'' | 6x6×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. 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 = '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//