# Debugging Guide

Guides in identifying and solving commonly encountered errors during the OptiStruct run.

## Basic Checks

Preliminary level of debugging an OptiStruct problem to help resolve an issue being produced.

Some basic checks which help in the debugging process.
Check Remedy
Verify for any syntactical issues using a check-run. Use the run option -check, while running OptiStruct.
Check for any issues in the HyperMesh model check tool. In HyperMesh, Tools > Model Checker.
Verify if the number of rigid body modes are consistent with the number of free components. Perform a free-free (without any SPCs) normal mode analysis.
Ensure that the units are consistent in the model. This could be verified from the mass (.out file) or from other results files.
Perform a check, to expose unintentional constraints. Add the GROUNDCHECK entry and check for the elements which fail the test.
Perform a check, to expose massless mechanisms. Add the MECHCHECK entry.
Verify for force balance within the model. Check the output from SPCF in the .out file.

## Nonlinear Static Analysis

Debugging methods for different types of convergence issues.

### General Convergence

Check Remedy
Check the unconverged result to see what is wrong. Use the NLOUT entry with SVNONCNV=YES.
Review the incremental results. Add the NLMON entry.

Debug the problematic subcase in HyperView using os_out_file_parser.tcl.

Use line search method for small displacement models including plasticity and friction. The parameters can be specified in NLPARM entry.
Use a different solver. This can be controlled using the SOLVTYP entry.
In case of problems involving a combination of contact, plasticity and pretension. Use PARAM, KTPLAST.
In case of snap through/back problems use displacement/load control methods or the arc-length method. Arc length method could be defined using the NLPCI entry.
In case of factorization failure for MUMPS, try different factorization. This can be viewed in the FCTRIZ module in .stat file. The factorization can be controlled using ORDM in SOLVTYP entry.

### With Contact

Check Remedy
Switch contacts to FREEZE, one by one and see when convergence happens.
Verify the selection of the Main and the Secondary.
• Select the surface with finer mesh as the secondary and the other as the main.
• Select the smaller surface as the secondary and the other as the main.
• Select the softer surface as the secondary and the other as the main.
Review the grids and elements involved in contact creation.
• for S2S: CONTPRM, CONTGRID, YES
• for N2S: CONTPRM, CONTGAP, YES and GAPPRM, HMGAPST, YES
Review if the contact stabilization is applied.

Make sure the amount of stabilization is right.

• PARAM, EXPERTNL, CNTSTB or CNTSTB (Bulk Data and Subcase Information Entry).
• Each one has an effect only in particular situations, check CNTSTB Reference Guide which one should be used in your model.
• Too little damping on CNTSTB has no significant effect.
• Too much damping can give “perfect” contact until almost the end of the subcase, due to prevented sliding. Then convergence fails, due to ramp down of the artificial contact damping towards the end.
• Try S2S, if N2S was used and vice-versa.

### With Material Nonlinearity

Check Remedy
Verify if the issue is resolved for a linear material model. If so, the issue might not be due to issues in nonlinear material definition.
Check the material data table definitions. if analysis goes “out of the tables’ range”.
• By default, OptiStruct extrapolates beyond the table ranges.
• Try the FLAT option in TABLE definition to flatten the curve beyond the range.
For hyperelastic materials models, perform a test using one element and adjust the material parameters to match experimental data, instead of using the experimental data directly.

### Large Displacement Nonlinear Static Analysis

Check Remedy
Verify if the issue is resolved for small displacements analysis. If so, the issue might be due to the large displacement analysis settings.
Try smaller time increments to apply the load slowly. Use DTMAX in the NLADAPT entry.
Activate linear extrapolation in the Newton-Raphson method.

This allows the displacement value from the previous load increment to be used as the initial guess for the current load increment.

Use EXTRA, LINEAR in NLADAPT entry.
Check if the problem runs with nonlinear transient analysis, with a suitable time.

## Dynamic Analysis

### Normal Modes Analysis

Check Remedy
• Try switching the Eigen solver (this might show modelling issues), from AMSES (EIGRA) to LANCZOS (EIGRL) and vice versa.
• AMSES/AMLS helps in detecting massless mechanisms automatically. They also output and constrain those DOFs.
Use PARAM, AMLS entry.
Enforce constraint reduction with LANCZOS. Use PARAM, AMLS, 2
Check if the upper bound on EIGRL/EIGRA card is reasonable.
Models with low number of modes (ND) but high V2 might still fail, due to too many modes. Try a smaller upper bound (V2, for example, 10Hz).

### Frequency Response Analysis (FRA)

Check Remedy
Run a normal modes analysis to check for rigid body modes. Use PARAM, AMLS entry.
Run direct and modal FRA.

If the model is too large to run direct, run only for a few loading frequencies to perform the verification.

The results should match if model is valid.
Verify if the applied damping is enough in the model.
Check if RESVECs are correctly generated, to detect modelling issues. For example, there must be as many RESVECs as the number of DAREAS used in the model.
For suspicious ERP results, first make sure velocity looks correct.
For large memory requirement or slow runtime, check if too many outputs are requested. Use PEAKOUT when appropriate.

### Transfer Analysis

Check Remedy
Run a normal modes analysis to check for rigid body modes. Use PARAM, AMLS entry.
Run direct and modal FRA.

If the model is too large to run direct, run only for a few loading frequencies to perform the verification.

