2.1 Nodes, DoFs and channels

The VIBES Toolbox for MATLAB contains several different classes that can be used to describe Finite Element nodes, Virtual Points, Degrees of Freedom, measurement channels, and more. These classes help you to make the bookkeeping of your data easier. This tutorial shows how to construct, modify and use objects of the following classes:

• vibes.Node
• vibes.VirtualPoint
• vibes.DoF
• vibes.Channel

Class hierarchy

See the figure below to gain insights into the hierarchy of the different node and DoF classes in the VIBES Toolbox.

Constructing nodes

The vibes.Node class is the most basic building block of any model. The easiest way to construct an object of this class is from an N x 3 matrix of node positions. We will demonstrate this by building the nodes that represent the vertices of a block.

pos =  [0 0 0;...
        0 1 0;...
        1 0 0;...
        1 1 0;...
        0 0 0.5;...
        0 1 0.5;...
        1 0 0.5;...
        1 1 0.5];

nodes = vibes.Node(pos);

% Display the node list to see what properties a node has. As you can see,
% the node number and name were set automatically.
disp(nodes)

Additional properties of the nodes, such as the node numbers and grouping, can be specified as extra input arguments. Setting a grouping can be useful to track which nodes belong together. We will give the bottom 4 nodes a different grouping from the top 4.

nnr = 101:108;

grp = [1; 1; 1; 1; 2; 2; 2; 2];

nodes = vibes.Node(pos,nnr,grp)

Selecting and plotting nodes

You can show the location of the nodes in the 3D viewer by using the plot command. You can also specify a plot style in this command.

V = vibes.figure3d;

nodes.plot('ro')

Suppose we would like to plot the bottom nodes with a different color. You can select nodes from the list using the vibes.Node/select method.

nodes1 = nodes.select('Grouping',1);
nodes2 = nodes.select('Grouping',2);

% Plot the bottom nodes in red and the top nodes in blue
V.clf();
nodes1.plot('ro')
nodes2.plot('bo')

A different way to do this is to select those nodes with a Z-coordinate smaller than 0.25. The vibes.Node/select method accepts <, > and == operators to achieve this.

nodes1 = nodes.select('Z','<',0.25);
nodes2 = nodes.select('Z','>',0.25);

V.clf();
nodes1.plot('ro')
nodes2.plot('bo')

Virtual Points

Virtual Points are a special type of node which contain extra information on the types of Interface Displacement Modes (IDM) associated with it. See vibes.VirtualPoint for more information on IDM types.

You can construct vibes.VirtualPoint objects similarly to vibes.Node objects. Use the third argument to specify the IDM types.

pos = [0 0 0];

nnr = 100;

types = 1:6;

vp = vibes.VirtualPoint(pos,nnr,types)

Nodes in numerical models

Usually, nodes are constructed automatically when loading or importing numerical models. The node list can be found in the Nodes property of the model object.

mck = vibes.load('VIBES,Examples,Datasets','mat','Crane','Crane.MCKModel.mat');
nodes = mck.Nodes;

Degrees of Freedom

Each node in the model has Degrees of Freedom (DoFs) associated with it, describing its motion in terms of translations and rotations. A table detailing which DoFs belong to which nodes can be found in the DoF property of the model object. For smaller models (<10.000 DoFs), it is also helpful to construct vibes.DoF objects. This happens automatically when the DoFs property of the model object is requested.

dofs = mck.DoFs;

% Display the first 12 DoFs of the model to see their properties
disp(dofs(1:12))

% You can also use the vibes.DoF/select method for vibes.DoF objects. Use
% this to select, for example, only the translational DoFs of node 22.
dofs_select = dofs.select('NodeNumber',22,'Type','Translation')

Channel objects

vibes.DoF objects can be converted to vibes.Channel objects, which is a subclass of vibes.DoF. The vibes.Channel class contains extra information which is helpful to describe physical measurement channels, such as units and an optional description. The following properties are added:

• Name: to denote the name of the channel
• Description: to add a description to the channel
• Quantity: a vibes.Quantity object indicating the physical quantity of the channel
• Unit: a vibes.Unit object which is actually a child of the Quantity property, but exposed here for convenience
• Notes: a field that can be used to store additional information

ch = dofs_select.toChannel

You can also construct DoFs and channels directly from nodes and Virtual Points.

% Specify the DoF types when constructing from a node.
types = 1:6;
dofs = nodes1.toDoF(types)

% Specify the quantity type when constructing channels.
qtype = 2; % Acceleration
ch = vp.toChannel(qtype)

Channels in datasets

Usually, channels are constructed automatically when loading or importing a dataset. The channel list can be found in the Channels property of the dataset object.

TS = vibes.load('VIBES,Examples,Datasets','mat','i3','i3Measurement.TimeSeries.mat');
ch = TS.Channels;

The channels for this particular dataset correspond to an acceleration sensor and a microphone. This is reflected in their respective quantities and units.

disp(ch)

You can use the select method to pick a specific channel from the list, for example, to plot it. We will demonstrate this by plotting only the microphone channel of the time series object.

ch_i = ch.select('Quantity','Sound Pressure');
TS.plot(ch_i)

Reference channels

Some dataset objects, namely the subclasses of vibes.abstract.RefDataset, have two sets of channels. The Channels are the measurement outputs, whereas the RefChannels are the reference or input channels. An example of such a class is the frequency response function matrix class, vibes.FRFMatrix.

% Load an object of class vibes.FRFMatrix
YA = vibes.load('VIBES,Examples,Datasets','mat','Benchmark','YAqm.FRFMatrix.mat');

Display its channels and reference channels. Notice that the reference channels describe force inputs, which are reflected in their quantities and units.

disp(YA.Channels)
disp(YA.RefChannels)

DoF-matching of DoFs and channels

Sometimes, it can be helpful to compare two sets of DoFs or channels to each other, for example, when coupling two substructures.

% Load the FRFMatrix of a different structure
YB = vibes.load('VIBES,Examples,Datasets','mat','Benchmark','YBqm.FRFMatrix.mat');

Display the channels of the second FRF matrix. Notice that the first six channels have the same positions, directions, and types as the first six channels of YA.

disp(YB.Channels)

The VIBES Toolbox identifies matching channels and DoFs automatically using the vibes.DoF/match method. This method compares the properties of two sets of DoFs, and when they are within a specified tolerance, they are marked as a match. The method returns two vectors containing the indices of matching DoFs.

uA = YA.Channels;
uB = YB.Channels;

[idxA,idxB] = match(uA,uB)

You can customize the properties that are used for the DoF-matching. By default, position, direction, and type are matched. This means that force channels and acceleration channels match when using the default settings:

fA = YA.RefChannels;
fB = YB.RefChannels;

[idxA,idxB] = match(uA,fB)

Match using the Unit property as well to prevent force channels matching with acceleration channels.

[idxA,idxB] = match(uA,fB,'Unit',true)

Matching operations

You can request extra output arguments from the vibes.DoF/match method to inspect the DoF-matching operation. The method will return a vibes.operation.MatchingOperation object. This object contains all the information on the matching operation, such as the tolerances used to compare the DoF properties.

[idxA,idxB,Opts] = match(uA,uB)

Automatic DoF-matching in operations

Many operations that can be performed on dataset objects, such as matrix multiplication and inverse operations, automatically keep track of matching channels and reference channels. If you would like to know the result of this automatic matching or if you would like to customize the properties and tolerances for the matching procedure, you can use the vibes.operation.MatchingOperation object.

% The matching options and results can be requested as an extra output
% argument.
[YC,Opts] = YA*YB

Customize the procedure by specifying extra properties or tolerances.

[YC,Opts] = mtimes(YA,YB,'DoFMatching',{'Grouping',true})