Table of Contents

4. Analysis Procedures - SolProc

The analysis procedure modules are designed to manage the series of tasks which must be followed to perform various types of analysis. The modules direct execution using a "reverse communication" mechanism. A solution procedure module, such as SolProc is executed repeatedly. Each time it is executed it performs a task related to controlling a specified solution procedure. Upon completion of each task a user "action" is returned. The user must perform the action before the procedure module is called again. User actions consist of forming reaction vectors and stiffness matrices and performing operations upon the stiffness matrix. Time evolution analysis procedures, static or dynamic, are implemented in the SolProc module.

The SolProc module is designed to manage the execution of linear and non-linear time evolution, static (steady-state) or transient analysis. The methods associated with a SolProc object are the following.

Instance a SolProc object using vfs_SolProcBegin. Once a SolProc object is instanced, specify the analysis type - structural or thermal - the number of equations, and the number of reactions using vfs_SolProcDef. Equations where a temporary restraint has been applied must be flagged with vfs_SolProcSetTemp. Use vfs_SolProcSetStrategy to specify the time specification - static or transient - the procedure type - linear or nonlinear - and the final analysis time. The evolution is controlled by a single independent "time" variable, which is initialized to zero upon calling vfs_SolProcDef. You can overwrite the initial time with vfs_SolProcSetParamd with the SOLPROC_BEGINTIME parameter before you start execution. You can also use vfs_SolProcInitTimeStep to specify an initial time step. Note that the time step is just a suggested value, and may be internally modified depending on convergence rate, and the final time specified in vfs_SolProcSetStrategy. The minimum and maximum time steps can be set in vfs_SolProcSetParamd using SOLPROC_MINTIMESTEP and SOLPROC_MAXTIMESTEP, respectively.

SOLPROC_MINTIMESTEP should be set according to the user's knowledge of the physical parameters defining the problem, and by limiting the maximum number of time steps N to be computed, assuming a worst-case scenario, with N = T / dt_min, where T is the total time and dt_min the minimum time step. The analysis aborts if it cannot achieve convergence at the minimum time step.

Likewise, SOLPROC_MAXTIMESTEP should also be set based on the user's knowledge of the physical parameters defining the problem. In transient problems this parameter is often shadowed by the half tolerance that controls the time integration error.

Various strategy parameters to control nonlinear analysis are set using vfs_SolProcSetParami and vfs_SolProcSetParamd. Strategy parameters include convergence tolerances, maximum number of iterations, etc.

For transient analysis, a predictor multi-corrector algorithm is employed. For structural analysis, the predictor is nothing but an initial guess at the displacements, velocities, and accelerations. These are consistent with two available methodologies, which can be set with vfs_SolProcSetParami: either the displacements or the accelerations at the current time step are repeated on the next time step. The remaining quantities are adjusted to maintain consistency with the time integration scheme utilized. Likewise, in thermal analysis the predictor maintains either the same temperature, or the same temperature rate.

The time integration procedure allows for both increasing and reducing the time step. Two conditions may lead to a reduction of the time step: failure to converge and/or inaccuracy at the half step during a transient analysis. In either case the time step is divided by 2. Alternatively, if convergence is achieved quickly and the half step convergence is optimal, the time step is increased by multiplying it by a factor of 1.25 for structural problems and 2 for thermal problems.

The actual solution procedure is initiated by calling vfs_SolProcDef. The SolProc module at this time will initialize internal counters, solution vectors, etc. The user then enters a continuous loop in which the function vfs_SolProcExecute is called repeatedly. This function returns an "action" which the user must perform before calling vfs_SolProcExecute again. This loop terminates when the action returned indicates that the solution procedure is complete. In order to carry out an action indicated by the SolProc module, the user will need to query the SolProc module for one or more SysVector objects using vfs_SolProcGetSysVector which contain solution-related vectors which must be used or updated in some way. The functions vfs_SolProcGetDouble and vfs_SolProcGetInteger are used to return additional information which may be required.

User actions generally include operations upon system level matrices such as factorizing a matrix, forming a matrix based upon a particular solution vector, etc. The SolProc module performs most of the system vector related operations. One notable exception is the updating of the total global dof solution vector with a solution increment. This operation, for structural analysis involving large rotations or other reasons, may involve an operation more complicated than simple addition, and must be performed by the user outside of the SolProc module.