The results should match if model is valid.
Verify if the applied damping is enough in the model.
Check if RESVECs are correctly generated, to detect modelling issues. For example, there must be as many RESVECs as the number of DAREAS used in the model.
Verify if PARAM, ENFMOTN gives the expected results.
For large memory requirement or slow runtime, check if too many outputs are requested. Use PEAKOUT when appropriate.

Check if the time step used is appropriate.

## Optimization Problems

Here debugging methods for optimization type problems are described.

### General Optimization

Check Remedy
Try with a smaller move limit to avoid overshooting the optimum or moving into unrealistic designs. Use DOPTPRM, DELSHP or DELSIZ or DELTOP entries.
Try different optimizer Use DOPTPRM, OPTMETH.
Control the retention of responses to avoid large memory and CPU requirements. Use the DSCREEN entry.
In case of premature convergence,
• Check if the optimization has reached the maximum number of iterations.
• Try a lower objective tolerance.
• Set DOPTPRM, DESMAX, to a higher value.
• Use the DOPTPRM, OBJTOL entry.
For unstable and slow convergence in buckling and normal modes optimizations, Add more constraints to include more modes – this avoids switching modes.

### Topology Optimization

Check Remedy
Check if there are excessive constraint violations. The limiting dimensions in the model can be controlled using MINDIM/MAXDIM/MINGAP in the DTPL entry.
Check if the optimization converges fully, i.e. are there three “2nd satisfied convergence” in .out file? -
Try a different initial material fraction. Use DOPTPRM, MATINIT.
If manufacturing constraints are present. Try removing them as they might lead to excessive constraints.
Try the model with a dual optimizer based on separable convex approximation to improve solution stability. Use DOPTPRM, OPTMETH, DUAL, 2.
If the optimization problem, OptiStruct errors out with “error 703 - OS failed to find a solution at current iteration”. Try to reduce the number of constraints, for example, instead of displacement constraints, use minimize compliance with volFrac constraint.
Try to use discrete topology optimization formulation. Use DOPTPRM, TOPDISC, YES.

### Size Optimization

Check Remedy
In case of infeasible design. Try a different starting point.
Use the Global search option. Use the DGLOBAL entry.
In case of 1D optimization, try reducing the problem size by controlling the internal constraints. Use DOPTPRM, BARCON.
In case of discrete design variables, use control options. Use DOPTPRM, DDVOPT, 2 or 3.
Check if a large-scale optimization algorithm works. Use DOPTPRM, OPTMETH, BIGOPT.

### Shape Optimization

Check Remedy
In case of infeasible design Try a different starting point.
Use the Global search option. Use the DGLOBAL entry.
Try alternative shape optimization algorithm. Use DOPTPRM, SHAPEOPT, 2.
Control the remeshing process, if the optimization runs into element quality errors. Use DOPTPRM, REMESH.

### Free Shape Optimization

Check Remedy
Control the splitting of the design grids. Use SPLIT option in the DSHAPE entry.
Try manually creating more DSHAPE entries with and reducing the grids.

### Topography Optimization

Check Remedy
Try a non-zero initial value of the variables that control the grid movement. Use INIT field on BOUNDS continuation line of DTPG entry.
Try to perturb few GRIDs out of plane by adjusting their coordinates in the deck.
Try the optimization without pattern repetition/grouping.

### Lattice Optimization

Check Remedy
Try a different porosity to control the number of bars that are created. Use DOPTPRM, POROSITY.
If stress constraint in second phase is not satisfied. Try including a stress constraint in the first phase.
Check the lower bound for beam generation. Use DOPTPRM, LATLB.
Due to missing or low penalty that is applied to semi dense elements. Change optimization setup in stage 1 as this might be expected for Porosity, High and Med.
For issues with remeshing. Try smoothing.

### Multi-Model Optimization (MMO)

Check Remedy
If the mapping between the models is not working. Check if the design variable IDs consistent across the models.
For mapping issues in topology optimization, check the mapping settings. Check the values of COORD and SCALE in DTPL entry.

1. Differences between MMO and single runs can be expected. Topology optimization in MMO turns on manufacturing constraints to allow for the mapping. If the individual models do not have manufacturing constraints, this can lead to differences.

## MPI, DDM, and MMO Problems

Check Remedy
Run the MPI tester to identify issues. Use the run option -testmpi.
Check MPI settings. See OptiStruct SPMD in the User Guide for further details.
If DDM results in issues, verify if LDM analysis runs successfully.

1. When comparing serial with DDM runs, remember that MUMPS is used for DDM by default, while serial might use BCS solver.

## Composite Problems

Here the debugging methods for composite analysis and optimization problems are described.

Check Remedy
Review the material orientation and shell normal in HyperMesh. See OS-T: 3200 Design of a Composite Aircraft Underbelly Fairing for optimization setup.
Visualize the shells as solids in HyperMesh. -
If DDM results in issues, verify if LDM analysis runs successfully. -
In case of factorization failure for MUMPS, try different factorization. This can be viewed in the FCTRIZ module in .stat file. The factorization can be controlled using ORDM in SOLVTYP entry.
In case of optimization with manufacturing constraints. Try running with less manufacturing constraints to see if the setup is too constrained.
In case of optimization, try cleaning up and splitting the created plies. Use OSSMOOTH.

## Buckling Problems

Check Remedy
In case of shell elements, try defining the type and order or approximation in plate geometric stiffness. Use PARAM, SHPBCKOR, 2.