(section:CBR)=
# Craig-Bampton Reduction

The CBR solution method makes a superelement as specified in the CBModel
section of the text input file. The requirements for Sierra/SD to use
this superelement are in the next section. This reduction is often
called a Component Mode Synthesis (or `CMS`). For limitations and use
cases see the `Craig-Bampton reduction Solution Case` section of the
Users manual.

## Input Required

The [following input](/tests/Salinas_rtest/training/exampleproblem/cbr/cbr.inp) is required to run the CBR solution.

### Solution

The solution section must contain input for the number of modes. This is
the number of fixed interface modes to compute. It must be entered, and
will be different than the number of system modes desired. It must also
contain shift to ensure that the matrices are not indefinite. See the
`Craig-Bampton reduction Solution Case` section of the Users manual for
more details on full list of solution parameters.

### CBModel

The `CBModel` defines most of the parameters for the solution. It
defines the interface boundary nodes. Note that all degrees of freedom
of each node is a part of the model. Either define all six degrees of
freedom as interface dofs, or permit them to be reduced in this step.
Interface nodes may be connected to any structural element (solids,
shells or beams), but not to a constraint relation.

For example,

:::{input}
CBMODEL
  nodeset=1
  format=mfile
  file=cbr.m
  GlobalSolution = yes
  inertia_matrix = yes
END
:::

See the example below for helpful insights on how to verify the model is
a good approximation of the original system.

### History

For the `CBR` solution case, the history file contains the Output
Transfer Matrix (OTM). The history section is only necessary if the OTM
output is desired. Otherwise, it is optional. Only the following will be
honored (others will be ignored).

- displacement

- strain

- stress

Note that the transfer matrices for acceleration and velocity are
obtained by differentiating the displacement equation.

## Mesh

The geometry as shown in Figure {numref}`%s <fig:CBR>` consists of a
cone with a nodeset on the top and bottom edge. The model reduction
consists in reducing the stiffness matrix from the 80 nodes in this
model to the interface nodes (3 nodes on the base in nodeset 3). Thus,
there are 18 constraint modes. We choose to retain 4 fixed interface
modes for this example.

:::{figure-md} fig:CBR

![](mesh.png)

[Example CBR model](/tests/Salinas_rtest/training/exampleproblem/cbr/cbr.exo)
:::

## Example

Running the model and examining the output, you will notice the
following.

1.  For this example there are two sets of eigenvalues (Ritz values)
    output to the screen. The first, a set of 10 modes, corresponds to
    the eigen problem of the unreduced model which includes 6 zero
    energy modes. The second set of modes is the fixed interface modes
    of the analysis. The first $4$ modes in **CBR-CBR.exo** correspond
    to these fixed interface modes.

2.  The result file, **CBR.rslt**, contains three sets of eigenvalues;
    the two mentioned above and the eigenvalues of the reduced system.
    No eigenvectors from the reduced system can be output since there is
    no geometry database associated with it. The last set of eigenvalues
    includes every eigenvalue of the reduced system.

    Notice also that the eigenvalues of the reduced system are not
    identical to the unreduced system. However, even with only four
    fixed interface modes, the first elastic mode agrees up to the 4th
    digit. General practice would ensure that the maximum frequency of
    the fixed interface modes is at least twice the frequency of
    interest.

3.  The `cbmap` is found in both the result file and the reduced model
    output file. This map relates rows and columns of the reduced system
    with physical quantities. The first of the $3$ nodes in the nodeset
    has global id $1$ as shown in the figure. All $6$ degrees of freedom
    are active at each node. And the `cbmap` has $18$ rows.

4.  The reduced system is $22$ degrees of freedom, which consists of $4$
    fixed interface modes and $18$ constraint modes ($6$ degrees of
    freedom associated with $3$ nodes). The mass and stiffness matrices
    are almost full. Generally, the constraint modes contribute full
    matrix terms to both mass and stiffness.

5.  Rerunning with `mfile` added to the output section creates many
    files that will not be described here including the $\Phi$ and
    $\Psi$ matrices.