At any time after vfs_SolProcExecute has been called at least once, you can query for the current time with vfs_SolProcGetDouble and request the value of SOLPROC_TIME.

The following actions are used.

Destroy an instance of a SolProc object using vfs_SolProcEnd.

Table of Contents

4.1 Function Descriptions

The currently available SolProc functions are described in detail in this section.


Table of Contents , SolProc

NAME

*vfs_SolProcBegin - create an instance of a SolProc object

C SPECIFICATION

vfs_SolProc *vfs_SolProcBegin ()

ARGUMENTS

None

FUNCTION RETURN VALUE

The function returns a pointer to the newly created SolProc object. If the object creation fails, NULL is returned.

DESCRIPTION

Create an instance of a SolProc object. Memory is allocated for the object private data and the pointer to the object is returned.

Destroy an instance of a SolProc object using

     void vfs_SolProcEnd (vfs_SolProc *solproc )

Return the current value of a SolProc object error flag using

     Vint vfs_SolProcError (vfs_SolProc *solproc )


Table of Contents , SolProc

NAME

vfs_SolProcDef - define type of analysis

C SPECIFICATION

void vfs_SolProcDef (vfs_SolProc *solproc,
                     Vint atype,
                     Vint neq,
                     Vint nre)

INPUT ARGUMENTS

solproc      Pointer to SolProc object.
atype        Analysis type
             =SYS_ANALYSIS_STRUCTURAL  Structural analysis
             =SYS_ANALYSIS_THERMAL     Thermal analysis
neq          Number of global dof
nre          Number of reaction dof

OUTPUT ARGUMENTS

None

ERRORS

SYS_ERROR_VALUE is generated if neq is less than or equal to zero or if nre is less than zero. SYS_ERROR_ENUM is generated if an improper atype is specified.

DESCRIPTION

Specify the number of global dof and the procedure's analysis type.

Inquire of defined neq, nre, and atype as output arguments using

     void vfs_SolProcInq (vfs_SolProc *solproc,
                          Vint *atype,
                          Vint *neq,
                          Vint *nre)


Table of Contents , SolProc

NAME

vfs_SolProcExecute - execute next procedure and return action

C SPECIFICATION

void vfs_SolProcExecute (vfs_SolProc *solproc,
                         Vint *action)

INPUT ARGUMENTS

solproc      Pointer to SolProc object.

OUTPUT ARGUMENTS

action       Execution action
             =VFS_ACTION_COMPLETE       Final procedure step complete
             =VFS_ACTION_INCOMPLETE     Unable to reach final solution step
             =VFS_ACTION_FACTOR         Factorize current matrix
             =VFS_ACTION_SOLVE          Solve given load vector
             =VFS_ACTION_STIFF          Form linear matrix
             =VFS_ACTION_REACT          Form reaction given solution vector
             =VFS_ACTION_REACTSTIFF     Form reaction and matrix
             =VFS_ACTION_ENDSTEP        Solution step complete
             =VFS_ACTION_UPDATE         Update solution vector
             =VFS_ACTION_PREDICTOR      Set boundary conditions
             =VFS_ACTION_FACTORMASS     Form and factor mass/capacitance matrix
             =VFS_ACTION_SOLVEMASS      Solve for initial acceleration/temperature rate
             =VFS_ACTION_INERTIA        Compute inertia contribution

DESCRIPTION

Execute the next task in the solution procedure and return a user action. The user must perform the action and call this function again.


Table of Contents , SolProc

NAME

vfs_SolProcGetInteger - get running SolProc parameters

C SPECIFICATION

void vfs_SolProcGetInteger (vfs_SolProc *solproc,
                            Vint type,
                            Vint *iparam)

void vfs_SolProcGetDouble (vfs_SolProc *solproc,
                           Vint type,
                           Vdouble *dparam)

INPUT ARGUMENTS

