HBMOPT

HBMOPT, Option, Value1, Value2, Value3, Value4, Value5
Specifies solution options for a harmonic balance method (HBM) analysis.

SOLUTION: Nonlinear Options

SOLUTION: Dynamic Options

Option

Harmonic balance method analysis option. There is no default. The semantic labels for Value1, Value2, Value3, Value4, and Value5 as well as their descriptions and default/range values depend on the option setting. See the command specifications for each option for details. Possible Option settings are:

AFT	—	Specify alternate frequency-time (AFT) procedure options. This command is optional. See Command Specification for `Option` = AFT
CONTLIST	—	List all continuation parameters. This command is optional. `Value1` .. `Value5` are Unused fields.
CONTSET	—	Required settings for a numerical continuation solution. You must issue this command to properly set up an HBM analysis. See Command Specification for `Option` = CONTSET.
CONTTERM	—	Specify termination criteria when continuation is on. This command is optional. See Command Specification for `Option` = CONTTERM.
CYCLIC	—	Activate an HBM cyclic analysis and specify parameters. This command is optional. See Command Specification for `Option` = CYCLIC.
LINEAR	—	Specify if nonlinearities are considered. This command is optional. See Command Specification for `Option` = LINEAR.
LIST	—	List all continuation parameters (except continuation). This command is optional. `Value1` .. `Value5` are Unused fields.
NR	—	Specify Newton-Raphson controls. This command is optional. See Command Specification for `Option` = NR.
SCAL	—	Linearly scale the solution vector to improve the convergence rate. See Command Specification for `Option` = SCAL.
TRTOL	—	Specify trust-region solver tolerances. This command is optional. See Command Specification for`Option` = TRTOL.
UINIT	—	Specify a solution guess at the beginning frequency of the solution. This command is optional. See Command Specification for `Option` = UINIT.

Command Specification for `Option` = AFT

HBMOPT, AFT, NP, NT, --, --, --

Table 179: Semantic labels and definitions of Value1, ... Value5 for Option = AFT

Value Label and description Default Value Range

`Value`	Label and description	Default Value	Range
`Value1`	*`NP`* Maximum number of time periods `NP` must be a positive integer. Note that the effective number of time periods may be smaller than `NP` as the AFT transient is stopped when periodic convergence is reached.	4	`NP` > 0
`Value2`	*`NT`* Number of time points per period `NT` cannot be less than 2*NH+1, where NH is the number of harmonics^[a]. The value of NT is automatically adjusted if this criterion is not met.	128	16 ≤ `NT` ≤ 16384 (= 2¹⁴)
`Value3`, … `Value5`	Unused fields

Value1

NP

Maximum number of time periods

NP must be a positive integer. Note that the effective number of time periods may be smaller than NP as the AFT transient is stopped when periodic convergence is reached.

NP > 0

Value2

NT

Number of time points per period

NT cannot be less than 2*NH+1, where NH is the number of harmonics^[a]. The value of NT is automatically adjusted if this criterion is not met.

128

16 ≤ NT ≤ 16384 (= 2¹⁴)

Value3, … Value5 Unused fields

^[a]Specify the number of harmonics NH by issuing HROPT,HBM,NH.

Command Specification for `Option` = CONTSET

HBMOPT, CONTSET, CorrMeth, DS, DSMIN, DSMAX, --

Table 180: Semantic labels and definitions of Value1, ... Value5 for Option = CONTSET

Value Label and description

Value1

CorrMeth

Corrector method

Specify the corrector type or alternative continuation method. The solver uses natural continuation for the first step for all continuation methods. (See notes for details.)

Possible CorrMeth settings are:

OFF	—	No continuation. Similar to natural continuation except there is no heuristic step adjustment, and the maximum number of allowed nonconverged steps is 1.
ARC (default)	—	Arc-length corrector
ORT	—	Orthogonal corrector

NAT

—

Natural continuation. No continuation method is used.

Value2

DS

Initial step size

Step size for the first substep. In the continuation process, the step size determines the size of the tangent prediction. Because it fully determines the predicted point, it also influences the correction, depending on the corrector method as listed below. From the predicted point, corrections occur:

