3. Algorithm Management#

We are going to focus on managing the algorithm. To manage convergence, the different levels of loops and the errors that occurred during a calculation, a common formalism is used, based on the concept of event.

3.1. The different loops#

In the algorithm, there are five levels of loops <BOUC>:

<RESI>: the loop over the various balance residues requested by the user (RESI_GLOB_RELA, RESI_GLOB_MAXI, etc.);
<NEWT>: the Newton iterations loop;
<FIXE>: the loop on fixed points (contact);
<INST>: the loop over the calculation times;
<CALC>: the calculation loop.

The <CALC> « loop » is not really a step. It is used to manage two situations:

The calculation is completed normally (no error) but other than when the time step loop has been reached. For the moment, the only case is when piloting has reached its limits;
An event is triggered outside the loop over the time steps, i.e. during post-processing (detection of instability by vibratory modes);

The various loops are divided between op0070, nmnewt (static and implicit dynamics) and ndexpl (explicit dynamics). For the loop on equilibrium residues, you have to look at the nmcore routine, called by nmconv. For the loop on fixed points, we use the nmible/nmtble routines, contained in nmnewt.

3.2. State of the loops#

The state of a loop is stored in object SDERRO (§ 2.4.2.6), accessed by nmleeb and nmeceb. There are six states:

CONT: the loop continues;
CONV: the converged loop (convergence and divergence events);
ERRE: an error (error type event) occurred during the loop, we will process it;
EVEN: an event (informational event) occurred during the loop;
STOP: an error (error type event) occurred during the loop, we stop;
CTCD: particular condition of the Newton loop for discrete contact;

3.3. The events#

Events can be classified according to their origin:

User defined events in DEFI_LIST_INST (for example, DELTA_GRANDEUR);
The events intrinsic to the algorithm: the errors and the convergence of the various loops;

3.3.1. Types of events#

An event is defined by its type, which is a two-part <XXXX_YYYY> string. The first string <XXXX> describes the type of the event:

< ERRC_ > < ERRI_>* The events giving rise to an error are prefixed by or;

< CONV_ > The events giving rise to convergence are prefixed by;

< DIVE_ > Events giving rise to a discrepancy are prefixed by;

< EVEN_ > Informative events are prefixed with;

The second string <YYYY> describes the event loop level:

*Loop on equilibrium residues <*_ RESI >;

*Loop over Newton iterations<*_ NEWT >;

*Fixed point loop for touch<*_ FIXE >;

*Loop over the time step<*_ INST >;

This information describes in which loop events can potentially trigger.

3.3.1.1. Error-type events < ERR _>#

Errors should be treated immediately (i.e. as soon as the event is triggered) because they are blocking the process, they are noted <ERRI>. The errors to be treated only when the loop converges are noted <ERRC>.

For example:

<ERRI_NEWT> is an error to be treated immediately in a Newton’s iteration as a defect in the integration of the law of behavior prevents or a matrix that cannot be factored;
<ERRC_NEWT> is an error to be treated at Newton convergence, for example an output of a physical criterion outside the limits of its domain of definition;
<ERRI_FIXE> is an error to be dealt with immediately in a fixed point loop;

Note:

The errors typed <ERRI_CALC> cause the calculation to stop immediately because no action can process them. These are the stops due to lack of time CPU and the external stop per user.

3.3.1.2. Convergence events < CONV_ *>#

Convergence events are processed at each loop level. This convergence may be linked to a feature that is activated or not (see § 2.4.1.1).

3.3.1.3. Divergence events < DIVE_ *>#

Divergence events are processed at each level of the loop. This discrepancy may be linked to a feature activated or not (see § 2.4.1.1).

In practice, the state of each loop is instead treated as a discrepancy. In fact, to avoid having to verify that a specific functionality is active (steering, Deborst, contact, etc.) and therefore test the convergence of a loop by verifying this functionality, we prefer to emit a divergence event than a convergence event: we can only have a divergence event: we can only have a discrepancy if the functionality is activated, while we could have convergence even if the functionality is not activated.

3.3.1.4. Informative events <EVEN>#

Informative events are the other events (no error, no convergence). By default, they are only used to give instructions to the user (often in the form of alarm messages, the transition from RESI_GLOB_RELA to RESI_GLOB_MAXI for example). Some can only be activated at the user’s request (command DEFI_LIST_INST).

These events can also be processed explicitly (other than by sending an alarm or information) via DEFI_LIST_INST.

These events are not linked to a loop level.

3.3.1.5. The case of return codes#