solproc      Pointer to SolProc object.
type         Parameter type
             =SOLPROC_NEWREACT          Flag for new computed reaction norm
             =SOLPROC_NUMITER           Number of iterations performed
             =SOLPROC_STEPID            The current step id
             =SOLPROC_STEPLAST          Query whether this is the last step
             =SOLPROC_REACTNORM         Final reaction norm
             =SOLPROC_SOLNORM           Final solution norm
             =SOLPROC_TIME              Current analysis time
             =SOLPROC_DAMPFACTOR        Factor that multiplies damping matrix
             =SOLPROC_MASSFACTOR        Factor that multiplies mass matrix
             =SOLPROC_STIFFFLAG         Flag with reason for stiffness reform
             =SOLPROC_LINESEARCH_ITER   Number of line search iterations

OUTPUT ARGUMENTS

iparam       integer value
dparam       double precision value

ERRORS

SYS_ERROR_ENUM is generated if an improper type is specified. SYS_ERROR_OPERATION is generated if vfs_SolProcExecute has not been called.

DESCRIPTION

The integer parameter SOLPROC_NUMITER indicates the total number of iterations performed. It is reset to zero at the beginning of each time step.

The integer parameter SOLPROC_STEPID indicates the current step number.

The integer parameter SOLPROC_STEPLAST returns either SYS_ON or SYS_OFF depending on whether the end of the analysis has been reached.

The double precision parameter SOLPROC_REACTNORM returns the final reaction norm once convergence at a time step has been achieved.

The double precision parameter SOLPROC_SOLNORM returns the final solution increment norm once convergence at a time step has been achieved.

The double precision parameter SOLPROC_TIME returns the time at the end of the current time step.

The double precision parameter SOLPROC_DAMPFACTOR returns the factor that multiplies the damping matrix during a structural analysis when forming the matrix to be factored. It is also the factor that multiplies the capacitance matrix during a thermal analysis. The double precision parameter SOLPROC_MASSFACTOR returns the factor that multiplies the mass matrix during a structural analysis when forming the matrix to be factored.

The integer parameter SOLPROC_STIFFFLAG returns an indicator of what caused SolProc to request a new stiffness. Possible return values are VFS_STIFF_LS_DIVERGE, issued when the internal line search algorithm diverges; VFS_STIFF_LS_MAXITER, issued when the maximum number of line search iterations is reached; VFS_STIFF_LS_MAXVAL, when the upper bound for the line search is reached; VFS_STIFF_LS_MINVAL, when the lower bound for the line search is reached; VFS_STIFF_LS_STALL, when the line search algorithm is stalled; VFS_STIFF_SPROP_NONLINEAR, when vfs_SolProcSetStrategy is called that changes the linear/nonlinear toggle; VFS_STIFF_SPROP_ANALYSIS, when vfs_SolProcSetStrategy is called that changes the analysis type; VFS_STIFF_START, if a stiffness has never been formed before; VFS_STIFF_NEWDT, when the time step changes; VFS_STIFF_NEWBC, whenever vfs_SolProcSetTemp is called; VFS_STIFF_REFORM_FREQ, when the number of time steps using the same stiffness reaches the value specified in vfs_SolProcSetParami with a type of SOLPROC_LHS_STEPFREQ; and VFS_STIFF_HALFTOL, when the transient half step threshold is reached. This parameter is only available whenever the actions are either VFS_ACTION_STIFF or VFS_ACTION_REACTSTIFF.


Table of Contents , SolProc

NAME

vfs_SolProcGetSysVector - get a system vector for processing

C SPECIFICATION

void vfs_SolProcGetSysVector (vfs_SolProc *solproc,
                              Vint type,
                              vfs_SysVector **sysvector)

INPUT ARGUMENTS

solproc      Pointer to SolProc object.
type         Parameter type
             =VFS_VECTOR_REACT          Reaction/load vector
             =VFS_VECTOR_U0             Displacement at beginning of step
             =VFS_VECTOR_U1             Displacement at end of step
             =VFS_VECTOR_V0             Velocity at beginning of step
             =VFS_VECTOR_V1             Velocity at end of step
             =VFS_VECTOR_A0             Acceleration at beginning of step
             =VFS_VECTOR_A1             Acceleration at end of step
             =VFS_VECTOR_INC            Displacement increment
             =VFS_VECTOR_DELTAINC       Linear system solution
             =VFS_VECTOR_INERTIA        Inertia vector
             =VFS_VECTOR_BCREACT        Reaction/load vector on BC dofs

