IMAT and its related toolboxes provide you with significant functionality. However, it may not seem obvious how to use IMAT's capabilities, even after reading the documentation. Because of this, we have provided several useful examples that demonstrate how to use IMAT. All of the example files can be found in the examples subdirectory of your IMAT installation. We highly recommend that you include this directory in your MATLAB path if you have not already done so.
The following sections describe what you can find in the examples directory.
IMAT provides a number of useful utilities. These utilities are provided as MATLAB m-files, so the source code is readily visible. The following table summarizes the example functions provided.
| Function | Description |
| calc_energy_fractions.m | Calculate and report kinetic and strain energy fractions for groups |
| cmif.m | Compute Complex Mode Indicator Functions |
| component_meff_mass.m | Computes the modal effective mass for portion(s) of a FEM |
| create_default_fn | Create a default imat_fn of a specified type |
| create_extse | Create an external superelement structure |
| format_ppt.m | Format an imat_fn plot for pasting into Microsoft Powerpoint |
| frfsyn.m | Synthesize Frequency Response Functions from real or complex mode shapes |
| gmif.m | Compute the various mode indicator functions |
| mmif.m | Compute Multivariate Mode Indicator Functions |
| ortho.m | Compute Modal Assurance Criterion or Orthogonality for a set of mode shapes |
| plot4views.m | Create a four-paneled mode shape plot |
| psmif.m | Compute Power Spectrum Mode Indicator Functions |
| qmif.m | Compute Quadrature Mode Indicator Functions (CMIF using the imaginary component of the FRF) |
| rbmodes.m | Generate rigid body modes from FEM geometry |
| readunv_180.m_example.m | Example for using the readunv API to import dataset 180 |
| tdm_xlsread.m | Read Test Display Model from Excel worksheets |
| tdm_xlsread_example_1.xlsx | TDM example Excel worksheet |
| tdm_xlsread_example_2.xlsx | TDM example Excel worksheet |
| tdm_xlsread_template.xlsx | TDM Excel worksheet template |
| tdm_xlswrite.m | Write Test Display Model to Excel worksheets |
| nastable2fcn.m | Import NASTRAN tables and return as FCN |
| writeblk.m | Write to a NASTRAN BLK file |
| writedmig.m | Write matrix in NASTRAN DMIG format |
| writempc.m | Write a row- or column-oriented matrix as NASTRAN MPC cards |
| writerandps.m | Write RANDPS and TABRND1 cards to a NASTRAN bulk data file |
| writetabled1.m | Write imat_fn or fcn as NASTRAN TABLED1 cards |
| write_nas_field.m | Pack real numbers into 16-character fields in NASTRAN format |
| Substructuring subdirectory | |
| Tplate/Test_System_TPlate.m | Substructuring example showing analysis- and test-based component assembly into systems with eigenvalue, transient, and frequency domain simulations. |
| SMAC subdirectory | |
| smac.m | Synthesize Modes and Correlate modal parameter extraction utility |
| Anapost subdirectory | |
| aelempost.m | Summarize solid element stress results from NASTRAN Output2/Punch files |
| max_von_mises.m | Compute the highest von Mises stress for a load of unknown direction |
| DBA subdirectory |
|
| compute_dba.m | Compute the Damage Based Analysis PSDs of the input signal. The script dba_example.m demonstrates how |
The examples we provide also happen to be useful. We provide functions to compute Modal Assurance Criteria (MAC) and orthogonality, generate rigid body mode shapes from supplied finite element model geometry, generate a modal substructure from mode shapes, compute normal, complex, and multivariate mode indicator functions, and synthesize frequency response functions (FRF) from real normal modes.
Another very useful set of example functions allows you to easily create and/or modify FEM connectivity using Microsoft Excel. This capability is particularly useful for test engineers who might use a test display model (TDM) for animating mode shapes. The examples directory contains several functions and spreadsheets whose filenames start with tdm_xls*. You can develop FEM connectivity including local coordinate systems, nodes, elements, and tracelines in Excel, and then invoke tdm_xlsread.m to import the TDM into an imat_fem in MATLAB for display. You can export an imat_fem from MATLAB using tdm_xlswrite.m to an Excel spreadsheet for modification and then subsequent import back into MATLAB. Also included are a blank template Excel file called tdm_xlsread_template.xlsx and two example TDM files.
In addition to these useful functions, we provide several readunv extension examples that show you how read Universal file datasets that are not natively handled by readunv. The three examples provided read datasets 2452, 2467, and 2477, which contain group information. If the examples directory is in your MATLAB path, readunv will automatically detect and use these extension functions.
The best way to familiarize yourself with the functions we provide is to browse the examples directory and read the help for these functions.
In addition to the sample functions found in this directory, the main IMAT source directory contains several MATLAB scripts that start with demo_*. These files contain code and comments that show you how to use IMAT by going through some simple examples. You can access these scripts by running them (type demo_ at the MATLAB prompt, followed by a <TAB> to see the available choices).
In the Demo_Files subdirectory you will find a number of data files. All of these files are related to a fictional spacecraft (the General Purpose Spacecraft, or GPSC). You can use these data files to exercise the various IMAT import functions, and also to load IMAT datatypes so you can exercise the functionality available to them.
This directory contains function and shape ADFs, NASTRAN bulk data, Output2, and Punch files, and an Abaqus Input file and ODB.
Substructuring involves assembling a structure of test- and/or analysis-based component representations into a system model. Components can be added to or subtracted from the system, allowing you to define a Transmission Simulator interface. You can use different types of connections between the available DOF on each component. Once the system of components and connections is defined, you can assemble the system-level mass, stiffness, and damping matrices. Once this is done, you can define inputs to the system and then perform transient or frequency domain solutions on the system.
You can find an introduction to this functionality here.
To use this functionality, simply add the examples/Substructuring directory to your MATLAB path. Example files can be found in the TPlate subdirectory. This directory also contains a script called Test_System_TPlate.m that walks you through how to use the substructuring capabilities
The substructuring functionality was generously funded by Sandia National Laboratories through the United States government, and is released under Mozilla Public License version 1.1. The text of this license can be found here.
SMAC, or Synthesize Modes and Correlate, is not so much an example as it is a fully functional modal curve-fitting utility. It utilizes a different approach from most modal curve-fitting algorithms. SMAC is based on modal filter theory. You can find an introduction to SMAC along with helpful hints on how best to use it here.
To use SMAC, simply add the examples/SMAC directory to your MATLAB path, and invoke it by typing 'smac' at the MATLAB prompt.
SMAC is generously provided by Sandia National Laboratories through the United States government, and is released under Mozilla Public License version 1.1. The text of this license can be found here.
The anapost directory contains a collection of useful functions for post-processing NASTRAN results. These include aelempost, a utility that reads solid element stress results from NASTRAN OP2 or PCH and post-processes them. max_von_mises calculates the worst direction von Mises stress on a per-element basis, given stress inputs in 3 orthogonal directions. For more details on the supplied utilities, please review the contents of this directory in your installation. README.txt, located in this directory, gives more details about the available utilities.
To use any of these utilities, simply add the examples/anapost directory to your MATLAB path.
Damage-Based Analysis (DBA) is a spectral data processing method built to handle the “difficult” time histories that are commonly seen in many industries. For a time history that is not stationary or ergodic and has time-varying magnitudes and frequency content, Fourier-based processing methods will typically be over- or under-conservative or require significant pre-processing work to obtain a trustworthy result. DBA is built to take these time histories and return a set of PSD’s that will result in the same peak response and the same fatigue damage as the input time history given a set of input parameters.
To do this, DBA employs the same response spectrum technique used for Shock Response Spectrum processing but extends the concept significantly. The input time history is fed into a bank of single degree of freedom (SDOF) oscillators and the integrated responses of those oscillators are used to calculate four PSDs: the G1 "strength" PSD, and three "fatigue" PSDs (G4, G8, G12) denoted by their associated fatigue exponents (b) of 4, 8, and 12. These PSDs are derived such that when input as a base excitation into the same bank of oscillators, they will produce an equivalent SDOF response as the input time history produced. In particular, the G1 PSD will produce an equivalent SDOF peak response while the G4, G8, and G12 PSDs will produce equivalent fatigue damage for every oscillator requested by the user (input parameters include frequency and damping).
In other words, DBA uses SDOF’s as the ‘middle-men’ between a measured environment and the ground test. Because DBA is examining frequency content along with fatigue damage at every frequency, the user has significantly more insight into both the underlying data and what kind of ground test and test duration is best suited to replicate that environment. The use of SDOF’s and damage equivalence allows for tailored and intelligent random vibration test specification above and beyond what has typically been possible with historical data processing methods.
The compute_dba function computes the damage based analysis Power Spectral Densities from a time history. This time history is fed into a bank of single degree of freedom oscillators, and the integrated responses of those oscillators (using Kelly-Richman integration) is used to calculate four PSDs: the G1 "strength" PSD, and three "fatigue" PSDs (G4, G8, G12) denoted by their associated fatigue exponents (b) of 4, 8, and 12. These PSDs are derived such that they will produce an equivalent SDOF response as the input time history produced over a given test duration T0. In particular, the G1 PSD will produce an equivalent SDOF peak response while the G4, G8, and G12 PSDs will produce equivalent fatigue.
To use this utility, simply add the examples/DBA directory to your MATLAB path.