A return code is a unique integer giving the status of an operation. It is possible to link an event to the value of a return code. Each value in the return code can generate a different event of any type. The return codes -1 and 0 always have the same meaning:

-1: we did nothing (no factorization, no integration of the law of behavior, etc.);
0: we did something and everything went well;

The other return code values have a meaning depending on their type:

Type	Description	Meaning of the code
FAC	Return of factorization	-1	No factorization
		0	Everything went well
		1	The matrix is singular
		2	Factorization failed
		3	We don’t know how to say if the matrix is singular
PIL	Return from piloting	-1	No piloting
		0	Everything went well
		1	No solution to the driving equation
		2	We have reached a limit (end of calculation)
LDC	Return of the integration of the law of behavior	-1	No integration of behavior
		0	Everything went well
		1	Failure to integrate the law of behavior
		2	A physical parameter is not in its domain of definition
		3	Constraint SIZZn is not zero (De Borst algorithm)
CTC	Return of the discreet contact treatment	-1	No discreet contact
		0	Everything went well
		1	Maximum number of contact iterations has been reached
		2	The contact matrix is unique

3.4. Event Management#

3.4.1. Modifying, adding, or deleting an event#

Most standardized events are provided for in the data structure and related utilities. In most cases, it is only a question of modifying the nmcrga routine (see § 2.4.2.6) by adding the characteristic of the event in DATA at the beginning of the routine.

Description	DATA
Event name	NEVEN
Name of the return code linked to the event (XXX if not return code)	NCRET
Value of the return code linked to the event (99 if no return code)	VCRET
Type and level of triggering the event	TEVEN
Feature that activates a convergence or divergence event	FEVEN
Message code to be displayed when the event is triggered	MEVEN

The message verification system means that the message code to be displayed (MEVEN) is not enough, you must also impact nmevim.

3.4.2. Event broadcasts#

To trigger an event, the developer must predict it in the algorithm by calling the nncrel routine. For example:

Command	Effect
CALL NMCREL (SDERRO, “ERRE_TIMN”,. TRUE. )	Lack of time CPU during a Newton’s iteration
CALL NMCREL (SDERRO, “RESI_MAXR”,. TRUE. )	Passage of RESI_GLOB_RELAà RESI_GLOB_MAXI
CALL NMCREL (SDERRO, “DIVE_FIXG”,. FALSE. )	No discrepancy of the fixed point loop on the geometry

If the event is of type <ERRI_BOUC>, the status of the <BOUC> loop is automatically changed. This is a precaution to prevent the developer from forgetting to process the event (and therefore risk causing false results). An immediate error of level <ERRI> is reflected at all loop levels for the same reasons.

To activate an event linked to a return code, you must use the nmcret routine instead of nmcrel. For example CALL NMCRET (SDERRO, “LDC”, LDCCVG) takes care of transforming the value of the return code of the law of behavior into an event.

3.4.3. Event processing#

The main idea is to process events at all loop levels, to change the state of the loops according to the result of this processing.

3.4.3.1. Convergence and Divergence Events#

Convergence or divergence events are examined at each loop level, in a dedicated routine called nmevcv. This routine changes the state of the loop:

It is initially assumed that the loop continues (state CONT, cf. § 3.2)
We loop through the type events and < CONV_ > taking < DIVE_> into account any activated functionalities;
The result state is calculated for this loop level: if all the divergence events are false and all the convergence events are true, then this loop level is in the converged state;
The states of convergence of the inner loops are checked at this level. For the final state of this loop to be converged, all of the inner loops must be converged. If this is the case, the loop goes into the converged state (state CONV, see § 3.2)
The state of the current loop is modified by calling the nmeceb routine;
The nmeceb routine transmits the status of the loop to the upper loops (avoids unprocessed errors);

Loop	Code	Routine	Calling routine
Residues	RESI	nmcvgr	nmconv
Newton	NEWT	nmcvgn	nmnewt
Fixed point	FIXE	nmcvgf	nmtble
No time	INST	nmcvgp	op0070
Calculus	CALC	nmcvgc	op0070

3.4.3.2. Error-type events#

Error-type events are particularly sensitive and should be treated very rigorously to avoid false results. First, the error-type event was sent using the standard routines: nmcrel and nmcret. It should be noted that in the case of error events, the state of the loop is systematically modified in ERREdans mode in order to avoid continuing these loops if the error has never been treated appropriately by the algorithm (oversight by the developer).

Systematically, error-type events are tested in the algorithm via the nmltev routine. If an error-type event is activated, a GOTO is immediately done in the program.