OUTPUT ARGUMENTS

sysvector    requested vector

ERRORS

SYS_ERROR_ENUM is generated if an improper type is specified. SYS_ERROR_OPERATION is generated if vfs_SolProcExecute has not been called.

DESCRIPTION

Each of the above vectors is properly described along with the resulting actions from vfs_SolProcExecute.


Table of Contents , SolProc

NAME

vfs_SolProcSetParami - set integer procedure parameters

C SPECIFICATION

void vfs_SolProcSetParami (vfs_SolProc *solproc,
                           Vint type,
                           Vint iparam)

INPUT ARGUMENTS

solproc      Pointer to SolProc object.
type         Parameter type
             =SOLPROC_FIXEDTIMESTEP     Toggle to run with fixed time step
             =SOLPROC_LHS_ITERFREQ	   Matrix nonlinear reform frequency
             =SOLPROC_LHS_STEPFREQ	   Matrix time step reform frequency
             =SOLPROC_MAXITER           Maximum number of nonlinear iterations
             =SOLPROC_MINITER           Minimum number of nonlinear iterations
             =SOLPROC_REACTCONVFLAG     Toggle to check convergence on reaction
             =SOLPROC_SOLCONVFLAG       Toggle to check convergence on solution
             =SOLPROC_PREDICTOR         Set predictor type
             =SOLPROC_LINESEARCH_FLAG   Toggle to use line search
             =SOLPROC_LINESEARCH_TYPE   Type of line search method to use
             =SOLPROC_LINESEARCH_MAXITER Maximum number of line search iterations
iparam       Specifies the integer value that type will be set to.
             =SYS_ON                    Turn parameter on
             =SYS_OFF                   Turn parameter off
             =SOLPROC_SAME_DISP         Set structural predictor to same displacement
             =SOLPROC_SAME_ACCEL        Set structural predictor to same acceleration
             =SOLPROC_SAME_TEMP         Set thermal predictor to same temperature
             =SOLPROC_SAME_TEMPRATE     Set thermal predictor to same temperature rate
             =SOLPROC_LINESEARCH_LINEAR Set linear line search type
             =SOLPROC_LINESEARCH_BISECTION Set bisection line search type

OUTPUT ARGUMENTS

None

ERRORS

SYS_ERROR_ENUM is generated if an improper type is specified, or if an invalid enumerated iparam is specified. SYS_ERROR_VALUE is generated if SOLPROC_LHS_REFORM is less than 1; or SOLPROC_MAXITER is less than 1; or SOLPROC_MINITER is less than 0.

DESCRIPTION

The parameter SOLPROC_FIXEDTIMESTEP determines whether the time step is allowed to change. If a fixed time step is chosen and, in a nonlinear problem iteration is not achieved within the maximum number of iterations then an error is generated and the analysis terminates. Defaults to SYS_OFF.

The parameter SOLPROC_LHS_ITERFREQ indicates the nonlinear iteration frequency with which the stiffness matrix is forced to be reformed, regardless of other convergence criteria. Defaults to 0, which forces the matrix to be reformed based only on failure to converge or time step changes.

The parameter SOLPROC_LHS_STEPFREQ indicates the time step frequency with which the stiffness matrix is forced to be reformed, regardless of other convergence criteria. Defaults to 0, which forces the matrix to be reformed based only on failure to converge or time step changes.

The parameter SOLPROC_MAXITER indicates the maximum number of nonlinear iterations that can be performed within a time step. Failure to converge within this limit will trigger actions such as time step reduction. Defaults to 10.

The parameter SOLPROC_REACTCONVFLAG indicates whether convergence is based on the magnitude of the reaction forces. Defaults to SYS_ON.

The parameter SOLPROC_SOLCONVFLAG indicates whether convergence is based on the change in the solution from nonlinear iteration to nonlinear iteration. Defaults to SYS_ON.