OFF or NAT - along the frequency direction

ARC - along the sphere of radius DS.

ORT - in the plane orthogonal to the tangent direction.

Since the step size depends on the solution DOFs, it does not correspond to the size between two consecutive computed frequencies.

No default value

Note: You must always specify a DS value except when CorrMeth = OFF.

Range: DSMIN ≤ DS ≤ DSMAX

Value3

DSMIN^[a]

Minimum step size

If the step size equals the minimum step size during solution and the nonlinear equation solver fails to converge, the solver will exit.

Default: DS/50

Range: 0 < DSMIN < DSMAX

Value4

DSMAX^[a]

Maximum step size

Default: 5*DS

Range: DSMAX > DSMIN

Value5 Unused field

^[a] During solution, if an internal step adjustment causes the step size to go either below DSMIN or above DSMAX, it is adjusted back to the relevant minimum (DSMIN) or maximum (DSMAX) allowed step size.

Command Specification for `Option` = CONTTERM

HBMOPT, CONTTERM, MAXSTEPS, FREQMIN, FREQMAX, --, --

Table 181: Semantic labels and definitions of Value1, ... Value5 for Option = CONTTERM

`Value`	Label and description	Default Value	Range
`Value1`	*`MAXSTEPS`* Maximum number of successful continuation steps^[a] If exceeded, the solver exits.	10000	`MAXSTEPS` ≥ 0
`Value2`	*`FREQMIN`* Minimum frequency During continuation, if the frequency is below this value, the solver exits.	MIN(`FREQB`, `FREQE`)^[b]	`FREQMIN` ≤ MIN(`FREQB`, `FREQE`)^[b]
`Value3`	*`FREQMAX`* Maximum frequency During continuation, if the frequency exceeds this value, the solver exits.	MAX(`FREQB`, `FREQE`)^[b]	`FREQMAX` ≥ MAX(`FREQB`, `FREQE`)^[b]
`Value4`, `Value5`	Unused fields

^[a]A continuation step is considered successful when the nonlinear equation solver converges and successfully produces solution points in two successive substeps. The number of substeps is equal to the number of successful continuation steps + 1.

^[b]Set the beginning and ending frequency using the HARFRQ command. Note that the beginning frequency can be larger than the ending frequency if the solution branch needs to be evaluated with decreasing frequency.

Command Specification for `Option` = CYCLIC

HBMOPT, CYCLIC, CYCkey, EO, SEPrefix, --, --

Table 182: Semantic labels and definitions of Value1, ... Value5 for Option = CYCLIC

Value Label and description

Value1

CYCkey

Key to activate an HBM cyclic analysis.

Used to solve for spatial harmonic indices greater than 0.

Possible CYCkey settings are:

0 or OFF (default)	—	Do not activate an HBM cyclic analysis.
1 or ON	—	Activate an HBM cyclic analysis.

Value2

EO

Fundamental engine order (EO).

Any integer value. Can be negative. No default value.

Value3

SEPrefix

Prefix for all single stage superelement names.

An alphanumeric name used to identify the superelement. SEPrefix may be up to 26 characters, beginning with a letter and containing only letters, numbers, and underscores. Names beginning with an underscore (for example, _LOOP) are reserved for use by Mechanical APDL and should be avoided. The component name ALL is not permitted

No default value.

Value4, Value5 Unused fields

Command Specification for `Option` = LINEAR

HBMOPT, LINEAR, AFTkey, --, --, --, --

Table 183: Semantic labels and definitions of Value1, ... Value5 for Option = LINEAR

Value Label and description

Value1

AFTkey

Key to ignore nonlinearities (no AFT)

Possible AFTkey settings are:

0 or OFF (default)	—	Do not ignore nonlinearities
1 or ON	—	Ignore nonlinearities (valid only in the first loadstep).

Value2, … Value5 Unused fields

Command Specification for `Option` = NR

HBMOPT, NR, MAXITER, MAXINITITER, --, --, --

Table 184: Semantic labels and definitions of Value1, ... Value5 for Option = NR