6.  The output is written to the file `CBR.m`. Extracts from this file
    are included below from which you note the following.

    1.  All the data required for the model reduction is found in a
        single file.

    2.  The map of the reduced model is defined in `cbmap`. A map of the
        output transfer matrix rows is `OutMap`.

    3.  There are always 6 degrees of freedom per node in the OutMap.
        This example does not show this, but there may be fewer in the
        `cbmap`. Note that while `Kr` and `Mr` are reduced system
        matrices which must be nonsingular, `OTM` is a transfer matrix
        and can include inactive degrees of freedom.

    :::{output}
    NumC=18;
    NumEig=4;
    Kr=zeros(22,22);
    Kr(1,1)=7.703363317234302e+04;
    Kr(2,2)=9.043236930586677e+04;
    ...

    Mr=zeros(22,22);
    Mr(1,1)=1.000000000000000e+00;
    Mr(1,5)=-9.545115933105166e-03;
    ...

    % map of nodes in the output transfer matrix
    % OutMap is the global node number
    % There are exactly 6 outputs per node.
    OutMap=zeros(1,32);
    OutMap=[1 5 6 10 11 15 16 20 21 25 26 30 31 35 36 40 41 45 ...
    OTM=zeros(192,22);
    OTM(1,5)=1.000000000000000e+00;
    OTM(2,6)=1.000000000000000e+00;
    ...

    %cbmap(:,1) is global node id (1:n)
    %cbmap(:,2) is coordinate (x=1, y=2, etc.)
    %the first 4 dofs in the matrices are modes,
    % while the last 18 dofs are interface dofs.
    cbmap=[1 1
    1 2
    1 3
    1 4
    1 5
    1 6
    ...
    :::

## Verification of the Model

The following are some things that can be done to ensure that the model
has been properly developed.

### Comparison of Reduced and Full Eigenvalues

It is a very good idea to compare the eigenvalues of the full and
reduced system. It will approximately double the computational effort of
the model reduction, but there is very little set up time. The example
does this. All that is required is to compute the results in a
multi-case approach. Begin by computing the eigenvalues of a full
system. Then, in the next case compute the reduced order model. By
including `GlobalSolution` in the `CBModel` section, the eigenvalues of
the reduced system are also computed. These eigenvalues and frequencies
appear in the text result file, under the heading
`Eigenvalues of Reduced System`.

### Comparison of Reduced and Full Displacements

It is significantly more complicated to compare the displacements of the
two models because there is no automatic upstream data recovery. Manual
data recovery will have to be done in MATLAB. We illustrate the method
with a small transient run, but it could also be done for a eigen
analysis (or statics if the model is statically determinant).

Consider a calculation of 2000 time steps each of $10^{-5}$ seconds. We
impulsively load the structure on the interface (nodeset 3) with a force
in the $y$ direction only. The load begins at zero, ramps to 10$^6$ at
$10\,\mu s$, and then ramps back to zero at $20\,\mu s$. Output will be
examined on nodesets 1 and 2. This example is found in `CBR_trans.inp`.

Following the calculation, data from any of the output nodes can be
evaluated using the history file. The following commands evaluate the
$x$ displacement on node 70.

:::{command}
unix% exo2mat CBR-transient.h
unix% matlab
load CBR-transient
k=find(node_num_map==70);
plot(time,nvar01(k,:));
:::

The reduced model can be used to perform the same calculation. The
MATLAB commands to do this work once `CBR.m` has been read into
MATLAB are included here.

:::{matlab}
nsteps=2000;
ff=zeros(1,nsteps);
ff(2)=1;
neq=max(size(Kr));
force=zeros(neq,1);
rows=NumEig + find(cbmap(:,2)==2);
force(rows)=1e6;
dt=1e-5;
u=CBRint(Kr,Mr,force,ff,dt);
time=(1:nsteps)*dt;
k=find(OutMap==70);
orow=(k-1)*6+1;  % x component of node 70
U70x=OTM(orow,:)*u;
:::

The time integration is a standard Newmark integration performed using
`CBRint.m`, which is available in the test directory.

Finally, we can compare the results, which are shown in Figure
{numref}`%s <fig:CBR_tint>`. The data in the figure is obtained by
running the CBR reduction with a varying number of fixed interface
modes. Note that 4 modes, and even 10 modes are not sufficient to
capture the gross response of the structure at node 70. Even at 50 modes
there is high frequency data that has been lost. This is as expected
since the reduced model is designed to capture only the low frequency
response of the structure. The first elastic mode at 21 Hz has a period
of 48 ms.

:::{figure-md} fig:CBR_tint

![](cbr_trans.png)

Example CBR transient computations.
:::
## What to do with the Results
### solving the system

The reduced mass and stiffness matrices contain the dynamics of the
system. These could be solved in an eigen analysis for example in
MATLAB.

:::{matlab}
[][e_value,e_vector]=eig(Kr,Mr);
:::

The eigenvalues, `e_value`, represent the system natural frequencies.
The eigenvectors are a mix of generalized and physical degrees of
freedom. The OTM is used to compute the response on the physical degrees
of freedom on the nodesets in the history file.

:::{matlab}
Out=OTM*e_vector;
:::

To find the response on a specific degree of freedom use the OutMap. For
example, to find the $Z$ degree of freedom on node 25 of the model.

:::{matlab}
index = find(OutMap==25);
k = (index-1)*6 + 3;
for i=1:size(Out,2)
  fprintf('Mode %d, Z value on node 25 = %g\n',i,Out(k,i))
end
:::

When this document was written no process was available to take these
results back into an Exodus database so the resulting displacement mode
shapes can be plotted on the original model.

### Incorporate the reduced model into another system model

This is one of the more important reasons for doing a model reduction.
The approach depends on the format of the new model. The following are
options.

* **Sierra/SD.**

    Sierra/SD can input a CBR model in netcdf format as a superelement.
    See Section {numref}`%s <superelement>`.

* **MATLAB.**

    The model can be combined with other models in MATLAB.
    The trick is to use the cbmap to tie together different degrees of freedom.

* **NASTRAN.**

    NASTRAN can do this.