The parameter SOLPROC_PREDICTOR defines the methodology to be used to consistently extrapolate the current solution to the next step. Use either SOLPROC_SAME_DISP or SOLPROC_SAME_ACCEL for structural analysis, and SOLPROC_SAME_TEMP or SOLPROC_SAME_TEMPRATE for thermal analysis. Defaults to SOLPROC_SAME_ACCEL for structural analysis and SOLPROC_SAME_TEMPRATE for thermal analysis.

The parameter SOLPROC_LINESEARCH_FLAG toggles between using an internal line search algorithm. Defaults to SYS_OFF.

The parameter SOLPROC_LINESEARCH_TYPE specifies the type of line search algorithm to use, if enabled by SOLPROC_LINESEARCH_FLAG. For a linear algorithm use SOLPROC_LINESEARCH_LINEAR; for a bisection algorithm use SOLPROC_LINESEARCH_BISECTION. Defaults to SOLPROC_LINESEARCH_LINEAR.

The parameter SOLPROC_LINESEARCH_MAXITER specifies the maximum number of line search iterations. Defaults to 10.


Table of Contents , SolProc

NAME

vfs_SolProcSetParamd - set double procedure parameters

C SPECIFICATION

void vfs_SolProcSetParamd (vfs_SolProc *solproc,
                           Vint type,
                           Vdouble dparam)

INPUT ARGUMENTS

solproc      Pointer to SolProc object.
type         Parameter type
             =SOLPROC_ETOL              Tolerance for energy convergence
             =SOLPROC_ENERMINVAL        Minimum residual for energy check
             =SOLPROC_FTOL              Tolerance for reaction convergence
             =SOLPROC_REACTMINVAL       Minimum residual for convergence check
             =SOLPROC_UTOL              Tolerance for solution convergence
             =SOLPROC_SOLMINVAL         Minimum residual for solution check
             =SOLPROC_BEGINTIME         Time at beginning of analysis
             =SOLPROC_MINTIMESTEP       Minimum time step
             =SOLPROC_MAXTIMESTEP       Maximum time step
             =SOLPROC_HHTALPHA          Damping for structural analysis
             =SOLPROC_HALFTOL           Half-step tolerance
             =SOLPROC_LINESEARCH_MAXSEARCH Maximum line search value
             =SOLPROC_LINESEARCH_MINSEARCH Minimum line search value
iparam       Specifies the integer value that type will be set to.

OUTPUT ARGUMENTS

None

ERRORS

SYS_ERROR_VALUE is generated if either SOLPROC_REACTCONVTOL, SOLPROC_SOLCONVTOL, SOLPROC_REACTMINVAL, SOLPROC_SOLMINVAL, or SOLPROC_MINTIMESTEP, or SOLPROC_MAXTIMESTEP are <= 0.0. SYS_ERROR_OPERATION is generated if you attempt to specify SOLPROC_BEGINTIME after a call to vfs_SolProcExecute.

DESCRIPTION

The parameter SOLPROC_FTOL defines the tolerance to be used when checking convergence based on reaction forces. Defaults to 5.0e-03.

The parameter SOLPROC_UTOL defines the tolerance to be used when checking convergence based on solution changes. Defaults to 1.0e-03.

The parameter SOLPROC_REACTMINVAL defines a reaction force below which the reactions are assumed converged. Defaults to 1.0e-12.

The parameter SOLPROC_SOLMINVAL defines a solution change below which the solution is assumed converged. Defaults to 1.0e-12.

The parameter SOLPROC_BEGINTIME defines the time the analysis is to start. It can only be set before calling vfs_SolProcExecute. Defaults to 0.0.

The parameter SOLPROC_ENDTIME defines the time the analysis is to end. Defaults to 1.0.

The parameter SOLPROC_MINTIMESTEP defines a minimum time step to increment the analysis. Defaults to 0.0.

The parameter SOLPROC_MAXTIMESTEP defines a maximum time step to increment the analysis. Defaults to 0.0, which in turns forces SolProc to ignore this parameter.

SOLPROC_MINTIMESTEP and SOLPROC_MAXTIMESTEP are ignored when the integer parameter SOLPROC_FIXEDTIMESTEP is set to SYS_ON. The time step value specified in vfs_SolProcInitTimeStep is then used to run the entire analysis.