`Value`	Label and description	Default Value	Range
`Value1`	*`MAXITER`* Maximum number of iterations at a frequency point	25 in most cases. 100 if continuation is turned off or natural continuation is selected by issuing HBMOPT,CONTSET with `CorrMeth` = OFF or NAT.	`MAXITER` ≥ 0
`Value2`	*`MAXINITITER`* Maximum number of iterations at initial solution, irrespective of continuation settings	500	`MAXINITITER` ≥ 0
`Value3`, … `Value5`	Unused fields

Command Specification for `Option` = SCAL

HBMOPT, SCAL, Type, UScal, FSCAL, DoF, Back

Table 185: Semantic labels and definitions of Value1, ... Value5 for Option = SCAL

Value Label and description

Value1

Type

Scale the solution vector by the selected scaling factor type and specification on UScal.

Note: See scaling equations in Equation Solution and example usage of HBMOPT,SCAL in Scaling the solution vector in the Harmonic Balance Method Analysis Guide.

Possible Type settings are:

0 or NONE (default)	—	No scaling.^[a]
1 or APDL	—	Scaling factors contained in a user-defined APDL array whose name is specified by `UScal` are used.
2 or VALU	—	Scalar value specified for `UScal` is used.

Value2

UScal

Name of the user-defined APDL array (if Type = 1 or APDL) or scalar value (if Type = 2 or VALU) used to scale the solution vector to improve convergence behavior.

UScal setting depends on Type specification as follows:

*For `Type`* = 1 or APDL**	—	`UScal` is the name (up to 32 characters) of a previously defined APDL array that contains scaling factors. It must be a 1D array (DIM, VEC, etc.) with size equal to the size of the solution vector.
*For `TYPE`* = 2 or VALU**	—	`UScal` is a scalar value.

Value3

FSCAL

Scaling value for the circular frequency (ω).

FSCAL is only valid for Type = 1 (or APDL) or 2 (or VALU)

Default: 1.0

Range:FSCAL > 0.0

Value4

DoF

Degree of freedom numbering of the user-defined scaling vector (UScal)

Optional. If Type = 1 or APDL, this indicates the degree of freedom ordering of the user-defined scaling vector.

Possible DoF settings are:

INT (default)	—	Internal Ansys DOFs. Length N_DOF= numdof*lenbac (See FULL File Format in the Programmer's Reference)
SOLU	—	HBM solution DOFs. Length N_DOF = number of multiharmonic equations/(2NH+1)

Value5

Back

APDL array name for the back nodal mapping vector corresponding to the user-defined scaling vector

Optional. Back is used to specify a back nodal mapping vector corresponding to the user-defined scaling vector, UScal. It must be a 1D array (*DIM) with size equal to the number of Ansys internal nodes. Back is used to reorder the user-defined scaling vector to match the internal node ordering at the time of solution. If it is not provided and DoF = INT, it is assumed that the user-defined scaling vector corresponds to the internal DOF ordering at the time of solution.

Note: When using HBMOPT,SCAL,APDL,UScal,FSCAL,INT to specify a user-defined scaling vector UScal in internal DOFs, it is recommended that you provide a Back vector to avoid any inconsistency between the array provided and the internal node ordering. For example usage, see Scaling the solution vector in the Harmonic Balance Method Analysis Guide.

No default value.

Back is limited to 32 characters.

^[a]UScal is not used if Type = 0 or NONE.

Command Specification for`Option` = TRTOL

HBMOPT, TRTOL, UTOL, RTOL, GTOL, --, --

Table 186: Semantic labels and definitions of Value1, ... Value5 for Option = TRTOL

`Value`	Label and description	Default Value	Range
`Value1`	*`UTOL`* Tolerance on the solution step size at any given iteration	1e-15	`UTOL` > 0
`Value2`	*`RTOL`* Tolerance on the function residual norm	1e-6	`RTOL` > 0
`Value3`	*`GTOL`* Tolerance on the gradient norm	1e-12	`GTOL` > 0
`Value4`, `Value5`	Unused fields

Command Specification for `Option` = UINIT

HBMOPT, UINIT, U0Flag, U0Name, U0dof, U0BackName, --

Table 187: Semantic labels and definitions of Value1, ... Value5 for Option = UINIT

Value Label and description

Value1

U0Flag

Initial solution guess

Possible U0Flag settings are:

0 or ZERO (default)	—	Use zero nodal solution as the initial guess.
1 or APDL	—	Use a user-defined APDL array as the initial guess.

Value2

U0name

Name of the APDL array for the initial solution guess

Optional. If U0Flag = 1 or APDL, this APDL array is used to specify the initial solution guess. It must be a 1D array (*DIM) containing the multiharmonic solution guess. The array size is (2*NH+1)*N_DOF where NH is the number of harmonics specified by HROPT,HBM,NH and N_DOF is the number of degrees of freedom, which depends on U0dof.

No default value

U0name is limited to 32 characters.

Value3

U0dof

Degree of freedom numbering of the initial solution guess

Optional. If U0Flag = APDL, this indicates the degree of freedom ordering of the initial guess.

Possible U0dof settings are:

INT (default)	—	Internal Ansys DOFs. Length N_DOF= numdof*lenbac (See FULL File Format in the Programmer's Reference)
SOLU	—	HBM solution DOFs. Length N_DOF = number of multiharmonic equations/(2NH+1)

Value4

U0BackName

APDL array name for the back nodal mapping vector corresponding to the initial guess

Optional. If Uodof = INT, the DOF ordering at the time of solution (see Degree of Freedom Ordering in the Ansys Parametric Design Language Guide) may be different from the intended DOF ordering corresponding to the initial solution guess (U0Name). To address this, U0BackName is used to specify a back nodal mapping vector corresponding to U0Name. It must be a 1D array (*DIM) with size equal to the number of Ansys internal nodes. U0BackName is used to reorder the initial solution guess to match the internal node ordering at the time of solution. If it is not provided and U0dof = INT, it is assumed that the initial solution guess corresponds to the internal DOF ordering at the time of solution.

Note: When using HBMOPT,UINIT,APDL,U0Name,INT to specify the initial solution guess U0Name in internal DOFs, it is recommended that you provide a U0BackName vector to avoid any inconsistency between the array provided and the internal node ordering. For example usage, see Example 3: Two Jointed Beams with Frictional Contact Interface.

No default value

U0BackName is limited to 32 characters.

Value5 Unused field

Notes

This command is used to specify solution options for a harmonic balance method analysis (see Harmonic Balance Method Analysis Guide).

There is no command default. For an HBM analysis (Method = HBM on HROPT), you must issue at least one of the following:

HBMOPT, CONTSET, OFF
HBMOPT, CONTSET, CorrMeth, DS where CorrMeth is blank or any setting except OFF.

No continuation solver options

For HBMOPT, CONTSET, OFF:

NSUBST is used to specify the number of substeps and calculate the fixed frequency step. The first substep is at FREQB + (FREQE - FREQB)/NSBSTP as in other harmonic analyses, where FREQB and FREQE are the beginning and ending frequencies of a solution specified with the HARFRQ command.
FREQB ≤ FREQE is enforced.
Values prescribed for the minimum and maximum frequency (via HBMOPT,CONTTERM,,,,FREQMIN,FREQMAX) for the continuation simulation are ignored.

Alternating frequency-time options

The alternating frequency-time (AFT) procedure and derivation of relevant Jacobians for a general nonlinearity is described in Alternating Frequency-Time Procedure in the Harmonic Balance Method Analysis Guide.

Trust-region solver options

An iterative process is used to solve the HBM nonlinear equations using a trust-region nonlinear equation solver as detailed in Equation Solution in the Harmonic Balance Method Analysis Guide. All tolerances (UTOL, RTOL, and GTOL specified by HBMOPT,TRTOL) are also stopping criteria. The only required convergence criteria is the tolerance on the functional residual norm (HBMOPT,TRTOL,,RTOL). The other tolerances on the gradient norm and the step size are additional convergence criteria that indicate stronger convergence if satisfied.