The parameter SOLPROC_HALFTOL is a tolerance that controls the variation of the solution within a time step. It controls transient problems so that the time step is kept under control so as to properly capture transient phenomena. Defaults to 0.01.

The parameters SOLPROC_LINESEARCH_MAXSEARCH and SOLPROC_LINESEARCH_MINSEARCH control the maximum and minimum line search values. Default to 4. and 0.001, respectively.


Table of Contents , SolProc

NAME

vfs_SolProcInitTimeStep - set the initial time step

C SPECIFICATION

void vfs_SolProcInitTimeStep (vfs_SolProc *solproc,
                              Vdouble dt)

INPUT ARGUMENTS

solproc      Pointer to SolProc object.
dt           Initial time step to be used

OUTPUT ARGUMENTS

NONE

ERRORS

SYS_ERROR_VALUE is generated if dt < 0.

DESCRIPTION

Set the initial time step to be used in the analysis. It may be subsequently changed for convergence or divergence reasons. Defaults to 1.0.


Table of Contents , SolProc

NAME

vfs_SolProcSetComputeError - flag that an error has occurred.

C SPECIFICATION

void vfs_SolProcSetComputeError (vfs_SolProc *solproc,
                                 Vint *action)

INPUT ARGUMENTS

solproc      Pointer to SolProc object.

OUTPUT ARGUMENTS

action       Next action to be performed by user

ERRORS

NONE

DESCRIPTION

Flag to SolProc that an error has occurred while performing a requested task. For example, during factorization the matrix may have been found singular, or a material computation may have failed to converge. SolProc will return the corrective action to be taken to accommodate the error, such as a reduction in time step.


Table of Contents , SolProc

NAME

vfs_SolProcSetFactorized - flag that a factorization exists or does not exist

C SPECIFICATION

void vfs_SolProcSetFactorized (vfs_SolProc *solproc,
                               Vint factorized)

INPUT ARGUMENTS

solproc      Pointer to SolProc object.

OUTPUT ARGUMENTS

factorized  Toggle for factorization flag
             =SYS_ON                    Matrix factorized
             =SYS_OFF                   Matrix not factorized

ERRORS

NONE

DESCRIPTION

Flag to SolProc that the stiffness matrix has or has not been factorized. This is invoked as a result of external factors to SolProc that may lead the matrix to change its status as it is known to SolProc.


Table of Contents , SolProc

NAME

vfs_SolProcSetTemp - indicate which equations have temporary restraints on.

C SPECIFICATION

void vfs_SolProcSetTemp (vfs_SolProc *solproc,
                         Vint ntemp,
                         Vint temp[])

INPUT ARGUMENTS

solproc      Pointer to SolProc object.
ntemp        Number of temporary restraints
temp         List of temporary restraints

OUTPUT ARGUMENTS

NONE

ERRORS

NONE

DESCRIPTION

Lets SolProc know which equations are to be ignored when computing dot products and/or vector norms because of applied temporary restraints.


Table of Contents , SolProc

NAME

vfs_SolProcSetStrategy - sets major strategy parameters for subsequent analysis

C SPECIFICATION

void vfs_SolProcSetStrategy (vfs_SolProc *solproc,
                             Vint sproptype,
                             Vint type,
                             Vdouble endtime)

INPUT ARGUMENTS

solproc      Pointer to SolProc object.
sproptype    Solution property type
             =SYS_SOL_STATIC                 Static analysis
             =SYS_SOL_TRANSIENT              Transient or dynamic analysis
type         Linear or nonlinear toggle
             =SOLPROC_LINEAR                 Linear analysis
             =SOLPROC_NONLINEAR              Nonlinear analysis
endtime      The final analysis time

OUTPUT ARGUMENTS

NONE

ERRORS

SYS_ERROR_OPERATION is generated if SolProcDef has not been called.
SYS_ERROR_ENUM is generated if either sproptype or type have invalid values. SYS_ERROR_VALUE is generated if endtime is not positive.

DESCRIPTION

Completes the specification of the analysis by indicating whether a static or transient analysis is to be performed, and whether the analysis is to be treated as linear or nonlinear. vfs_SolProcSetStrategy can be repeatedly called with the same endtime; if this is the case, then the last step will be repeated until convergence is achieved.